Vant Steps 步骤条组件完全指南状态机制、自定义样式与源码级实现解析【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vantSteps 是 Vant 移动端组件库中用于展示流程进度的步骤条组件它通过van-steps与van-step的父子组合将多步骤流程的「完成 / 进行中 / 待进行」三种状态可视化呈现。本文以 Vant 仓库中 Steps README 为核心骨架结合 Steps.tsx、Step.tsx 等源码实现系统讲解步骤条的安装注册、基础用法、状态判定原理、全部 API 参数以及主题定制方案读完即可在移动端项目中独立落地一套可交互、可定制的步骤流程。Steps 组件简介步骤条组件用于展示操作流程的各个阶段帮助用户明确「当前动作处于整个流程的哪个位置」。典型应用场景包括订单状态跟踪买家下单 → 商家接单 → 买家提货 → 交易完成、物流进度展示、多步表单引导等。组件由两部分组成Steps容器负责接收active等配置属性并通过依赖注入向下分发Step子项负责根据自身索引与active的关系渲染出「完成 / 进行中 / 待进行」三种不同视觉状态。两者的父子关系在源码层通过useChildren/useParent实现基于注入键STEPS_KEYStep组件如果脱离Steps单独使用会在非生产环境输出错误提示[Vant] Step must be a child component of Steps.见 Step.tsx。安装与注册组件支持全局注册通过 Vue 的app.use挂载Step与Steps需要分别注册import { createApp } from vue; import { Step, Steps } from vant; const app createApp(); app.use(Step); app.use(Steps);更多注册方式按需引入、自动按需引入等可参考 组件注册文档。在 index.ts 中可以看到Steps通过withInstall封装导出并声明了VanSteps全局组件类型因此模板中可直接使用van-steps/van-step标签同时获得完整的 TypeScript 类型提示declare module vue { export interface GlobalComponents { VanSteps: typeof Steps; } }基础用法通过active属性指定当前激活步骤的索引从 0 开始van-steps :activeactive van-stepStep1/van-step van-stepStep2/van-step van-stepStep3/van-step van-stepStep4/van-step /van-stepsimport { ref } from vue; export default { setup() { const active ref(1); return { active }; }, };当active 1时Step1 处于「完成」状态Step2 处于「进行中」状态Step3、Step4 处于「待进行」状态。三种状态的含义Step组件内部通过getStatus()方法判定每个子项的状态见 Step.tsxconst getStatus () { const active parentProps.active; if (index.value active) { return finish; // 已完成 } return index.value active ? process : waiting; // 进行中 / 待进行 };finish已完成索引小于active显示完成连接线和完成图标process进行中索引等于active标题高亮并使用激活色渲染waiting待进行索引大于active使用非激活色渲染。容器在渲染时会为每个van-step根节点追加对应的状态 class如van-step--finish、van-step--process、van-step--waiting便于样式区分。注意active虽然声明类型为number | string但判定时统一通过运算符转换为数字因此传入字符串数字如2同样有效。动态推进流程仓库 Demo 展示了如何用按钮推进步骤——点击「下一步」后active在 0~3 之间循环const nextStep () { active.value active.value % 4; };active是一个响应式 ref改变其值即可驱动整个步骤条状态流转无需手动操作 DOM。自定义样式通过active-icon、active-color、inactive-icon等属性可以替换激活图标、调整激活颜色、指定非激活图标van-steps :activeactive active-iconsuccess active-color#07c160 van-stepStep1/van-step van-stepStep2/van-step van-stepStep3/van-step van-stepStep4/van-step /van-steps上面的例子将激活图标换为success激活色换为微信绿#07c160。Demo 中还同时使用了inactive-iconarrow来给非激活步骤指定箭头图标。图标名取自 Vant 内置 图标库若配合自定义图标可通过icon-prefix属性修改图标的类名前缀默认van-icon。图标渲染的优先级从 Step.tsx 的renderCircle方法可以梳理出图标渲染的完整优先级进行中优先使用active-icon插槽否则渲染activeIcon属性指定的图标已完成仅当设置了finish-icon属性或提供了finish-icon插槽时才渲染完成图标优先插槽否则回退到下一步逻辑其余情况优先inactive-icon插槽其次inactiveIcon属性图标若都未提供则渲染一个纯 CSS 小圆点.van-step__circle圆点颜色由lineStyle决定——完成步骤使用激活色其余使用非激活色。这一优先级设计保证了「未配置时不显示图标、仅显示圆点」的默认外观同时给高度定制留足空间。竖向步骤条设置directionvertical即可切换为竖向布局常用于物流、时间线等纵向信息流场景van-steps directionvertical :active0 van-step h3【城市】物流状态1/h3 p2016-07-12 12:40/p /van-step van-step h3【城市】物流状态2/h3 p2016-07-11 10:00/p /van-step van-step h3【城市】物流状态3/h3 p2016-07-10 09:30/p /van-step /van-steps竖向模式下每个van-step的默认插槽可自由放置任意内容如标题、时间戳插槽内容会渲染在.van-step__title容器内。容器组件会依据direction给根节点追加van-steps--horizontal或van-steps--vertical的修饰类见 Steps.tsx样式层面对应不同的内边距布局见 index.less。API 参考Steps Props属性说明类型默认值active当前步骤number | string0direction步骤条方向可设为verticalstringhorizontalactive-color激活步骤颜色string#1989fainactive-color未激活步骤颜色string#969799active-icon激活步骤图标名称stringcheckedinactive-icon未激活步骤图标名称string-finish-icon已完成步骤图标名称string-icon-prefix图标类名前缀stringvan-icon对应的属性定义位于 Steps.tsx其中active使用makeNumericProp(0)声明同时接受数字与字符串direction使用makeStringPropStepsDirection(horizontal)声明类型限定为horizontal | vertical。需要说明的是active-color/inactive-color在源码中默认值为undefined文档表格中标注的默认色#1989fa、#969799实际来源于 CSS 变量的最终取值见下文 Theming 章节组件内部在使用activeColor/inactiveColor前会先回退到对应 CSS 变量。Step Slots名称说明default步骤内容active-icon自定义激活图标inactive-icon自定义未激活图标finish-icon自定义完成图标插槽的渲染优先级与「图标渲染优先级」一节完全一致插槽优先级高于同名属性。仓库 测试用例 分别验证了三个图标插槽active-icon、inactive-icon、finish-icon的渲染结果可作为自定义插槽写法的参考Steps active{0} Step v-slots{{ active-icon: () Custom Active Icon }}B/Step Step v-slots{{ inactive-icon: () Custom Inactive Icon }}A/Step /StepsSteps Events事件名说明回调参数click-step点击步骤条标题或图标时触发index: number事件从Step侧向上冒泡Step在标题.van-step__title和图标容器.van-step__circle-container上都绑定了点击处理调用父级通过依赖注入提供的onClickStep(index)最终由Steps统一对外emit(clickStep, index)见 Steps.tsx。注意点击子项根节点.van-step本身并不会触发事件测试用例中专门验证了这一点——只有点击.van-step__title或.van-step__circle-container才会派发click-step见 index.spec.tsx。典型用法结合click-step事件实现「点击步骤跳转」例如在点击时同步更新activevan-steps :activeactive click-steponClickStep van-stepStep1/van-step van-stepStep2/van-step van-stepStep3/van-step /van-stepsconst onClickStep (index) { active.value index; };类型定义组件导出了以下类型方便在 TypeScript 项目中获取完整的属性与方向类型import type { StepsProps, StepsDirection } from vant;其中StepsDirection即horizontal | vertical的联合类型。此外StepsThemeVars见 types.ts可用于配合 CSS 变量做主题类型约束。主题定制CSS Variables组件提供了如下 CSS 变量可在任意层级覆盖以定制样式推荐配合 ConfigProvider 组件 统一管理主题变量名默认值说明--van-step-text-colorvar(--van-text-color-2)步骤文字颜色--van-step-active-colorvar(--van-primary-color)激活步骤颜色--van-step-process-text-colorvar(--van-text-color)进行中步骤文字颜色--van-step-font-sizevar(--van-font-size-md)步骤字号--van-step-line-colorvar(--van-border-color)步骤连接线颜色--van-step-finish-line-colorvar(--van-primary-color)完成步骤连接线颜色--van-step-finish-text-colorvar(--van-text-color)完成步骤文字颜色--van-step-icon-size12px图标尺寸--van-step-circle-size5px圆点尺寸--van-step-circle-colorvar(--van-gray-6)圆点颜色--van-step-horizontal-title-font-sizevar(--van-font-size-sm)横向模式标题字号--van-steps-backgroundvar(--van-background-2)步骤条背景色可以看到默认值大量复用了 Vant 的设计令牌--van-primary-color、--van-text-color-2、--van-border-color等因此当全局主题色调整后步骤条的激活色、完成线颜色会自动跟随变化。--van-steps-background在 index.less 中声明于:root层级其余变量则由组件类选择器内部定义。源码实现要点回顾父子通信Steps通过useChildren(STEPS_KEY)建立注入关系Step通过useParent(STEPS_KEY)获取父级 props 与onClickStep回调无需逐层透传属性见 Steps.tsx。状态机渲染getStatus()以「索引与 active 比较」为唯一判定依据派生出的lineStyle、titleStyle、图标与圆点均随状态响应式更新见 Step.tsx。样式分区容器样式横向 flex 排布、竖向左侧留白与子项样式状态修饰类、圆点、连接线分别定义在steps与step两个命名空间下全部基于 BEM 规范生成类名。测试保障index.spec.tsx 覆盖了图标插槽、click-step事件、inactive-color、inactive-icon、finish-icon、icon-prefix六类关键行为同时 demo.spec.ts 对 Demo 页面做了快照测试保证组件行为与官方示例始终一致。综上Vant Steps 以「容器注入配置 子项自判状态」的简洁架构支撑了从基础进度展示到高度定制视觉的完整能力。在实际业务中只需维护好active这一个响应式值再配合click-step事件与 CSS 变量即可快速构建出交互流畅、风格统一的步骤流程。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Vant Steps 步骤条组件完全指南状态机制、自定义样式与源码级实现解析【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vantSteps 是 Vant 移动端组件库中用于展示流程进度的步骤条组件它通过van-steps与van-step的父子组合将多步骤流程的「完成 / 进行中 / 待进行」三种状态可视化呈现。本文以 Vant 仓库中 Steps README 为核心骨架结合 Steps.tsx、Step.tsx 等源码实现系统讲解步骤条的安装注册、基础用法、状态判定原理、全部 API 参数以及主题定制方案读完即可在移动端项目中独立落地一套可交互、可定制的步骤流程。Steps 组件简介步骤条组件用于展示操作流程的各个阶段帮助用户明确「当前动作处于整个流程的哪个位置」。典型应用场景包括订单状态跟踪买家下单 → 商家接单 → 买家提货 → 交易完成、物流进度展示、多步表单引导等。组件由两部分组成Steps容器负责接收active等配置属性并通过依赖注入向下分发Step子项负责根据自身索引与active的关系渲染出「完成 / 进行中 / 待进行」三种不同视觉状态。两者的父子关系在源码层通过useChildren/useParent实现基于注入键STEPS_KEYStep组件如果脱离Steps单独使用会在非生产环境输出错误提示[Vant] Step must be a child component of Steps.见 Step.tsx。安装与注册组件支持全局注册通过 Vue 的app.use挂载Step与Steps需要分别注册import { createApp } from vue; import { Step, Steps } from vant; const app createApp(); app.use(Step); app.use(Steps);更多注册方式按需引入、自动按需引入等可参考 组件注册文档。在 index.ts 中可以看到Steps通过withInstall封装导出并声明了VanSteps全局组件类型因此模板中可直接使用van-steps/van-step标签同时获得完整的 TypeScript 类型提示declare module vue { export interface GlobalComponents { VanSteps: typeof Steps; } }基础用法通过active属性指定当前激活步骤的索引从 0 开始van-steps :activeactive van-stepStep1/van-step van-stepStep2/van-step van-stepStep3/van-step van-stepStep4/van-step /van-stepsimport { ref } from vue; export default { setup() { const active ref(1); return { active }; }, };当active 1时Step1 处于「完成」状态Step2 处于「进行中」状态Step3、Step4 处于「待进行」状态。三种状态的含义Step组件内部通过getStatus()方法判定每个子项的状态见 Step.tsxconst getStatus () { const active parentProps.active; if (index.value active) { return finish; // 已完成 } return index.value active ? process : waiting; // 进行中 / 待进行 };finish已完成索引小于active显示完成连接线和完成图标process进行中索引等于active标题高亮并使用激活色渲染waiting待进行索引大于active使用非激活色渲染。容器在渲染时会为每个van-step根节点追加对应的状态 class如van-step--finish、van-step--process、van-step--waiting便于样式区分。注意active虽然声明类型为number | string但判定时统一通过运算符转换为数字因此传入字符串数字如2同样有效。动态推进流程仓库 Demo 展示了如何用按钮推进步骤——点击「下一步」后active在 0~3 之间循环const nextStep () { active.value active.value % 4; };active是一个响应式 ref改变其值即可驱动整个步骤条状态流转无需手动操作 DOM。自定义样式通过active-icon、active-color、inactive-icon等属性可以替换激活图标、调整激活颜色、指定非激活图标van-steps :activeactive active-iconsuccess active-color#07c160 van-stepStep1/van-step van-stepStep2/van-step van-stepStep3/van-step van-stepStep4/van-step /van-steps上面的例子将激活图标换为success激活色换为微信绿#07c160。Demo 中还同时使用了inactive-iconarrow来给非激活步骤指定箭头图标。图标名取自 Vant 内置 图标库若配合自定义图标可通过icon-prefix属性修改图标的类名前缀默认van-icon。图标渲染的优先级从 Step.tsx 的renderCircle方法可以梳理出图标渲染的完整优先级进行中优先使用active-icon插槽否则渲染activeIcon属性指定的图标已完成仅当设置了finish-icon属性或提供了finish-icon插槽时才渲染完成图标优先插槽否则回退到下一步逻辑其余情况优先inactive-icon插槽其次inactiveIcon属性图标若都未提供则渲染一个纯 CSS 小圆点.van-step__circle圆点颜色由lineStyle决定——完成步骤使用激活色其余使用非激活色。这一优先级设计保证了「未配置时不显示图标、仅显示圆点」的默认外观同时给高度定制留足空间。竖向步骤条设置directionvertical即可切换为竖向布局常用于物流、时间线等纵向信息流场景van-steps directionvertical :active0 van-step h3【城市】物流状态1/h3 p2016-07-12 12:40/p /van-step van-step h3【城市】物流状态2/h3 p2016-07-11 10:00/p /van-step van-step h3【城市】物流状态3/h3 p2016-07-10 09:30/p /van-step /van-steps竖向模式下每个van-step的默认插槽可自由放置任意内容如标题、时间戳插槽内容会渲染在.van-step__title容器内。容器组件会依据direction给根节点追加van-steps--horizontal或van-steps--vertical的修饰类见 Steps.tsx样式层面对应不同的内边距布局见 index.less。API 参考Steps Props属性说明类型默认值active当前步骤number | string0direction步骤条方向可设为verticalstringhorizontalactive-color激活步骤颜色string#1989fainactive-color未激活步骤颜色string#969799active-icon激活步骤图标名称stringcheckedinactive-icon未激活步骤图标名称string-finish-icon已完成步骤图标名称string-icon-prefix图标类名前缀stringvan-icon对应的属性定义位于 Steps.tsx其中active使用makeNumericProp(0)声明同时接受数字与字符串direction使用makeStringPropStepsDirection(horizontal)声明类型限定为horizontal | vertical。需要说明的是active-color/inactive-color在源码中默认值为undefined文档表格中标注的默认色#1989fa、#969799实际来源于 CSS 变量的最终取值见下文 Theming 章节组件内部在使用activeColor/inactiveColor前会先回退到对应 CSS 变量。Step Slots名称说明default步骤内容active-icon自定义激活图标inactive-icon自定义未激活图标finish-icon自定义完成图标插槽的渲染优先级与「图标渲染优先级」一节完全一致插槽优先级高于同名属性。仓库 测试用例 分别验证了三个图标插槽active-icon、inactive-icon、finish-icon的渲染结果可作为自定义插槽写法的参考Steps active{0} Step v-slots{{ active-icon: () Custom Active Icon }}B/Step Step v-slots{{ inactive-icon: () Custom Inactive Icon }}A/Step /StepsSteps Events事件名说明回调参数click-step点击步骤条标题或图标时触发index: number事件从Step侧向上冒泡Step在标题.van-step__title和图标容器.van-step__circle-container上都绑定了点击处理调用父级通过依赖注入提供的onClickStep(index)最终由Steps统一对外emit(clickStep, index)见 Steps.tsx。注意点击子项根节点.van-step本身并不会触发事件测试用例中专门验证了这一点——只有点击.van-step__title或.van-step__circle-container才会派发click-step见 index.spec.tsx。典型用法结合click-step事件实现「点击步骤跳转」例如在点击时同步更新activevan-steps :activeactive click-steponClickStep van-stepStep1/van-step van-stepStep2/van-step van-stepStep3/van-step /van-stepsconst onClickStep (index) { active.value index; };类型定义组件导出了以下类型方便在 TypeScript 项目中获取完整的属性与方向类型import type { StepsProps, StepsDirection } from vant;其中StepsDirection即horizontal | vertical的联合类型。此外StepsThemeVars见 types.ts可用于配合 CSS 变量做主题类型约束。主题定制CSS Variables组件提供了如下 CSS 变量可在任意层级覆盖以定制样式推荐配合 ConfigProvider 组件 统一管理主题变量名默认值说明--van-step-text-colorvar(--van-text-color-2)步骤文字颜色--van-step-active-colorvar(--van-primary-color)激活步骤颜色--van-step-process-text-colorvar(--van-text-color)进行中步骤文字颜色--van-step-font-sizevar(--van-font-size-md)步骤字号--van-step-line-colorvar(--van-border-color)步骤连接线颜色--van-step-finish-line-colorvar(--van-primary-color)完成步骤连接线颜色--van-step-finish-text-colorvar(--van-text-color)完成步骤文字颜色--van-step-icon-size12px图标尺寸--van-step-circle-size5px圆点尺寸--van-step-circle-colorvar(--van-gray-6)圆点颜色--van-step-horizontal-title-font-sizevar(--van-font-size-sm)横向模式标题字号--van-steps-backgroundvar(--van-background-2)步骤条背景色可以看到默认值大量复用了 Vant 的设计令牌--van-primary-color、--van-text-color-2、--van-border-color等因此当全局主题色调整后步骤条的激活色、完成线颜色会自动跟随变化。--van-steps-background在 index.less 中声明于:root层级其余变量则由组件类选择器内部定义。源码实现要点回顾父子通信Steps通过useChildren(STEPS_KEY)建立注入关系Step通过useParent(STEPS_KEY)获取父级 props 与onClickStep回调无需逐层透传属性见 Steps.tsx。状态机渲染getStatus()以「索引与 active 比较」为唯一判定依据派生出的lineStyle、titleStyle、图标与圆点均随状态响应式更新见 Step.tsx。样式分区容器样式横向 flex 排布、竖向左侧留白与子项样式状态修饰类、圆点、连接线分别定义在steps与step两个命名空间下全部基于 BEM 规范生成类名。测试保障index.spec.tsx 覆盖了图标插槽、click-step事件、inactive-color、inactive-icon、finish-icon、icon-prefix六类关键行为同时 demo.spec.ts 对 Demo 页面做了快照测试保证组件行为与官方示例始终一致。综上Vant Steps 以「容器注入配置 子项自判状态」的简洁架构支撑了从基础进度展示到高度定制视觉的完整能力。在实际业务中只需维护好active这一个响应式值再配合click-step事件与 CSS 变量即可快速构建出交互流畅、风格统一的步骤流程。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
