多步表单、提交与恢复
本页在声明式业务表单基础上,说明如何通过插件 Operation 保存业务草稿、提交申请和核实未知结果。多步导航本身不要求业务服务器。
完成后:运行多步表单案例,检查提交、恢复与失败路径。
前置条件:按本页具体步骤准备所需文件与工具;学习路线中的上一页不自动构成依赖。
本页内容
01运行完整业务模板
先完成插件入门指南的本地包准备,在 extension-work 中执行并保留 AMBLELOFT_PACKS。CLI 不自动安装依赖。
npx --no-install amble-extension init expense-demo --name expense-demo --template expense
cd expense-demo
npm install --save-dev "$AMBLELOFT_PACKS/ambleloft-extension-sdk-0.1.0-alpha.9.tgz" "$AMBLELOFT_PACKS/ambleloft-extension-core-0.1.0-alpha.9.tgz" "$AMBLELOFT_PACKS/ambleloft-extension-cli-0.1.0-alpha.9.tgz"
npm run build
npm run validate
npm run pack02完整模板:行程 → 费用 → 确认
以下为现有 expense-workflow 案例模板。操作 ID 属于 samples.expense-workflow;复制到自己插件时必须同步改清单与模板,不能只改 publisher。next 在推进步骤时执行,submit 在最终提交时执行。
version: 1
id: travel
title: 财务报销助手
description: 本机模拟报销。修改行程会生成新草稿;返回上一步不会撤销业务记录。
steps:
- id: itinerary
title: 行程
fields:
- name: region
type: select
label: 出差地区
required: true
options:
- {label: 上海, value: shanghai}
- {label: 北京, value: beijing}
- {name: date, type: date, label: 出差日期, required: true}
next:
kind: operation
label: 保存行程并继续
operation: samples.expense-workflow.saveDraft
input:
region: {from: steps.itinerary.region}
date: {from: steps.itinerary.date}
recovery: {operation: samples.expense-workflow.lookupDraft}
- id: expenses
title: 费用
fields:
- {name: amount, type: money, label: 金额, currency: CNY, scale: 2, minimum: '0.01', maximum: '1000000.00', required: true}
- {name: remark, type: textarea, label: 说明, maxLength: 2000, required: true}
- id: confirmation
title: 确认
fields:
- {name: confirmed, type: checkbox, label: 我已核对报销信息, required: true}
submit:
kind: operation
label: 提交报销
operation: samples.expense-workflow.submitExpense
input:
draftId: {from: results.itinerary.draftId}
amount: {from: steps.expenses.amount}
remark: {from: steps.expenses.remark}
confirmed: {from: steps.confirmation.confirmed}
recovery: {operation: samples.expense-workflow.lookupExpense}
03输入绑定如何解析
绑定由宿主解析,YAML 不能执行 JavaScript 或拼接 API URL。业务 operation 的 inputSchema / outputSchema 仍是最终契约。
| 字段 / API | 说明 |
|---|---|
| steps.<step>.<field> | 读取指定步骤的字段,如 steps.expenses.amount。 |
| results.<step>.<key> | 读取已完成步骤 operation 的输出,如草稿 draftId。 |
| context.projectId | 绑定当前项目;项目级操作需匹配调用上下文。 |
| { value: ... } | 固定 string / number / boolean 字面值。 |
04写入必须使用 submissionId
处理函数通过 invocation.form 获取宿主签发的 submissionId、flowInstanceId、stepId、templateDigest、conversationId。将 submissionId 作为业务端幂等键;requestId 不是替代品,也不能相信用户 input.form。表单写入操作应暴露给 page,由宿主确认后调用。
05恢复操作的返回协议
recovery 指向同扩展的 page 可调用 read 操作。它从 input.submissionId 读取要查询的提交,不从 invocation.form 读取。succeeded.result 返回原业务输出并再次按原 outputSchema 校验。超时或查不到记录不能自动返回 notExecuted;只有业务端明确保证未执行才可以。unknown 时继续查询,不重放写入。
type FormRecoveryResult<T> =
| { status: 'succeeded'; result: T }
| { status: 'notExecuted' }
| { status: 'unknown' };06验收失败路径
至少检查:必填与金额边界、用户取消确认、服务断开、服务已写入但响应丢失、重新打开后的查询恢复。返回上一步不会撤销已经保存的草稿;模板变更后旧实例不能迁移。当前没有公开 forms_resume API。
查阅 YAML 字段参考检查结果与排错
运行多步表单案例,检查提交、恢复与失败路径。
按本页的验证步骤核对实际结果。涉及业务服务时,分别检查界面提交、工具回执与服务端记录。
打开错误代码与排错 →