调用后端 API

如果你要在前端页面中直接使用 A2UI 渲染器，并且需要：

页面打开时自动从后端加载初始数据
用户点击按钮时自动调用后端 API

那么 processMessages2 可以帮你用一次调用搞定这些，而不需要手动监听事件、手动发请求。

完整示例

什么时候用它

场景	用什么
前端页面直接对接后端 API，需要自动加载初始数据、按钮直接调接口	processMessages2（本文档）
AI/大模型对话式交互，事件流程由后端/AI 驱动	processMessages + 事件监听

两种方式可以共存：即使在 processMessages2 模式下，你仍然可以通过 onEvent / window.addEventListener 监听事件。

processMessages2 接口

typescript

processor.processMessages2(
  sessionCtx: Record<string, any>,
  businessParams: Record<string, any>,
  json: Record<string, any>,
  callback: (actionInfo, interfaceInfo) => void,
): void

参数	类型	必填	说明
`sessionCtx`	`object`	是	会话上下文（用户信息、token 等），会自动透传给所有 API 调用
`businessParams`	`object`	是	业务参数（订单 ID 等），透传给 `loadEventHandler`
`json`	`object`	是	A2UI 模板片段，详见下方
`callback`	`function`	是	API 调用后的回调函数

json 参数结构 + callback

processMessages2 的第 3 个参数 json 是 A2UI 模板片段，第 4 个参数 callback 是 API 调用后的回调函数：

typescript

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

// json 参数结构
{
  // Surface ID（可选，默认 '@default'）
  surfaceId?: string;

  // 组件列表（必填）
  components: AnyComponent[];

  // 初始数据（可选）：渲染前写入 dataModel
  data?: Record<string, any>;

  // 初始数据加载（可选）：渲染完成后自动发请求
  loadEventHandler?: {
    url: string;           // 后端接口地址
    method?: string;       // 请求方法，默认 'POST'
    headers?: Record<string, string>;  // 请求头，默认 { 'Content-Type': 'application/json' }，会与默认值合并
    desc?: string;         // 动作描述
    constParams?: Array<{ name: string; value: any }>;
  };
}

// callback: API 调用后的回调函数
//   - 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 }）

参数	类型	必填	说明
`json`	`object`	是	A2UI 模板片段，见上方结构
`callback`	`function`	是	API 调用后的回调函数，详见下方说明

json 内部字段：

字段	类型	必填	说明
`surfaceId`	`string`	否	Surface ID，默认 `@default`
`components`	`array`	是	组件列表，格式同 `updateComponents`
`data`	`object`	否	初始数据，渲染前写入 dataModel
`loadEventHandler`	`object`	否	初始数据加载配置

组件格式、数据绑定、action 配置详见 JSON 消息格式

callback 回调

callback 在两种场景触发：

触发场景	actionType	actionName	说明
loadEventHandler 加载完成	`'load'`	空字符串 `''`	初始数据加载完成后触发
action API 调用后	`'event'`	事件名称	用户点击按钮调用 API 后触发

typescript

callback(actionInfo, interfaceInfo) => void

// actionInfo: 触发的动作信息
{
  actionType: 'load' | 'event',  // 触发来源
  actionName: string,             // 'load' 时为空，'event' 时为事件名称
  actionDesc: string              // 动作描述
}

// interfaceInfo: 后端 API 返回的 JSON
//   正常时为 API 响应 JSON
//   异常时为 { error: true, message: string }

示例 — 区分两种场景：

typescript

processor.processMessages2(
  sessionCtx,
  businessParams,
  json,
  (actionInfo, interfaceInfo) => {
    if (actionInfo.actionType === 'load') {
      console.log('初始数据加载完成:', interfaceInfo);
    } else if (actionInfo.actionType === 'event') {
      console.log(`事件 ${actionInfo.actionName} 触发:`, interfaceInfo);
    }
  },
);

工作流程

了解 processMessages2 内部做了什么：

processMessages2(sessionCtx, businessParams, json, callback)
│
├─ 1. 存储 sessionCtx / businessParams / callback
│
├─ 2. 创建 Surface（如果是新的）
│     → 派发 surface-created 事件
│
├─ 3. 如果传入了 data → 写入 dataModel
│
├─ 4. 解析 json.components → 构建组件树
│     → 派发 rendered 事件
│
└─ 5. 如果有 loadEventHandler.url
      └─ 异步请求加载初始数据（默认 POST，可通过 method 配置）
          → 写入 dataModel → 刷新组件树 → 触发 callback（actionType: 'load'）

━━━ 以上是初始化阶段，以下是用户操作阶段 ━━━

用户点击带 action.event.api 配置的按钮时：
│
├─ 1. 渲染器自动调用后端 API
│     ├─ 收集 formParams（从 dataModel 中提取绑定了 path 的组件值）
│     ├─ 请求 action.event.api.url（默认 POST，可通过 method 配置）
│     └─ 调用 callback(actionInfo, interfaceInfo)
│
└─ 2. 同时派发 window 事件 + onEvent（业务可正常监听）

formParams 自动收集

用户点击按钮时，渲染器自动收集表单参数发送给后端：

json

{
  "sessionCtx": { "userId": "user_001" },
  "formParams": {
    "name": "张三",
    "phone": "13800138000"
  },
  "constParams": { ... }
}

收集规则：

扫描 surface 中所有组件属性，查找值为 { path: "/xxx" } 或字符串 "/xxx" 的属性
排除 action、dataSource、child、children 等非数据属性
排除 WTable 组件（其 dataSource 是展示数据，不作为表单参数）
从 dataModel 中读取路径对应的值

如果需要固定参数，在 action.event.api.constParams 中配置

与事件监听的关系

使用 processMessages2 时，事件监听机制仍然正常工作：

typescript

// processMessages2 模式下，仍然可以监听事件
processor.onEvent((event) => {
  console.log('用户操作:', event.message.userAction.name);
  event.resolve([]); // 必须调用
});

协作关系：

配置了 action.event.api 的按钮被点击时，渲染器会同时：
1. 自动调用后端 API → 触发 callback
2. 派发 window 事件 / 触发 onEvent 回调
你可以在 onEvent 中做额外的业务处理（如日志、跳转等），不需要处理 API 调用本身

注意事项

callback 在两种场景触发：
- loadEventHandler 加载完成后触发，actionType 为 'load'
- action API 调用后触发，actionType 为 'event'
多次调用会覆盖：多次调用 processMessages2 会覆盖之前存储的 sessionCtx、businessParams 和 callback。如果需要多个 Surface，建议在同一个调用中处理。
formParams 不包含 WTable 数据：只有表单类组件（WInput、WInputNumber、WSelect、WCascader、WColorPicker、WRate、WSlider、WDatePicker、WTimePicker、WTimeSelect、WRadioGroup、WCheckboxGroup、WiRadioGroup 等）绑定 path 的值才会被收集。
API 调用失败处理：
- loadEventHandler API 失败会触发 callback，interfaceInfo 为 { error: true, message: string }
- action API 失败同样会将 { error: true, message } 传给 callback
API 与事件并行：配置了 action.event.api 的按钮被点击时，渲染器同时调 API 并派发事件，两种方式都能监听。

下一步

JSON 消息格式：查阅组件格式、action 配置、loadEventHandler 等详细格式
事件监听与 API 参考：了解如何在 callback 外额外监听事件

调用后端 API ​

完整示例 ​

什么时候用它 ​

processMessages2 接口 ​

json 参数结构 + callback ​

callback 回调 ​

工作流程 ​

formParams 自动收集 ​

与事件监听的关系 ​

注意事项 ​

下一步 ​

调用后端 API

完整示例

什么时候用它

processMessages2 接口

json 参数结构 + callback

callback 回调

工作流程

formParams 自动收集

与事件监听的关系

注意事项

下一步