# 进度条 · ProgressBar

- 页面: https://jiguang132.com/zh/resources/astryx/docs/progress-bar
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

进度条用于反馈与状态场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **进度条 · 综合展示 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **进度条 · 自定义 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **进度条 · 交互示例 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **进度条 · 样式变化 / 样式 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **进度条 · 交互示例 5**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## Progress Bar

A horizontal bar showing the completion progress of a task. Use it for operations where the duration is known, or as an animated indicator when progress can't be calculated. Supports semantic color variants, value labels, and custom formatting.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label * | string |  | 无障碍标签（必填）。 |
| value | number | 0 | 当前值（不确定模式下忽略）。 |
| max | number | 100 | 最大值。 |
| isLabelHidden | boolean | false | 视觉上隐藏标签（仍保持无障碍可访问性）。 |
| hasValueLabel | boolean | false | 显示格式化的值文本（不确定模式下忽略）。 |
| formatValueLabel | (value: number, max: number) => string |  | 自定义值标签格式化器；默认为百分比字符串。 |
| variant | 'accent' \| 'success' \| 'warning' \| 'error' \| 'neutral' | 'accent' | 语义颜色变体。 |
| isIndeterminate | boolean | false | 用于未知进度的动画加载指示器。 |
| marks | ReadonlyArray<{value: number; label: string}> |  | 在轨道上按与 value 相同的 0..max 刻度绘制的固定目标标记（例如目标线）。无论进度低于还是超过它们都保持可见，并根据所处位置取色：位于已填充区域内的标记使用与填充变体配对的前景色（on-accent、on-warning、on-error 等），仍位于空轨道上的标记使用主文本颜色（禁用状态下会降为次要文本颜色，与其整体弱化的呈现保持一致）。每个标记都必须提供 label——它既是标记的无障碍名称，也是悬停/聚焦时通过工具提示显示的文本。不确定模式下忽略。 |
| isDisabled | boolean | false | 视觉禁用状态——使填充条和文本变灰。用于已取消或不活跃的操作。 |
| xstyle | StyleXStyles |  | 用于布局自定义的 StyleX 样式（边距、定位、尺寸）。必须是 stylex.create() 的值，而非内联样式对象如 style={{}}。 |

### 使用建议

- Use a determinate bar when the total amount of work is known, and indeterminate when it's not.
- Choose a color variant that matches the context: accent for general progress, success for completion, warning or error for alerts.
- Always provide a label, even if hidden; screen readers need it to announce what's loading.
- 避免：Place icons or labels inside the bar; compose them alongside it using layout components.
- 避免：Use a progress bar for instant actions; it's meant for operations that take noticeable time.
- 避免：Use multiple progress bars stacked together for the same operation; use one bar with a value label instead.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-progress-bar",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-progress-bar-fill",
      "visualProps": [
        "variant"
      ]
    },
    {
      "className": "astryx-progress-bar-track"
    },
    {
      "className": "astryx-progress-bar-mark",
      "visualProps": [
        "variant",
        "placement"
      ]
    }
  ],
  "vars": [
    {
      "name": "--_progressbar-mark-width",
      "description": "目标标记刻度宽度",
      "default": "2px",
      "private": true
    },
    {
      "name": "--_progressbar-mark-height",
      "description": "目标标记刻度高度",
      "default": "8px",
      "private": true
    }
  ],
  "derived": [
    {
      "property": "width",
      "vars": [
        "--_progressbar-mark-width"
      ],
      "replaces": true
    },
    {
      "property": "height",
      "vars": [
        "--_progressbar-mark-height"
      ],
      "replaces": true
    }
  ]
}
```

### 组件结构

- **Progress bar**: Container arranging the label row and progress track.
- **Label**: Text naming the operation, optionally hidden visually while remaining accessible.
- **Value text**: Formatted determinate value shown beside the label when requested.
- **Track**: Remaining-progress rail that carries the progressbar semantics.
- **Fill**: Painted segment showing completed progress or indeterminate movement.
- **Mark**: Labeled target tick positioned on a determinate track.

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt