Ant Design Steps 步骤条 error 状态实战用 status 精准标记步骤运行错误【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design在 Ant Designantd的 Steps 步骤条组件中status属性用于指定当前步骤的展示状态其中最常用的场景之一是把正在执行却已出错的步骤标记为error出错步骤的图标会变为红色的叉号标题与描述随之标红前序步骤与出错步骤之间的连接线也会同步变为错误色。本文以仓库内 components/steps/demo/error.md 及配套示例 components/steps/demo/error.tsx 为主线结合 Steps 组件源码 与 样式源码 及测试快照完整讲解error状态的使用方法、语义规则、底层渲染实现与主题定制方式读完即可在表单分步提交、任务流水线等场景中直接落地。一、官方演示文档与示例代码解读官方演示文档 error.md 对场景的说明非常凝练zh-CN使用 Steps 的status属性来指定当前步骤的状态。en-USBy usingstatusofSteps, you can specify the state for current step.即error不是单独存在的展示模式而是 Steps 的status属性取值之一用来把当前步骤渲染为运行出错的视觉状态。配套的可运行示例 error.tsx 完整代码如下import React from react; import { Steps } from antd; const description This is a description; const App: React.FC () ( Steps current{1} statuserror items{[ { title: Finished, description, }, { title: In Process, description, }, { title: Waiting, description, }, ]} / ); export default App;要点拆解current{1}表示从 0 开始计数当前步骤是第二项 In Processstatuserror把当前步骤current指向的那一项标记为错误状态items数组承载三个步骤项每项只配置了title与description未单独配置status因此全部交由 Steps 的current自动推导推导规则见下文第三节。实际渲染结果中三项依次呈现为第一项 Finished已完成连接线指向错误步骤处同步标红、第二项 In Process错误红色叉号图标、标题与描述标红、第三项 Waiting等待中。这一结构非常适合模拟第 2 步执行失败的分步任务流。二、status 的取值语义与优先级规则根据 Steps 组件 API 文档Steps 级status属性说明如下参数说明类型默认值版本status指定当前步骤的状态可选waitprocessfinisherrorstringprocess-四个取值的含义分别为wait等待中步骤尚未开始process进行中即默认的当前步骤样式finish已完成通常显示对勾error出错当前步骤执行失败显示红色叉号。StepItem 级别的 status 覆盖除了在 Steps 上设置status还可以在单个步骤项上设置status。文档中 StepItem 的说明为参数说明类型默认值status指定状态。当不配置该属性时会使用 Steps 的current来自动指定状态。可选waitprocessfinisherrorstringwait优先级规则可以概括为若某个步骤项显式配置了status则该步骤按显式值渲染不受current影响若步骤项未配置status则由 Steps 的current自动推导index current为finishindex current为processSteps 级status可覆盖此默认值index current为waitSteps 级status只影响current对应的那一个步骤。也就是说error既可以通过 Steps 级statuserror作用于当前步骤error.md 演示的正是这种用法也可以直接写在某个 StepItem 上例如{ title: Upload, status: error }灵活实现指定某一步出错的精确控制。items 与旧版 children 写法示例中使用的是items数组4.24.0 起支持。从 useLegacyItems.ts 的实现可以看到items存在时直接使用items否则会把Steps.Step子元素转换为数组。同时该文件在非生产/测试环境会对children写法给出Step is deprecated. Please use items instead.的废弃警告相关测试见 index.test.tsx因此新代码应优先使用items写法。三、源码视角error 状态如何被渲染出来1. 类型定义与默认值components/steps/index.tsx 中StepsProps与StepProps对status的类型约束完全一致status?: wait | process | finish | error;StepProps单个步骤项还额外支持description、icon、subTitle、disabled等字段说明错误步骤同样可以携带描述、自定义图标与子标题渲染语义上与其他状态保持一致。2. error 图标的注入在 index.tsx 中Steps 为finish与error两种状态注入了内置图标const icons { finish: CheckOutlined className{${prefixCls}-finish-icon} /, error: CloseOutlined className{${prefixCls}-error-icon} /, };即error状态使用ant-design/icons的CloseOutlined叉号并挂上ant-steps-error-icon类名finish使用 CheckOutlined。这两个图标通过icons透传给底层rc-stepsRcSteps完成替换。3. 状态样式与错误连接线的生成components/steps/style/index.ts 中的genStepsItemStatusStyle用统一的模板函数为四种状态生成图标、标题、描述与尾部连接线的样式error对应的关键 token 包括Token 名含义源码注释errorIconColorerror 图标前景色errorTitleColorerror 状态下标题颜色errorDescriptionColorerror 状态下描述颜色errorTailColorerror 状态下尾部连接线颜色errorIconBgColorerror 图标背景色errorIconBorderColorerror 图标边框色errorDotColor点状模式下 error 圆点颜色在默认主题中这些 token 的取值见 style/index.ts为errorIconColor为colorTextLightSolid白色errorTitleColor/errorDescriptionColor为colorError主题错误红errorIconBgColor/errorIconBorderColor为colorErrorerrorDotColor为colorError。即错误步骤呈现为红底白叉的圆形图标 红色标题/描述。另一个值得注意的细节是next-error规则[${stepsItemCls}${componentCls}-next-error ${componentCls}-item-title::after]: { background: token.colorError, },它让紧邻错误步骤的前一个已完成步骤的标题延伸线title 后的连接线也变为错误红直观提示出错的节点就在这里这正是 error 场景下前序步骤连接线同步标红的实现来源。4. 与 percent 进度结合时的行为从 index.tsx 可以看出当status process且配置了percent时当前步骤图标会被替换为圆形Progress进度环并叠加步骤图标。也就是说percent的进度环只作用于process状态的当前步骤error状态不渲染进度环直接展示错误图标避免错误与进度两种语义同时出现造成混淆若在错误态下想展示已完成部分的进度推荐做法是保留current不变把失败步骤单独用 StepItem 级statuserror标记其他步骤维持finish/process语义。四、实战组合错误状态 步骤切换 进度展示error状态在实际业务中几乎总是与步骤切换联动出现。仓库中的 step-next.tsx 演示了通过useState驱动current的切换模式clickable.tsx 演示了通过onChange让用户点击步骤直接跳转。将其与错误处理结合一个典型的分步提交 出错中断实现如下import React, { useState } from react; import { Button, Steps, message } from antd; const steps [ { title: 填写信息 }, { title: 上传附件 }, { title: 提交确认 }, ]; const App: React.FC () { const [current, setCurrent] useState(0); const [hasError, setHasError] useState(false); const next () { // 模拟第 2 步index1执行失败 if (current 1 Math.random() 0.5) { setHasError(true); message.error(上传失败请重试); return; } setHasError(false); setCurrent(current 1); }; const prev () { setHasError(false); setCurrent(current - 1); }; return ( Steps current{current} status{hasError ? error : process} onChange{setCurrent} items{steps.map((s, i) ({ title: s.title, status: i current hasError ? error : undefined, }))} / div style{{ marginTop: 24 }} {current steps.length - 1 ( Button typeprimary onClick{next}下一步/Button )} {current 0 Button style{{ margin: 0 8px }} onClick{prev}上一步/Button} /div / ); }; export default App;关键点步骤项级status: error精确标记失败步骤Steps 级status再兜底设置当前步骤当步骤失败时不要推进current用户可停留在出错步骤重试或回退若需要展示重试中的进度可再结合percent给当前process步骤渲染进度环参见 progress.tsx 的percent{60}写法。五、测试快照验证error 渲染结果的可信依据仓库为 Steps 提供了完整的测试覆盖components/steps/tests/其中 demo.test.ts 会对error.tsx等所有 demo 做渲染快照测试。从快照 demo.test.ts.snap 中可以看到error.tsx的实际 DOM 输出第一项Finished渲染为ant-steps-item ant-steps-item-finish ant-steps-next-error证实已完成步骤 连接线指向错误步骤第二项当前步骤渲染为ant-steps-item ant-steps-item-error ant-steps-item-active内部图标为anticon anticon-close ant-steps-error-icon即 CloseOutlined 叉号证实错误图标与激活态同时生效描述文本 This is a description 正常输出在ant-steps-item-description中。这套快照既是 error 状态渲染结果的权威证据也说明在升级 antd 版本后快照测试可自动拦截错误态样式/结构被意外改动的回归问题。六、小结error 状态的使用要点入口Steps 级statuserror作用于current指向的当前步骤StepItem 级statuserror可精确标记任意一步且优先级高于自动推导。视觉呈现错误步骤为红色背景 白色叉号CloseOutlined标题/描述变红前序步骤连接线同步标红next-error规则。语义边界percent进度环仅渲染于process状态错误态不会叠加进度环避免语义冲突。主题定制通过errorIconColor、errorTitleColor、errorDescriptionColor、errorIconBgColor、errorIconBorderColor、errorDotColor等 Design Token见 style/index.ts可整体调整错误态配色。最佳实践步骤失败时不推进current用错误态停留在失败步骤并配合onChange提供点击跳转与重试入口。相关源码与文档索引error.md 演示文档、error.tsx 示例、Steps 组件实现、Steps 样式与 Token、API 文档、demo 快照测试。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
