rsuite Steps 步骤条组件完整指南：基础用法、状态控制与动态流程实现

前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载Steps是 rsuite 中用于引导用户按流程完成任务的导航组件广泛应用于订单状态、注册向导、多步骤表单等场景。本文以 docs/pages/components/steps 文档为骨架结合 rsuite 仓库源码完整讲解 Steps 的基础用法、标题描述、状态机制、尺寸方向、自定义图标与动态步骤控制并深入剖析其状态推导逻辑与底层实现帮助你快速上手并正确使用该组件。获取组件Steps 组件可直接从 rsuite 主包中导入无需额外安装依赖import { Steps } from rsuite;组件通过Steps与子组件Steps.Item组合使用外层Steps负责整体布局与状态分发内层每个Steps.Item定义一个步骤节点。基础用法最简步骤条文档 basic.md 给出了最基础的用法——只声明步骤个数与当前步骤索引不设置任何标题import { Steps } from rsuite; const App () ( Steps current{1} Steps.Item / Steps.Item / Steps.Item / Steps.Item / /Steps ); ReactDOM.render(App /, document.getElementById(root));这里current{1}表示第 2 个步骤索引从 0 开始处于进行中状态。从源码 src/Steps/Steps.tsx 看current的默认值为0即不传current时第一个步骤即为当前步骤。不设置标题时每个节点仅显示一个圆形图标占位默认显示步骤序号见下文“状态与图标”。实际项目中几乎总会为步骤设置标题与描述以提供更清晰的导航信息。设置标题提供清晰导航为每个步骤传入title即可在圆形图标右侧显示步骤名称帮助用户理解每一步的用途import { Steps } from rsuite; const App () ( Steps current{1} Steps.Item titleFinished / Steps.Item titleIn progress / Steps.Item titleWaiting / Steps.Item titleWaiting / /Steps ); ReactDOM.render(App /, document.getElementById(root));对应演示见 title.md。title的类型为ReactNode除了字符串也可以传入任意 React 元素。源码 src/Steps/StepItem.tsx 将标题渲染在.rs-steps-item-title容器内样式文件 src/Steps/styles/index.scss 为其定义了字号、行高与最小高度等样式。设置描述补充上下文信息每个步骤还可以通过description添加一行辅助说明例如时间、订单号等上下文信息import { Steps } from rsuite; const OrderStatus () ( Steps current{1} Steps.Item titleOrder Placed descriptionJune 28, 10:00 AM - Order #12345 / Steps.Item titleProcessing descriptionJune 28, 10:05 AM - Payment confirmed / Steps.Item titleShipped descriptionJune 29, 2:30 PM - Shipped via Express Delivery / Steps.Item titleDelivered descriptionEstimated delivery: July 1 - July 3 / /Steps ); ReactDOM.render(OrderStatus /, document.getElementById(root));对应演示见 description.md。description同为ReactNode类型源码中仅在传入该属性时才渲染.rs-steps-item-description容器src/Steps/StepItem.tsx样式上它拥有独立的字号--rs-font-size-sm与上边距src/Steps/styles/index.scss与标题形成层级区分。状态机制finish / wait / process / error四种状态Steps 的每个节点拥有四种状态通过data-status属性挂在.rs-steps-item上src/Steps/StepItem.tsx状态含义默认图标finish已完成对勾Checkprocess进行中步骤序号wait等待中步骤序号error出错叉号Close在 src/Steps/StepItem.tsx 中finish与error分别映射到rsuite/icons的Check与Close图标wait与process则显示stepNumber步骤序号。自动推导规则你通常无需为每个Steps.Item手动指定status。外层Steps会在渲染前根据current与currentStatus自动推导每个节点的状态src/Steps/Steps.tsxindex current当前步骤状态取currentStatus默认processindex current已完成状态为finishindex current等待中状态为wait如果某个Steps.Item显式传入了status则以显式传入值为准不被覆盖。标记错误状态将currentStatus设为error可让当前步骤以错误状态高亮展示突出流程中的问题import { Steps } from rsuite; const App () ( Steps current{1} currentStatuserror Steps.Item titleFinished / Steps.Item titleIn progress / Steps.Item titleWaiting / Steps.Item titleWaiting / /Steps ); ReactDOM.render(App /, document.getElementById(root));对应演示见 status.md。除当前节点变为叉号图标外源码还针对错误状态做了尾巴颜色修正当currentStatus error且节点索引为current - 1时会为其前一个已完成节点设置data-next-error属性src/Steps/Steps.tsx样式上该节点的连接线将显示为错误色src/Steps/styles/index.scss保证视觉上错误发生在当前节点之前的连线也能正确提示。尺寸与方向小尺寸与垂直布局小尺寸small在空间紧凑的界面中可通过small属性启用更小尺寸的步骤条import { Steps } from rsuite; const App () ( Steps current{1} small Steps.Item titleFinished / Steps.Item titleIn progress / Steps.Item titleWaiting / Steps.Item titleWaiting / /Steps ); ReactDOM.render(App /, document.getElementById(root));对应演示见 size.md。small属性在渲染时体现为容器上的data-sizesmallsrc/Steps/Steps.tsx样式层通过[data-sizesmall]选择器统一缩小图标尺寸、字号与步骤间距等 CSS 变量src/Steps/styles/index.scss。垂直布局vertical当水平空间有限时使用vertical属性将步骤条切换为垂直方向展示import { Steps, ButtonGroup, Button } from rsuite; const OrderStatus () { const [current, setCurrent] React.useState(1); return ( div Steps current{current} vertical Steps.Item titleOrder Placed descriptionJune 28, 10:00 AM / Steps.Item titleProcessing descriptionPreparing your order / Steps.Item titleShipped descriptionOn the way / Steps.Item titleDelivered descriptionEstimated: July 1 - July 3 / /Steps hr / ButtonGroup Button onClick{() setCurrent(p Math.max(0, p - 1))}Previous/Button Button onClick{() setCurrent(p Math.min(3, p 1))}Next/Button /ButtonGroup /div ); }; ReactDOM.render(OrderStatus /, document.getElementById(root));对应演示见 vertical.md。vertical同样通过data-directionvertical属性驱动src/Steps/Steps.tsx样式层分别定义了水平与垂直两套布局规则src/Steps/styles/index.scss水平布局下各节点以 flex 均分宽度、节点间通过标题后的伪元素绘制连接线垂直布局下连接线改为图标中心向下的左边框线并隐藏最后一个节点的尾部线条。自定义图标通过Steps.Item的icon属性可传入任意 React 元素如react-icons替换默认的序号或状态图标import { Steps, ButtonGroup, Button } from rsuite; import { FaShoppingCart, FaTruck, FaCheckCircle, FaBoxOpen } from react-icons/fa; const OrderStatus () { const [current, setCurrent] React.useState(1); return ( div Steps current{current} vertical Steps.Item titleOrder Placed description2023-06-01 10:30 AM icon{FaShoppingCart size{26} /} / Steps.Item titleProcessing descriptionPreparing your order icon{FaTruck size{26} /} / Steps.Item titleShipped descriptionOn the way icon{FaBoxOpen size{26} /} / Steps.Item titleDelivered descriptionOrder completed icon{FaCheckCircle size{26} /} / /Steps hr / ButtonGroup Button onClick{() setCurrent(p Math.max(0, p - 1))}Previous/Button Button onClick{() setCurrent(p Math.min(3, p 1))}Next/Button /ButtonGroup /div ); }; ReactDOM.render(OrderStatus /, document.getElementById(root));对应演示见 icon.md。icon的类型为React.ReactElementIconPropssrc/Steps/StepItem.tsx。传入自定义图标后节点容器会标记data-custom-icontrue样式层会移除默认的圆形边框与背景使自定义图标以裸图标形式呈现src/Steps/styles/index.scss。动态展示用按钮控制流程最后是完整的动态演示——将步骤条与Panel、ButtonGroup、Tag组合通过状态管理实现上一步/下一步的流程控制这是实际业务中最典型的用法import { Steps, Panel, ButtonGroup, Button, Tag } from rsuite; import { FaShoppingCart, FaBoxOpen, FaTruck, FaCheckCircle } from react-icons/fa; const App () { const [step, setStep] React.useState(0); const [orderStatus, setOrderStatus] React.useState(Processing); const steps [ { title: Order Placed, description: Order received and confirmed, icon: FaShoppingCart size{26} /, content: ( div pstrongOrder #RS-2023-00145/strong/p pDate: June 28, 2023 14:30/p pPayment: Tag colorgreenPaid/Tag/p pEstimated delivery: July 5, 2023/p /div ) }, { title: Processing, description: Preparing your order, icon: FaBoxOpen size{26} /, content: ( div pItems in this order:/p ul liWireless Earbuds Pro × 1/li liPhone Case × 2/li liScreen Protector × 1/li /ul pStatus: Tag colorbluePackaging/Tag/p /div ) }, { title: Shipped, description: On the way to you, icon: FaTruck size{26} /, content: ( div pShipped with: strongExpress Shipping/strong/p pTracking #: EX123456789/p pEstimated delivery: strongJuly 3, 2023/strong/p pStatus: Tag colororangeIn Transit/Tag/p /div ) }, { title: Delivered, description: Order completed, icon: FaCheckCircle size{26} /, content: ( div pDelivered on: strongJuly 2, 2023 15:45/strong/p pReceived by: Front Desk/p pDelivery note: Left at the front door/p pStatus: Tag colorgreenDelivered/Tag/p /div ) } ]; const onChange nextStep { const newStep nextStep 0 ? 0 : nextStep steps.length - 1 ? steps.length - 1 : nextStep; setStep(newStep); setOrderStatus(steps[newStep].title); }; const onNext () onChange(step 1); const onPrevious () onChange(step - 1); return ( div Box mb{20} h4Order Status: {orderStatus}/h4 /Box Steps current{step} {steps.map((item, index) ( Steps.Item key{index} title{item.title} description{item.description} icon{item.icon} / ))} /Steps Panel header{steps[step].title} bordered my{20} {steps[step].content} /Panel ButtonGroup Button onClick{onPrevious} disabled{step 0} Previous /Button Button onClick{onNext} disabled{step steps.length - 1} {step steps.length - 1 ? Complete : Next} /Button /ButtonGroup /div ); }; ReactDOM.render(App /, document.getElementById(root));对应演示见 dynamic.md。该示例的关键点用useState管理step索引Steps current{step}驱动状态自动推导通过ButtonGroupButton的onClick修改索引并使用Math.max / Math.min将索引钳制在[0, steps.length - 1]范围内首尾节点通过disabled禁用越界操作最后一步将按钮文案切换为Complete步骤对应的业务内容放在Panel中随step同步切换形成完整的步骤条 内容面板向导式交互。Props 一览Steps属性名称类型默认值描述classPrefixstring(steps)组件 CSS 类的前缀currentnumber(0)当前执行步骤从 0 开始currentStatusfinish | wait | process | error(process)当前执行步骤的状态smallboolean设置小尺寸的步骤条verticalboolean设置垂直显示Steps.Item属性名称类型默认值描述classPrefixstring(steps-item)组件 CSS 类的前缀descriptionReactNode设置步骤描述iconElementtypeof Icon设置步骤图标statusfinish | wait | process | error步骤状态显式设置后不会被自动推导覆盖titleReactNode设置步骤标题完整的 Props 定义可参考 Steps.tsx 与 StepItem.tsx 中的 TypeScript 接口其中Steps还继承自BoxProps因此as、className、style等通用属性同样可用。底层实现剖析状态分发mapCloneElement 注入Steps使用rch.count统计子节点数量并通过rch.mapCloneElement为每个Steps.Item克隆并注入stepNumber从 1 开始、默认状态以及水平布局下的宽度样式src/Steps/Steps.tsxconst itemStyles { flexBasis: index count - 1 ? ${100 / (count - 1)}% : undefined, maxWidth: index count - 1 ? ${100 / count}% : undefined };这是水平布局下各步骤等分、末节点自适应的布局依据与 styles/index.scss 中justify-content: space-between配合实现。图标与状态渲染StepItem内部根据status从STEP_STATUS_ICON映射表取默认图标finish显示对勾、error显示叉号其余状态显示序号传入icon时优先渲染自定义图标src/Steps/StepItem.tsx。DOM 结构为tail连接线icon-wrapper圆形图标容器content标题与描述与 SCSS 中的选择器一一对应。测试用例验证仓库测试 Steps.spec.tsx 覆盖了关键行为默认渲染rs-steps类且data-directionhorizontal传vertical后data-direction变为verticalcurrent{2}时第 3 个节点标题 C的data-status为processcurrent{1} currentStatuserror时对应节点的data-status为error传small后容器带data-sizesmall。StepItem.spec.tsx 则验证了自定义图标data-custom-icontrue、步骤序号渲染stepNumber、wait/process状态显示序号以及title、description的渲染结果。这些测试同时可作为使用 Steps 组件时理解行为边界的参考。总结rsuite 的 Steps 组件覆盖了从最简占位步骤条到标题 描述 自定义图标 动态切换的完整场景状态完全由current/currentStatus驱动自动推导small与vertical提供紧凑与垂直布局能力配合ButtonGroup、Panel等组件即可快速搭建订单追踪、多步表单等向导型界面。结合 源码 与 样式 理解其data-status、data-direction、data-size的属性驱动机制能帮助你在自定义样式或排查问题时事半功倍。赞分享前端UI组件【免费下载链接】rsuite A suite of React components .项目地址https://gitcode.com/gh_mirrors/rs/rsuite点击查看免费下载相关推荐RevokeMsgPatcher 使用指南4 步为 PC 微信/QQ/TIM 装上防撤回补丁RevokeMsgPatcher 使用指南4 步为 PC 微信/QQ/TIM 装上防撤回补丁 RevokeMsgPatcher 是一款面向 Windows 的桌面应用即时通讯ant-design-vue Steps 步骤条组件完整指南API 参数、状态机制与实战用法ant design vue Steps 步骤条组件完整指南API 参数、状态机制与实战用法 Steps 是 ant design vue 中用于引导用户按流前端UI组件设计系统Element Plus Steps 步骤条组件完全指南从基础用法到源码级状态流转原理Element Plus Steps 步骤条组件完全指南从基础用法到源码级状态流转原理 本指南以 steps.md https://link.gitcode.前端UI组件上一篇Emscripten渐进式加载性能指标关键绩效指标下一篇SillyTavern 1.18.0 企业级部署实战指南从零构建AI对话前端解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考