# @dt-dds/react-stepper 中文文档

规范地址：https://npmcn.com/package/%40dt-dds/react-stepper/

版本：1\.0\.0-beta\.69
npm 元数据更新时间：2026-11-13T11:46:11.223Z
中文译文更新时间：2026-11-13T01:59:14.887Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dt-dds/react-stepper
原文对照：https://npmcn.com/package/%40dt-dds/react-stepper/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：62.2 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：react \>=17\.0\.2，react-dom \>=17\.0\.2，@emotion/css ^11\.7\.1，@emotion/react ^11\.8\.2，@emotion/styled ^11\.8\.1
- 首次发布：2025-08-06T17:19:31.161Z
- 最新版本发布：2026-11-13T11:46:10.829Z
- 近 30 天下载量：2475（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 29 个）

## 中文简介

阶梯通过编号,项目符号,或以图标为基础的相继步骤传递进度.

## 安装

```sh
npm install @dt-dds/react-stepper
```

也可以使用：`pnpm add @dt-dds/react-stepper`、`yarn add @dt-dds/react-stepper`、`bun add @dt-dds/react-stepper`

## README

# 步进

阶梯通过编号,项目符号,或以图标为基础的相继步骤传递进度.

它们支持各种状态,包括已完成、不完整、警告、错误和残疾.

## 图片参考

[图片](https://www.figma.com/design/kMk36nv0ZT4AHhBbw9jq0S/%E2%86%B3-1.-Daimler-Truck-DDS--Beta-?node-id=21077-21455&t=Q2vzJQbSCO9jHwxx-4)

## 步进用法

```jsx
import { Stepper } from '@dt-dds/react-stepper';

export const App = () => {
  return (
    <Stepper>
      <Stepper.Step
        title='Completed Step'
        description='This step is done'
        state='completed'
      />
      <Stepper.Step
        title='Current Step'
        description='Working on this'
        state='incomplete'
        isActive={true}
      />
      <Stepper.Step
        title='Warning Step'
        description='Needs attention'
        state='warning'
      />
      <Stepper.Step
        title='Error Step'
        description='Something went wrong'
        state='error'
      />
      <Stepper.Step
        title='Disabled Step'
        description='Not available yet'
        state='disabled'
      />
    </Stepper>
  );
};
```

## 备选案文

### 数字变量( 默认)

```jsx
<Stepper variant='number'>
  <Stepper.Step title='Step 1' />
  <Stepper.Step title='Step 2' />
  <Stepper.Step title='Step 3' />
</Stepper>
```

### 符号变量

```jsx
<Stepper variant='bullet'>
  <Stepper.Step title='Step 1' />
  <Stepper.Step title='Step 2' />
  <Stepper.Step title='Step 3' />
</Stepper>
```

### 图标变量

```jsx
import { Icon } from '@dt-dds/react-icon';

<Stepper variant='icon'>
  <Stepper.Step title='Upload' icon={<Icon code='upload' size='small' />} />
  <Stepper.Step title='Process' icon={<Icon code='settings' size='small' />} />
  <Stepper.Step
    title='Complete'
    icon={<Icon code='check_circle' size='small' />}
  />
</Stepper>;
```

## 使用Stepper Hook 软件

使用Stepper钩为后继器提供了一个完整的状态管理解决方案,包括导航,完成跟踪和边界检查.

```jsx
import { useStepper } from '@dt-dds/react-stepper';

export const ControlledStepper = () => {
  const { activeStep, handleNext, handleBack, canGoNext, canGoBack } =
    useStepper({
      initialStep: 0,
      totalSteps: 3,
    });

  return (
    <>
      <Stepper activeStep={activeStep}>
        <Stepper.Step title='Step 1' description='First step' />
        <Stepper.Step title='Step 2' description='Second step' />
        <Stepper.Step title='Step 3' description='Third step' />
      </Stepper>

      <button onClick={handleBack} disabled={!canGoBack}>
        Back
      </button>
      <button onClick={handleNext} disabled={!canGoNext}>
        Next
      </button>
    </>
  );
};
```

## 使用Stepper Hook API 软件

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `initialStep` | `number` | `0` | 初始主动步骤( 基于 0 ) |
| `totalSteps` | `number` | —— 说 | 步骤总数(用于边界检查) |

### 使用Stepper 返回值

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `activeStep` | `number` | 当前活动步骤索引 |
| `isFirstStep` | `boolean` | 目前是否处于第一步 |
| `isLastStep` | `boolean` | 目前是否在最后一步 |
| `canGoNext` | `boolean` | 是否允许导航到下一步 |
| `canGoBack` | `boolean` | 是否允许向上一步导航 |
| `completedSteps` | `Set<number>` | 一套已完成的步数指数 |
| `handleNext` | `() => void` | 导航到下一步 |
| `handleBack` | `() => void` | 导航到上一步 |
| `handleChangeStep` | `(step: number) => void` | 导航到特定步骤 |
| `handleReset` | `() => void` | 重置为第一步并清除已完成的步骤 |
| `markStepComplete` | `(step: number) => void` | 将特定步骤标为已完成 |
| `markStepIncomplete` | `(step: number) => void` | 将特定步骤标为不完整 |
| `isStepComplete` | `(step: number) => boolean` | 检查特定步骤是否完成 |

## 属性

### 步进道具

| 财产 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `children` | `ReactNode` | —— 说 | 所需步骤组件 |
| `orientation` | `"vertical" | "horizontal"` | `vertical` | 步进方向 |
| `variant` | `"number" | "bullet" | "icon"` | `number` | 步骤指标的视觉样式 |
| `activeStep` | `number` | —— 说 | 主动步骤索引(基于 0) |
| `dataTestId` | `string` | `stepper` | 步进容器的测试标识符 |

### 步骤道具

| 财产 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `title` | `string` | —— 说 | 步骤的标题文本 |
| `description` | `string` | —— 说 | 描述该步骤的文字 |
| `state` | `"completed" | "warning" | "error" | "disabled" | "incomplete"` | `incomplete` | 步骤的可视状态 |
| `isActive` | `boolean` | `false` | 该步骤是否当前活动 |
| `icon` | `ReactNode` | —— 说 | 自定义图标变量 |
| `dataTestId` | `string` | `step-{index}` | 测试该步骤的标识符 |

## 堆栈

-   [类型脚本](https://www.typescriptlang.org/) 用于静态类型检查
-   [反应](https://reactjs.org/) — JavaScript 用户界面库
-   [情感](https://emotion.sh/docs/introduction) 用于使用 JavaScript 写入 Css 样式
-   [故事书](https://storybook.js.org/) ——由Vite供电的UI组件环境
-   [欢乐](https://jestjs.io/) - JavaScript 测试框架
-   [反应测试库](https://testing-library.com/) - 以用户为中心测试用户界面组件
-   [ESLint 语录](https://eslint.org/) 代码林入
-   [高级](https://prettier.io/) 用于代码格式
-   [苏普](https://github.com/egoist/tsup) - 由Esbuild供电的脚本捆绑机
-   [雅伦](https://yarnpkg.com/) 从管理软件包

## 图标

-   `yarn build` - 制作软件包
-   `yarn dev` - 在当地运行软件包
-   `yarn lint` - 将所有文件输入此软件包
-   `yarn test` - 测试所有单位
-   `yarn test:report` - 打开测试覆盖报告
-   `yarn test:update:snapshot` - 进行所有单元测试并更新快照

## 汇编

运行 `yarn build` 从软件包的根部 [齐声](https://tsup.egoist.dev/) 将原始的 TypeScript 和 React 代码编译为普通 JavaScript .

这个 `/dist` 文件夹包含编译输出.

```bash
stepper
└── dist
    ├── index.d.ts  <-- Types
    ├── index.js    <-- CommonJS version
    └── index.mjs   <-- ES Modules version
    ...
```

## 版本

跟着 [语义版本](https://semver.org/)

## 许可证

许可证根据 [MIT 许可证](https://npmcn.com/package/%40dt-dds/react-stepper/LICENSE)

## 常见问题

### @dt-dds/react-stepper 是什么？

阶梯通过编号,项目符号,或以图标为基础的相继步骤传递进度\.

### 如何安装 @dt-dds/react-stepper？

在项目目录运行 npm install @dt-dds/react-stepper，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=17\.0\.2）、react-dom（\>=17\.0\.2）、@emotion/css（^11\.7\.1）、@emotion/react（^11\.8\.2）、@emotion/styled（^11\.8\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dt-dds/react-stepper 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dt-dds/react-stepper 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @dt-dds/react-stepper 可以商用吗？

@dt-dds/react-stepper 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dt-dds/react-stepper 的下载量有多少？

根据 npm 官方下载统计，@dt-dds/react-stepper 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,475 次，日均约 83 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dt-dds/react-stepper 还在维护吗？

最新版本 1\.0\.0-beta\.69 发布于 2026/11/13（今天）；至今共发布 39 个版本，其中过去 12 个月发布了 29 个；首次发布于 2025/08/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。