跳到主要内容

Step

Step 用于把一个较长、具有明确先后顺序的任务拆成多个阶段。每个步骤既有标题和状态，也有自己的内容区，可以放置 Form、输入控件、说明和操作按钮。

阅读本手册后，你可以完成以下配置：

  • 添加 Step 容器和多个 StepItem
  • 配置横向、纵向、导航和紧凑外观
  • 使用默认编号和自动状态图标，或按需配置一整组业务图标
  • 在每个步骤中组合表单与按钮
  • 使用组件接口完成下一步、上一步、跳转和重置
  • 在切换前校验表单，并在 onChange 中读取当前步骤

Step、Tab 和 Progress 的用途不同。Step 表达“必须或建议按顺序完成的任务”；Tab 表达同一对象下的并列内容；Progress 只显示完成比例，不承载每一步的页面内容。

1. 示例：活动发布向导​

Spark Sample 的 Step 页面使用一个四步活动发布向导：

步骤内容展示重点
Campaign details活动名称、负责人、发布日期和摘要两列表单、必填校验、整行 TextArea
Audience & budget受众、渠道、预算和转化目标上一步、下一步、数字字段
Review前两步内容的只读汇总跨步骤共享页面状态、提交提示
Submitted活动编号和完成说明完成状态、重置向导

这个示例不依赖后端接口。按钮通过 Step 的组件接口切换步骤，因此适合直接理解控件结构和 Interaction。如果要真正提交数据，可在 Review 步骤的按钮交互中增加 Send Request。

2. 添加 Step 容器​

  1. 打开目标页面并进入 Page Designer。
  2. 在左侧组件面板展开 Containers。
  3. 将 Step 拖入 Screen 或其他允许容器控件的区域。
  4. 选中 Step，在 Steps 子元素区域添加 StepItem。
  5. 选中每个 StepItem，填写 Title。
  6. 在 StepItem 内容区添加 Form、Panel 或输入控件。

Step 与 StepItem 是两层结构：

Step
├── Campaign details
│   └── Form + Next button
├── Audience & budget
│   └── Form + Back / Next buttons
├── Review
│   └── Read-only Form + Back / Submit buttons
└── Submitted
    └── Result Form + Reset button

子元素列表支持拖动排序。调整 StepItem 的顺序后，步骤编号和前进/后退顺序会一起变化。

3. 配置 Step 容器​

选中外层 Step，可配置：

属性可选值说明
Initial Step从 1 开始的整数页面首次打开时显示哪个步骤；超出范围时自动收敛到首尾步骤
Directionhorizontal、vertical步骤头横向或纵向排列
Step Styledefault、navigation、inline普通流程、导航式流程或紧凑内联样式
Marker Sizesmall、medium、large统一控制整组步骤编号或图标的尺寸；默认 Medium
Label Placementhorizontal、vertical标题位于图标右侧或下方
Progress Dots开 / 关用点代替编号或图标；开启后标题按纵向方式显示
Allow Step Click开 / 关是否允许最终用户直接点击步骤头切换
Show Step Content开 / 关是否显示当前 StepItem 的内容区
Responsive开 / 关窄屏时是否自动切换为适合阅读的纵向布局
Current Step Statusprocess、wait、finish、error当前步骤的默认状态
Current Step Progress0～100当前步骤内部的可选进度；主要用于 Default + Process 状态

3.1 三种 Step Style​

  • Default：适合普通表单向导，状态和步骤关系最清楚。
  • Navigation：步骤头更像流程导航，适合允许用户返回已填写步骤的场景。
  • Inline：信息更紧凑，适合空间有限且标题很短的流程。纵向 Direction 下会自动使用 Default，避免产生不可读组合。

如果流程必须按顺序完成，关闭 Allow Step Click，只保留内容区中的 Back、Next 和 Submit 按钮。

4. 配置 StepItem​

选择单个 StepItem，可配置：

属性说明
Title步骤主标题，必填；建议 2～5 个词
Subtitle辅助信息，例如阶段名称、预计时间或负责人
Description对当前步骤内容的简短说明
Statusauto、wait、process、finish、error
Disabled禁止点击和组件接口跳转到该步骤
Icon可选。通过统一 Icon 选择器选用系统图标并设置前景色/背景色，或上传自定义图片

Status 使用 auto 时，系统会根据当前步骤自动推导：当前步骤之前为 Finish，之后为 Wait，当前项使用 Step 的 Current Step Status。只有需要长期表达错误、等待或特殊完成状态时，才覆盖单个 StepItem 的 Status。

4.1 编号、状态与业务图标​

不配置 Icon 时，Step 默认显示 1、2、3……，这是表单向导和审批流程的推荐方式。步骤完成后系统自动用勾替换编号；当前、等待和错误状态也会自动使用对应颜色与标记，不需要为每一步手工配置红、黄、绿背景。

只有图标能明显帮助识别业务阶段时，才为 StepItem 配置 Icon，例如 User、Document、Payment、Review、Send 或 Milestone。此时应为整组步骤统一配置图标，不要出现一部分步骤使用编号、另一部分使用图标的混合样式。Icon 选择器提供搜索、选中预览、前景色、背景色和无背景选项；属性面板会显示当前图标的名称与标识。

Marker Size 由外层 Step 统一控制，保证所有编号和图标大小一致。不要通过上传尺寸不同的图片来改变单个步骤的视觉权重。

在设计器中编辑不同步骤​

进入 Design Mode 后，直接点击步骤条中的编号或标题即可切换当前设计步骤。下方内容区展示的是该 StepItem 自己包含的 Form、Panel、输入控件和按钮；切换步骤后，内容区和右侧属性面板会同步切换到对应 StepItem。

Allow Step Click 和 StepItem 的 Disabled 控制的是保存后页面的运行行为，不会阻止设计人员进入该步骤编辑内容。也可以在左侧页面结构中展开 Steps → StepItem → Form，直接选择后续步骤的表单或字段。

Disabled 适合“当前条件暂不满足”的步骤。Next 和 Previous 会自动跳过禁用步骤；如果该步骤完全不适用于当前用户，应使用通用显示条件隐藏，而不是只设为 Disabled。

5. 在步骤中组织表单​

推荐先在 StepItem 中添加 Form，再把字段和 ButtonSet 放入 Form：

  1. Form 统一控制 Controls Per Row、Layout、Label Alignment 和标签/内容比例。
  2. 字段校验由 Form 负责，Step 只负责流程切换。
  3. 每个中间步骤提供一个明确的 Next；第二步以后同时提供 Back。
  4. 最后一个业务步骤用于 Review 和 Submit；提交完成后再进入结果步骤。

示例的 Form 使用 Controls Per Row = 2、Label 4 / Content 8。Campaign summary 开启 Display Full Row，它的 Label 仍占 4 列并与 Launch date 对齐，Content 自动使用本行剩余空间。

多个步骤需要读取同一个值时，使用相同的字段 Name。例如编辑区和 Review 区都使用 campaignName，Review 中的只读字段就能显示用户在第一步填写的最新值。

6. 配置前进、后退和重置​

Step 提供四个组件接口：

函数参数行为
nextStep无进入下一个可用步骤，并跳过 Disabled 项
previousStep无返回上一个可用步骤，并跳过 Disabled 项
goToStepstepNumber跳转到指定步骤；编号从 1 开始
resetSteps无返回 Initial Step

以第一步的 Next 按钮为例：

  1. 选择按钮，打开 Interaction。
  2. 在 onClick 下先添加 Trigger Form Validation，Form 选择 campaign_details_form。
  3. 再添加 组件接口。
  4. Target Component 选择 campaign_steps。
  5. Function 选择 nextStep。

动作按从上到下的顺序执行。表单校验失败时，后面的 nextStep 不会执行；校验通过后才进入下一步。

Back 按钮只需要调用 previousStep。提交完成页的 “Create another campaign” 按钮调用 resetSteps。

7. 配置步骤切换交互​

Step 支持两层交互：

  1. 外层 Step 的 onChange。
  2. 单个 StepItem 的 onClick。

切换前，系统会把目标步骤写入 step 上下文：

step.id
step.index
step.number
step.previousIndex
step.previousNumber
step.name
step.description
step.status

index 从 0 开始，便于表达式计算；number 从 1 开始，与属性面板和用户看到的步骤编号一致。

直接点击步骤头时，先执行该 StepItem 的 onClick，步骤实际变化后再执行外层 Step 的 onChange。通过 Next、Previous、Go to 或 Reset 切换时执行外层 onChange，不会把程序化跳转误当成用户点击 StepItem。Disabled 步骤不会切换，也不会执行交互。

例如，在 Step 的 onChange 中添加 Toast，可以显示：

Now viewing step [[step.number]]: [[step.name]]

8. 场景一：后端校验失败时停留在当前步骤​

Step Validation Gate 是一个两步示例。第一步默认填写错误审批码 TRY-AGAIN；点击 Submit and continue 后，后端返回业务错误，页面仍停留在第一步。把审批码改为 APPROVE-2026 再提交，后端成功返回，随后才进入第二步。

8.1 配置两步结构​

  1. 添加 Step 和两个 StepItem，分别命名为 Submit request、Accepted。
  2. 将 Initial Step 设为 1，关闭 Allow Step Click，防止用户直接绕过校验进入第二步。
  3. 在第一步添加 Form，ID 设为 validation_gate_form，加入 requestTitle 和 approvalCode 两个字段。
  4. 在第二步添加只读结果内容和返回按钮；返回按钮调用 previousStep。

8.2 配置 Submit and continue​

按钮的 onClick 必须按以下顺序配置：

  1. Submit Form：Form 选择 validation_gate_form，Submission Mode 选择 Custom URL，URL 填写 /spark/api/sample/step/validation-gate。
  2. 组件接口：Target Component 选择外层 validation_gate_steps，Function 选择 nextStep。

动作顺序就是流程控制。Submit Form 收到 HTTP 错误或 success: false 时会中断本次动作链，后面的 nextStep 不会执行；成功时才继续。不要把 nextStep 放在提交动作之前，也不要在请求尚未成功时先切换页面。

示例后端使用 Lattice Message 返回本地化业务错误：

public StepValidationReceiptDTO validateAndAccept(
        StepValidationSubmission request,
        SparkPageRequestContext context) {
    if (!StringUtils.equals("APPROVE-2026", StringUtils.trim(request.getApprovalCode()))) {
        throw new LatticeRuntimeException(Message.code("SPARK-SAMPLE-STEP-0003"));
    }
    return new StepValidationReceiptDTO(
            "STEP-" + context.getEnvironment().name(),
            "ACCEPTED",
            context.getEnvironment(),
            context.getRenderMode(),
            Instant.now());
}

完整参考位于 spark-sample 的 StepWorkflowSampleController、StepWorkflowSampleService 和 step-validation-gate-page.json。

9. 场景二：多人处理时按后端状态打开当前步骤​

Step Handoff 演示两个人依次处理同一个流程：Avery Chen 已完成第一步，Morgan Lee 负责第二步。Morgan 打开页面时，页面先从后端读取当前流程状态，默认显示第二步；Allow Step Click 保持开启，因此仍可返回第一步查看已提交内容。

9.1 配置 Step 与已完成内容​

  1. 添加 Requester submission、Manager review 两个 StepItem。
  2. 将 Initial Step 保持为 1，作为请求失败或状态尚未加载时的安全回退。
  3. 开启 Allow Step Click，让当前处理人可以查看已经完成的步骤。
  4. 将第一步的 Form 设置为只读。能否修改、能否提交仍必须由后端权限校验决定，不能只依赖界面状态。

9.2 在 Page onLoad 中定位当前步骤​

选择页面根节点，在 onLoad 中按顺序配置：

  1. Send Request：GET /spark/api/sample/step/handoff/status，参数 caseId=CAM-2048。
  2. 在 Response Bindings 中把 activeStep 写入 workflow.activeStep；还可以把 step1Completed、step1CompletedBy、step2Assignee 写入 Page Context，供状态说明和权限提示使用。
  3. 组件接口：Target Component 选择 handoff_steps，Function 选择 goToStep；参数 stepNumber 读取 workflow.activeStep。
Page onLoad
├── Send Request: GET /spark/api/sample/step/handoff/status
│   └── activeStep → workflow.activeStep
└── handoff_steps.goToStep([[workflow.activeStep]])

运行态会等待 onLoad 动作完成后结束页面加载状态，避免先短暂显示第一步再跳到第二步。请求失败时，后续 goToStep 被中断，页面保留 Initial Step。

示例后端根据业务状态返回从 1 开始的步骤编号，并同时读取平台自动携带的环境和渲染模式：

public StepHandoffStatusDTO handoffStatus(
        String caseId,
        SparkPageRequestContext context) {
    boolean step1Completed = workflowRepository.isStep1Completed(caseId);
    return new StepHandoffStatusDTO(
            caseId,
            step1Completed ? 2 : 1,
            step1Completed,
            workflowRepository.step1CompletedBy(caseId),
            workflowRepository.step1CompletedAt(caseId),
            workflowRepository.step2Assignee(caseId),
            context.getEnvironment(),
            context.getRenderMode());
}

后端必须根据当前登录用户、流程状态和权限计算可见数据及可执行动作。activeStep 只决定页面打开位置，不是授权凭据；即使用户切回第一步或手工构造请求，后端也必须拒绝无权修改或提交的操作。

10. 接入后端提交​

原始四步活动向导为了便于学习没有后端依赖。真实业务可在 Review 的 Submit 按钮中按顺序配置：

  1. Trigger Form Validation。
  2. Send Request 或 Submit Form。
  3. 成功 Toast。
  4. 调用 nextStep 进入完成页。

页面请求会自动携带当前环境和渲染模式，不需要在单个 Step 中手工增加协议 Header。完整协议见页面请求上下文与后端调试。

如果 Send Request 失败，后续动作应停止，当前步骤保持不变，让用户修改后重试。不要先进入完成页，再异步等待提交结果。

11. 复现 Spark Sample​

可以按以下顺序复现本文示例：

  1. 添加 Step，设置 Horizontal、Default、Vertical Label、Responsive 和 Allow Step Click。
  2. 设置 Marker Size 为 Medium，保留默认编号标记。
  3. 添加 Campaign details、Audience & budget、Review、Submitted 四个 StepItem，不配置 Icon。
  4. 在前三个步骤中添加两列 Horizontal Form；最后一步添加一列只读 Form。
  5. 第一、二步的 Next 按钮先校验本步骤 Form，再调用 nextStep。
  6. 第二、三步的 Back 按钮调用 previousStep。
  7. Review 的 Submit 按钮显示成功 Toast，再调用 nextStep。
  8. Submitted 的重置按钮调用 resetSteps。
  9. 保存页面，在 Preview 和运行态分别走完一次完整流程。

进阶场景可分别参考 step-validation-gate-page.json 与 step-handoff-page.json。它们是独立页面，便于观察动作中断和页面加载定位，不需要改动原来的四步向导。

12. 常见问题​

12.1 点击 Next 没有变化​

检查：

  • 组件接口的 Target Component 是否选择外层 Step。
  • Function 是否为 nextStep。
  • 当前步骤后面是否只有 Disabled 或隐藏步骤。
  • 前一个 Trigger Form Validation 是否因为必填字段为空而中止。
  • 页面是否已保存，运行态是否使用当前 versionId。

12.2 直接点击步骤头没有反应​

确认 Allow Step Click 已开启，并检查目标 StepItem 是否 Disabled。关闭直接点击是常见的受控流程设计，此时应使用内容区按钮切换。

12.3 Review 显示的不是前面填写的值​

确认编辑字段和 Review 只读字段使用相同且稳定的 Name。Display Name 只影响界面标题，不能用于共享页面状态。

12.4 步骤状态与预期不一致​

通常把 StepItem Status 保持为 auto。如果手工把某一项设为 Finish 或 Error，该状态会覆盖自动推导；恢复为 Auto 后才重新跟随当前步骤。

12.5 页面打开后没有定位到后端返回的步骤​

检查 Page 根节点是否配置 onLoad，Response Binding 是否写入 workflow.activeStep，goToStep 的 stepNumber 是否读取该路径，以及后端返回值是否为从 1 开始的有效整数。再检查 Send Request 是否失败；失败会按设计中断后续跳转。

12.6 移动端步骤被挤压​

开启 Responsive，并避免过长的 Title、Subtitle 和 Description。移动端仍难以阅读时，改用 Vertical Direction，或减少同时显示的文字。

13. 设计建议​

  • 一个向导通常保持 3～7 个步骤；超过 7 个时考虑拆成多个页面或分组。
  • 标题使用动作结果或业务阶段，例如 Details、Audience、Review，不使用长句。
  • Next 按钮明确提示下一步，例如 “Next: Review”，比单独写 “Continue” 更容易理解。
  • 不允许跳步的流程关闭 Allow Step Click，并在每一步校验成功后前进。
  • 提交前提供 Review；提交后提供独立完成页，不要只显示短暂 Toast。
  • Error、Disabled 和完成状态都应有可读说明，不能只依赖颜色。
最后于 更新