## 26 · 进度条 Progress

### 26.1 用途
把一个过程的完成度可视化（上传、审核、额度耗尽）；移动端的进度多数伴随文字出现，因此百分比文案与状态色是标配而非可选，且进度变化要能被读屏播报而不只是画出来。

### 26.2 结构（anatomy）
- `progress`：根元素，承载轨道与文案
- `track`：轨道，未完成部分的底色
- `bar`：已完成部分，宽度由 percentage 决定
- `ring`：环形进度的圆环轨道（type=circle 时替代 track/bar）
- `label`：百分比文案，可置于条内、条右侧或环心
- `status`：状态图标位（成功 / 失败），非进行中时显示

### 26.3 变体维度
- `type`：`line`（线形）/ `circle`（环形）
- `status`：`normal`（进行中，品牌色）/ `success`（成功）/ `error`（失败）
- `labelPlacement`：`inside`（文案在条内）/ `right`（条右侧）/ `center`（环心，仅 circle）

### 26.4 状态
- default：进行中（0 < percentage < 100）
- complete：percentage = 100，文案显示 100%
- error：失败，进度停在断点并转为错误色
- paused：暂停，条体降透明度

### 26.5 交互与触控
- 进度条本身不可交互、不接收点击；需要取消时由宿主在旁边放按钮
- 数值变化用 CSS 宽度过渡（240ms，`--kole-m-progress-duration`），不做无限循环动画（省电且不干扰读屏）
- 无动画偏好（`prefers-reduced-motion`）下直接跳到目标宽度

### 26.6 无障碍
- 根节点 `role="progressbar"` + `aria-valuemin="0"` / `aria-valuemax="100"` / `aria-valuenow`
- 文案节点 `aria-hidden="true"`，避免与 `aria-valuenow` 重复播报
- 不确定进度（无法给出百分比）用 `aria-valuetext="进行中"` 表达

### 26.7 doNotInvent
- 环形进度的线宽与半径的自适应规则（由 size 决定，不做响应式推导）
- 进度到达 100% 后的自动隐藏时机

### 26.8 unknowns
- 百分比是否四舍五入到整数
- 环形进度是否支持渐变描边

---