For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt, and this page is available as Markdown at https://rickyshin93.github.io/tao-ui/zh/components/steps.md.
v0.0.57
  • 简体中文
  • Steps

    导航@rockshin/tao-ui

    引导用户按顺序完成多阶段的任务。

    何时使用

    当任务存在先后顺序时使用 Steps——结算流程、引导向导、发布流水线。它同样可以作为「用户旁观而非操作」的过程进度指示。

    推荐

    • 标题保持在一到两个词,细节放进 content。
    • 整条步骤条由 current 驱动,状态从位置自动推导。
    • 当回退到已完成步骤有意义时,提供 onChange。
    • 流程较长或容器较窄时改用 orientation="vertical"。

    避免

    • 不要用 Steps 承载同级内容切换,请使用 Tabs。
    • 不要用 Steps 表示单一的不确定操作,请使用 Spinner。
    • 除非某一步确实失败或被跳过,否则不要逐项设置 status。

    代码演示

    基础用法

    已完成
    这一步已经完成。
    2
    进行中
    正在处理。
    3
    等待中
    尚未开始。
    TSX

    垂直与可点击

    onChange 回调收到的是绝对步骤序号。点击当前步骤不会触发回调,disabled 的步骤始终不可交互。

    1
    已完成
    这一步已经完成。
    2
    进行中
    正在处理。
    3
    等待中
    尚未开始。
    4
    已锁定
    暂不可用。
    1
    已完成
    这一步已经完成。
    2
    进行中
    正在处理。
    3
    等待中
    尚未开始。
    4
    已锁定
    暂不可用。
    TSX

    状态、变体与尺寸

    status 设置当前步骤的状态,其余步骤的状态由与当前位置的关系推导。variant 决定图标是实心还是描边,size 切换密度。

    已完成
    这一步已经完成。
    进行中
    正在处理。
    3
    等待中
    尚未开始。
    已完成
    这一步已经完成。
    2
    进行中
    正在处理。
    3
    等待中
    尚未开始。
    已完成
    这一步已经完成。
    2
    进行中
    正在处理。
    3
    等待中
    尚未开始。
    TSX

    类型

    type 改变整条步骤条的形态:dot 用小圆点替代数字图标,navigation 把每步变成带下划线指示的可点击标签,panel 则把步骤渲染成彼此咬合的缺口面板。

    第一步
    第一段说明
    第二步
    第二段说明
    第三步
    第三段说明
    第一步
    第一段说明
    2
    第二步
    第二段说明
    3
    第三步
    第三段说明
    第一步
    第一段说明
    2
    第二步
    第二段说明
    3
    第三步
    第三段说明
    第一步
    第一段说明
    2
    第二步
    第二段说明
    3
    第三步
    第三段说明
    TSX

    内联

    type="inline" 渲染一条紧凑的圆点条,说明文字改由 Tooltip 承载。offset 沿主轴推移整条步骤条,titlePlacement 把标题移到圆点下方。

    第一步
    第一段说明
    第二步
    第二段说明
    第三步
    第三段说明
    第一步
    第一段说明
    第二步
    第二段说明
    第三步
    第三段说明
    TSX

    进度与最大数量

    percent 会在当前图标外圈画出进度环。maxCount 用于收拢过长的流程:被隐藏的区间折叠为一个禁用的省略步骤,而 onChange 依旧回传原始序号。

    已完成
    这一步已经完成。
    2
    进行中
    正在处理。
    3
    等待中
    尚未开始。
    步骤 1
    步骤 3
    4
    步骤 4
    5
    步骤 5
    10
    步骤 10
    TSX

    自定义图标

    items[].icon 替换单个步骤的图标。iconRender 替换全部图标,并会收到步骤序号、是否为当前步骤,以及用于渲染语义化图标容器的 Icon 组件。

    1
    已完成
    这一步已经完成。
    2
    进行中
    正在处理。
    3
    等待中
    尚未开始。
    TSX

    语义化 DOM 定制

    每个部件都可以通过 classNames 与 styles 定位,单个步骤也能覆盖自己的部件。 使用 finishIconBackground 和 finishIconColor 可分别设置已完成步骤的内置圆形背景和对勾颜色,适用于默认、导航和面板类型;点状步骤和自定义图标不受影响。

    已完成
    这一步已经完成。
    2
    进行中
    正在处理。
    3
    等待中
    尚未开始。
    TSX

    可点击切换

    维护 current 并处理 onChange,步骤切换后同步展示当前内容。

    1
    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.

    current: 0

    TSX

    当前步骤出错

    status="error" 明确标识当前步骤失败,错误原因由旁边的说明表达。

    Finished
    This step is done.
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    TSX

    独立步骤状态

    为单个步骤设置状态,可表达部分完成、失败和等待并存的流程。

    Done
    Finished.
    Failed
    Something broke.
    3
    Running
    In progress.
    4
    Queued
    Not started.
    TSX

    标题位置

    控制标题相对步骤图形的位置,匹配可用空间。

    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    TSX

    步骤内进度

    通过 percent 展示当前步骤的进度,示例可切换进度值。

    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.

    percent: 40

    TSX

    点状步骤

    type="dot" 使用更紧凑的节点,适合状态追踪。

    Finished
    This step is done.
    In Progress
    Working on it now.
    Waiting
    Not started yet.
    TSX

    自定义步骤点

    通过渲染回调定制步骤点,保留标题与状态信息。

    Finished
    This step is done.
    In Progress
    Working on it now.
    Waiting
    Not started yet.
    TSX

    导航型步骤

    导航型步骤适合在多个流程阶段之间切换。

    1
    Step 1
    First
    2
    Step 2
    Second
    3
    Step 3
    Third
    TSX

    面板型步骤

    面板型步骤为标题和说明提供更大的操作区域。

    One
    2
    Two
    3
    Three
    4
    Four
    One
    2
    Two
    3
    Three
    4
    Four
    TSX

    限制可见步骤

    用 maxCount 折叠较长流程,移动当前步骤时观察显示范围变化。

    Step 1
    Step 3
    4
    Step 4
    5
    Step 5
    10
    Step 10
    TSX

    禁用某个步骤

    单独禁用不可进入的步骤,不影响其他可点击步骤。

    First
    2
    Second
    3
    Locked
    TSX

    长标题截断

    长标题在受限宽度内截断,详细解释放在步骤内容中。

    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    1
    A rather long first title
    with a subtitle
    And a long description that will be truncated.
    2
    Second
    Also truncated when needed.
    TSX

    起始序号

    通过 initial 调整显示序号,current 仍使用组件约定的索引。

    Finished
    This step is done.
    4
    In Progress
    Working on it now.
    5
    Waiting
    Not started yet.
    TSX

    继承全局配置

    继承尺寸与外观配置,也可以在单个步骤组件上覆盖。

    Finished
    This step is done.
    2
    In Progress
    Working on it now.
    3
    Waiting
    Not started yet.
    TSX

    API

    Steps

    属性说明类型默认值
    itemsStep data.StepItem[] | undefined-
    currentCurrent step, counted from 0. Overridden per step by items.status.number | undefined-
    initialNumbering offset — the first step is numbered initial + 1.number | undefined-
    statusStatus of the current step; the others derive theirs from position.StepsStatus | undefinedprocess
    orientationLayout axis.StepsOrientation | undefined-
    titlePlacementWhere the title sits relative to the icon.StepsTitlePlacement | undefined-
    responsiveCollapse to vertical below 576px.boolean | undefinedtrue
    sizeVisual density.StepsSize | undefined-
    variantStyle variant.StepsVariant | undefinedfilled
    typeSteps flavour.StepsType | undefined-
    percentProgress ring on the process icon; ignored by type="inline".number | undefined-
    maxCountCollapse to at most N steps (>= 3); hidden ranges become an ellipsis step.number | undefined-
    offsetLeading flex offset for type="inline".number | undefined-
    ellipsisTruncate overflowing titles, subtitles, and content.boolean | undefined-
    iconRenderReplace the icon node of every step.StepsIconRender | undefined-
    finishIconBackgroundBackground of the built-in finished-step circle.BackgroundColor | undefined-
    finishIconColorColor of the built-in finished-step check mark.Color | undefined-
    onChangeFires with the absolute step index when a non-current step is activated.((current: number) => void) | undefined-
    className节点类名string | undefined-
    style节点样式CSSProperties | undefined-