进度条 · ProgressBar

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

安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

进度条 · 综合展示 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

{
  "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.