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

# Steps

导航`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

引导用户按顺序完成多阶段的任务。

## 何时使用

当任务存在先后顺序时使用 Steps——结算流程、引导向导、发布流水线。它同样可以作为「用户旁观而非操作」的过程进度指示。

**推荐**

- 标题保持在一到两个词，细节放进 `content`。
- 整条步骤条由 `current` 驱动，状态从位置自动推导。
- 当回退到已完成步骤有意义时，提供 `onChange`。
- 流程较长或容器较窄时改用 `orientation="vertical"`。

**避免**

- 不要用 Steps 承载同级内容切换，请使用 Tabs。
- 不要用 Steps 表示单一的不确定操作，请使用 Spinner。
- 除非某一步确实失败或被跳过，否则不要逐项设置 `status`。

## 代码演示


### 基础用法
```tsx preview
import { Steps } from '@rockshin/tao-ui';

function StepsExample() {
  return (
    <Steps
      current={1}
      items={[
        { title: '已完成', content: '这一步已经完成。' },
        { title: '进行中', content: '正在处理。' },
        { title: '等待中', content: '尚未开始。' },
      ]}
    />
  );
}

export default StepsExample;
```

### 垂直与可点击
`onChange` 回调收到的是绝对步骤序号。点击当前步骤不会触发回调，`disabled` 的步骤始终不可交互。
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
import { useState } from 'react';

const items = [
  { title: '已完成', content: '这一步已经完成。' },
  { title: '进行中', content: '正在处理。' },
  { title: '等待中', content: '尚未开始。' },
  { title: '已锁定', content: '暂不可用。', disabled: true },
];

function ClickableSteps() {
  const [current, setCurrent] = useState(0);

  return (
    <Stack gap="lg">
      <Steps items={items} current={current} onChange={setCurrent} />
      <Steps
        items={items}
        current={current}
        onChange={setCurrent}
        orientation="vertical"
        style={{ maxWidth: 320 }}
      />
    </Stack>
  );
}

export default ClickableSteps;
```

### 状态、变体与尺寸
`status` 设置当前步骤的状态，其余步骤的状态由与当前位置的关系推导。`variant` 决定图标是实心还是描边，`size` 切换密度。
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

const items = [
  { title: '已完成', content: '这一步已经完成。' },
  { title: '进行中', content: '正在处理。' },
  { title: '等待中', content: '尚未开始。' },
];

function StepsStatus() {
  return (
    <Stack gap="lg">
      <Steps items={items} current={1} status="error" />
      <Steps items={items} current={1} variant="outlined" />
      <Steps items={items} current={1} size="small" variant="outlined" />
    </Stack>
  );
}

export default StepsStatus;
```

### 类型
`type` 改变整条步骤条的形态：`dot` 用小圆点替代数字图标，`navigation` 把每步变成带下划线指示的可点击标签，`panel` 则把步骤渲染成彼此咬合的缺口面板。
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
import { useState } from 'react';

const items = [
  { title: '第一步', content: '第一段说明' },
  { title: '第二步', content: '第二段说明' },
  { title: '第三步', content: '第三段说明' },
];

function StepsTypes() {
  const [current, setCurrent] = useState(1);

  return (
    <Stack gap="lg">
      <Steps items={items} current={current} type="dot" />
      <Steps
        items={items}
        current={current}
        type="navigation"
        onChange={setCurrent}
      />
      <Steps
        items={items}
        current={current}
        type="panel"
        onChange={setCurrent}
      />
      <Steps
        items={items}
        current={current}
        type="panel"
        variant="outlined"
        onChange={setCurrent}
      />
    </Stack>
  );
}

export default StepsTypes;
```

### 内联
`type="inline"` 渲染一条紧凑的圆点条，说明文字改由 Tooltip 承载。`offset` 沿主轴推移整条步骤条，`titlePlacement` 把标题移到圆点下方。
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';
import { useState } from 'react';

const items = [
  { title: '第一步', content: '第一段说明' },
  { title: '第二步', content: '第二段说明' },
  { title: '第三步', content: '第三段说明' },
];

function InlineSteps() {
  const [current, setCurrent] = useState(1);

  return (
    <Stack gap="lg">
      <Steps
        items={items}
        current={current}
        type="inline"
        onChange={setCurrent}
      />
      <Steps
        items={items}
        current={current}
        type="inline"
        titlePlacement="vertical"
        offset={1}
        onChange={setCurrent}
      />
    </Stack>
  );
}

export default InlineSteps;
```

### 进度与最大数量
`percent` 会在当前图标外圈画出进度环。`maxCount` 用于收拢过长的流程：被隐藏的区间折叠为一个禁用的省略步骤，而 `onChange` 依旧回传原始序号。
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

const items = [
  { title: '已完成', content: '这一步已经完成。' },
  { title: '进行中', content: '正在处理。' },
  { title: '等待中', content: '尚未开始。' },
];

function StepsProgress() {
  return (
    <Stack gap="lg">
      <Steps items={items} current={1} percent={60} />
      <Steps
        current={3}
        maxCount={5}
        items={Array.from({ length: 10 }, (_, index) => ({
          title: `步骤 ${index + 1}`,
        }))}
      />
    </Stack>
  );
}

export default StepsProgress;
```

### 自定义图标
`items[].icon` 替换单个步骤的图标。`iconRender` 替换全部图标，并会收到步骤序号、是否为当前步骤，以及用于渲染语义化图标容器的 `Icon` 组件。
```tsx preview
import { Steps } from '@rockshin/tao-ui';

const items = [
  { title: '已完成', content: '这一步已经完成。' },
  { title: '进行中', content: '正在处理。' },
  { title: '等待中', content: '尚未开始。' },
];

function CustomIconSteps() {
  return (
    <Steps
      items={items}
      current={1}
      iconRender={(_node, { index, active }) => (
        <span
          style={{
            width: 32,
            height: 32,
            borderRadius: 8,
            display: 'grid',
            placeItems: 'center',
            fontSize: 12,
            border: `1px solid ${active ? 'currentColor' : 'transparent'}`,
          }}
        >
          {index + 1}
        </span>
      )}
    />
  );
}

export default CustomIconSteps;
```

### 语义化 DOM 定制
每个部件都可以通过 `classNames` 与 `styles` 定位，单个步骤也能覆盖自己的部件。
使用 `finishIconBackground` 和 `finishIconColor` 可分别设置已完成步骤的内置圆形背景和对勾颜色，适用于默认、导航和面板类型；点状步骤和自定义图标不受影响。
```tsx preview
import { Steps } from '@rockshin/tao-ui';

function StyledSteps() {
  return (
    <Steps
      current={1}
      finishIconBackground="#e5f4e8"
      finishIconColor="#16a34a"
      items={[
        { title: '已完成', content: '这一步已经完成。' },
        { title: '进行中', content: '正在处理。' },
        { title: '等待中', content: '尚未开始。' },
      ]}
      styles={{ itemTitle: { letterSpacing: '0.02em' } }}
      classNames={{ itemContent: 'demo-step-content' }}
    />
  );
}

export default StyledSteps;
```

### 可点击切换
维护 `current` 并处理 `onChange`，步骤切换后同步展示当前内容。
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

import { useState } from 'react';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsClickable() {
  function Demo() {
    const [current, setCurrent] = useState(0);
    return (
      <Stack gap="md">
        <Steps items={basicItems} current={current} onChange={setCurrent} />
        <p style={{ color: 'var(--tao-color-text-secondary)', fontSize: 13 }}>
          current: {current}
        </p>
      </Stack>
    );
  }
  return <Demo />;
}
```

### 当前步骤出错
`status="error"` 明确标识当前步骤失败，错误原因由旁边的说明表达。
```tsx preview
import { Steps } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsErrorStatus() {
  return <Steps items={basicItems} current={1} status="error" />;
}
```

### 独立步骤状态
为单个步骤设置状态，可表达部分完成、失败和等待并存的流程。
```tsx preview
import { Steps } from '@rockshin/tao-ui';

export default function StepsPerStepStatus() {
  return (
    <Steps
      current={2}
      items={[
        { title: 'Done', content: 'Finished.' },
        { title: 'Failed', content: 'Something broke.', status: 'error' },
        { title: 'Running', content: 'In progress.' },
        { title: 'Queued', content: 'Not started.' },
      ]}
    />
  );
}
```

### 标题位置
控制标题相对步骤图形的位置，匹配可用空间。
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsTitlePlacement() {
  return (
    <Stack gap="lg">
      <Steps items={basicItems} current={1} titlePlacement="horizontal" />
      <Steps items={basicItems} current={1} titlePlacement="vertical" />
    </Stack>
  );
}
```

### 步骤内进度
通过 `percent` 展示当前步骤的进度，示例可切换进度值。
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

import { useState } from 'react';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsWithProgress() {
  function Demo() {
    const [percent, setPercent] = useState(40);
    return (
      <Stack gap="md">
        <Steps
          items={basicItems}
          current={1}
          percent={percent}
          onChange={() => setPercent((p) => (p >= 100 ? 10 : p + 30))}
        />
        <p style={{ color: 'var(--tao-color-text-secondary)', fontSize: 13 }}>
          percent: {percent}
        </p>
      </Stack>
    );
  }
  return <Demo />;
}
```

### 点状步骤
`type="dot"` 使用更紧凑的节点，适合状态追踪。
```tsx preview
import { Steps } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsDotStyle() {
  return <Steps items={basicItems} current={1} type="dot" />;
}
```

### 自定义步骤点
通过渲染回调定制步骤点，保留标题与状态信息。
```tsx preview
import { Steps } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsDotWithCustomDot() {
  return (
    <Steps
      items={basicItems}
      current={1}
      type="dot"
      iconRender={() => (
        <span
          style={{
            width: 10,
            height: 10,
            borderRadius: '50%',
            background: 'currentColor',
          }}
        />
      )}
    />
  );
}
```

### 导航型步骤
导航型步骤适合在多个流程阶段之间切换。
```tsx preview
import { Steps } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function StepsNavigation() {
  function Demo() {
    const [current, setCurrent] = useState(0);
    return (
      <Steps
        type="navigation"
        current={current}
        onChange={setCurrent}
        items={[
          { title: 'Step 1', content: 'First' },
          { title: 'Step 2', content: 'Second' },
          { title: 'Step 3', content: 'Third' },
        ]}
      />
    );
  }
  return <Demo />;
}
```

### 面板型步骤
面板型步骤为标题和说明提供更大的操作区域。
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

import { useState } from 'react';

export default function StepsPanel() {
  function Demo() {
    const [current, setCurrent] = useState(1);
    return (
      <Stack gap="lg">
        <Steps
          type="panel"
          current={current}
          onChange={setCurrent}
          items={[
            { title: 'One' },
            { title: 'Two' },
            { title: 'Three' },
            { title: 'Four' },
          ]}
        />
        <Steps
          type="panel"
          variant="outlined"
          current={current}
          onChange={setCurrent}
          items={[
            { title: 'One' },
            { title: 'Two' },
            { title: 'Three' },
            { title: 'Four' },
          ]}
        />
      </Stack>
    );
  }
  return <Demo />;
}
```

### 限制可见步骤
用 `maxCount` 折叠较长流程，移动当前步骤时观察显示范围变化。
```tsx preview
import { Steps } from '@rockshin/tao-ui';

export default function StepsMaxCount() {
  return (
    <Steps
      current={3}
      maxCount={5}
      items={Array.from({ length: 10 }, (_, index) => ({
        title: `Step ${index + 1}`,
      }))}
    />
  );
}
```

### 禁用某个步骤
单独禁用不可进入的步骤，不影响其他可点击步骤。
```tsx preview
import { Steps } from '@rockshin/tao-ui';

export default function StepsDisabledStep() {
  return (
    <Steps
      current={1}
      onChange={() => {}}
      items={[
        { title: 'First' },
        { title: 'Second' },
        { title: 'Locked', disabled: true },
      ]}
    />
  );
}
```

### 长标题截断
长标题在受限宽度内截断，详细解释放在步骤内容中。
```tsx preview
import { Stack, Steps } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsEllipsis() {
  return (
    <Stack gap="lg">
      <div style={{ maxWidth: 520 }}>
        <Steps items={basicItems} current={1} ellipsis />
      </div>
      <div style={{ maxWidth: 520 }}>
        <Steps
          items={[
            {
              title: 'A rather long first title',
              subTitle: 'with a subtitle',
              content: 'And a long description that will be truncated.',
            },
            { title: 'Second', content: 'Also truncated when needed.' },
          ]}
          current={0}
          ellipsis
        />
      </div>
    </Stack>
  );
}
```

### 起始序号
通过 `initial` 调整显示序号，`current` 仍使用组件约定的索引。
```tsx preview
import { Steps } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsInitial() {
  return <Steps items={basicItems} initial={2} current={3} />;
}
```

### 继承全局配置
继承尺寸与外观配置，也可以在单个步骤组件上覆盖。
```tsx preview
import { Steps, TaoProvider } from '@rockshin/tao-ui';

const basicItems = [
  { title: 'Finished', content: 'This step is done.' },
  { title: 'In Progress', content: 'Working on it now.' },
  { title: 'Waiting', content: 'Not started yet.' },
];

export default function StepsProviderInherit() {
  return (
    <TaoProvider size="small">
      <Steps items={basicItems} current={1} variant="outlined" />
    </TaoProvider>
  );
}
```

## API


### [#](#steps)Steps



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| items | Step data. | `StepItem[] | undefined` | `-` |
| current | Current step, counted from 0. Overridden per step by `items.status`. | `number | undefined` | `-` |
| initial | Numbering offset — the first step is numbered `initial + 1`. | `number | undefined` | `-` |
| status | Status of the `current` step; the others derive theirs from position. | `StepsStatus | undefined` | `process` |
| orientation | Layout axis. | `StepsOrientation | undefined` | `-` |
| titlePlacement | Where the title sits relative to the icon. | `StepsTitlePlacement | undefined` | `-` |
| responsive | Collapse to `vertical` below 576px. | `boolean | undefined` | `true` |
| size | Visual density. | `StepsSize | undefined` | `-` |
| variant | Style variant. | `StepsVariant | undefined` | `filled` |
| type | Steps flavour. | `StepsType | undefined` | `-` |
| percent | Progress ring on the `process` icon; ignored by `type="inline"`. | `number | undefined` | `-` |
| maxCount | Collapse to at most N steps (`>= 3`); hidden ranges become an ellipsis step. | `number | undefined` | `-` |
| offset | Leading flex offset for `type="inline"`. | `number | undefined` | `-` |
| ellipsis | Truncate overflowing titles, subtitles, and content. | `boolean | undefined` | `-` |
| iconRender | Replace the icon node of every step. | `StepsIconRender | undefined` | `-` |
| finishIconBackground | Background of the built-in finished-step circle. | `BackgroundColor | undefined` | `-` |
| finishIconColor | Color of the built-in finished-step check mark. | `Color | undefined` | `-` |
| onChange | Fires with the absolute step index when a non-current step is activated. | `((current: number) => void) | undefined` | `-` |
| className | 节点类名 | `string | undefined` | `-` |
| style | 节点样式 | `CSSProperties | undefined` | `-` |

