企业官网建设流程全解析

• 前端
• UI组件
• 移动开发
• 小程序

导读

本文是 wot-design-uni 组件库中 Steps 步骤条（含 Step 步骤项）组件的技术实战指南。Steps 组件用于引导用户按照既定流程完成任务，或向用户直观展示多阶段流程的当前进度状态，典型场景包括注册引导、订单流转、表单分步填写等。读完本文，你将掌握wd-steps/wd-step的全部属性与插槽用法、水平/竖向/点状三种布局形态、状态定制与国际化默认文案机制，并通过源码分析理解父子组件通信与进度推导的底层实现。

一、组件定位与基本用法

Steps 步骤条由容器组件wd-steps和步骤项组件wd-step组合使用。进度由active属性控制，它是number 类型，表示当前激活步骤的下标（从 0 开始），默认值为0。

<wd-steps :active="active"> <wd-step /> <wd-step /> <wd-step /> </wd-steps>

const active = ref<number>(0) function nextStep() { active.value = active.value + 1 }

active会随着业务推进动态变化，例如配合按钮事件自增，即可实现"下一步"的进度驱动。组件本身不内置跳转逻辑，进度完全由业务侧控制，这种设计保证了灵活性与可定制性。

该组件同样适用于微信小程序、App、H5 等多端场景，因为其实现仅依赖 uni-app 的view/text等基础节点，具体可参见 示例页面，该页面完整复现了本文介绍的全部用法。

二、布局形态：水平居中、间距与宽度分配

水平居中

设置align-center即可让横向步骤条在容器内水平居中，该属性只对横向步骤条有效：

<wd-steps :active="0" align-center> <wd-step /> <wd-step /> <wd-step /> </wd-steps>

步骤间距 space

space用于控制步骤条之间的间距，类型为string，默认不设置时自动计算。从源码（wd-step.vue）可以看到间距的计算逻辑：

const rootStyle = computed(() => { const style: CSSProperties = {} if (steps) { const { vertical, space } = steps.props if (vertical) { if (isDef(space)) { style['height'] = space // 竖向：space 决定每个步骤的高度 } } else { style['width'] = space || 100 / steps.children.length + '%' // 横向：默认按子项数均分宽度 } } return `${objToStyle(style)}${props.customStyle}` })

这段实现揭示了两个关键细节：

• 横向布局下，未设置space时，每个步骤项的宽度按100 / 步骤数 + '%'自动均分，保证步骤条铺满容器宽度；
• 竖向布局下，space作为每个步骤的高度传入，可用于控制纵向间距。

三、设置标题与描述信息

通过title和description属性可分别设置步骤的标题与描述：

<wd-steps :active="active" align-center> <wd-step title="Step 1" description="Register an account" /> <wd-step title="Step 2" description="Login and bind phone number" /> <wd-step title="Step 3" description="Complete personal information" /> </wd-steps> <wd-button size="small" @click="nextStep">Next Step</wd-button>

const active = ref<number>(0) function nextStep() { active.value = active.value + 1 }

两点使用细节值得注意：

1. 不设置标题时使用默认文案。默认文案并非硬编码在组件中，而是来自国际化语言包。在 wd-step.vue 中，getCurrentTitle通过useTranslate('steps')按当前状态取对应文案，例如中文语言包（zh-CN.ts）定义了：wait: '未开始'、finished: '已完成'、process: '进行中'、failed: '失败'；英文语言包（en-US.ts）则提供Not Started / Expired / In Progress / Failed等对应文案。这意味着组件默认文案会跟随 Locale 配置自动切换，详见仓库中的 locale 配置文档。
2. 当只有标题而没有描述时，标题字号会缩小 2 号。其样式依据在 index.scss 中，标题默认字号较小，只有存在描述（is-description）时才使用完整字号。

四、自定义图标：icon 属性与插槽

通过 icon 属性指定图标

传入图标名称即可替换默认的数字图标：

<wd-steps :active="1" align-center> <wd-step icon="invite" /> <wd-step icon="link" /> <wd-step icon="clock" /> </wd-steps>

图标名称取自 wot-design-uni 内置图标库（对应wd-icon组件）。在 wd-step.vue 中，图标渲染优先级为：点状圆点 > icon 插槽 > icon 属性 > 默认数字/状态图标。即当未设置任何图标时，完成态自动渲染对勾（check-bold）、错误态渲染叉号（close-bold）、其余状态渲染步骤序号数字。

通过 icon 插槽自定义

:::tip 破坏性更新提醒（版本 1.2.10） 在1.2.10版本中，step组件废弃了title-slot、icon-slot、description-slot三个控制插槽使用的布尔字段，新增支持直接使用title、icon、description插槽，同时废弃了default插槽。 :::

因此从1.2.10起，使用插槽自定义图标无需再设置icon-slot（该字段已从 types.ts 的 props 定义中移除），直接书写插槽内容即可：

<wd-steps :active="1" align-center> <wd-step> <template #icon>🎉</template> </wd-step> <wd-step icon="link" /> <wd-step icon="clock" /> </wd-steps>

源码中通过$slots.icon判断插槽是否被使用（见 wd-step.vue），实现了"有插槽走插槽、无插槽走属性"的自动降级逻辑。

五、竖向步骤条与点状步骤条

竖向步骤条

设置vertical属性即可切换为纵向排列：

<wd-steps :active="1" vertical> <wd-step description="Register an account" /> <wd-step description="Login and bind phone number" /> <wd-step description="Complete personal information" /> </wd-steps>

竖向布局下，步骤头部（图标与连接线）固定在左侧，内容区域右移并带有底部留白（index.scss 中.is-vertical相关样式），连接线由横向的水平线变为纵向的 1px 竖线。

点状步骤条

在竖向的基础上叠加dot属性，可将默认的圆形数字图标切换为小圆点：

<wd-steps :active="1" vertical dot> <wd-step description="Register an account" /> <wd-step description="Login and bind phone number" /> <wd-step description="Complete personal information" /> </wd-steps>

点状样式在 index.scss 中定义：图标尺寸收窄为圆点大小（默认7px，可经 CSS 变量--wot-steps-dot-size调整），并去除边框与背景。进行中的点状步骤还会渲染一圈半透明光晕（::after伪元素，见is-process状态样式），用于强调当前进度位置。

六、状态定制：finished / process / error

通过status属性可手动指定单个步骤的状态，支持'finished'（完成）、'process'（进行中）、'error'（失败）三种取值：

<wd-steps :active="1" align-center> <wd-step title="Bind Phone" status="error" /> <wd-step title="Rebind Phone" /> <wd-step title="Step 3" /> </wd-steps>

状态推导的源码逻辑

在 wd-step.vue 中，getCurrentStatus遵循"显式优先、自动兜底"的原则：

function getCurrentStatus(index: number) { if (props.status) { return props.status // 1. 显式设置的 status 优先级最高 } if (steps) { const { active } = steps.props if (Number(active) > index) { return 'finished' // 2. 下标小于 active：已完成 } else if (Number(active) === index) { return 'process' // 3. 下标等于 active：进行中 } else { return 'wait' // 4. 下标大于 active：等待 } } return 'wait' }

也就是说，只有未显式设置status的步骤项，才会根据active自动推导状态。三种状态分别对应不同的视觉表现（index.scss）：

• finished（完成态）：标题与图标边框变为主题色，默认图标替换为对勾；
• process（进行态）：图标背景填充主题色并反白显示，点状模式附带光晕；
• error（错误态）：标题与图标变为危险色，默认图标替换为叉号。

此外，处于error状态时默认标题文案取语言包中的failed（如中文"失败"），见getCurrentTitle的映射逻辑。

七、完整 API 参考

Steps Attributes（步骤条容器）

以上属性定义可在 wd-steps/types.ts 中查到，所有属性均继承自baseProps。

Step Attributes（步骤项）

status的类型约束在 wd-step/types.ts 中定义为StepStatus = 'finished' | 'process' | 'error'。

Step Slot（步骤项插槽）

从1.2.10起三个插槽均可直接使用，无需配合废弃的*-slot布尔字段；同时default插槽已废弃，请按具名插槽组织内容。

外部样式类

custom-class与custom-style均来自baseProps（定义于 common/props.ts），用于覆盖根节点类名与内联样式。在 wd-steps.vue 中，容器根节点会将customClass拼入wd-steps类名；wd-step同样将customStyle追加到计算后的rootStyle中。

八、样式主题定制与暗黑模式

步骤条的核心视觉变量定义在 variable.scss，全部以 CSS 变量形式暴露，可直接覆盖以定制主题：

例如通过:root { --wot-steps-finished-color: #07c160; }即可将完成态统一改为绿色。在暗黑模式下，wd-step/index.scss 通过.wot-theme-dark选择器对图标背景、连接线、圆点、文字颜色等做了专门的暗色适配，因此组件开箱即支持仓库的暗黑模式体系。

九、源码原理剖析：父子组件如何协同工作

1. 父子通信：provide / inject 注入

wd-steps与wd-step是一对典型的"容器 + 子项"组件。容器通过 useChildren 在STEPS_KEY（定义于 wd-steps/types.ts）上注入自己的props与子项注册能力：

// wd-steps.vue 核心逻辑 const props = defineProps(stepsProps) const { linkChildren } = useChildren(STEPS_KEY) linkChildren({ props })

每个wd-step通过 useParent 注入父级上下文，拿到steps.props、steps.children以及自己在兄弟节点中的index，并在卸载时自动注销。子项注册后会按虚拟 DOM 顺序排序（sortChildren），保证index与渲染顺序一致——这正是active下标能正确对应步骤位置的基础。

2. 连接线的渲染边界

步骤之间的连接线（.wd-step__line）只在非末尾步骤渲染，源码中通过v-if="index < childrenLength - 1"控制（wd-step.vue），因此最后一个步骤项后面不会出现多余的线条。

3. 测试覆盖

仓库在 wd-steps.test.ts 中对组件行为做了系统验证，覆盖了：基础渲染（根节点含wd-steps类）、竖向布局（is-vertical类）、居中对齐、点状样式、customClass/customStyle透传，以及多步骤场景下子项数量、标题与描述的挂载与active属性传递。这些测试可作为理解组件契约与回归保障的参考。

十、常见用法总结

至此，从属性使用到状态推导、从插槽升级到源码实现，Steps 步骤条的完整技术图景已经清晰。更多组合用法可对照 组件示例页 与 中文文档 实践验证。

• 前端
• UI组件
• 移动开发
• 小程序