# @fiscozen/progress 中文文档

规范地址：https://npmcn.com/package/%40fiscozen/progress/

版本：4\.0\.2
npm 元数据更新时间：2026-09-07T07:16:49.902Z
中文译文更新时间：2026-11-14T20:51:41.863Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fiscozen/progress
原文对照：https://npmcn.com/package/%40fiscozen/progress/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：587 kB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- peer 依赖：tailwindcss ^3\.4\.1，vue ^3\.4\.13，@fiscozen/icons ^1\.0\.8
- 首次发布：2024-11-28T15:04:28.689Z
- 最新版本发布：2026-09-07T07:16:49.659Z
- 近 30 天下载量：2436（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 9 个）

## 中文简介

设计系统进展部分

## 安装

```sh
npm install @fiscozen/progress
```

也可以使用：`pnpm add @fiscozen/progress`、`yarn add @fiscozen/progress`、`bun add @fiscozen/progress`

## README

# @fiscozen/ 进步

Vue 3应用程序的进步指标,包括动画加载自旋器和可自定义范围的视觉进步条.

## 特征

-   **正在装入自旋器**: 用于装入状态的动画自旋器组件
-   **进度栏**: 具有自定义分/最大范围的视觉进度指标
-   **自定义范围**: 支持负值和自定义范围(例如 -15至50)
-   **平滑过渡**: 更新进度栏的 CSS 转换
-   **无障碍**页:1 AA 符合 ARIA 属性
-   **类型脚本**: 具有类型脚本定义的完整类型安全

## 安装

```bash
npm install @fiscozen/progress
```

## 构成部分

此套件输出两个组件:

-   `FzProgress` - 动画装入自旋器指示器
-   `FzProgressBar` - 显示百分比的视觉进步栏

## 基本用途

### Fz 进展

```vue
<script setup lang="ts">
import { FzProgress } from '@fiscozen/progress'
</script>

<template>
  <FzProgress />
</template>
```

### Fz 进展栏

```vue
<script setup lang="ts">
import { FzProgressBar } from '@fiscozen/progress'
</script>

<template>
  <FzProgressBar :current="50" />
</template>
```

## Fz 进展

### 带有自定义大小

```vue
<template>
  <FzProgress size="sm" />
  <FzProgress size="lg" />
  <FzProgress size="xl" />
</template>
```

## Fz 进展栏

### 基本进展

```vue
<template>
  <!-- 0% -->
  <FzProgressBar :current="0" />
  
  <!-- 50% -->
  <FzProgressBar :current="50" />
  
  <!-- 100% -->
  <FzProgressBar :current="100" />
</template>
```

### 自定义范围

```vue
<template>
  <!-- Range from -15 to 50, current value 30 -->
  <FzProgressBar :current="30" :min="-15" :max="50" />
  
  <!-- Range from 0 to 200, current value 150 -->
  <FzProgressBar :current="150" :min="0" :max="200" />
</template>
```

### 自定义标签

```vue
<template>
  <FzProgressBar
    :current="75"
    label="Caricamento file"
  />
</template>
```

### 带有值的背景进展

```vue
<template>
  <FzProgressBar
    :current="3"
    :max="10"
    label="Caricamento file"
    valueText="Caricamento file 3 di 10"
  />
</template>
```

### 自定义大小

```vue
<template>
  <!-- Small size -->
  <FzProgressBar :current="50" size="sm" />
  
  <!-- Medium size (default) -->
  <FzProgressBar :current="50" size="md" />
</template>
```

### 自定义颜色

```vue
<template>
  <!-- Purple (default) -->
  <FzProgressBar :current="50" color="purple" />
  
  <!-- Blue -->
  <FzProgressBar :current="50" color="blue" />
  
  <!-- Orange -->
  <FzProgressBar :current="50" color="orange" />
  
  <!-- Pink -->
  <FzProgressBar :current="50" color="pink" />
  
  <!-- Yellow -->
  <FzProgressBar :current="50" color="yellow" />
  
  <!-- Grey -->
  <FzProgressBar :current="50" color="grey" />
  
  <!-- Red (semantic error) -->
  <FzProgressBar :current="50" color="red" />
</template>
```

## 道具

### Fz 进步道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `size` | `'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'` | `'lg'` | 旋转器大小 |
| `label` | `string` | `'Caricamento…'` | 可通过 `role="status"` 作为隐形文字 |

### Fz 进步栏道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `current` | `number` | **所需经费** | 分钟最大范围内的当前进度值 |
| `max` | `number` | `100` | 进度计算的最大值 |
| `min` | `number` | `0` | 进度计算的最低值 |
| `label` | `string` | `'Avanzamento'` | 可通过 `aria-label` |
| `valueText` | `string` | —— 说 | 可选的可读文本 `aria-valuetext` (例如:. `'Caricamento file 3 di 10'`(中文(简体) ) |
| `size` | `'sm' | 'md'` | `'md'` | 进步栏的高度 |
| `color` | `'purple' | 'blue' | 'orange' | 'pink' | 'yellow' | 'grey' | 'red'` | `'purple'` | 颜色变相. `yellow` 财务报告和审定财务报表 `red` 地图到 `semantic-warning-*` 财务报告和审定财务报表 `semantic-error-*` 符号 |

## 行为和概念

### 进度计算

进度栏计算 `current` 数值 `[min, max]` 范围 :

```
percentage = ((current - min) / (max - min)) * 100
```

CSS宽度在0%至100%之间.

**实例:**

-   `current=50, min=0, max=100` → `50%`
-   `current=30, min=-15, max=50` → `(30 - (-15)) / (50 - (-15)) * 100 = 69%`
-   `current=-10, min=0, max=100` → `0%` (尖叫声)
-   `current=150, min=0, max=100` → `100%` (尖叫声)

### 自定义范围

该组件支持自定义范围,包括负值:

```vue
<template>
  <!-- Temperature range: -25°C to 75°C, current 0°C -->
  <FzProgressBar
    :current="0"
    :min="-25"
    :max="75"
    label="Temperatura"
  />
  <!-- Result: (0 - (-25)) / (75 - (-25)) * 100 = 25% -->
</template>
```

## 无障碍

### Fz 进展

-   包装器有 `role="status"` (隐含) `aria-live="polite"`),所以屏幕阅读器在旋转器进入DOM时宣布装载状态
-   `aria-label` 默认为 `'Caricamento…'`,通过 `label` 道具,并被镜像为偏好文本内容的屏幕阅读器所隐藏的图像文本
-   动画在 `@media (prefers-reduced-motion: reduce)` 遵守《保护所有人免受强迫失踪公约》
-   **消费者指导**: 切换旋转器应设置的容器 `aria-busy="true"` 在装入时, 因此周围的内容标记为尚未准备好 。 示例
    
    ```vue
    <div :aria-busy="loading">
      <FzProgress v-if="loading" />
      <slot v-else />
    </div>
    ```
    

### Fz 进展栏

遵循WCAG 2.1 AA,包括:

-   **ARIA 属性**数字 :
    -   `role="progressbar"` 对于语义意义
    -   `aria-valuenow` 带有当前值(为 NaN/ Infinity 系统化)
    -   `aria-valuemin` 最小值
    -   `aria-valuemax` 最大值
    -   `aria-label` 从 `label` 屏幕阅读器描述的道具
    -   `aria-valuetext` 从可选 `valueText` 可读环境进展道具
-   **减少动议**: 使用宽度过渡 `motion-safe:` 尾风公用设备,所以自动禁用 `prefers-reduced-motion: reduce` (世界会计学咨询小组2.3.3)
-   **屏幕阅读器支持**: 进度值和背景描述在浏览进度栏时可以访问
-   **键盘导航**: 进步栏可以通过键盘访问(虽然不是交互式的)

## 未来的增强(最好有)

当真正的消费者需要这些产品时,这些产品被故意排除在目前的API之外,并追踪到将来的少量释放:

-   **不确定状态 `FzProgressBar`** ——通过动画条纹,行走填充,或脉冲来表达"进展未知"的方法 `aria-valuenow` 省略(按ARIA APG计算)。 将作为添加剂添加 `indeterminate?: boolean` 需要的时候做道具.

## 页:1

### 为什么Div 代替 HTML 进步元素 ?

我们用 `div` 元素代替 HTML `<progress>` 用于更好的 CSS 交叉浏览器兼容性的元素。 进度元素需要特定浏览器的伪元素(`::-webkit-progress-bar`, (中文(简体) ), `::-moz-progress-bar`),这在浏览器之间可能不一致,与Tailwind CSS的风格更难.

## 相关构成部分

-   **福兹康**: Fz 进步在内部用于图标渲染

## 常见问题

### @fiscozen/progress 是什么？

设计系统进展部分

### 如何安装 @fiscozen/progress？

在项目目录运行 npm install @fiscozen/progress，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：tailwindcss（^3\.4\.1）、vue（^3\.4\.13）、@fiscozen/icons（^1\.0\.8）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fiscozen/progress 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fiscozen\_\_progress 是否存在。

### @fiscozen/progress 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fiscozen/progress 可以商用吗？

@fiscozen/progress 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fiscozen/progress 的下载量有多少？

根据 npm 官方下载统计，@fiscozen/progress 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,436 次，日均约 81 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fiscozen/progress 还在维护吗？

最新版本 4\.0\.2 发布于 2026/09/07（2 个月前）；至今共发布 11 个版本，其中过去 12 个月发布了 9 个；首次发布于 2024/11/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。