JSON 消息格式

A2UI 通过 JSON 消息驱动页面渲染。本文档汇总所有 JSON 配置格式，方便编写和查阅。

完整示例

下面是一个包含所有特性的 JSON 消息示例，涵盖创建 Surface、组件树、数据绑定、事件绑定、初始数据加载等：

json

[
  {
    "version": "v0.9",
    "createSurface": {
      "surfaceId": "main",
      "catalogId": "default",
      "eventInputParams": [{ "userId": "user_001", "role": "admin" }]
    }
  },
  {
    "version": "v0.9",
    "updateDataModel": {
      "surfaceId": "main",
      "path": "/clickCount",
      "value": 0
    }
  },
  {
    "version": "v0.9",
    "updateComponents": {
      "surfaceId": "main",
      "components": [
        {
          "id": "row_main",
          "component": "WRow",
          "gutter": 16,
          "children": ["col_left", "col_right"]
        },
        {
          "id": "col_left",
          "component": "WCol",
          "span": 12,
          "children": ["input_name"]
        },
        {
          "id": "col_right",
          "component": "WCol",
          "span": 12,
          "children": ["btn_submit"]
        },
        {
          "id": "input_name",
          "component": "WInput",
          "placeholder": "请输入姓名",
          "modelValue": { "path": "/userName" },
          "action": {
            "event": {
              "name": "onInput",
              "type": "input"
            }
          }
        },
        {
          "id": "btn_submit",
          "component": "WButton",
          "type": "primary",
          "action": {
            "event": {
              "name": "submit",
              "desc": "提交表单",
              "api": {
                "url": "/api/submit",
                "constParams": [{ "name": "source", "value": "web" }]
              },
              "context": [
                { "key": "userName", "value": { "path": "/userName" } },
                { "key": "clickCount", "value": { "path": "/clickCount" } }
              ]
            }
          },
          "child": "btn_text"
        },
        {
          "id": "btn_text",
          "component": "Text",
          "text": "提交"
        }
      ]
    }
  }
]

以下分类型详细说明各字段格式。

快速开始

如果你是第一次编写 A2UI JSON，从最简单的页面开始：

最小示例（一个按钮）：

json

[
  {
    "version": "v0.9",
    "createSurface": { "surfaceId": "main", "catalogId": "default" }
  },
  {
    "version": "v0.9",
    "updateComponents": {
      "surfaceId": "main",
      "components": [
        {
          "id": "btn_hello",
          "component": "WButton",
          "type": "primary",
          "child": "btn_text"
        },
        {
          "id": "btn_text",
          "component": "Text",
          "text": "门诊工作站"
        }
      ]
    }
  }
]

三步理解：

createSurface - 创建一个 UI 容器（必须先创建才能渲染）
updateComponents - 定义组件树（按钮、文本、布局等）
组件通过 child / children 引用子组件

详细说明继续往下看 ↓

消息类型

A2UI v0.9 支持四种消息类型：

消息类型	作用	示例场景
`createSurface`	创建一个 UI 容器	初始化页面、打开新窗口
`updateComponents`	注册/更新组件树	渲染页面内容、动态更新组件
`updateDataModel`	更新数据模型	设置表单默认值、更新列表数据
`deleteSurface`	删除 Surface	关闭窗口、清理页面

createSurface

创建一个新的 Surface（UI 容器），每个 Surface 有独立的组件树和数据模型。

json

{
  "version": "v0.9",
  "createSurface": {
    "surfaceId": "main",
    "catalogId": "default",
    "eventInputParams": [{ "userId": "user_001", "role": "admin" }]
  }
}

字段	类型	必填	说明
`surfaceId`	`string`	是	Surface 唯一标识
`catalogId`	`string`	否	组件目录 ID，默认 `default`
`eventInputParams`	`array`	否	业务参数，会在所有事件中原样返回
`theme`	`object`	否	主题配置

updateComponents

注册或更新组件树，是渲染 UI 的核心消息。

json

{
  "version": "v0.9",
  "updateComponents": {
    "surfaceId": "main",
    "components": [
      {
        "id": "row1",
        "component": "WRow",
        "gutter": 16,
        "children": ["col1", "col2"]
      },
      {
        "id": "col1",
        "component": "WCol",
        "span": 12,
        "children": ["btn_submit"]
      },
      {
        "id": "btn_submit",
        "component": "WButton",
        "type": "primary",
        "action": {
          "event": { "name": "submit", "desc": "提交表单" }
        },
        "child": "btn_text"
      },
      {
        "id": "btn_text",
        "component": "Text",
        "text": "提交"
      }
    ]
  }
}

组件通用字段

每个组件对象都包含以下通用字段：

字段	类型	必填	说明
`id`	`string`	是	组件唯一标识
`component`	`string`	是	组件类型，如 `WButton`、`WInput`
`weight`	`number`	否	渲染权重（用于排序）
其他属性	`any`	否	组件特定属性，如 `type`、`disabled`

组件引用关系

组件通过 child 和 children 引用子组件：

字段	类型	说明
`child`	`string`	单个子组件的 ID
`children`	`string[]`	多个子组件的 ID 数组

json

// 单子组件
{ "id": "btn", "component": "WButton", "child": "btn_text" }

// 多子组件
{ "id": "row", "component": "WRow", "children": ["col1", "col2"] }

updateDataModel

更新数据模型中指定路径的值。

json

{
  "version": "v0.9",
  "updateDataModel": {
    "surfaceId": "main",
    "path": "/formData/name",
    "value": "张三"
  }
}

字段	类型	必填	说明
`surfaceId`	`string`	是	Surface ID
`path`	`string`	是	数据路径，以 `/` 开头
`value`	`any`	是	要设置的值

deleteSurface

删除指定的 Surface。

json

{
  "version": "v0.9",
  "deleteSurface": {
    "surfaceId": "main"
  }
}

数据绑定格式

组件属性可以通过数据绑定从 dataModel 获取值，支持多种格式：

DataBindingValue 对象

json

{
  "id": "input_name",
  "component": "WInput",
  "modelValue": { "path": "/formData/name" }
}

字段	类型	说明
`path`	`string`	数据模型路径，如 `/formData/name`
`literalString`	`string`	字符串字面量
`literalNumber`	`number`	数字字面量
`literalBoolean`	`boolean`	布尔字面量
`literalArray`	`array`	数组字面量（范围值、级联路径等）
`literalObject`	`object`	对象字面量（如级联 props 配置）
`literal`	`any`	通用字面量（字符串/数字/布尔）

各组件具体支持哪些字段，见 path 数据绑定速查。

字符串路径

部分属性支持直接使用字符串路径（以 / 开头）：

json

{
  "id": "text_name",
  "component": "WText",
  "text": "/formData/name"
}

@ 前缀

@ 前缀表示字段名字面量，常用于表格列绑定：

json

{
  "id": "col_name",
  "component": "WTableColumn",
  "prop": "@patientName",
  "label": "患者姓名"
}

action 配置

action 配置在组件的 action.event 字段中，定义用户交互行为。

基本结构

json

{
  "id": "btn_submit",
  "component": "WButton",
  "action": {
    "event": {
      "name": "submit",
      "desc": "提交表单",
      "api": { "url": "/api/submit" },
      "actions": [],
      "constParams": []
    }
  }
}

action.event 字段

字段	类型	必填	说明
`name`	`string`	是	事件名称，用于回调中识别
`type`	`string`	否	事件类型：`click`、`change`、`input` 等
`desc`	`string`	否	动作描述，用于 AI 识别意图
`api`	`object`	否	API 配置，触发时自动调用后端
`actions`	`LocalAction[]`	否	本地操作规则，触发时直接在前端执行
`constParams`	`Array<{ name, value }>`	否	固定参数，每次请求都会携带

api 配置

配置后，事件触发时自动调用后端 API：

json

{
  "action": {
    "event": {
      "name": "submitOrder",
      "desc": "提交处方",
      "api": {
        "url": "/api/order/submit",
        "method": "POST",
        "headers": { "Authorization": "Bearer xxx" },
        "constParams": [{ "name": "orderType", "value": "urgent" }]
      }
    }
  }
}

字段	类型	必填	说明
`url`	`string`	是	后端接口地址
`method`	`string`	否	请求方法，默认 `'POST'`
`headers`	`Record<string, string>`	否	自定义请求头，默认 `{ 'Content-Type': 'application/json' }`，会与默认值合并
`constParams`	`Array<{ name, value }>`	否	固定参数，每次请求都会携带

actions 本地操作

本地操作规则，触发时直接在前端修改数据模型或组件属性，无需调用 API：

json

{
  "action": {
    "event": {
      "name": "lockForm",
      "desc": "锁定表单",
      "actions": [
        {
          "type": "updateProp",
          "componentId": "input_name",
          "prop": "disabled",
          "value": true
        },
        {
          "type": "updateProp",
          "componentId": "input_phone",
          "prop": "disabled",
          "value": true
        },
        { "type": "updateData", "path": "/status", "value": "已锁定" }
      ]
    }
  }
}

LocalAction 类型：

字段	类型	必填	说明
`type`	`'updateData' \| 'updateProp' \| 'updatePangoEditor'`	是	操作类型
`surfaceId`	`string`	否	目标 Surface ID，默认为触发事件的 surface
`componentId`	`string`	否*	目标组件 ID（`updateProp` 时必填，`updatePangoEditor` 时为编辑器 domId）
`path`	`string`	否*	数据模型路径（`updateData` 时必填）
`prop`	`string`	否*	属性名（`updateProp` 时必填）
`value`	`any`	是	设置的值（`updatePangoEditor` 时传 `'reset'`）

三种操作类型：

类型	说明	必填字段
`updateData`	更新数据模型中指定路径的值	`path`, `value`
`updateProp`	更新组件的属性（如 `disabled`、`visible`）	`componentId`, `prop`, `value`
`updatePangoEditor`	重置 PangoEditor 编辑器（用初始数据重新渲染）	`value: 'reset'`，`componentId` 可选（不传重置所有）

actions 与 api 并存

actions 和 api 可以同时配置。触发时执行顺序：

先执行本地操作（actions，同步立即生效）
再调用 API（api，异步）
同时派发 window 事件 + onEvent

loadEventHandler

配置在 processMessages2 的 json 参数中，用于页面加载时自动从后端获取初始数据。

json

{
  "surfaceId": "main",
  "components": [...],
  "loadEventHandler": {
    "url": "/api/loadData",
    "method": "POST",
    "headers": { "Authorization": "Bearer xxx" },
    "desc": "加载患者列表",
    "constParams": [
      { "name": "departmentId", "value": "1001" }
    ]
  }
}

字段	类型	必填	说明
`url`	`string`	是	后端接口地址
`method`	`string`	否	请求方法，默认 `'POST'`
`headers`	`Record<string, string>`	否	自定义请求头，默认 `{ 'Content-Type': 'application/json' }`，会与默认值合并
`desc`	`string`	否	动作描述，用于回调识别
`constParams`	`Array<{ name, value }>`	否	固定参数

请求格式：

渲染器自动发送请求（默认 POST，可通过 method 配置）：

json

{
  "sessionCtx": { "userId": "user_001" },
  "businessParams": { "orderId": "ORD-001" },
  "constParams": { "departmentId": "1001" }
}

数据映射规则：

API 返回的数据会根据组件的 dataSource 路径自动映射到 dataModel：

按路径名匹配：组件 dataSource 为 /patientList 时，从返回数据中取 patientList 键的值
单 dataSource 兼容：只有一个 dataSource 且未匹配时，尝试取常见列表字段（list / rows / items / records / data）
响应格式兼容：支持 { code, data: {...} } 和直接返回数据两种格式

processMessages2 json 结构

processMessages2 接受 4 个参数：sessionCtx、businessParams、json、callback。其中 json 是简化的模板结构，callback 是 API 调用后的回调函数：

typescript

processor.processMessages2(sessionCtx, businessParams, json, callback);

json 结构：

json

{
  "surfaceId": "main",
  "components": [
    { "id": "row1", "component": "WRow", "children": [...] },
    { "id": "input_name", "component": "WInput", "modelValue": { "path": "/name" } },
    { "id": "btn_submit", "component": "WButton", "action": {...} }
  ],
  "data": {
    "name": "张三",
    "phone": "13800138000"
  },
  "loadEventHandler": {
    "url": "/api/loadData",
    "constParams": [...]
  }
}

callback：API 调用后的回调函数（processMessages2 的第 4 个参数）

typescript

// 两种触发场景：
//   - loadEventHandler 加载完成后触发（actionType: 'load'）
//   - 按钮 action.event.api 调用后触发（actionType: 'event'）
(actionInfo: {
  actionType: 'load' | 'event',  // 触发来源
  actionName: string,             // 'load' 时为空，'event' 时为事件名称
  actionDesc: string              // 动作描述
}, interfaceInfo: any) => void    // 后端 API 返回的 JSON（异常时为 { error: true, message: string }）

参数汇总：

字段	类型	必填	说明
`surfaceId`	`string`	否	Surface ID，默认 `@default`
`components`	`array`	是	组件列表，格式同 `updateComponents`
`data`	`object`	否	初始数据，渲染前写入 dataModel
`loadEventHandler`	`object`	否	初始数据加载配置
`callback`	`function`	是	API 调用后的回调函数（`loadEventHandler` 加载完成或按钮 API 调用后触发）

callback 的详细说明和示例见 调用后端 API - callback 回调

组件事件类型映射

不同组件触发事件时的 type 值：

组件	触发时机	type 值
WButton	点击按钮	`click`
WLink	点击链接	`click`
WBreadcrumb	点击节点	`click`
WDropdown	点击菜单项	`command`
WAlert	关闭提示	`close`
WScrollbar	滚动	`scroll`
WScrollbar	到达边缘	`end-reached`
WInput	输入内容	`input`
WAutocomplete	输入内容	`input`
WAutocomplete	选中建议	`change`
WMention	输入内容	`input`
WMention	选中提及	`select`
WInputTag	标签变化	`change`
WInputNumber	数值变化	`change`
WPagination	分页变化	`change`
WSelect	选择变化	`change`
WSelectV2	选择变化	`change`
WTableSelect	选择变化	`change`
WTransfer	选项移动	`change`
WSwitch	状态变化	`change`
WRadioGroup	选择变化	`change`
WRate	评分变化	`change`
WCheckboxGroup	勾选变化	`change`
WSegmented	切换变化	`change`
WSlider	滑块变化	`change`
WTreeSelect	选择变化	`change`
WCascader	选择变化	`change`
WColorPicker	选择变化	`change`
WDatePicker	选择变化	`change`
WTimePicker	选择变化	`change`
WTimeSelect	选择变化	`change`
WiCheckboxGroup	勾选变化	`change`
WiRadioGroup	选择变化	`change`
WiListTableSelect	选择变化	`change`
WiListTableSelect	添加项	`add`
WiListTableSelect	删除项	`remove`
WSplitter	拖拽结束	`resize-end`
WSplitter	面板折叠	`collapse`
WTabs	切换标签	`tab-click`
WTabs	关闭标签	`tab-remove`

完整示例

一个包含数据绑定、action、loadEventHandler 的完整示例：

json

{
  "surfaceId": "patient_list",
  "components": [
    {
      "id": "row_toolbar",
      "component": "WRow",
      "gutter": 16,
      "children": ["col_search", "col_add"]
    },
    {
      "id": "col_search",
      "component": "WCol",
      "span": 18,
      "children": ["input_search"]
    },
    {
      "id": "input_search",
      "component": "WInput",
      "placeholder": "搜索患者",
      "modelValue": { "path": "/searchKeyword" }
    },
    {
      "id": "col_add",
      "component": "WCol",
      "span": 6,
      "children": ["btn_add"]
    },
    {
      "id": "btn_add",
      "component": "WButton",
      "type": "primary",
      "action": {
        "event": {
          "name": "addPatient",
          "desc": "新增患者",
          "actions": [
            { "type": "updateData", "path": "/dialogVisible", "value": true }
          ]
        }
      },
      "child": "btn_add_text"
    },
    {
      "id": "btn_add_text",
      "component": "Text",
      "text": "新增"
    },
    {
      "id": "table_patients",
      "component": "WTable",
      "dataSource": "/patientList",
      "children": ["col_name", "col_age", "col_action"]
    },
    {
      "id": "col_name",
      "component": "WTableColumn",
      "prop": "@patientName",
      "label": "姓名"
    },
    {
      "id": "col_age",
      "component": "WTableColumn",
      "prop": "@age",
      "label": "年龄"
    },
    {
      "id": "col_action",
      "component": "WTableColumn",
      "label": "操作",
      "children": ["btn_edit"]
    },
    {
      "id": "btn_edit",
      "component": "WButton",
      "type": "text",
      "action": {
        "event": {
          "name": "editPatient",
          "desc": "编辑患者",
          "api": {
            "url": "/api/patient/detail",
            "constParams": [
              { "name": "patientId", "value": { "path": "/selectedPatientId" } }
            ]
          }
        }
      },
      "child": "btn_edit_text"
    },
    {
      "id": "btn_edit_text",
      "component": "Text",
      "text": "编辑"
    }
  ],
  "data": {
    "searchKeyword": "",
    "dialogVisible": false
  },
  "loadEventHandler": {
    "url": "/api/patient/list",
    "desc": "加载患者列表"
  }
}

下一步

核心概念：了解 A2UI 的架构和工作流程
事件监听与 API 参考：了解如何监听事件、调用 processor 方法
简化 API 对接：通过 processMessages2 快速对接后端 API

JSON 消息格式 ​

完整示例 ​

快速开始 ​

消息类型 ​

createSurface ​

updateComponents ​

组件通用字段 ​

组件引用关系 ​

updateDataModel ​

deleteSurface ​

数据绑定格式 ​

DataBindingValue 对象 ​

字符串路径 ​

@ 前缀 ​

action 配置 ​

基本结构 ​

action.event 字段 ​

api 配置 ​

actions 本地操作 ​

loadEventHandler ​

processMessages2 json 结构 ​

组件事件类型映射 ​

完整示例 ​

下一步 ​

JSON 消息格式

完整示例

快速开始

消息类型

createSurface

updateComponents

组件通用字段

组件引用关系

updateDataModel

deleteSurface

数据绑定格式

DataBindingValue 对象

字符串路径

@ 前缀

action 配置

基本结构

action.event 字段

api 配置

actions 本地操作

loadEventHandler

processMessages2 json 结构

组件事件类型映射

完整示例

下一步