#3138·layui

[steps] 新增 Steps 步骤条组件

Author: sunxiaobin89Created Aug 14, 2026Updated Aug 17, 2026
Labelswonderful

背景

管理后台「分步表单、流程引导、进度展示」等场景的高频组件。目前 layui 2.x → 3.0 均未提供步骤条组件。步骤条作为管理后台的通用能力,主流 UI 组件库(Element Plus / Ant Design)普遍内置支持。

目标

  • 新增通用 steps 步骤条组件,基于 3.0 组件基类(Component)实现
  • 支持水平 / 垂直布局、当前步骤控制(已完成 / 当前 / 待处理状态)、尺寸、状态色
  • 支持点击切换步骤(业务可阻断)、动态控制当前步、数据数组渲染
  • 遵循 lay- 命名空间与 CSS Variables 令牌体系

范围

  • 新增src/components/steps.jssrc/css/modules/steps.csstests/visual/steps.html
  • 修改src/components/initializer.jssrc/css/index.csssrc/index.js / src/index.umd.jssrc/core/i18n.js
  • 无需:docs、tests/unit

设计

控制方式

配置维度(布局 / 当前步 / 尺寸 / 状态色 / 可点击)通过 data-lay-* 属性承载(对齐 menu 组件与官方 lay.parseDataset 前缀约定),CSS 用属性选择器驱动;class 仅保留结构(lay-steps / lay-steps-item)与状态(lay-is-done / lay-is-active / lay-is-disabled)。

xml
<div class="lay-steps" data-lay-current="2">
  <div class="lay-steps-item">
    <div class="lay-steps-icon">1</div>
    <div class="lay-steps-content">
      <div class="lay-steps-title">步骤一</div>
      <div class="lay-steps-desc">填写基本信息</div>
    </div>
  </div>
  <div class="lay-steps-item">
    <div class="lay-steps-icon">2</div>
    <div class="lay-steps-content">
      <div class="lay-steps-title">步骤二</div>
      <div class="lay-steps-desc">完善个人资料</div>
    </div>
  </div>
</div>

功能

  • 布局:data-lay-layout(horizontal 水平,默认 / vertical 垂直)
  • 当前步骤:data-lay-current(从 1 开始),之前步骤已完成(lay-is-done 并自动打勾)、当前步激活(lay-is-active)、之后待处理;越界自动兜底
  • 尺寸:data-lay-size(xs / sm / lg)
  • 状态色:data-lay-status(success / error / warning),作用于当前步骤
  • 可点击切换:data-lay-clickable,点击 / 键盘(Enter / 空格)切换;click(filter) 事件回调返回 false 可阻断;change(filter) 切换成功后触发;事件参数含 { elem, from, to, item }
  • 动态控制:steps.setCurrent(id, index) 实例方法(静态委托),供业务推进 / 回退当前步
  • 数据渲染:steps.generate({ data, ...公共属性 }),字符串项用公共属性、对象项个性覆盖(支持 title / description / icon / disabled
  • 事件隔离:lay-filter 属性区分多实例(对齐 tag / form 惯例)
  • 禁用步骤:lay-is-disabled 状态类,置灰不可点

CSS 要点

  • 全量走令牌:--lay-steps-* 组件级令牌(激活 / 完成 / 待处理 / 状态色 / 尺寸)+ --lay-color-* / --lay-gray-* / --lay-spacing-*
  • 水平布局连接线用 ::after、垂直布局用 ::before(timeline 技巧),已完成段连接线自动着色
  • 完成步自动打勾:纯数字序号在 render 时替换为 lay-icon-ok 图标,回退时还原数字序号
  • 图标 / 文字垂直居中(line-height 收紧 + 数字微调补偿字体字形偏上)

文件清单

操作 文件
新增 src/components/steps.jssrc/css/modules/steps.csstests/visual/steps.html
修改 src/components/initializer.jssrc/css/index.csssrc/index.jssrc/index.umd.jssrc/core/i18n.js