ambleloft

多步表单、提交与恢复

本页在声明式业务表单基础上,说明如何通过插件 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 pack
打开完整可运行案例

02完整模板:行程 → 费用 → 确认

以下为现有 expense-workflow 案例模板。操作 ID 属于 samples.expense-workflow;复制到自己插件时必须同步改清单与模板,不能只改 publisher。next 在推进步骤时执行,submit 在最终提交时执行。

expense-workflow/skills/expense/forms/travel.yaml
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 时继续查询,不重放写入。

Recovery protocol · signature
type FormRecoveryResult<T> =
  | { status: 'succeeded'; result: T }
  | { status: 'notExecuted' }
  | { status: 'unknown' };

06验收失败路径

至少检查:必填与金额边界、用户取消确认、服务断开、服务已写入但响应丢失、重新打开后的查询恢复。返回上一步不会撤销已经保存的草稿;模板变更后旧实例不能迁移。当前没有公开 forms_resume API。

查阅 YAML 字段参考

检查结果与排错

运行多步表单案例,检查提交、恢复与失败路径。

按本页的验证步骤核对实际结果。涉及业务服务时,分别检查界面提交、工具回执与服务端记录。

打开错误代码与排错 →
SDK / CLI 0.1.0-alpha.9 · 接口基线 兼容性与预览说明 · 案例源码