---
title: 开发文档
order: 3
category: pro
---

# PisellSteps 开发文档

## 1. 组件基本信息

### 1.1 组件名称

- **中文名称**：步骤条
- **英文名称**：PisellSteps
- **组件编号**：pcp_na_steps_V1.0

### 1.2 组件版本

- **当前版本**：1.0.0
- **更新日期**：2025-11-28
- **版本说明**：首次发布

### 1.3 组件分类

- **类型**：Pro Components
- **分类**：Navigation（导航类）
- **依赖**：Ant Design Steps

## 2. 组件描述

PisellSteps 是一个基于 Ant Design Steps 组件进行二次封装和增强的步骤条组件。用于引导用户完成多步骤任务的核心导航组件，通过可视化方式展示当前进度、已完成步骤和待完成步骤。

### 2.1 核心能力

1. **流程可视化**：清晰展示任务阶段和当前进度
2. **进度反馈**：实时显示步骤状态（已完成/进行中/等待/错误）
3. **导航控制**：支持步骤间的前进、返回和跳转操作
4. **错误处理**：明确标识问题步骤并提供视觉反馈
5. **高度定制**：支持丰富的样式和布局配置
6. **灵活扩展**：支持自定义图标、内容和渲染

### 2.2 适用场景

- 多步骤表单提交流程（用户注册、问卷调查）
- 订单处理流程（购物车 → 支付 → 完成）
- 复杂任务分步操作（配置向导、系统设置）
- 审批流程（申请 → 审核 → 批准）
- 时间轴展示（竖向布局）

## 3. 组件需求点罗列

### 3.1 功能需求

- [x] 基于 Ant Design Steps 二次封装
- [x] 支持受控和非受控两种模式
- [x] 支持横向（horizontal）和竖向（vertical）布局
- [x] 支持三种尺寸：large、default、small
- [x] 支持多种展示类型：default（基础）、dot（点状）、navigation（导航）
- [x] 支持步骤状态：wait、process、finish、error
- [x] 支持自定义步骤图标（icon）
- [x] 支持自定义步骤标题和描述
- [x] 支持步骤点击交互（可配置是否可点击）
- [x] 支持步骤变更回调
- [x] 支持进度百分比显示（在连接器上）
- [x] 支持动态步骤（通过 items 配置）
- [x] 支持自定义连接器样式
- [x] 支持响应式布局和自适应

### 3.2 样式需求

- [x] 支持自定义整体容器样式（className、style）
- [x] 支持自定义标识区样式（大小、颜色、背景、边框、圆角）
- [x] 支持自定义文本区样式（字体、颜色、粗细、间距）
- [x] 支持自定义连接器样式（粗细、颜色、位置）
- [x] 支持主题色配置
- [x] 支持栅格布局配置

### 3.3 交互需求

- [x] 支持点击已完成步骤返回
- [x] 支持点击事件回调
- [x] 支持步骤切换动画（可选）
- [x] 支持键盘导航（可选）
- [x] 支持禁用特定步骤

## 4. 组件 API 设计

### 4.1 PisellSteps Props

| 属性           | 说明                   | 类型                                                                   | 默认值         | 版本  |
| -------------- | ---------------------- | ---------------------------------------------------------------------- | -------------- | ----- |
| 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 \| ((dot, {index, status, title, description}) => ReactNode)` | `false`        | 1.0.0 |

### 4.2 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 |
| onClick     | 点击回调     | `() => void`                                 | -        | 1.0.0 |
| className   | 自定义类名   | `string`                                     | -        | 1.0.0 |
| style       | 自定义样式   | `CSSProperties`                              | -        | 1.0.0 |

### 4.3 扩展 Props（增强功能）

| 属性                | 说明                   | 类型                            | 默认值     | 版本  |
| ------------------- | ---------------------- | ------------------------------- | ---------- | ----- |
| clickable           | 是否允许点击步骤切换   | `boolean`                       | `false`    | 1.0.0 |
| allowClickFinished  | 是否允许点击已完成步骤 | `boolean`                       | `true`     | 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 |

### 4.4 ScrollActionsConfig（滚动箭头配置）

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

## 5. 组件模块拆解

### 5.1 组件结构层级

```
PisellSteps（主容器）
├── 样式配置层（处理尺寸、方向、主题）
├── 状态管理层（受控/非受控逻辑）
├── 步骤渲染层
│   ├── StepItem（单个步骤）
│   │   ├── StepIcon（标识区）
│   │   │   ├── 序号显示
│   │   │   ├── 图标显示
│   │   │   ├── 自定义内容
│   │   │   └── 状态指示
│   │   ├── StepContent（文本区）
│   │   │   ├── 标题
│   │   │   ├── 副标题
│   │   │   ├── 描述
│   │   │   └── 自定义内容
│   │   └── StepConnector（连接器）
│   │       ├── 线条渲染
│   │       ├── 进度百分比
│   │       └── 自定义样式
│   └── 步骤集合渲染
└── 交互逻辑层（点击、切换、回调）
```

### 5.2 核心子组件

#### 5.2.1 StepIcon 组件

- **职责**：渲染步骤标识区（序号/图标/自定义内容）
- **输入**：图标配置、状态、索引
- **输出**：标识区 UI

#### 5.2.2 StepContent 组件

- **职责**：渲染步骤文本区（标题/副标题/描述）
- **输入**：文本内容、状态
- **输出**：文本区 UI

#### 5.2.3 StepConnector 组件

- **职责**：渲染步骤连接器（线条/进度）
- **输入**：连接器样式、进度百分比、状态
- **输出**：连接器 UI

### 5.3 工具函数模块

#### utils/index.ts

```
/**
 * 计算当前步骤的进度百分比
 */
export function calculateProgress(current: number, total: number): number;

/**
 * 判断步骤是否可点击
 */
export function isStepClickable(
  index: number,
  current: number,
  status: StepStatus,
  clickable: boolean,
  allowClickFinished: boolean
): boolean;

/**
 * 获取步骤状态
 */
export function getStepStatus(
  index: number,
  current: number,
  status?: StepStatus
): StepStatus;

/**
 * 合并样式类名
 */
export function mergeStepClassName(
  baseClass: string,
  status: StepStatus,
  customClass?: string
): string;
```

### 5.4 自定义 Hooks

#### hooks/useStepsState.ts

```
/**
 * 管理步骤条状态（受控/非受控）
 */
export function useStepsState(
  current?: number,
  defaultCurrent?: number,
  onChange?: (current: number) => void
): [number, (value: number) => void];
```

#### hooks/useStepClick.ts

```
/**
 * 处理步骤点击逻辑
 */
export function useStepClick(
  currentStep: number,
  clickable: boolean,
  allowClickFinished: boolean,
  onStepChange: (step: number) => void
): (index: number, item: StepItem) => void;
```

## 6. 组件实现方案

### 6.1 技术栈

- **React**：18.x
- **TypeScript**：严格模式
- **Ant Design**：5.x（Steps 组件）
- **Less**：样式预处理器
- **classnames**：类名合并工具

### 6.2 实现思路

#### 6.2.1 基础封装

1. 基于 Ant Design 的 `Steps` 组件进行封装
2. 继承 Ant Design Steps 的所有原生功能
3. 在原生基础上扩展增强功能

#### 6.2.2 状态管理

```
// 受控模式：由外部 props.current 控制
// 非受控模式：由内部 state 管理，使用 defaultCurrent 初始化

const [innerCurrent, setInnerCurrent] = useState(defaultCurrent || 0);
const currentStep = current !== undefined ? current : innerCurrent;
```

#### 6.2.3 步骤渲染

```
// 通过 items 数组配置步骤
// 每个 item 可独立配置状态、图标、内容等
// 支持动态显示/隐藏步骤

const renderSteps = () => {
  return items
    .filter((item) => !item.hidden)
    .map((item, index) => ({
      ...item,
      status: getStepStatus(index, currentStep, item.status),
      onClick: handleStepClick(index, item),
    }));
};
```

#### 6.2.4 点击交互

```
// 支持可配置的点击行为
// 1. 全局 clickable 控制是否可点击
// 2. allowClickFinished 控制已完成步骤是否可点击
// 3. 单个步骤的 disabled 属性
// 4. 自定义 onClick 回调

const handleStepClick = (index: number, item: StepItem) => {
  if (
    !isStepClickable(
      index,
      currentStep,
      item.status,
      clickable,
      allowClickFinished
    )
  ) {
    return;
  }

  item.onClick?.();
  onChange?.(index);
};
```

#### 6.2.5 样式定制

```
// 1. 通过 Less 变量定义主题色
// 2. 通过 className 支持外部样式覆盖
// 3. 通过 style 支持内联样式
// 4. 通过 CSS 变量控制局部样式
```

### 6.3 兼容性处理

1. **向下兼容**：完全兼容 Ant Design Steps 的所有 API
2. **渐进增强**：新增的功能通过额外 props 提供，不影响基础使用
3. **类型安全**：所有 props 都有明确的 TypeScript 类型定义

### 6.4 性能优化

1. **按需渲染**：仅渲染可见步骤
2. **事件委托**：步骤点击使用事件委托减少事件监听器
3. **memo 优化**：对子组件使用 React.memo 避免不必要的重渲染
4. **样式优化**：使用 CSS 变量减少样式计算

### 6.5 响应式设计

```
// 1. 默认宽度撑满父容器
// 2. 宽度减少时，步骤间距自动缩小（最小 16px）
// 3. 再次缩小时，启动横向滚动
// 4. 可通过 responsive prop 控制是否开启响应式

@media (max-width: 768px) {
  .pisell-steps {
    overflow-x: auto;

    &-item {
      min-width: 120px;
    }
  }
}
```

### 6.6 横向滚动模式

```
// 当 enableScrollMode 为 true 时：
// 1. 使用 PisellScrollView 组件包裹步骤条
// 2. 强制 direction='horizontal' 和 responsive={false}
// 3. 当内容宽度超出容器宽度时，显示左右滚动箭头
// 4. 通过 scrollActionsConfig 配置箭头样式和滚动距离

{enableScrollMode ? (
  <PisellScrollView
    overflow="x"
    scrollbarStyle="none"
    scrollActionsConfig={{
      show: true,
      type: 'lrArrows',
      ...scrollActionsConfig,
    }}
  >
    <AntdSteps direction="horizontal" responsive={false} />
  </PisellScrollView>
) : (
  <AntdSteps />
)}
```

## 7. 通用性与可扩展性

### 7.1 通用性设计

1. **场景通用**：适配多种业务场景（表单、订单、审批等）
2. **样式通用**：支持多种展示样式和布局方式
3. **数据通用**：通过配置化的 items 支持任意步骤数量
4. **交互通用**：支持多种交互模式（线性/非线性）

### 7.2 可扩展性设计

1. **插槽扩展**：支持自定义图标、标题、描述等内容
2. **样式扩展**：支持通过 className 和 style 自定义样式
3. **事件扩展**：提供丰富的回调事件
4. **功能扩展**：预留扩展接口，方便后续功能增强

### 7.3 扩展示例

#### 自定义图标

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

#### 自定义渲染

```
<PisellSteps
  progressDot={(dot, { index, status, title }) => (
    <Popover content={`步骤 ${index + 1}: ${title}`}>
      {dot}
    </Popover>
  )}
/>
```

#### 自定义样式

```
<PisellSteps
  className="custom-steps"
  style={{ padding: '20px' }}
/>
```

## 8. 开发注意事项

### 8.1 代码规范

1. 必须使用 TypeScript 严格模式
2. 所有函数和组件必须添加 JSDoc 注释
3. Props 接口必须继承 Ant Design Steps 的原生 Props
4. 样式类名必须使用 `pisell-steps-` 前缀

### 8.2 依赖管理

1. 必须将 Ant Design 作为 peerDependencies
2. 不引入额外的第三方依赖（除非必要）
3. 工具函数优先使用项目内的 utils

### 8.3 测试要求

1. 必须编写单元测试覆盖核心功能
2. 必须测试受控和非受控模式
3. 必须测试不同 props 组合的渲染结果
4. 必须测试交互行为（点击、切换等）

### 8.4 文档要求

1. 必须提供完整的使用文档和示例
2. 必须提供 API 文档说明
3. 必须提供常见问题解答

## 9. 里程碑计划

### 9.1 开发阶段

- [x] 第一步：了解项目结构
- [x] 第二步：了解需求
- [x] 第三步：产出开发文档
- [x] 第四步：开发 TS 定义
- [x] 第五步：开发组件框架
- [x] 第六步：依次组件实现
- [x] 第七步：开发 lowcode meta 信息
- [x] 第八步：开发组件测试用例文档
- [x] 第九步：开发组件测试
- [x] 第十步：开发组件文档
- [x] 第十一步：查漏补缺
- [x] 第十二步：完成组件开发

### 9.2 质量保证

- [x] 代码审查
- [x] 单元测试通过
- [x] 样式审查
- [x] 文档审查
- [x] 低代码平台集成测试

## 10. 参考资料

- [Ant Design Steps 组件](https://ant.design/components/steps-cn)
- [Figma 设计稿](https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=12031-9962&m=dev)
- [项目开发规范](.cursor/rules/create-component-rule.mdc)
