不能用progress组件替代步骤条,因其仅为数值驱动的线性加载指示器,缺乏步骤语义、节点点击、状态切换及多端对齐能力;强行使用会导致线条错位、文字截断、iOS渲染异常,且无法标记“审核中”等阶段状态、响应点击或控制高亮节点。

uni-app 没有内置的 uni-steps 官方组件,所谓“步骤条”必须靠手写或引入第三方插件实现;直接用 uni-progress 或 progress 组件是错的,它只适合线性加载进度,不支持阶段语义、节点点击、状态切换和多端对齐。
为什么不能用 progress 组件替代步骤条
progress 是纯数值驱动的线性进度指示器,它没有“步骤”概念:无法标记第 2 步是“审核中”、第 3 步是“失败”,也不能让每个节点可点击、带图标、显示时间或自定义文案。在小程序真机上强行套用,常出现线条错位、文字截断、iOS WebView 渲染异常等问题。
- 错误现象:
progress的percent值设为 66,但用户需要看到“已提交 → 审核中 → 待发放”三段独立状态 - 兼容性风险:微信小程序基础库低于 2.10.0 时,
progress的show-info在某些机型上不显示文字 - 语义缺失:无法响应
@click到某一步,也不能通过active控制当前高亮节点
手写轻量级步骤条(view + flex + class 控制)
这是最稳定、多端兼容性最好的方案,不依赖 Canvas/SVG,避免 iOS 和安卓低版本 flex 布局塌陷问题。
- 外层用
,设display: flex; justify-content: space-between - 每个步骤项用
包裹图标 + 文字,通过:class动态绑定active/finish/disabled类 - 步骤连线不用伪元素
::before(安卓低版本不兼容),改用绝对定位的,宽度固定为100%,top: 24rpx居中对齐图标 - 关键逻辑靠
current变量控制:例如steps = ['填写', '提交', '审核', '完成'],current = 2表示停在“审核”步(索引从 0 开始),则前两步加finish类,第 2 步加active类,后续加disabled类
示例片段:
<view class="steps-container"><view v-for="(step, i) in steps" :key="i" class="step-item"><view :class="['step-icon', i < current ? 'finish' : i === current ? 'active' : 'disabled']"><text v-if="i < current">✓</text><text v-else-if="i === current">●</text><text v-else>○</text></view><view class="step-label">{{ step }}</view></view><view class="step-line"></view></view>
用插件快速落地(uni-steps 或 u-steps)
如果项目周期紧、需要垂直/横向切换、错误状态、图标自定义等能力,优先选成熟插件,但要注意初始化和样式覆盖细节。
-
uni-steps(插件市场):需手动 import 并注册,options是数组,每项含title、desc、status(process/finish/error),active控制当前索引;注意direction设"column"时,.uni-steps__column-line的高度需重置,否则竖向连线太短 -
u-steps(uView):需安装 uView 并全局注册,current是字符串(如"2"),不是数字;dot模式下图标默认是圆点,要换勾/叉得用slot="icon"自定义,否则样式会错位 - 坑点:所有插件在 H5 端可能默认用
transform动画,但在微信小程序里若未关闭animation属性,会导致步骤线闪烁或跳动
状态异常时怎么显示错误节点(如取消订单、审核驳回)
多数插件和手写方案默认只支持 finish/process/error 三种状态,但真实业务中常需“第 2 步失败,第 3 步禁用,第 1 步仍为完成”。这时不能只靠 current 推进,得用数组记录每步状态。
- 定义
stepStatus = ['finish', 'error', 'disabled', 'disabled'],比单个current更精确 - 渲染时判断:
:class="stepStatus[i] === 'error' ? 'step-error' : ...",再单独给.step-error .step-icon设置红色背景 +×字符或uni-icons的close图标 - ColorUI 的
cuIcon-roundclosefill类可以直接复用,但注意它依赖cuIcon字体文件,没引入会显示空白 - 容易被忽略的点:错误状态的步骤线应截断——即第 1 步到第 2 步有线,但第 2 步到第 3 步无线;这需要额外用
v-if控制.step-line的渲染,而不是仅靠 CSS 隐藏











