Progress
展示任务完成程度。中文惯用名：进度条。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.progress |
| 名称 | Progress |
| 二级分类 | 反馈（feedback） |
| 用途 | 展示任务完成程度 |
| 描述 | 中文惯用名：进度条。 |
预览
静态结构：根节点 <div data-slot="progress">（relative w-full）内为轨道 + 指示条——轨道（data-slot="progress-track"，h-2 全宽、rounded-full、bg-(--progress-track) 令牌底色、overflow-hidden）内是指示条（data-slot="progress-indicator"，h-full、bg-(--progress-indicator) 令牌前景色，宽度由 Base UI 按 value 百分比设置并带 width 过渡）。value 经适配器钳制到 0~100；undefined / null / 非有限数透传为不确定态，不显示固定比例。
DSL 结构
{
"type": "Progress",
"props": {
"value": 70
}
}何时用
何时使用
- 展示任务完成程度：上传 / 下载、导入导出、批量处理的百分比反馈。
- 有明确总量与已完成量、进度可计算的可控任务，用户据此判断还需等待多久。
- 无法估算进度时用不确定态（value 缺省 / null）表示「处理中但无完成度」。
何时不用
- 只需表示「紧邻内容正在处理」：使用 Spinner（局部指示，不算完成度）。
- 需要覆盖页面或区块并阻断操作：使用 LoadingOverlay（Spinner + 遮罩）。
- 结构已知的加载占位：使用 Skeleton（比进度条更贴近最终版式）。
- 表达评分 / 指标占比等静态数值：使用 Statistic 或图表，Progress 的语义是任务进度。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 进行中（0 < value < 100） | 指示条按比例填充 | 上传 / 导入等可估算进度的任务 |
| 已完成（value = 100） | 指示条铺满轨道 | 任务收尾的完成态展示 |
| 不确定态（value 缺省 / null） | 透传 Base UI 不确定态，不显示固定比例 | 处理中但总量未知、无法计算百分比 |
| 边界值钳制 | 越界值按 0 / 100 展示 | 计算误差导致越界时的兜底（如完成数大于总数） |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | `number | null` | — |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式 |
使用规范
- 有总量就传 value（按已完成 / 总量计算百分比）；无法估算时用不确定态或改用 Spinner，不要造假进度。
- 进度须真实反映任务状态：绑定数据源的完成量，任务结束（成功或失败）都要停止推进并切换为 Result / Alert 反馈。
- 长任务在进度条旁给出文字说明（「已处理 120 / 300」）与可取消入口，只有条形容器用户无法判断还剩多久。
- 与 Spinner / LoadingOverlay 的分工：进度条表达完成程度，Spinner 表达局部处理中，LoadingOverlay 覆盖区块并阻断操作。
- 配色沿用令牌（--progress-track / --progress-indicator），不要用 Progress 表达评分或指标占比。
正例
- ✓ 文件上传：value 绑定已上传字节百分比，完成后切换为 Result / Alert 反馈结果。
- ✓ 批量导入：value = 已完成数 / 总数，旁侧附「已处理 120 / 300」文案与取消入口。
- ✓ 无法估算时：不传 value（不确定态），配合文案「正在准备数据…」。
反例
- ✕ 用定时器推进假进度（进度必须真实反映任务状态）。
- ✕ 首屏结构已知的加载也用 Progress（应使用 Skeleton）。
- ✕ 用 Progress 表达评分或完成度指标（应使用 Statistic 或图表）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。