Steps

基础反馈

基于 Bootstrap 5 的步骤条组件，用于展示一个流程的进度与当前状态，支持横向/纵向布局、居中布局、圆点样式、自定义图标、错误状态、禁用步骤以及点击切换的受控/非受控模式

Component Demo

Basic usage and examples of the Steps component

基础用法

active 之前的步骤显示为完成状态，active 所在步骤为进行中，其余为等待中；完成步骤的指示器渲染为勾号

居中布局

center 开启后，指示器与标题、描述在各自的步骤列中水平居中，连接线从相邻指示器之间衔接；仅 horizontal 方向生效

垂直布局

direction 设为 vertical 时步骤纵向排列，连接线跟随各步骤内容高度延伸

圆点样式

variant 设为 dots 时指示器渲染为小圆点，进行中的圆点附带光环

自定义图标

通过 icon 传入任意内容即可替换指示器，优先级高于序号与勾号

错误状态

为单个步骤设置 status="error" 可覆盖位置推导，指示器渲染为叉号并使用危险色；错误不会向后传播

禁用步骤

2验证不可点击

禁用步骤无法点击切换，并整体降低透明度

交互示例

点击步骤即可切换当前步骤：受控时通过 active 与 onChange 管理，非受控时由组件内部维护（defaultActive 设置初始值）

API Documentation

Complete API reference for the Steps component

Props

Steps

属性名	类型	默认值	描述
`active`	`number`	-	受控的当前步骤序号（从 0 开始）；提供后点击步骤不会自动更新，仅触发 onChange 回调
`as`	`ElementType`	`'ol'`	根列表渲染的元素类型
`center`	`boolean`	`false`	是否在水平布局中将指示器与标题、描述居中显示；仅 `horizontal` 方向生效
`children`	`ReactNode`	-	步骤内容，仅识别 `StepsItem`，其余子项会被忽略
`className`	`string`	-	自定义类名，作用于根列表
`clickable`	`boolean`	`true`	是否允许点击步骤切换当前步骤；设为 `false` 时仅作展示
`defaultActive`	`number`	`0`	非受控模式下的初始步骤序号
`direction`	`StepsDirection`	`'horizontal'`	布局方向，`horizontal` 横向排列、`vertical` 纵向排列
`onChange`	`(active: number) => void`	-	点击步骤时回调，参数为新的步骤序号
`variant`	`StepsVariant`	`'default'`	指示器样式，`default` 为圆形序号，`dots` 为小圆点
`...rest`	`HTMLAttributes`	-	根列表的所有原生属性（如 `style`、`aria-label` 等）

StepsItem

属性名	类型	默认值	描述
`as`	`ElementType`	`'li'`	列表项渲染的元素类型
`children`	`ReactNode`	-	步骤额外内容，渲染在描述之后
`className`	`string`	-	自定义类名，作用于列表项
`description`	`ReactNode`	-	步骤描述内容
`disabled`	`boolean`	`false`	是否禁用该步骤的点击
`icon`	`ReactNode`	-	自定义指示器内容，替代序号、勾号或叉号
`status`	`StepsStatus`	-	手动指定步骤状态，覆盖根据 `active` 推导的状态
`title`	`ReactNode`	-	步骤标题内容
`...rest`	`HTMLAttributes`	-	列表项的所有原生属性（如 `style`、`onClick` 等）

Type Definitions

StepsProps

步骤条组件属性接口

export interface StepsProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {
  active?: number;
  as?: ElementType;
  center?: boolean;
  children?: ReactNode;
  className?: string;
  clickable?: boolean;
  defaultActive?: number;
  direction?: StepsDirection;
  onChange?: (active: number) => void;
  variant?: StepsVariant;
}

StepsItemProps

步骤项组件属性接口

export interface StepsItemProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  description?: ReactNode;
  disabled?: boolean;
  icon?: ReactNode;
  index?: number;
  status?: StepsStatus;
  title?: ReactNode;
}

StepsContextValue

步骤条上下文值，可通过 `useSteps` 获取（不在 `Steps` 内返回 `null`）

export interface StepsContextValue {
  active: number;
  clickable: boolean;
  direction: StepsDirection;
  handleSelect: (index: number) => void;
  variant: StepsVariant;
}

StepsDirection

步骤条布局方向类型

export type StepsDirection = 'horizontal' | 'vertical';

StepsStatus

步骤状态类型

export type StepsStatus = 'error' | 'finish' | 'process' | 'wait';

StepsVariant

步骤条指示器样式类型

export type StepsVariant = 'default' | 'dots';