构建离线表单

使用活字格命令生成和校验离线表单 JSON，把设计器中的内容组装为可下发的 Pattern。

构建阶段使用 3 个插件命令：先转换页面内容，再组装完整表单，最后校验 JSON。建议按下面顺序执行：

使用“构建离线页面内容”命令，将设计器中的分组、普通文本和表单项转换为页面内容 JSON，适合复用或动态生成某个步骤的页面内容。
使用“构建离线表单”命令，传入项目编号、名称、描述、版本号与步骤，生成完整 Pattern JSON。
使用“检测离线表单 JSON”命令校验生成的 JSON，确认结构与字段约束正确。

构建离线页面内容命令

命令名称：构建离线页面内容。

作用：将设计器中配置的页面节点转换为页面内容 JSON，并返回到变量。通常用于复用或动态生成某个步骤的页面内容。

命令参数：

参数	说明
`页面内容`	页面节点树，可以配置分组、普通文本和表单项。
`将页面内容返回到变量`	保存生成结果的变量名，默认值为 `OfflineFormItem`。

页面节点类型：

类型	说明
分组	包含子节点，可以设置默认折叠和填报进度。
普通文本	用于显示说明文字、填报进度或说明文档。
表单项	用于配置实际填写内容。

返回的 JSON 是一个可直接放入 step.items 或 group.children 的节点对象，例如：

{
  "nodeType": "group",
  "title": "巡检单-防小动物检查-主控室",
  "defaultCollapsed": false,
  "children": [
    {
      "nodeType": "text",
      "title": "二级设备类型",
      "content": "主控室"
    },
    {
      "nodeType": "text",
      "title": "巡检标准",
      "content": "1. 防鼠挡板完好。2. 各类电缆沟及孔洞封堵措施完好。"
    },
    {
      "nodeType": "field",
      "title": "是否合格？",
      "field": {
        "itemId": "PDA_Insp_Qualified",
        "itemType": "selectItem",
        "required": true,
        "options": {
          "selectOptions": [
            { "value": "1", "label": "是" },
            { "value": "0", "label": "否" }
          ]
        }
      }
    },
    {
      "nodeType": "field",
      "title": "现场照片",
      "field": {
        "itemId": "PDA_Insp_Photo",
        "itemType": "imageItem",
        "required": true,
        "options": {
          "maxCount": 3,
          "compression": {
            "enableCompression": true,
            "maxLongEdge": 1600,
            "jpegQuality": 80,
            "maxFileSizeKb": 0,
            "minQuality": 60
          }
        }
      }
    }
  ]
}

命令组装规则：

当配置了多个顶层页面节点时，命令会自动将它们包装为一个分组节点。
当只有一个顶层节点时，命令直接返回该节点。
页面节点支持分组、普通文本和表单项三类，开发者可根据业务规则灵活组装。例如后台允许拍照时插入 imageItem 字段，不允许时不插入。

图片占位

构建离线页面内容命令示意

建议准备一张活字格设计器截图，展示“构建离线页面内容”命令的配置面板：左侧是页面节点树，右侧是返回到变量的设置。

如果命令面板较长，可以裁剪为面板主区域，并突出默认变量名 OfflineFormItem。

field.itemId 是整个表单结构中的唯一标识，也是导出结果中填报值的 key。它对应哪个业务字段、属于哪张表，应由表单定义或开发者维护的映射关系决定；解析时不得靠拆分 itemId 猜测业务含义。

构建离线表单命令

命令名称：构建离线表单。

作用：生成完整的 Pattern JSON，供“下载离线表单”命令使用。

命令参数：

参数	说明
`项目编号`	离线表单项目的唯一标识。
`名称`	离线表单项目名称。
`描述`	离线表单项目说明。
`版本号`	同一项目编号下的表单定义版本，用于区分表单结构变更。
`步骤`	离线表单的多步骤定义。
`将离线表单JSON返回到变量`	保存生成 JSON 的变量名，默认值为 `OfflinePatternJson`。

“构建离线表单”命令支持的表单项类型及特有参数：

类型	特有参数及业务含义
文本框	默认值、最小长度、最大长度、正则表达式校验。
密码框	默认值、最小长度、最大长度、正则表达式校验。
选择框	选项列表，每个选项包含值和显示文本。
单选框	选项列表，以及水平或垂直排列方向。
日期选择	是否包含时间。开启后可以同时选择日期和时间。
时间选择	是否包含秒。开启后可以选择时、分、秒。
图片列表	最大图片数量、是否允许从本地选择图片、图片压缩和拍照水印配置。最大数量为 `0` 时表示不限制。
文件上传	最大文件数量、允许扩展名、单文件最大大小。对应数量或大小为 `0` 时表示不限制。
签名	签名人员列表和签名前显示的免责声明。
列表	最小数量、最大数量、默认数量、添加按钮文本、列表项标题和列表子项。

表单项通常还包含以下通用参数：

参数	说明
`编号`	表单项唯一标识。当前项目内不能重复，代码描述中还要求跨项目保持唯一。
`类型`	表单项类型。
`标题`	表单项显示标题。
`水印`	未填写时显示的提示文字。
`必填`	是否必须填写。
`默认值`	表单项初始值。

以上通用参数及对应 JSON 字段规则见表单项类型。

填报进度配置

启用填报进度：仅步骤中的最外层分组生效，将该分组作为一个填报进度统计单位。
填报进度标识项：仅最外层分组的直接表单项生效，将该表单项作为填报完成标识。
普通文本节点可以配置填报进度显示内容：总填报项、已填报项和完成率。

步骤配置

步骤定义中需要配置 步骤编号 与 标题。每一步可通过“使用页面内容公式”选择来源：

为 false 时，使用设计器中的页面内容。
为 true 时，使用“页面内容公式”的结果；此时设计器中的页面内容不参与生成。

命令生成的根 JSON 结构如下：

{
  "patternId": "PDA_Inspection",
  "schemaVersion": "1.0.0",
  "title": "PDA巡检离线表单",
  "description": "覆盖所有离线表单节点类型、表单项类型及其 options 可选值的示例。",
  "steps": [
    {
      "stepId": "basic-info",
      "title": "基础信息",
      "items": [
        {
          "nodeType": "group",
          "title": "任务信息",
          "defaultCollapsed": false,
          "children": []
        }
      ]
    }
  ]
}

该结构就是 HAC 最终需要接收的离线表单定义。命令本身主要负责组装 JSON，不负责完整校验；建议生成后使用“检测离线表单 JSON”命令校验，下载前也会再次校验该 JSON。

图片占位

构建离线表单命令参数示意

建议准备一张活字格命令配置截图，展示项目编号、名称、描述、版本号、步骤以及默认输出变量 OfflinePatternJson 的配置。

可选用巡检表单作为示例，与文档中的 PDA_Inspection 保持一致。

检测离线表单 JSON

命令名称：检测离线表单 JSON。

作用：检测离线表单 JSON 是否符合“构建离线表单”命令生成的结构。命令只返回校验结果，不会自动修复或改写 JSON。

命令参数：

参数	说明
`离线表单JSON`	要校验的 JSON 字符串或 JSON 对象。
`将是否有效返回到变量`	返回 `true` 或 `false`，默认变量名为 `OfflinePatternJsonIsValid`。
`将错误点返回到变量`	成功时返回空字符串；失败时返回第一个错误的 JSON 路径和错误原因，默认变量名为 `OfflinePatternJsonError`。

校验内容如下：

JSON 格式是否正确。
根节点是否包含有效的 patternId、schemaVersion、title 和 steps。
步骤编号是否为空或重复。
表单项编号是否为空或重复。
表单项类型是否合法。
普通文本、进度文本和说明文档是否符合各自结构。
选择框和单选框是否包含非空选项列表。
签名人员是否为非空字符串数组。
列表子项是否有效，数量限制是否为非负数字。
图片最大数量是否为非负数字。

校验通过后，下一步就是下发到 HAC。

构建离线页面内容命令

构建离线表单命令

填报进度配置

步骤配置

检测离线表单 JSON

本页目录