---
title: 设计文档
order: 2
category: pro
---

# PisellProcedure 设计文档

## 1. 资源链接

### 任务链接
https://m1ed09stz4r.feishu.cn/wiki/KhgRwDR5CiQjbbkqG8mcWR1Snnf

### Figma 设计稿链接
https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=11932-6736

### Figma 完整 MCP 链接
@https://www.figma.com/design/pM8Ho6d7kCMv9vIBvFHUlj/Pisell-2.0-Component-Library?node-id=11932-6737&m=dev

## 2. 组件概述

- **组件名称（英文）**：Procedure
- **组件编号**：pcp_de_procedure_V1.0
- **组件类型**：Pro Components
- **组件分类**：Data Entry
- **简介**：Procedure 是一个用于管理多步骤流程的复合容器组件。它集成了步骤导航、内容操作、实时信息反馈和动作执行功能，通过头部步骤条、中部内容与信息分区、底部操作区的结构，引导用户完成复杂流程（如订单创建、数据配置），并确保操作过程中的实时预览和错误预防。

## 3. 版本信息

- **版本**：1.0
- **更新简介**：首次发布

## 4. 需求来源

- 需要处理多步骤流程的界面（如电商结账、用户注册、产品配置），要求步骤清晰、操作高效
- 用户需在流程中实时查看操作摘要或预览，以减少错误（如订单确认页）
- 底部操作区需固定显示主要动作，避免用户频繁滚动，提升任务完成率

## 5. 组件设计目的

1. **简化复杂流程**：通过步骤导航拆解多步任务，降低用户认知负荷
2. **实时反馈增强信心**：内容区操作即时同步到信息区，提供预览效果，减少误操作
3. **提升操作效率**：固定底部操作区确保主要动作始终可访问，优化交互路径
4. **保证一致性**：统一流程类界面的交互模式，符合用户心智模型

## 6. 适用场景

- **多步骤流程页**：商品配置、下单、审批、注册引导等
- **复杂表单提交**：分阶段信息填写，如"基础信息 > 附加设置 > 预览确认"
- **电商结账流程**：步骤为"地址确认→支付方式→订单预览"，信息区实时显示订单摘要
- **配置向导**：系统设置、产品配置等需要多步完成的操作

## 7. UI 设计

### 7.1 整体结构

基于 `PisellLayout`、`PisellSteps`、`PisellModal` 组件来生成该组件，分为三大区域：

1. **头部区域（Header）**：步骤导航
   - 左侧：返回/上一步按钮（插槽）
   - 中间：步骤条（PisellSteps）
   - 右侧：关闭按钮（插槽）

2. **主体区域（Body）**：左右分栏布局
   - 左侧：内容区（contentSlot）- 主要操作区域，跟随整体页面滚动
   - 右侧：信息区（sidebarSlot）- 实时预览/摘要，使用 sticky 定位，有独立滚动条

3. **底部操作区（Footer）**：固定或悬浮于底部
   - 左侧：移动端总结按钮（summaryButton）
   - 中间：自定义内容插槽（leftSlot）
   - 右侧：操作按钮组（actions）

> 注意：该组件是纯容器组件，所有内容都通过插槽控制

### 7.2 响应式规则

#### 7.2.1 信息区宽度自适应

| 屏幕宽度 | 信息区宽度 | 内容区 | 特殊处理 |
|---------|-----------|--------|---------|
| ≥1366px | 405px（固定） | 自适应 | 标准布局 |
| 1133px-1366px | 405px | 随宽度减少 | - |
| 960px-1133px | 376px | 随宽度减少 | - |
| 744px-960px | 290px | 随宽度减少 | - |
| <744px | 隐藏 | 占满宽度 | 移动端模式 |

#### 7.2.2 布局模式

- **固定宽度模式（fixed）**：信息区按断点固定宽度，内容区自适应
- **比例模式（ratio）**：按照设定比例（如 7:3）分配宽度

#### 7.2.3 头部步骤条

- 当头部区域宽度不足时，步骤条另起一行，与返回/关闭按钮上下排列
- 当步骤条一行展示不下时，开启横向滚动，并出现箭头指示

#### 7.2.4 底部操作区

- 当宽度不足以放下所有操作按钮时，次序列的按钮依次放入 More 下拉菜单
- 根据屏幕自适应计算 More 菜单中的按钮
- 最后一个按钮默认触发下一步事件

#### 7.2.5 移动端适配

- 信息区隐藏
- 显示总结按钮（购物车图标）
- 点击总结按钮，用 PisellModal 从底部拉起弹窗展示信息区内容
- **底部操作区自动改为吸底悬浮模式**（`position: 'float-all'`），固定在屏幕底部，带阴影效果，无视用户配置的 position 参数

## 8. 配置项详解

### 8.1 通用配置

| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| mode | 'page' \| 'modal' | 'page' | 组件使用模式 |
| showHeader | boolean | true | 是否显示头部区域 |
| showSidebar | boolean | true | 是否显示信息区（侧边栏） |
| showFooter | boolean | true | 是否显示底部区域 |
| defaultCurrent | number | 0 | 初始步骤索引（从 0 开始） |

**mode 模式说明：**
- **page（页面模式）**：默认模式，应用所有响应式规则，包括移动端适配
- **modal（弹窗模式）**：禁用移动端响应式行为，适用于在 Modal/Drawer 中使用

### 8.2 头部区域（headerProps）

#### 8.2.1 插槽配置

| 配置项 | 类型 | 说明 |
|-------|------|------|
| left | ReactNode | 左侧插槽（返回/上一步按钮、图标等） |
| right | ReactNode | 右侧插槽（关闭按钮、图标等） |

#### 8.2.2 样式配置

| 配置项 | 类型 | 说明 |
|-------|------|------|
| className | string | 自定义类名 |
| style | CSSProperties | 自定义样式（背景、边框、圆角、padding、阴影等） |

#### 8.2.3 步骤条配置（stepsProps）

| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| items | StepItem[] | [] | 步骤列表 |
| current | number | 0 | 当前步骤索引 |
| 其他 | - | - | 透传给 PisellSteps 组件的所有属性 |

#### 8.2.4 返回按钮配置

| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| showBackOnFirstStep | boolean | false | 第一步时是否显示返回按钮 |

#### 8.2.5 返回确认弹窗配置（backConfirmModal）

| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| enabled | boolean | true | 是否启用返回确认弹窗 |
| title | string | '提示' | 弹窗标题（支持多语言） |
| describe | string | - | 弹窗描述内容（支持多语言） |
| footer | array | - | 弹窗底部按钮配置数组 |

**footer 配置示例：**
```javascript
footer: [
  { text: '保留', action: 'cancel' },
  { text: '清除', type: 'primary', action: 'confirm' }
]
```

#### 8.2.6 关闭确认弹窗配置（closeConfirmModal）

| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| enabled | boolean | false | 是否启用关闭确认弹窗 |
| title | string | '确认退出？' | 弹窗标题（支持多语言） |
| describe | string | - | 弹窗描述内容（支持多语言） |
| footer | array | - | 弹窗底部按钮配置数组 |

### 8.3 主体区域（bodyProps）

#### 8.3.1 布局配置

| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| direction | 'horizontal' \| 'vertical' | 'horizontal' | 排列方向 |
| layoutMode | 'fixed' \| 'ratio' | 'fixed' | 布局模式 |
| layoutRatio | string | '7:3' | 内容区与信息区比例（仅 ratio 模式生效） |

**direction 说明：**
- 'horizontal' - 横向排列（左右布局，默认）
- 'vertical' - 纵向排列（上下布局）

**layoutRatio 可选值：**
- '7:3' - 内容区 70%，信息区 30%
- '6:4' - 内容区 60%，信息区 40%

#### 8.3.2 内容区配置

| 配置项 | 类型 | 说明 |
|-------|------|------|
| contentSlot | ReactNode | 内容区插槽 |
| contentClassName | string | 内容区自定义类名 |
| contentStyle | CSSProperties | 内容区自定义样式 |

**内容区滚动行为：**
- 内容区跟随整体页面滚动，不设置独立的滚动条
- 内容区高度由内容自然撑开，不限制最大高度
- 当内容超出视口时，通过整体页面滚动查看

#### 8.3.3 信息区配置

| 配置项 | 类型 | 说明 |
|-------|------|------|
| sidebarSlot | ReactNode | 信息区插槽 |
| sidebarClassName | string | 信息区自定义类名 |
| sidebarStyle | CSSProperties | 信息区自定义样式 |

**信息区滚动行为：**
- 信息区使用 `position: sticky` 定位，固定在视口顶部
- 信息区高度通过 `useElementHeight` Hook 动态计算：`视口高度 - header高度 - footer高度 - body padding`
- 信息区内容区域（`.pisell-procedure-sider-content-top`）有独立的滚动条（`overflow-y: auto`）
- 信息区不跟随整体页面滚动，始终保持可见状态

### 8.4 底部操作区（footerProps）

#### 8.4.1 插槽配置

| 配置项 | 类型 | 说明 |
|-------|------|------|
| summaryButton | ReactNode | 移动端总结按钮（< 744px 显示） |
| leftSlot | ReactNode | 左侧插槽（总价信息、提示文案等） |
| actions | ReactNode | 右侧操作按钮组 |

**actions 按钮自动事件注入：**
- 最后一个按钮默认触发下一步

#### 8.4.2 样式配置

| 配置项 | 类型 | 说明 |
|-------|------|------|
| className | string | 自定义类名 |
| style | CSSProperties | 自定义样式 |

#### 8.4.3 功能配置

| 配置项 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| position | FooterPositionMode | 'float-sidebar' | 底部操作区位置模式 |
| enableOverflow | boolean | true | 是否启用溢出收纳功能 |
| moreText | string | 'More' | More 按钮文案（支持多语言） |
| summaryModalTitle | string | '详情' | 移动端弹窗标题 |

**position 可选值：**
- `fixed-bottom` - 固定在整体底部
- `fixed-content-bottom` - 内嵌在 content 区域底部
- `fixed-sidebar-bottom` - 内嵌在 sidebar 区域底部
- `float-all` - 悬浮在整体区域
- `float-content` - 悬浮在 content 区域
- `float-sidebar` - 悬浮在 sidebar 区域（默认）

### 8.5 步骤控制

#### 8.5.1 步骤确认机制

- **返回上一步**：可配置是否弹窗确认
  - 默认启用确认弹窗
  - 弹窗提示："是否保留此步骤之前的数据？"
  - 按钮："保留" / "清除"
  
- **首步返回**：第一步的返回按钮
  - 默认不显示
  - 可通过 `showBackOnFirstStep` 配置显示
  - 点击默认跳转到首页（/），可通过 `onFirstStepBack` 自定义

- **关闭流程**：右上角关闭按钮
  - 可配置是否弹窗确认
  - 默认不启用确认弹窗
  - 弹窗提示："确认退出？退出后将丢失所有已填写的信息"

#### 8.5.2 步骤事件拦截

- 支持在上一步/下一步之前进行验证
- 通过 `onPrev` / `onNext` 事件返回 `false` 可阻止步骤更新
- 适用于表单验证、数据保存等场景

## 9. 交互规则

### 9.1 步骤导航

1. **点击头部步骤条**：可直接跳转到对应步骤
   - 如果启用了确认弹窗，会先显示确认弹窗
   - 确认后调用 `goToStep(step)` 跳转到指定步骤
   - 与返回按钮使用相同的确认弹窗配置
2. **点击左侧返回按钮**：返回上一步
   - 如果启用了确认弹窗，会先显示确认弹窗
   - 确认后调用 `goPrev()` 返回上一步
   - 第一步时根据 `showBackOnFirstStep` 配置决定是否显示
3. **点击右侧关闭按钮**：关闭流程（可配置确认弹窗）
4. **底部"下一步"按钮**：进入下一步

**统一处理机制**：
- 返回按钮和步骤条点击都走 `handleBackClick` 方法
- 根据是否有步骤参数（`step >= 0`）来区分是步骤跳转还是返回上一步
- 确认弹窗确认后，根据保存的目标步骤决定调用 `goToStep` 还是 `goPrev`

### 9.2 确认弹窗

#### 返回确认弹窗（默认启用）
- **触发时机**：
  - 点击返回按钮且非第一步
  - 点击步骤条跳转到其他步骤
- **弹窗内容**：
  - 标题："提示"
  - 描述："您是要保留此步骤之前的数据，还是根据上一步更改的数据更新清除此步骤的相关数据"
  - 按钮："保留" / "清除"
- **点击保留**：
  - 如果是返回按钮：执行返回上一步（`goPrev()`）
  - 如果是步骤条点击：执行跳转到指定步骤（`goToStep(step)`）
- **点击清除**：执行对应操作（业务层可根据 action 清除数据）
- **点击右上角 X**：只关闭弹窗，不执行操作

#### 关闭确认弹窗（默认禁用）
- **触发时机**：点击右上角关闭按钮且启用了确认
- **弹窗内容**：
  - 标题："确认退出？"
  - 描述："退出后将丢失所有已填写的信息，确定要退出吗？"
  - 按钮："继续" / "退出"
- **点击退出**：执行关闭操作
- **点击继续**：只关闭弹窗
- **点击右上角 X**：只关闭弹窗

### 9.3 移动端交互

- **< 744px**：信息区隐藏
- **总结按钮**：显示在底部左侧（购物车图标）
- **点击总结按钮**：从底部拉起弹窗展示信息区内容
- **弹窗标题**：可通过 `summaryModalTitle` 配置

### 9.4 底部按钮溢出

- 当底部宽度不足时，自动收纳次序列按钮到 More 菜单
- 收纳规则：从左到右依次收纳
- More 按钮显示在可见按钮的左侧

## 10. 设计规范

### 10.1 间距规范

- 头部区域内边距：16px
- 主体区域间距：16px
- 底部区域内边距：16px
- 按钮之间间距：16px

### 10.2 颜色规范

- 主要按钮：使用 primary 类型
- 次要按钮：使用 default 类型
- 危险操作：使用 danger 类型

### 10.3 尺寸规范

- 信息区最小宽度：290px
- 信息区最大宽度：405px

### 8.6 Ref 方法

组件支持通过 `ref` 调用内部方法进行外部控制：

| 方法 | 说明 |
|------|------|
| goPrev() | 跳转到上一步 |
| goNext() | 跳转到下一步 |
| goToStep(step) | 跳转到指定步骤 |
| getCurrentStep() | 获取当前步骤索引 |
| openSummaryModal() | 打开移动端总结弹窗 |
| closeSummaryModal() | 关闭移动端总结弹窗 |

## 11. 注意事项

1. 该组件是纯容器组件，不包含业务逻辑
2. 所有内容区域通过插槽控制，完全可自定义
3. 步骤控制需要外部配合 `onStepsChange` 事件管理状态
4. 移动端总结按钮需要手动配置
5. 弹窗模式（mode="modal"）会禁用所有移动端响应式行为
6. 可通过 ref 调用组件方法进行外部控制


