步骤条 · Stepper

步骤条用于导航场景。下面的官方示例展示原生用法与状态，属性名保持上游 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：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
步骤条 · 交互示例 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
步骤条 · 交互示例 7：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
步骤条 · 交互示例 8：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
步骤条 · 状态 9：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
步骤条 · 响应式布局 10：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
步骤条 · 多种状态 11：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

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

Step

Individual step within a Stepper. Renders a progress-bar segment, an indicator, and a label with optional description. Progress (completed/active/not-started) is derived from the parent Stepper's activeStep and this step's step index.

属性	类型	默认值	说明
step *	number		Zero-based index of this step. Used to derive progress (completed/active/not-started) relative to the parent activeStep.
label *	string		Step label text. Kept to a single line and ellipsized when the step is narrower than the label, so a row of horizontal steps stays the same height and the track under them stays straight. The full string is still read out as part of the step, so a truncated label costs nothing in the accessible name — but short labels survive narrow layouts better.
description	string		Optional description shown below the label for additional context.
children	ReactNode		Content rendered below the label and description. Useful in vertical steppers for form fields or detailed step content. In a compact horizontal Stepper, the content remains mounted to preserve local state while it is hidden with the expanded step details.
status	'accent' \| 'success' \| 'warning' \| 'error'		Semantic color for the step. Controls color only and maps to the global Astryx semantic tokens. Leave unset for the progress-derived default coloring.
indicator	'auto' \| 'number' \| 'none' \| ReactNode	'auto'	What to show as the step indicator. 'auto' shows a number until completed then a check, 'number' always shows a numbered badge, 'none' hides it, or pass any ReactNode (e.g. an Icon) for a fully custom indicator.
isDisabled	boolean	false	Disables interaction and dims the step indicator and label.
isOptional	boolean	false	Marks the step as optional, appending an "Optional" affordance after the label.
endContent	ReactNode		Trailing content rendered at the end of the label row.
density	'compact' \| 'balanced' \| 'spacious'		Controls vertical padding of the step. Falls back to the stepper-level density when unset.

Stepper

步骤器显示通过一系列逻辑编号步骤的进度。用于多步骤工作流程，如表单、入职流程或结账流程。

使用建议

保持步骤标签简短和描述性。
当步骤有较长描述时使用垂直方向。水平步骤器会自行处理窄容器：当每个步骤的可用宽度不足 horizontalOptions.minimumStepWidth（默认为 112px）时，它会收起标签，并按 collapsedVariant 显示紧凑内容。
当页面已有返回/继续控件时，将 horizontalOptions.collapsedVariant 设为 'withLabel'；当周围界面同时提供当前步骤标题和导航、只需要裸进度轨道时，将其设为 'hiddenLabel'。
为非线性工作流程提供 onStepClick。
避免：少于3个步骤时使用步骤器。
避免：超过7个步骤时使用步骤器。

主题 API

{
  "targets": [
    {
      "className": "astryx-stepper",
      "visualProps": [
        "orientation",
        "indicatorPosition"
      ]
    },
    {
      "className": "astryx-stepper-frame"
    },
    {
      "className": "astryx-stepper-summary"
    },
    {
      "className": "astryx-step",
      "visualProps": [
        "progress",
        "status"
      ]
    },
    {
      "className": "astryx-step-indicator",
      "visualProps": [
        "progress",
        "status"
      ]
    },
    {
      "className": "astryx-step-label",
      "visualProps": [
        "progress",
        "status",
        "disabled"
      ]
    },
    {
      "className": "astryx-step-description",
      "visualProps": [
        "progress",
        "status"
      ]
    },
    {
      "className": "astryx-step-bar"
    },
    {
      "className": "astryx-step-connector"
    }
  ],
  "vars": [
    {
      "name": "--step-connector-gap",
      "description": "连接线与指示器相接处留出的间隙，落在朝向指示器的一侧。适用于 on-track 布局——其连接线由节点两侧各一段绘制；取 0 时轨道将不间断地穿过节点。",
      "default": "0px"
    }
  ]
}

Stepper

容器组件，管理步骤状态并以水平或垂直方向渲染步骤。

属性	类型	默认值	说明
activeStep *	number		当前活动步骤的从零开始的索引。
children *	ReactNode		要在步骤器中渲染的 Step 元素。
orientation	'horizontal' \| 'vertical'	'horizontal'	步骤器的布局方向。
onStepClick	(index: number) => void		点击步骤或紧凑摘要控件时调用。启用非线性导航；水平步骤器折叠后，导航转移到会跳过已禁用步骤的摘要控件。
label	string	'Progress' (localized)	有序列表的无障碍标签。
density	'compact' \| 'balanced' \| 'spacious'	'balanced'	控制所有步骤的内边距。
indicatorPosition	'separated' \| 'on-track'	'separated'	步骤指示器相对于连接轨道的位置。
horizontalOptions	{ minimumStepWidth: number; collapsedVariant: 'withLabelAndControls' \| 'withLabel' \| 'hiddenLabel' }	{ minimumStepWidth: 112, collapsedVariant: 'withLabelAndControls' }	水平布局的收起选项。minimumStepWidth 是每个步骤的像素阈值。collapsedVariant 可选择显示标签和控件、仅显示标签，或只显示裸进度轨道而不显示紧凑行。仅当 collapsedVariant 为 withLabelAndControls 且设置 onStepClick 时显示控件，每个步骤始终保留无障碍名称。
xstyle	StyleXStyles		用于布局自定义的 StyleX 样式。

Step

步骤器中的单个步骤。渲染进度条、指示器和带可选描述的标签。

步骤条

步骤条 · Stepper

安装与前置条件

示例与使用方式

API 与上游详细参考

Step

Stepper

使用建议

主题 API

Stepper

Step

组件结构