> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/components/steps.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# Steps 步骤条

展示任务的进展和当前步骤。


## 基础用法

当前步骤索引从 `0` 开始。未指定单项 `status` 时，会根据 `current` 显示已完成、进行中和等待状态。


1. 创建
1. 2确认
1. 3完成

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/steps/basic.tsx"
import { Steps } from '@ifhover/leaf-ui';

const items = [{ title: '创建' }, { title: '确认' }, { title: '完成' }];

export function StepsBasic() {
  return <Steps aria-label="任务步骤" items={items} current={1} />;
}
```

展开代码


## 示例

### 受控切换

传入 `onChange` 后可点击步骤，由应用将返回的索引写回 `current`，组件不会自动推进步骤。


1. 1创建
1. 2确认
1. 3完成

当前步骤：创建

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/steps/controlled.tsx"
import { Flex, Steps, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const items = [{ title: '创建' }, { title: '确认' }, { title: '完成' }];

export function StepsControlled() {
  const [current, setCurrent] = useState(0);
  return (
    <Flex direction="column" gap="md">
      <Steps aria-label="可切换步骤" items={items} current={current} onChange={setCurrent} />
      <Text role="status" tone="muted">
        当前步骤：{items[current]?.title}
      </Text>
    </Flex>
  );
}
```

展开代码

### 纵向排列

设置 `direction="vertical"`，按纵向排列步骤。


1. 创建填写基本信息
1. 2确认检查并确认配置
1. 3完成开始使用

vertical.tsx

复制代码

```tsx lineNumbers file="../../src/examples/steps/vertical.tsx"
import { Steps } from '@ifhover/leaf-ui';

const items = [
  { title: '创建', description: '填写基本信息' },
  { title: '确认', description: '检查并确认配置' },
  { title: '完成', description: '开始使用' },
];

export function StepsVertical() {
  return <Steps aria-label="纵向步骤" direction="vertical" current={1} items={items} />;
}
```

展开代码

### 错误状态

通过 `status="error"` 标记当前步骤的错误状态。


1. 创建
1. 确认
1. 3完成

error.tsx

复制代码

```tsx lineNumbers file="../../src/examples/steps/error.tsx"
import { Steps } from '@ifhover/leaf-ui';

const items = [{ title: '创建' }, { title: '确认' }, { title: '完成' }];

export function StepsError() {
  return <Steps aria-label="出错步骤" current={1} status="error" items={items} />;
}
```

展开代码

### 点状步骤

设置 `progressDot`，使用点状标记展示步骤。


1. 创建
1. 确认
1. 完成

capabilities.tsx

复制代码

```tsx lineNumbers file="../../src/examples/steps/capabilities.tsx"
import { Steps } from '@ifhover/leaf-ui';

const items = [{ title: '创建' }, { title: '确认' }, { title: '完成' }];

export function Capabilities() {
  return <Steps aria-label="点状步骤" progressDot current={1} items={items} />;
}
```

展开代码

### 步骤内进度

`percent` 表示当前步骤图标内的进度，不是整个任务的完成度；点状模式不显示此进度。


1. 创建
1. 2确认65%
1. 3完成

progress.tsx

复制代码

```tsx lineNumbers file="../../src/examples/steps/progress.tsx"
import { Steps } from '@ifhover/leaf-ui';

const items = [{ title: '创建' }, { title: '确认', description: '65%' }, { title: '完成' }];

export function StepsProgress() {
  return <Steps aria-label="步骤内进度" current={1} percent={65} items={items} />;
}
```

展开代码


## API

### Steps API

配置当前步骤、步骤数据和排列方式。

| 属性            | 类型                                                                                    | 默认值            | 说明                         |
| ------------- | ------------------------------------------------------------------------------------- | -------------- | -------------------------- |
| `items`       | `readonly `[`StepItem`](#stepitem)`[]`                                                | 必填             | 步骤列表                       |
| `current`     | `number`                                                                              | `0`            | 当前步骤的索引，从 0 开始             |
| `status`      | `'process' \| 'finish' \| 'error'`                                                    | `'process'`    | 当前步骤状态                     |
| `direction`   | `'horizontal' \| 'vertical'`                                                          | `'horizontal'` | 排列方向                       |
| `size`        | `'sm' \| 'md' \| 'lg'`                                                                | `'md'`         | 步骤尺寸                       |
| `loading`     | `boolean`                                                                             | `false`        | 当前步骤展示加载图标                 |
| `onChange`    | `(current: number) => void`                                                           | —              | 设置后可点击步骤                   |
| `progressDot` | `boolean \| ((dot: ReactNode, info: { index: number; status: string }) => ReactNode)` | —              | 使用点状步骤，可自定义点的内容。           |
| `percent`     | `number`                                                                              | —              | 当前步骤图标内的进度（0–100）；点状模式不显示。 |

### StepItem

描述单个步骤的标题、状态与补充内容。

| 属性            | 类型                                           | 默认值     | 说明      |
| ------------- | -------------------------------------------- | ------- | ------- |
| `key`         | `string`                                     | —       | 稳定标识    |
| `title`       | `ReactNode`                                  | 必填      | 步骤名称    |
| `description` | `ReactNode`                                  | —       | 补充说明    |
| `icon`        | `ReactNode`                                  | —       | 自定义图标   |
| `status`      | `'wait' \| 'process' \| 'finish' \| 'error'` | —       | 覆盖该步骤状态 |
| `disabled`    | `boolean`                                    | `false` | 禁用交互。   |
