Processor API 参考

本文档汇总 MessageProcessor 所有公开方法的详细说明。通过 useMessageProcessor() 获取 processor 实例。

方法一览

typescript

import { useMessageProcessor } from 'win-design-a2ui-vue';

const processor = useMessageProcessor();

// ─── Surface 管理 ───────────────────────────────────────────
processor.getSurfaces();              // 获取所有 Surface 的响应式 Map
processor.clearSurfaces('main');      // 清除指定 Surface（不传则清除全部）
processor.processMessages([...]);     // 处理 A2UI 消息数组
processor.processMessages2(           // 简化接口：一次调用完成渲染 + API 对接
  sessionCtx, businessParams, json, callback
);

// ─── 数据操作 ───────────────────────────────────────────────
processor.getDataValue('main', '/userName');  // 读取数据模型中的值

// ─── 事件监听 ───────────────────────────────────────────────
processor.onSurfaceCreated((surfaceId, surface, apis) => { ... });  // Surface 创建事件
processor.onSurfaceUpdated((surfaceId, surface, apis) => { ... });  // 渲染完成事件
processor.onEvent((event) => { ... });                               // 用户交互事件

// ─── 事件派发 ───────────────────────────────────────────────
processor.dispatch('main', { userAction: { name: 'custom', type: 'click' } });

// ─── 表单操作 ───────────────────────────────────────────────
processor.getFormInstance('form_001');     // 获取表单实例（支持 validate / resetFields）

// ─── 编辑器操作 ─────────────────────────────────────────────
processor.getPangoEditorInstance('editor-001');  // 获取编辑器实例
processor.getPangoEditorInstance();              // 获取所有编辑器实例 Map
processor.getPangoEditorParams('editor-001');    // 获取编辑器 FileSave 结果
processor.getPangoEditorParams();                // 获取所有编辑器 FileSave 结果数组
processor.resetPangoEditorInstance('editor-001');// 重置编辑器（用初始数据重新渲染）
processor.resetPangoEditorInstance();            // 重置所有编辑器

以下按分类详细说明每个方法。

Surface 管理

getSurfaces

获取所有 Surface 的响应式映射表，可直接在模板 v-for 中使用。

typescript

getSurfaces(): ReadonlyMap<string, Surface>

返回值： ReadonlyMap<string, Surface> - Surface ID 到 Surface 对象的只读映射

示例：

typescript

const surfaces = processor.getSurfaces();

// 模板中使用
<A2UISurface
  v-for="[id, surface] in surfaces"
  :key="id"
  :surface-id="id"
  :surface="surface"
/>

clearSurfaces

清除 Surface。支持清除全部或指定 Surface。

typescript

clearSurfaces(surfaceId?: string): void

参数：

参数	类型	说明
不传参数	-	清除所有 Surface
`surfaceId`	`string`	仅清除指定的 Surface

示例：

typescript

// 清除所有 Surface
processor.clearSurfaces();

// 仅清除指定 Surface
processor.clearSurfaces('main_surface');

消息处理

processMessages

处理 A2UI 消息数组，是消息的入口方法。

typescript

processMessages(messages: A2uiMessage[]): void

参数：

参数	类型	说明
`messages`	`A2uiMessage[]`	A2UI 消息数组

支持的消息类型：

消息类型	作用
`createSurface`	创建 UI 容器
`updateComponents`	注册/更新组件树
`updateDataModel`	更新数据模型
`deleteSurface`	删除 Surface

示例：

typescript

processor.processMessages([
  { version: 'v0.9', createSurface: { surfaceId: 'main', catalogId: 'default' } },
  { version: 'v0.9', updateComponents: { surfaceId: 'main', components: [...] } },
]);

消息格式详见 JSON 消息格式

processMessages2

简化版消息处理接口，适合前端页面直接对接后端 API。一次调用完成渲染、初始数据加载、按钮点击自动调 API。

typescript

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

详细说明见 简化 API 对接

数据操作

getDataValue

读取数据模型中指定路径的值，路径不存在时返回 null。

typescript

getDataValue(surfaceId: string, path: string): DataValue | null

参数：

参数	类型	说明
`surfaceId`	`string`	Surface ID
`path`	`string`	数据路径，如 `/userName`

返回值： DataValue | null - 数据值，不存在返回 null

示例：

typescript

const userName = processor.getDataValue('main', '/userName');
const clickCount = processor.getDataValue('main', '/clickCount') || 0;

事件监听

Processor 提供三个方法监听不同阶段的事件。不需要的可以不注册。

事件	方法	触发时机	用途	需要调用 resolve？
页面创建	`onSurfaceCreated`	Surface 创建完成，组件还没渲染	设置初始数据	不需要
渲染完成	`onSurfaceUpdated`	组件树渲染完毕	操作组件、获取实例	不需要
用户操作	`onEvent`	用户点击按钮、输入文字等	处理业务逻辑	必须调用

onSurfaceCreated

页面刚创建，组件还没渲染。适合在这里设置初始数据。

typescript

onSurfaceCreated(
  handler: (surfaceId: string, surface: Surface, apis: SurfaceApis) => void,
): () => void  // 返回取消监听的函数

回调参数：

参数	说明
`surfaceId`	页面标识
`surface`	Surface 实例，包含 `eventInputParams` 等
`apis`	操作方法集合，见下方 SurfaceApis 表格

示例：

typescript

const unsubscribe = processor.onSurfaceCreated((surfaceId, surface, apis) => {
  // 设置初始数据（就像给输入框设默认值）
  apis.updateDataModel(surfaceId, '/userName', '');
  apis.updateDataModel(surfaceId, '/clickCount', 0);

  // 拿到 createSurface 时传入的业务参数
  console.log('业务参数:', surface.eventInputParams);
});

// 不需要监听时取消
unsubscribe();

TIP

onSurfaceCreated 在 processMessages 中同步派发，必须在调用 processMessages 之前注册。不要放到 onMounted 中。

onSurfaceUpdated

页面上的组件都渲染好了。适合在这里操作组件或获取表单/编辑器实例。

typescript

onSurfaceUpdated(
  handler: (surfaceId: string, surface: Surface, apis: SurfaceApis) => void,
): () => void

示例：

typescript

processor.onSurfaceUpdated((surfaceId, surface, apis) => {
  // 比如把提交按钮设为可用
  apis.updateComponentProp(surfaceId, 'btn_submit', 'disabled', false);

  // 获取表单实例
  const form = apis.getFormInstance('form_001');

  // 获取编辑器实例和数据
  const editor = apis.getPangoEditorInstance('editor-001');
  const editorData = apis.getPangoEditorParams('editor-001');
});

onEvent

用户点击了按钮、输入了文字等。处理完后必须调用 resolve()，否则页面会卡住。

typescript

onEvent(handler: (event: DispatchedEvent) => void): () => void

回调参数（event 对象）：

属性	说明
`event.message`	事件消息，包含 `userAction`
`event.message.userAction.name`	事件名称，如 `'submit'`
`event.message.userAction.type`	事件类型，如 `'click'`
`event.message.userAction.surfaceId`	页面标识
`event.eventInputParams`	createSurface 时传入的业务参数
`event.resolve`	完成回调，必须调用
`event.reject`	错误回调

示例：

typescript

processor.onEvent((event) => {
  const { name, type, surfaceId } = event.message.userAction;

  if (name === 'submit') {
    // 读取用户输入的数据
    const userName = processor.getDataValue(surfaceId, '/userName');
    console.log('用户输入了：', userName);

    // 获取表单实例并校验
    const form = processor.getFormInstance('form_001');

    // 获取编辑器数据
    const editorData = processor.getPangoEditorParams('editor-001');

    // 处理完后调用 resolve，可以传新的 JSON 来更新页面
    event.resolve([
      {
        version: 'v0.9',
        updateDataModel: { surfaceId, path: '/result', value: '提交成功' },
      },
    ]);
  } else {
    event.resolve([]); // 不需要更新页面，传空数组即可。但必须调用！
  }
});

resolve 的三种用法：

typescript

// 1. 不更新页面，只告诉 A2UI "我处理完了"
event.resolve([]);

// 2. 更新某个数据（比如显示"提交成功"）
event.resolve([
  { version: 'v0.9', updateDataModel: { surfaceId, path: '/result', value: '提交成功' } },
]);

// 3. 可以同时传多条消息（更新数据 + 创建新页面 + ...）
event.resolve([
  { version: 'v0.9', updateDataModel: { surfaceId, path: '/count', value: 1 } },
  { version: 'v0.9', updateComponents: { surfaceId, components: [...] } },
]);

DANGER

不调用 resolve，页面会卡住！ 无论你做了什么处理，最后都必须调用一次。

事件派发

dispatch

手动派发客户端事件消息，返回 Promise 等待响应。

typescript

dispatch(message: A2UIClientEventMessage): Promise<A2uiMessage[]>

参数：

参数	类型	说明
`message`	`A2UIClientEventMessage`	事件消息

返回值： Promise<A2uiMessage[]> - 响应消息数组

示例：

typescript

const messages = await processor.dispatch({
  userAction: {
    name: 'refreshData',
    type: 'click',
    sourceComponentId: 'btn_refresh',
    surfaceId: 'main',
    timestamp: new Date().toISOString(),
  },
});

WARNING

dispatch 返回的 Promise 需要事件监听器调用 resolve 才能完成，否则会一直 pending。

表单操作

getFormInstance

获取 WForm 注册的表单实例，支持校验和重置。

typescript

getFormInstance(formId: string): A2UIFormInstance | undefined

参数：

参数	类型	说明
`formId`	`string`	表单组件 ID

返回值： A2UIFormInstance | undefined

表单实例方法：

方法	类型	说明
`validate`	`() => Promise<boolean>`	校验表单，返回是否通过
`resetFields`	`() => void`	重置表单到初始值

示例：

typescript

processor.onEvent(async (event) => {
  const { message, resolve } = event;
  if (message.userAction.name === 'onSubmit') {
    const form = processor.getFormInstance('form_001');
    const valid = await form?.validate();
    if (!valid) {
      resolve([]); // 校验失败，不提交
      return;
    }
    // 校验通过，处理提交逻辑...
    resolve([]);
  }
});

TIP

WForm 挂载时自动注册实例到 processor，卸载时自动注销。formId 为 WForm 的 id 属性值。

编辑器操作

getPangoEditorInstance

获取 PangoEditor 注册的编辑器实例，用于手动操作编辑器。

typescript

getPangoEditorInstance(domId?: string): any

参数：

参数	类型	说明
`domId`	`string`	容器 DOM 标识（可选）

返回值：

调用方式	返回类型	说明
`getPangoEditorInstance(domId)`	`any \| undefined`	传入 domId 返回对应编辑器实例
`getPangoEditorInstance()`	`Map<string, any>`	不传返回所有实例的 Map

示例：

typescript

processor.onEvent((event) => {
  const { message, resolve } = event;
  if (message.userAction.name === 'submit') {
    // 获取单个编辑器实例
    const editor = processor.getPangoEditorInstance('my-editor-001');

    // 获取所有编辑器实例
    const allEditors = processor.getPangoEditorInstance();
  }
});

TIP

PangoEditor 挂载时自动注册实例到 processor，卸载时自动注销。domId 对应组件配置中的 domId 属性值。

getPangoEditorParams

获取 PangoEditor 编辑器数据，内部调用 FileSave 返回结果。

typescript

getPangoEditorParams(domId?: string): any

参数：

参数	类型	说明
`domId`	`string`	容器 DOM 标识（可选）

返回值：

调用方式	返回类型	说明
`getPangoEditorParams(domId)`	`any`	传入 domId 返回对应实例的 FileSave 结果
`getPangoEditorParams()`	`any[]`	不传返回所有实例结果的数组

示例：

typescript

processor.onEvent((event) => {
  const { message, resolve } = event;
  if (message.userAction.name === 'submit') {
    // 获取单个编辑器数据
    const result = processor.getPangoEditorParams('my-editor-001');
    console.log({ result });

    // 获取所有编辑器数据
    const allResults = processor.getPangoEditorParams();
  }
});

resetPangoEditorInstance

重置 PangoEditor 编辑器，用初始数据重新渲染（清空当前编辑内容，恢复到初始打开状态）。

typescript

resetPangoEditorInstance(domId?: string): void

参数：

参数	类型	说明
`domId`	`string`	容器 DOM 标识（可选）

行为：

调用方式	说明
`resetPangoEditorInstance(domId)`	重置指定编辑器
`resetPangoEditorInstance()`	重置所有编辑器

原理： 重新发送编辑器挂载时的初始命令（type + param），使编辑器恢复到初始渲染状态。

示例：

typescript

processor.onEvent((event) => {
  const { message, resolve } = event;
  if (message.userAction.name === 'resetEditor') {
    // 重置指定编辑器
    processor.resetPangoEditorInstance('my-editor-001');

    // 重置所有编辑器
    // processor.resetPangoEditorInstance();

    resolve([]);
  }
});

在事件回调中通过 apis 参数获取的操作方法集合。

typescript

interface SurfaceApis {
  updateDataModel: (surfaceId: string, path: string, value: DataValue) => void;
  updateComponentProp: (
    surfaceId: string,
    componentId: string,
    propName: string,
    propValue: any,
  ) => void;
  getDataValue: (surfaceId: string, path: string) => DataValue | null;
  getFormInstance: (formId: string) => A2UIFormInstance | undefined;
  getPangoEditorInstance: (domId?: string) => any;
  getPangoEditorParams: (domId?: string) => any;
  resetPangoEditorInstance: (domId?: string) => void;
}

updateDataModel

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

typescript

updateDataModel(surfaceId: string, path: string, value: DataValue): void

示例：

typescript

apis.updateDataModel(surfaceId, '/userName', '张三');

WARNING

在用户交互事件中，updateDataModel 只更新数据，之后必须调用 resolve([]) 才能让 UI 刷新。在通知型事件中则不需要，数据立即生效。

updateComponentProp

直接更新组件的属性。

typescript

updateComponentProp(
  surfaceId: string,
  componentId: string,
  propName: string,
  propValue: any,
): void

示例：

typescript

// 禁用按钮
apis.updateComponentProp(surfaceId, 'btn_submit', 'disabled', true);

// 修改输入框占位文字
apis.updateComponentProp(surfaceId, 'input_name', 'placeholder', '请输入姓名');

下一步

核心概念：5 分钟上手 A2UI
JSON 消息格式：查阅消息格式和配置
简化 API 对接：通过 processMessages2 快速对接
Window 事件监听：非 Vue 环境下的事件监听方式

Processor API 参考 ​

方法一览 ​

Surface 管理 ​

getSurfaces ​

clearSurfaces ​

消息处理 ​

processMessages ​

processMessages2 ​

数据操作 ​

getDataValue ​

事件监听 ​

onSurfaceCreated ​

onSurfaceUpdated ​

onEvent ​

事件派发 ​

dispatch ​

表单操作 ​

getFormInstance ​

编辑器操作 ​

getPangoEditorInstance ​

getPangoEditorParams ​

resetPangoEditorInstance ​

updateDataModel ​

updateComponentProp ​

下一步 ​

Processor API 参考

方法一览

Surface 管理

getSurfaces

clearSurfaces

消息处理

processMessages

processMessages2

数据操作

getDataValue

事件监听

onSurfaceCreated

onSurfaceUpdated

onEvent

事件派发

dispatch

表单操作

getFormInstance

编辑器操作

getPangoEditorInstance

getPangoEditorParams

resetPangoEditorInstance

updateDataModel

updateComponentProp

下一步