amis Steps 步骤条组件完全指南用 JSON 配置实现多步骤流程展示与状态控制【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amisSteps步骤条是 amis 前端低代码框架中用于展示分步流程的展示型组件典型应用场景包括表单多步骤引导、订单流转进度、任务状态跟踪等。本指南以官方文档 docs/zh-CN/components/steps.md 为主线结合 渲染器源码 与 基础组件源码 的底层实现系统讲解 Steps 的配置项、状态计算规则、数据映射/接口映射机制与动态数据加载方案读完即可在自己的 amis 页面中直接落地使用。组件定位与工作原理Steps 是一个纯展示型渲染器其注册类型为steps。它接收一个步骤数组steps与当前进度value由渲染层自动为每一步推导出wait等待、process进行中、finish已完成、error出错四种状态并渲染出图标、标题、子标题与描述信息。从源码结构看Steps 的完整链路分为两层渲染器层packages/amis/src/renderers/Steps.tsx 中通过Renderer({type: steps})注册负责 Schema 解析、数据域取值与远程数据加载UI 层packages/amis-ui/src/components/Steps.tsx 中的Steps组件负责最终 DOM 渲染与状态图标计算并导出StepStatus枚举wait | process | finish | error。样式定义位于 packages/amis-ui/scss/components/_steps.scss渲染器层还通过CustomStyle支持按is-finish、is-process、is-wait、is-error等状态 class 定制标题、子标题、描述与图标的主题样式。基本用法在任意页面容器中声明一个type: steps节点通过value指定当前处于第几步从 0 开始计数通过steps数组配置每一步的标题、子标题与描述{ type: page, body: [ { type: steps, value: 1, steps: [ { title: First, subTitle: this is subTitle, description: this is description }, { title: Second }, { title: Last } ] } ] }上述配置中value: 1表示第 2 步处于进行中状态。底层实现上UI 组件的getStepStatus会先按索引计算基础状态i current的步骤为finish并自动补上check对勾图标i current的步骤为process其余为wait见 packages/amis-ui/src/components/Steps.tsx。设置步骤状态当希望当前步骤呈现特定状态而非默认的 process时可通过status配置例如将当前步骤标记为错误{ type: page, body: { type: steps, value: 1, status: error, steps: [ { title: First }, { title: Second, subTitle: this is subTitle, description: this is description }, { title: Last } ] } }status的取值类型为StepStatus即wait | process | finish | error之一。从源码看字符串形式的status只作用于当前步骤UI 层在i current时优先使用step.status || status当结果为error时自动补上close图标packages/amis-ui/src/components/Steps.tsx。指定步骤条方向mode用于控制步骤条的排布方向支持horizontal水平默认、vertical竖直与simple简单三种模式{ type: page, body: { type: steps, mode: vertical, value: 1, steps: [ { title: First, subTitle: this is subTitle, description: this is description }, { title: Second, subTitle: this is subTitle, description: this is description }, { title: Last, subTitle: this is subTitle, description: this is description } ] } }垂直模式适合步骤较多、文案较长的场景。对应 DOM 上UI 层会依据mode生成Steps--horizontal/Steps--vertical/Steps--simple等 classpackages/amis-ui/src/components/Steps.tsx样式在 _steps.scss 中按模式分别排版。指定标签放置位置labelPlacement用于控制标题/描述的摆放位置默认horizontal文字在图标右侧可切换为vertical文字在图标下方{ type: page, body: { type: steps, value: 1, labelPlacement: vertical, steps: [ { title: First, subTitle: this is subTitle, description: this is description }, { title: Second, subTitle: this is subTitle, description: this is description }, { title: Last, subTitle: this is subTitle, description: this is description } ] } }需要注意一个实现细节源码注释与类名拼接逻辑表明纵向模式mode: vertical下暂不支持labelPlacement属性同时当progressDot开启或labelPlacement vertical且非纵向模式时会拼接Steps--Placement-vertical类名以调整图文布局packages/amis-ui/src/components/Steps.tsx。点状步骤条progressDot: true可将图标区域渲染为点状指示器常用于简洁的进度展示{ type: page, body: { type: steps, value: 1, progressDot: true, steps: [ { title: First, subTitle: this is subTitle, description: this is description }, { title: Second, subTitle: this is subTitle, description: this is description }, { title: Last, subTitle: this is subTitle, description: this is description } ] } }开启后UI 层不再渲染数字/图标节点而是渲染StepsItem-containerProgressDot圆点并追加Steps--ProgressDot、StepsItem-ProgressDot类名packages/amis-ui/src/components/Steps.tsx。简单模式mode: simple提供仅保留箭头连接的极简样式适合流程感明确、无需强状态区分的场景{ type: page, body: [ { type: steps, value: 1, mode: simple, steps: [ { title: First }, { title: Second }, { title: Last } ] } ] }简单模式下除最后一个步骤外的每个步骤右侧都会渲染StepsItem-icon-line右箭头图标作为连接符packages/amis-ui/src/components/Steps.tsx。数据映射Steps 通过name关联数据域中的变量来决定当前处于第几步其余配置则支持用模板语法${xxx}引用上下文变量。注意name只负责关联当前步骤位置不做模板替换{ type: page, data: { step: 1, status: error, secondTitle: Second }, body: [ { type: steps, name: step, status: ${status}, steps: [ { title: First, subTitle: this is subTitle, description: this is description }, { title: ${secondTitle} }, { title: Last } ] } ] }其底层逻辑在渲染器 Steps.tsx 中name的值最终通过getPropValue与resolveVariable从数据域解析得到当前步骤值status若为纯变量表达式isPureVariable判断则通过resolveVariableAndFilter求值title/subTitle/description为字符串时统一经filter做模板插值${secondTitle}会被替换为 Second。接口映射当页面通过initApi拉取数据后接口返回的数据同样进入当前数据域Steps 的取值方式与数据映射完全一致{ type: page, initApi: /api/mock2/steps/get, body: [ { type: steps, name: step, status: ${status}, steps: [ { title: First, subTitle: this is subTitle, description: this is description }, { title: Secord }, { title: Last } ] } ] }即接口返回的数据结构中需要包含step、status等字段位于data内符合 amis 接口规范步骤条就会自动读取并驱动当前进度与状态。动态数据远程拉取除了从数据域读取静态变量source还支持配置 API 来动态返回步骤选项组。远程拉取在 Form 中配置source指向一个接口{ type: page, body: { type: form, body: [ { type: steps, name: steps, source: /api/mock2/steps/steps } ] } }接口返回的数据结构除需满足 amis 接口基本结构status/msg/data包裹外必须使用steps作为选项组的 key示例{ status: 0, msg: , data: { steps: [ { title: First, subTitle: this is sub title, value: first }, { title: Secord, description: this is description, value: secord }, { title: Last, value: last } ], value: secord, status: error } }仓库中 mock/cfc/mock/steps/steps.json 正是与该约定完全一致的模拟数据文件可直接作为联调参考。注意data中还携带了value当前步骤值与status状态二者同样会被合并进数据域供组件消费。从源码看远程加载能力由渲染器层的withRemoteConfig()高阶组件实现packages/amis/src/renderers/Steps.tsx加载结果会作为config合并进组件 props加载期间通过loading、deferLoad、updateConfig等参数支持异步刷新。数据域变量配置1.9.1 及以上版本source也可以直接指向数据域中的数组变量此处不可用模板插值获取数组直接用${steps}引用整个变量{ type: page, data: { steps: [ { title: First, subTitle: this is subTitle, description: this is description }, { title: Second }, { title: Last } ] }, body: [ { type: steps, name: step, source: ${steps} } ] }渲染器层通过resolveVariableAndFilter(source, data, | raw)解析source只有当结果确实是数组时才作为步骤数据源覆盖steps配置packages/amis/src/renderers/Steps.tsx。Form 中静态展示Steps 可作为 Form 内的静态展示项使用source从数据域取步骤数组name关联当前步骤值{ type: page, body: { type: form, initApi: /api/mock2/steps/steps, body: [ { type: steps, source: ${steps}, name: current } ] } }自定义不同步骤以及状态当每一步都有独立value时status可以配置为一个以步骤 value 为 key、以 StepStatus 为 value的对象从而为每个步骤单独指定状态。同时value也支持字符串形式的步骤值{ type: page, body: { type: steps, value: b, status: { a: finish, b: error, c: wait }, steps: [ { title: First, value: a }, { title: Second, subTitle: this is subTitle, description: this is description, value: b }, { title: Third, value: c } ] } }这里的执行顺序值得说明渲染器层首先在stepsRow中查找step.value resolveValue即b的索引作为currentValue找不到时才把value当作数字索引使用packages/amis/src/renderers/Steps.tsx随后 UI 层的getStepStatus在status为对象时直接以step.value作为 key 从status对象中取出对应状态packages/amis-ui/src/components/Steps.tsx。因此状态按 value 精确匹配、图标按索引推导是两者协作的结果。属性表Steps 属性属性名类型默认值说明typestringsteps指定为步骤条渲染器stepsArraystep[]数组配置步骤信息sourceAPI 或 数据映射选项组源可通过数据映射获取当前数据域变量、或者配置 API 对象namestring关联上下文变量valuestring|number-设置默认值注意不支持表达式statusStepStatus | {[propName: string]: stepStatus;}-状态classNamestring-自定义类名modehorizontal|vertical|simplehorizontal指定步骤条模式。目前支持水平horizontal、竖直vertical和简单simple模式labelPlacementhorizontal|verticalhorizontal指定标签放置位置默认水平放图标右侧可选 (vertical) 放图标下方progressDotbooleanfalse点状步骤条step属性名类型默认值说明titlestring| SchemaNode标题subTitlestring| SchemaNode子标题descriptionstring| SchemaNode详细描述iconstringicon 名支持 fontawesome v4 或使用 urlvaluestringvalueclassNamestring自定义类名说明title、subTitle、description支持字符串模板插值也支持传入 SchemaNode 进行嵌套渲染icon支持字体图标名或 URLvalue用于自定义状态对象匹配与当前步骤定位字符串形式。StepStatuswait|process|finish|error小结本文从官方文档的 9 个典型示例出发完整梳理了 amis Steps 组件的能力边界通过value/name控制进度、status控制状态、mode/labelPlacement/progressDot控制外观、source实现动态步骤数据。同时结合 渲染器源码 与 UI 组件源码 还原了索引推导基础状态 value 精确匹配自定义状态的双层状态计算机制并给出了 mock 数据文件 作为接口联调参考。无论是要快速搭建表单分步引导还是对接后端动态渲染复杂流程Steps 都是一份开箱即用的配置化方案。【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考