Element UI Steps 步骤条组件全解从六大用法到 active 驱动状态机的源码实现【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/element本文围绕 Element UI 官方文档 steps.md 中 Steps步骤条组件的全部用法与参数展开并结合 packages/steps 的源码、test/unit/specs/steps.spec.js 测试用例和 TypeScript 类型声明讲清active如何驱动每一步的wait / process / finish / error / success状态流转、space如何换算成实际布局宽度以及simple、vertical两种形态的渲染差异。读完本文你可以直接复制运行文档中的全部示例并能读懂状态类名与连接线动画背后的实现逻辑。一、组件定位与代码入口Steps 用于“按照业务流程引导用户完成任务”步骤数量按实际场景设定文档明确要求步骤数不能少于 2。组件由两个文件构成packages/steps/src/steps.vueElSteps容器负责布局方向、整体主题并维护子步骤注册表packages/steps/src/step.vueElStep单步负责图标、连接线、标题与描述的渲染以及自身状态的推导packages/steps/index.js安装入口Vue.component(Steps.name, Steps)配合ElStep全局注册后模板中可直接写el-steps/el-step类型声明见 types/steps.d.ts 与 types/step.d.ts。ElSteps的 props 定义与文档属性表一一对应见 steps.vue L20-L37props: { space: [Number, String], // 每步间距省略时自适应支持百分比 active: Number, // 当前激活步骤从 0 开始 direction: { type: String, default: horizontal }, alignCenter: Boolean, simple: Boolean, finishStatus: { type: String, default: finish }, processStatus: { type: String, default: process } }另外从源码的Migratingmixin 配置可以看到旧版的center属性已被移除现由align-center取代见 steps.vue L47-L53。二、基础用法active 驱动的步骤条文档的第一个示例展示了最简单的步骤条active是Number类型表示当前步骤的索引从 0 开始space用于固定每步宽度单位px不设置时宽度自适应finish-status改变已完成步骤的展示状态。el-steps :activeactive finish-statussuccess el-step titleStep 1/el-step el-step titleStep 2/el-step el-step titleStep 3/el-step /el-steps el-button stylemargin-top: 12px; clicknextNext step/el-button script export default { data() { return { active: 0 }; }, methods: { next() { if (this.active 2) this.active 0; } } } /script这里finish-statussuccess让已通过步骤显示为绿色对勾若保持默认值finish已通过步骤则显示主题色primary。一个文档未提及、但源码中存在的交互点active变化时ElSteps会对外抛出change事件携带新值与旧值见 steps.vue L56-L59watch: { active(newVal, oldVal) { this.$emit(change, newVal, oldVal); }, // ... }因此业务侧可以直接监听changeonStepChange来与表单提交、接口校验等流程联动而无需自行 diff 新旧值。三、状态系统五种状态如何被推导出来文档第二个示例展示“带状态的步骤条”title设置步骤名也可以用同名slot覆盖。el-steps :space200 :active1 finish-statussuccess el-step titleDone/el-step el-step titleProcessing/el-step el-step titleStep 3/el-step /el-steps五个状态wait / process / finish / error / success的定义在 types/step.d.tsexport type StepStatus wait | process | finish | error | success状态推导规则从 step.vue 的 updateStatus 方法 看每一步的实际状态由“自身status属性”或“父级active推导值”二选一currentStatus() { return this.status || this.internalStatus; }active index该步骤已完成取父级finishStatus默认finishactive index且前一步不是error该步骤为当前步骤取父级processStatus默认process其余情况wait。第 2 条中的“前一步是 error 则阻止 process”是关键细节当某一步被标记为error时后续步骤不会被点亮为 process连接线也不会填充进度。这一点有专门测试用例佐证见 steps.spec.js L146-L162active2、第二步statuserror时第二条连接线宽度为 0第三步保持is-wait。error/success状态下图标区域会被状态图标替代el-icon-checksuccess或el-icon-closeerror见 step.vue L22-L35。相应地process-statuserror会让当前步直接显示红色叉号测试用例 steps.spec.js L46-L59 验证了.el-step__head.is-error的数量。process-status还是响应式的动态修改后当前步状态立即更新测试见 steps.spec.js L61-L82。连接线的“进度填充”动画步骤间的连接线通过calcProgress计算进度见 step.vue L152-L170已完成步骤的连接线填充100%wait步骤填充0%水平方向控制width、垂直方向控制height并给每一步加上transitionDelay 150 * index毫秒的延迟形成依次亮起的级联动画。四、布局与样式变体4.1 居中对齐align-center标题和描述可以整体居中只需加align-centerel-steps :active2 align-center el-step titleStep 1 descriptionSome description/el-step el-step titleStep 2 descriptionSome description/el-step el-step titleStep 3 descriptionSome description/el-step el-step titleStep 4 descriptionSome description/el-step /el-steps4.2 带描述的步骤条通过description属性给每步补充说明文字未设置align-center时描述左对齐el-steps :active1 el-step titleStep 1 descriptionSome description/el-step el-step titleStep 2 descriptionSome description/el-step el-step titleStep 3 descriptionSome description/el-step /el-steps4.3 带图标的步骤条图标由icon属性设置取值为 Element Icon 的类名如el-icon-edit也可以通过icon具名slot传入自定义图标el-steps :active1 el-step titleStep 1 iconel-icon-edit/el-step el-step titleStep 2 iconel-icon-upload/el-step el-step titleStep 3 iconel-icon-picture/el-step /el-steps从源码看icon为字符串时渲染为i :class[icon]同时图标容器由is-text24px 圆形切换为is-icon40px 方形样式见 step.scss L55-L77。success/error状态时 slot 会被状态图标覆盖不再显示自定义图标。4.4 垂直步骤条只需将el-steps的direction设为verticaldiv styleheight: 300px; el-steps directionvertical :active1 el-step titleStep 1/el-step el-step titleStep 2/el-step el-step titleStep 3/el-step /el-steps /div垂直模式下容器切换为flex-flow: column并占满height: 100%见 steps.scss L16-L19此时space控制的是每一步的高度而非宽度——测试用例验证:space200时首个步骤的flexBasis为200px见 steps.spec.js L133-L144。4.5 简易步骤条simplesimple主题下align-center、description、direction与space均被忽略描述不再渲染每步之间以箭头分隔el-steps :space200 :active1 simple el-step titleStep 1 iconel-icon-edit/el-step el-step titleStep 2 iconel-icon-upload/el-step el-step titleStep 3 iconel-icon-picture/el-step /el-steps el-steps :active1 finish-statussuccess simple stylemargin-top: 20px el-step titleStep 1/el-step el-step titleStep 2/el-step el-step titleStep 3/el-step /el-steps样式上el-steps--simple带padding: 13px 8%、圆角和浅灰背景见 steps.scss L6-L10源码中ElStep的space计算属性在isSimple时直接返回空串印证了“simple 忽略 space”的文档说明见 step.vue L111-L114。五、属性与插槽速查Steps Attributes来源文档 types/steps.d.tsAttributeDescriptionTypeAccepted ValuesDefaultspacethe spacing of each step, will be responsive if omitted. Supports percentage.number / string——directiondisplay directionstringvertical/horizontalhorizontalactivecurrent activation stepnumber—0process-statusstatus of current stepstringwait / process / finish / error / successprocessfinish-statusstatus of end stepstringwait / process / finish / error / successfinishalign-centercenter title and descriptionboolean—falsesimplewhether to apply simple themeboolean-falseStep Attributes来源文档 types/step.d.tsAttributeDescriptionTypeAccepted ValuesDefaulttitlestep titlestring——descriptionstep descriptionstring——iconstep icons class name. Icons can be passed via named slot as wellstring——statuscurrent status. It will be automatically set by Steps if not configured.wait / process / finish / error / success-—Step SlotNameDescriptioniconcustom icontitlestep titledescriptionstep description六、布局实现space 如何变成真实宽度space的换算逻辑集中在ElStep的style计算属性见 step.vue L115-L134const space (typeof this.space number ? this.space px // 数字 → 固定 px 宽 : this.space ? this.space // 字符串 → 原样使用可写 30% : 100 / (len - (this.isCenter ? 0 : 1)) %); // 未设置 → 均分剩余宽度 style.flexBasis space;三条规则可以归纳为数字space200→ 每步flex-basis: 200px字符串如30%直接透传这也是文档中“支持百分比”的实现出处省略100 / (步骤数 - (isCenter ? 0 : 1)) %均分容器宽度align-center时不减 1因为居中布局下最后一步也要占满一份。非最后一步还会叠加marginRight: -stepOffset px来让连接线穿过图标区域stepOffset由容器维护最后一步在未设space且未居中时加is-flex类样式表中将其flex-basis: auto !important; flex-shrink: 0; flex-grow: 0使尾部不拉伸见 step.scss L8-L18。测试用例 steps.spec.js L21-L44 精确验证了这两条路径不设space的 3 步场景下首步flexBasis为50%100/(3-1)设:space100的场景下为100px。七、父子协作步骤的注册与注销ElSteps并不直接渲染步骤而是由slot透传。每个ElStep在beforeCreate阶段把自己 push 进父级steps数组在beforeDestroy时按索引 splice 移除见 step.vue L75-L85beforeCreate() { this.$parent.steps.push(this); }, beforeDestroy() { const steps this.$parent.steps; const index steps.indexOf(this); if (index 0) { steps.splice(index, 1); } }父级再通过 watcher 给每个子步骤回写index并在mounted时为每个步骤建立对$parent.active和$parent.processStatus的监听immediate: true首次挂载即完成状态推导见 step.vue L173-L182。这种“子组件自注册 父级 active 广播”的结构意味着动态增删el-step例如v-for渲染后状态会自动重算这也是官方允许步骤数随场景变化的底层保障。测试中的create用例验证了三个el-step会渲染出三个.el-step节点见 steps.spec.js L9-L19。八、落地要点小结active从0开始索引配合finish-status/process-status即可表达“已完成 / 进行中 / 失败”等流程语义active变化会触发change(newVal, oldVal)事件适合驱动业务跳转给某一步单独设置statuserror会阻断其后继步骤进入process连接线同步清零可用于“当前节点失败、整体暂停”的场景space支持数字px与字符串百分比不设置则按100/(n-1)均分且末步不拉伸align-center、simple会改变该公式与渲染结构垂直布局中space语义变为高度simple模式下描述、方向、间距属性全部失效仅保留图标与标题自定义内容优先用icon/title/description三个具名插槽图标可用 Element 图标类名或任意 slot 节点。以上所有行为均可在 packages/steps 源码、test/unit/specs/steps.spec.js 测试与 packages/theme-chalk/src/steps.scss、packages/theme-chalk/src/step.scss 样式中逐条核对。【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/element创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考