---
nav:
  title: 组件
  order: 1
group:
  title: Data Entry
  order: 1
title: PisellSteps
order: 1
category: pro
---

# PisellSteps 步骤条

步骤条组件，用于引导用户完成多步骤任务的核心导航组件。

## 何时使用

- 当任务需要分成多个步骤完成时
- 需要告知用户当前进度和整体流程时
- 当有一个较长的流程需要进行分步展示时

## 代码演示

### 基础用法

最简单的用法。

```tsx
import { PisellSteps } from '@pisell/materials';

export default () => {
  return (
    <PisellSteps
      current={1}
      items={[
        {
          title: '已完成',
          description: '这是一条描述信息',
        },
        {
          title: '进行中',
          description: '这是一条描述信息',
        },
        {
          title: '等待中',
          description: '这是一条描述信息',
        },
      ]}
    />
  );
};
```

### 迷你版

迷你版的步骤条，适用于紧凑的空间。

```tsx
import { PisellSteps } from '@pisell/materials';

export default () => {
  return (
    <PisellSteps
      size="small"
      current={1}
      items={[{ title: '已完成' }, { title: '进行中' }, { title: '等待中' }]}
    />
  );
};
```

### 带图标的步骤条

通过设置 `items` 的 `icon` 属性，可以自定义每个步骤的图标。

```tsx
import { PisellSteps } from '@pisell/materials';
import {
  UserOutlined,
  SolutionOutlined,
  LoadingOutlined,
  SmileOutlined,
} from '@ant-design/icons';

export default () => {
  return (
    <PisellSteps
      current={1}
      items={[
        {
          title: '登录',
          icon: <UserOutlined />,
        },
        {
          title: '验证',
          icon: <SolutionOutlined />,
        },
        {
          title: '付款',
          icon: <LoadingOutlined />,
        },
        {
          title: '完成',
          icon: <SmileOutlined />,
        },
      ]}
    />
  );
};
```

### 点状步骤条

包含步骤点的简化版步骤条。

```tsx
import { PisellSteps } from '@pisell/materials';

export default () => {
  return (
    <PisellSteps
      progressDot
      current={1}
      items={[
        { title: '已完成', description: '这是一条描述' },
        { title: '进行中', description: '这是一条描述' },
        { title: '等待中', description: '这是一条描述' },
      ]}
    />
  );
};
```

### 竖向步骤条

竖直方向的步骤条。

```tsx
import { PisellSteps } from '@pisell/materials';

export default () => {
  return (
    <PisellSteps
      direction="vertical"
      current={1}
      items={[
        {
          title: '已完成',
          description: '这是一条描述信息',
        },
        {
          title: '进行中',
          description: '这是一条描述信息',
        },
        {
          title: '等待中',
          description: '这是一条描述信息',
        },
      ]}
    />
  );
};
```

### 可点击的步骤条

设置 `clickable` 允许点击切换步骤。

```tsx
import { PisellSteps } from '@pisell/materials';
import { useState } from 'react';

export default () => {
  const [current, setCurrent] = useState(0);

  return (
    <PisellSteps
      current={current}
      onChange={setCurrent}
      clickable
      allowClickFinished
      items={[
        { title: '步骤1', description: '这是步骤1的描述' },
        { title: '步骤2', description: '这是步骤2的描述' },
        { title: '步骤3', description: '这是步骤3的描述' },
      ]}
    />
  );
};
```

### 错误状态

使用 `status` 属性指定当前步骤的状态。

```tsx
import { PisellSteps } from '@pisell/materials';

export default () => {
  return (
    <PisellSteps
      current={1}
      status="error"
      items={[
        { title: '已完成' },
        { title: '错误', description: '发生了一个错误' },
        { title: '等待中' },
      ]}
    />
  );
};
```

### 导航步骤条

导航样式的步骤条。

```tsx
import { PisellSteps } from '@pisell/materials';

export default () => {
  return (
    <PisellSteps
      type="navigation"
      current={1}
      items={[
        { title: '步骤1', description: '描述1' },
        { title: '步骤2', description: '描述2' },
        { title: '步骤3', description: '描述3' },
      ]}
    />
  );
};
```

### 横向滚动模式

当步骤条宽度不足时，启用横向滚动并显示左右箭头按钮。

```tsx
import { PisellSteps } from '@pisell/materials';

export default () => {
  return (
    <PisellSteps
      current={2}
      enableScrollMode
      scrollActionsConfig={{
        show: true,
        type: 'lrArrows',
        scrollDistance: 200,
      }}
      items={[
        { title: '步骤1', description: '描述1' },
        { title: '步骤2', description: '描述2' },
        { title: '步骤3', description: '描述3' },
        { title: '步骤4', description: '描述4' },
        { title: '步骤5', description: '描述5' },
        { title: '步骤6', description: '描述6' },
      ]}
    />
  );
};
```

## API

### PisellSteps

| 参数                | 说明                   | 类型                                         | 默认值         | 版本  |
| ------------------- | ---------------------- | -------------------------------------------- | -------------- | ----- |
| type                | 步骤条类型             | `'default' \| 'navigation'`                  | `'default'`    | 1.0.0 |
| progressDot         | 点状步骤条             | `boolean \| function`                        | `false`        | 1.0.0 |
| current             | 当前步骤（受控）       | `number`                                     | `0`            | 1.0.0 |
| defaultCurrent      | 默认当前步骤（非受控） | `number`                                     | `0`            | 1.0.0 |
| direction           | 步骤条方向             | `'horizontal' \| 'vertical'`                 | `'horizontal'` | 1.0.0 |
| size                | 步骤条尺寸             | `'small' \| 'default' \| 'large'`            | `'default'`    | 1.0.0 |
| status              | 当前步骤状态           | `'wait' \| 'process' \| 'finish' \| 'error'` | `'process'`    | 1.0.0 |
| initial             | 起始步骤索引           | `number`                                     | `0`            | 1.0.0 |
| items               | 步骤数据配置           | `StepItem[]`                                 | `[]`           | 1.0.0 |
| percent             | 当前步骤进度百分比     | `number`                                     | -              | 1.0.0 |
| labelPlacement      | 标签文本位置           | `'horizontal' \| 'vertical'`                 | `'horizontal'` | 1.0.0 |
| responsive          | 是否开启响应式         | `boolean`                                    | `true`         | 1.0.0 |
| onChange            | 步骤变更回调           | `(current: number) => void`                  | -              | 1.0.0 |
| className           | 自定义类名             | `string`                                     | -              | 1.0.0 |
| style               | 自定义样式             | `CSSProperties`                              | -              | 1.0.0 |
| progressDot         | 自定义点状步骤条渲染   | `boolean \| function`                        | `false`        | 1.0.0 |
| clickable           | 是否允许点击步骤切换   | `boolean`                                    | `false`        | 1.0.0 |
| allowClickFinished  | 是否允许点击已完成步骤 | `boolean`                                    | `true`         | 1.0.0 |
| gridLayout          | 是否开启栅格布局       | `boolean`                                    | `false`        | 1.0.0 |
| gridColumns         | 栅格列数               | `number`                                     | -              | 1.0.0 |
| itemGap             | 项间距（px）           | `number`                                     | -              | 1.0.0 |
| enableAnchor        | 是否开启锚链接         | `boolean`                                    | `false`        | 1.0.0 |
| anchorContainer     | 锚链接容器             | `string \| HTMLElement`                      | -              | 1.0.0 |
| mobileMode          | 移动端显示模式         | `'full' \| 'current' \| 'auto'`              | `'full'`       | 1.0.0 |
| mobileBreakpoint    | 移动端断点宽度（px）   | `number`                                     | `744`          | 1.0.0 |
| enableScrollMode    | 是否启用横向滚动模式   | `boolean`                                    | `false`        | 1.0.0 |
| scrollActionsConfig | 滚动箭头配置           | `ScrollActionsConfig`                        | -              | 1.0.0 |

### ScrollActionsConfig

| 参数           | 说明                     | 类型                                | 默认值       | 版本  |
| -------------- | ------------------------ | ----------------------------------- | ------------ | ----- |
| show           | 是否显示滚动箭头         | `boolean`                           | `true`       | 1.0.0 |
| type           | 箭头类型                 | `'lrArrows' \| 'tbArrows' \| 'dot'` | `'lrArrows'` | 1.0.0 |
| scrollDistance | 每次点击滚动的距离（px） | `number`                            | `200`        | 1.0.0 |

### StepItem

| 参数        | 说明       | 类型                                         | 默认值   | 版本  |
| ----------- | ---------- | -------------------------------------------- | -------- | ----- |
| title       | 标题       | `ReactNode`                                  | -        | 1.0.0 |
| subTitle    | 副标题     | `ReactNode`                                  | -        | 1.0.0 |
| description | 描述       | `ReactNode`                                  | -        | 1.0.0 |
| status      | 步骤状态   | `'wait' \| 'process' \| 'finish' \| 'error'` | `'wait'` | 1.0.0 |
| icon        | 自定义图标 | `ReactNode`                                  | -        | 1.0.0 |
| disabled    | 是否禁用   | `boolean`                                    | `false`  | 1.0.0 |
| hidden      | 是否隐藏   | `boolean`                                    | `false`  | 1.0.0 |
| onClick     | 点击回调   | `() => void`                                 | -        | 1.0.0 |
| className   | 自定义类名 | `string`                                     | -        | 1.0.0 |
| style       | 自定义样式 | `CSSProperties`                              | -        | 1.0.0 |

## 注意事项

1. `current` 和 `defaultCurrent` 不要同时使用，`current` 用于受控模式，`defaultCurrent` 用于非受控模式
2. 设置 `clickable` 后，可以点击步骤进行切换，但需要配合 `onChange` 使用
3. `type="navigation"` 时，建议横向布局使用，竖向布局可能显示效果不佳
4. 开启 `responsive` 后，在小屏幕设备上会自动适配布局
5. `enableScrollMode` 开启后，步骤条会强制使用横向布局，宽度不足时显示左右滚动箭头
6. 开启滚动模式时，`responsive` 属性会被忽略，不会自动切换为垂直布局

## FAQ

### 如何实现受控模式？

使用 `current` 属性并配合 `onChange` 回调：

```
const [current, setCurrent] = useState(0);

<PisellSteps current={current} onChange={setCurrent} items={items} />;
```

### 如何实现非受控模式？

使用 `defaultCurrent` 属性：

```
<PisellSteps defaultCurrent={0} items={items} />
```

### 如何自定义步骤图标？

在 `items` 中为每个步骤设置 `icon` 属性：

```
<PisellSteps
  items={[
    { title: '步骤1', icon: <UserOutlined /> },
    { title: '步骤2', icon: <SolutionOutlined /> },
  ]}
/>
```

### 如何禁用某个步骤的点击？

在 `items` 中为特定步骤设置 `disabled: true`：

```
<PisellSteps
  clickable
  items={[
    { title: '步骤1' },
    { title: '步骤2', disabled: true },
    { title: '步骤3' },
  ]}
/>
```
