快速上手

安装

前置要求：Vue 3.4+，Node.js 18+

npm

npm install win-design-a2ui-vue --registry http://172.16.9.57:8081/repository/npm-group/ --save

pnpm

pnpm add win-design-a2ui-vue --registry http://172.16.9.57:8081/repository/npm-group/ --save

yarn

yarn add win-design-a2ui-vue --registry http://172.16.9.57:8081/repository/npm-group/ --save

引入样式

// main.ts 或入口文件
import 'win-design-a2ui-vue/dist/win-design-a2ui-vue.css';

---

最小示例（3 步跑起来）

不管你用哪种模式，前两步都一样：

第 1 步：配置 A2UI（App.vue）

<!-- App.vue -->
<script setup lang="ts">
import { provideA2UI, DEFAULT_CATALOG } from 'win-design-a2ui-vue';

// 只需调用一次，告诉 A2UI 用哪些组件
provideA2UI({ catalog: DEFAULT_CATALOG, theme: {} });
</script>

<template>
  <RouterView />
</template>

第 2 步：创建 processor（页面组件）

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

const processor = useMessageProcessor();

第 3 步：选择你的模式

根据你的场景，二选一：

---

模式 A：processMessages2（推荐 - 对接后端 API）

特点：一个调用搞定渲染 + 数据加载 + 按钮点击自动调 API。

流程说明：

你的代码                          A2UI 自动完成
────────                          ──────────────
processMessages2(...)
    │
    ├─ components ───────────────► 渲染组件（输入框 + 按钮）
    ├─ data ─────────────────────► 填充初始数据
    │
    │  ...用户点击"提交"按钮...
    │
    └─ callback 自动触发  ◄─────── 自动 POST 到 /api/submit
                                   参数包含：表单数据 + sessionCtx + businessParams

callback 参数说明：

参数	说明
actionInfo.actionType	'load'（页面加载）或 'event'（按钮点击）
actionInfo.actionName	事件名称（对应 action.event.name）
result	后端 API 返回的 JSON。异常时为 { error: true, message: string }

---

模式 B：processMessages（AI Agent 推送）

特点：分步发送消息，手动监听事件处理业务逻辑。

流程说明：

你的代码                          你需要处理的
────────                          ────────────
processMessages([...])
    │
    ├─ createSurface ────────────► 创建画布
    ├─ updateComponents ─────────► 渲染组件树
    │
    │  ...用户点击按钮...
    │
    └─ onEvent 回调触发  ◄──────── 你在这里处理业务逻辑
                                   处理完调用 resolve([]) 或 resolve(更新消息)

resolve 必须调用

event.resolve() 必须调用，否则按钮会一直 loading。即使不更新 UI 也要调用 resolve([])。

---

两种模式对比

	processMessages2	processMessages
适合场景	前端页面直接对接后端 API	AI Agent 推送消息
调用次数	一次调用搞定	分步调用
事件处理	按钮点击自动调 API，callback 接收结果	手动在 onEvent 中处理
数据加载	配置 loadEventHandler 自动加载	手动调用 updateDataModel
API 对接文档	调用后端 API	—
事件监听文档	—	Processor API

---

Processor 方法速查

两种模式共用的方法：

方法	说明
processor.processMessages(messages)	处理 A2UI 消息数组（模式 B）
processor.processMessages2(sessionCtx, params, json, callback)	一次调用：渲染 + 加载数据 + 自动调 API（模式 A）
processor.onEvent(handler)	监听事件，返回取消监听函数
processor.getSurfaces()	获取所有 Surface（非响应式）
processor.clearSurfaces(surfaceId?)	清除 Surface，不传清除全部
processor.getFormInstance(formId)	获取表单实例
processor.getPangoEditorInstance(domId?)	获取编辑器实例
processor.getPangoEditorParams(domId?)	获取编辑器 FileSave 数据
processor.resetPangoEditorInstance(domId?)	重置编辑器（用初始数据重新渲染）

完整 API 说明见 Processor API 参考

---

下一步

• 核心概念 — JSON 是怎么变成页面的？渲染管线详解
• JSON 消息格式 — 所有 JSON 字段参考（组件、数据绑定、action 配置）
• 调用后端 API — processMessages2 详细用法 + callback 说明
• Processor API 参考 — processor 所有方法和事件监听
• PangoEditor 编辑器 — 富文本编辑器组件的配置和使用