# 步骤条

- 页面: https://jiguang132.com/zh/resources/ant-design/docs/steps
- 资源: Ant Design (https://jiguang132.com/zh/resources/ant-design.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design/docs.md

引导用户按照流程完成任务的导航条。


## 何时使用 {#when-to-use}

当任务复杂或者存在先后关系时，将其分解成一系列步骤，从而简化任务。

## 代码演示 {#examples}


- 基本用法 · `simple`
- 步骤运行错误 · `error`
- 竖直方向的步骤条 · `vertical`
- 可点击 · `clickable`
- 面板式步骤 · `panel`
- 带图标的步骤条 · `icon`

- 标签放置位置与进度 · `title-placement`
- 限量展示 · `max-count`
- 点状步骤条 · `progress-dot`

- 导航步骤 · `nav`



- 内联步骤 · `inline`
- 内联样式组合 · `inline-variant`


- 自定义语义结构的样式和类 · `style-class`

## API

通用属性参考：[通用属性](#jguang-common-props)

### Steps

整体步骤条。

| 参数 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - |  | 6.0.0 |
| current | 指定当前步骤，从 0 开始记数。在子 Step 元素中，可以通过 `status` 属性覆盖状态 | number | 0 |  | × |
| ~~direction~~ | 指定步骤条方向。目前支持水平（`horizontal`）和竖直（`vertical`）两种方向 | string | `horizontal` |  | × |
| iconRender | 自定义渲染图标，请优先使用 `items.icon` | (oriNode, info: { index, active, item }) => ReactNode | - |  | × |
| initial | 起始序号，从 0 开始记数 | number | 0 |  | × |
| ~~labelPlacement~~ | 指定标签放置位置，默认水平放图标右侧，可选 `vertical` 放图标下方 | string | `horizontal` |  | × |
| maxCount | 最大可见步骤项数量（`>= 3`）。超出数量的步骤区间会聚合成禁用的省略号步骤。 | number | - |  | × |
| orientation | 指定步骤条方向。目前支持水平（`horizontal`）和竖直（`vertical`）两种方向 | string | `horizontal` |  | × |
| percent | 当前 `process` 步骤显示的进度条进度（只对基本类型的 Steps 生效） | number | - | 4.5.0 | × |
| ~~progressDot~~ | 点状步骤条，可以设置为一个 function，请使用 `type="dot"` 替代。`titlePlacement` 将强制为 `vertical` | boolean \| (iconDot, { index, status, title, content }) => ReactNode | false |  | × |
| responsive | 当屏幕宽度小于 `532px` 时自动变为垂直模式 | boolean | true |  | × |
| size | 指定大小，目前支持普通（`medium`）和迷你（`small`） | string | `medium` |  | × |
| status | 指定当前步骤的状态，可选 `wait` `process` `finish` `error` | string | `process` |  | × |
| styles | 用于自定义组件内部各语义化结构的行内 style，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), CSSProperties> | - |  | 6.0.0 |
| titlePlacement | 指定标签放置位置，默认水平放图标右侧，可选 `vertical` 放图标下方 | string | `horizontal` |  | × |
| type | 步骤条类型，可选 `default` `dot` `inline` `navigation` `panel` | string | `default` |  | × |
| variant | 设置样式变体 | `filled` \| `outlined` | `filled` |  | × |
| onChange | 点击切换步骤时触发 | (current) => void | - |  | × |
| items | 配置选项卡内容 | [StepItem](#stepitem) | [] | 4.24.0 | × |

### StepItem

步骤条内的每一个步骤。

| 参数 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- |
| content | 步骤的详情描述，可选 | ReactNode | - |  |
| ~~description~~ | 步骤的详情描述，可选 | ReactNode | - |  |
| disabled | 禁用点击 | boolean | false |  |
| icon | 步骤图标的类型，可选 | ReactNode | - |  |
| status | 指定状态。当不配置该属性时，会使用 Steps 的 `current` 来自动指定状态。可选：`wait` `process` `finish` `error` | string | `wait` |  |
| subTitle | 子标题 | ReactNode | - |  |
| title | 标题 | ReactNode | - |  |

## Semantic DOM

### Steps

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 根元素，包含 flex 布局、禁止换行、对齐方式、CSS 变量等步骤条容器的基础样式 | — |
| `item` | 步骤项元素，包含 flex 布局、相对定位等单个步骤项的基础容器样式 | — |
| `itemWrapper` | 步骤项内裹元素，包含 flex 布局、禁止换行、顶部内边距等步骤项内容的包装样式 | — |
| `itemIcon` | 步骤项图标元素，包含图标的尺寸、定位、字体大小等图标显示相关样式 | — |
| `itemHeader` | 步骤项头部元素，包含 flex 布局、禁止换行、对齐方式等头部区域的布局样式 | — |
| `itemTitle` | 步骤项标题元素，包含颜色、字体大小、行高、文字换行、过渡动画等标题文字样式 | — |
| `itemSubtitle` | 步骤项副标题元素，包含颜色、字体权重、字体大小、行高、外边距、文字换行等副标题样式 | — |
| `itemSection` | 步骤项区域元素，包含步骤项内容区域的布局和样式 | — |
| `itemContent` | 步骤项内容元素，包含颜色、字体大小、行高、文字换行、过渡动画等内容文字样式 | — |
| `itemRail` | 步骤项连接线元素，包含边框样式、边框宽度、过渡动画等连接线的样式 | — |

语义说明来源: `vendor/components/steps/demo/_semantic.tsx`

### StepItem

| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 根元素 | — |
| `wrapper` | 步骤项内裹元素 | — |
| `icon` | 步骤项图标元素 | — |
| `header` | 步骤项头部元素 | — |
| `title` | 步骤项标题元素 | — |
| `subtitle` | 步骤项副标题元素 | — |
| `section` | 步骤项区域元素 | — |
| `content` | 步骤项内容元素 | — |
| `rail` | 步骤项连接线元素 | — |

语义说明来源: `vendor/components/steps/demo/_semantic_items.tsx`

## 主题变量（Design Token）{#design-token}

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

| 令牌 | 类型 | 原生说明 |
| --- | --- | --- |
| `descriptionMaxWidth?` | `number` | 描述区域最大宽度 |
| `customIconSize` | `number` | 自定义图标容器尺寸 |
| `customIconTop` | `number` | 自定义图标 top |
| `customIconFontSize` | `number` | 自定义图标大小 |
| `iconSize` | `number` | 图标容器尺寸 |
| `iconTop` | `number` | 图标 top |
| `iconFontSize` | `number` | 图标大小 |
| `dotSize` | `number` | 点状步骤点大小 |
| `dotCurrentSize` | `number` | 点状步骤点当前大小 |
| `navArrowColor` | `string` | 可跳转步骤条箭头颜色 |
| `navContentMaxWidth` | `CSSProperties['maxWidth']` | 可跳转步骤条内容最大宽度 |
| `iconSizeSM` | `number \| string` | 小号步骤条图标大小 |
| `titleLineHeight` | `number \| string` | 标题行高 |

声明来源: `vendor/components/steps/style/index.ts`

```ts
import type { CSSProperties } from 'react';

import type { CSSObject } from '@ant-design/cssinjs';

import { genFocusOutline, resetComponent, textEllipsis } from '../../style';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

import { genCssVar } from '../../theme/util/genStyleUtils';

import genHorizontalStyle from './horizontal';

import genIconStyle from './icon';

import genInlineStyle from './inline';

import genLabelPlacementStyle from './label-placement';

import genMaxCountStyle from './max-count';

import genLegacyNavStyle from './nav';

import genPanelStyle from './panel';

import genStepsProgressStyle from './progress';

import genDotStyle from './progress-dot';

import genRTLStyle from './rtl';

import genSmallStyle from './small';

import genStatusStyle from './status';

import genVerticalStyle from './vertical';

export interface ComponentToken {
  /**
   * @desc 描述区域最大宽度
   * @descEN Max width of description area
   * @deprecated This value has been removed by default since v6
   */
  descriptionMaxWidth?: number;
  /**
   * @desc 自定义图标容器尺寸
   * @descEN Size of custom icon container
   */
  customIconSize: number;
  /**
   * @desc 自定义图标 top
   * @descEN Top of custom icon
   */
  customIconTop: number;
  /**
   * @desc 自定义图标大小
   * @descEN Font size of custom icon
   */
  customIconFontSize: number;
  /**
   * @desc 图标容器尺寸
   * @descEN Size of icon container
   */
  iconSize: number;
  /**
   * @desc 图标 top
   * @descEN Top of icon
   */
  iconTop: number;
  /**
   * @desc 图标大小
   * @descEN Size of icon
   */
  iconFontSize: number;
  /**
   * @desc 点状步骤点大小
   * @descEN Size of dot
   */
  dotSize: number;
  /**
   * @desc 点状步骤点当前大小
   * @descEN Current size of dot
   */
  dotCurrentSize: number;
  /**
   * @desc 可跳转步骤条箭头颜色
   * @descEN Color of arrow in nav
   */
  navArrowColor: string;
  /**
   * @desc 可跳转步骤条内容最大宽度
   * @descEN Max width of nav content
   */
  navContentMaxWidth: CSSProperties['maxWidth'];
  /**
   * @desc 小号步骤条图标大小
   * @descEN Size of small steps icon
   */
  iconSizeSM: number | string;
  /**
   * TODO: deprecated warning since not used anymore
   * @desc 标题行高
   * @descEN Line height of title
   * @deprecated Not used anymore
   */
  titleLineHeight: number | string;
}

export interface StepsToken extends FullToken<'Steps'> {
  inlineDotSize: number;
}
```


## 原生通用属性 {#jguang-common-props}


> Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| style | 自定义样式 | CSSProperties | - |
| className | 自定义类名 | string | - |
| rootClassName | 添加在组件最外层的 className | string | - |
| autoFocus | 自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效 | boolean | false |


## 安装并复现示例

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

## 原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

- `vendor/components/steps/PanelArrow.tsx`
- `vendor/components/steps/ProgressIcon.tsx`
- `vendor/components/steps/context.ts`
- `vendor/components/steps/index.tsx`
- `vendor/components/steps/style/index.ts`
- `vendor/components/steps/useDisplaySteps.ts`

## 来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt