A2UI AI 界面 | AIUI | Rokid

a2ui 用于把 AI 生成的结构化指令转换成可见的界面。适合在界面内容由智能体动态决定时使用,例如根据用户问题生成结果卡片、列表或图表。

A2UI AI 界面

a2ui 用于把 AI 生成的结构化指令转换成可见的界面。适合在界面内容由智能体动态决定时使用,例如根据用户问题生成结果卡片、列表或图表。

如果界面结构是固定的,直接使用 view、text 等普通组件会更简单。

显示初始界面

先给组件设置一个唯一的 id,再通过 commands 传入 A2UI 指令。commands 只会在组件首次渲染时处理一次。

<a2ui id="answer" commands="{{initialCommands}}"></a2ui>
export default {
  data: {
    initialCommands: JSON.stringify([
      {
        version: 'v0.9',
        createSurface: { surfaceId: 'main' }
      },
      {
        version: 'v0.9',
        updateComponents: {
          surfaceId: 'main',
          components: [
            { id: 'title', component: 'Text', text: '今日天气:晴' }
          ]
        }
      }
    ])
  }
};

commands 接收字符串,因此需要使用 JSON.stringify() 把指令数组转换成 JSON 字符串。

更新已经显示的界面

当新的 AI 结果到达时,通过组件的 id 创建上下文,再调用 write():

const context = a2ui.createA2UIContext('answer');

if (context) {
  context.write(JSON.stringify([
    {
      version: 'v0.9',
      updateComponents: {
        surfaceId: 'main',
        components: [
          { id: 'title', component: 'Text', text: '今日天气:多云' }
        ]
      }
    }
  ]));
}

找不到对应 id 时,createA2UIContext() 返回 null,因此调用前应先检查结果。

分段接收 AI 输出

如果 AI 的响应是逐步返回的,可以创建写入器,将收到的字符串片段依次写入。最后必须调用 close(),让组件处理剩余内容。

const context = a2ui.createA2UIContext('answer');

if (context) {
  const writer = context.startStream();
  writer.writeChunk('{"version":"v0.9","createSurface":');
  writer.writeChunk('{"surfaceId":"stream-result"}}');
  writer.close();
}

需要移除当前生成的界面时,调用 context.clear()。

属性

属性类型默认值说明
idString-组件标识,供 a2ui.createA2UIContext() 查找组件。动态更新时必须设置。
commandsString-首次渲染时处理的 A2UI JSON 指令,只处理一次。
default-chart-animateBooleantrueA2UI 创建图表且指令没有明确设置动画时,是否默认启用动画。也可写成 defaultChartAnimate。

JavaScript 方法

方法说明
a2ui.createA2UIContext(id)根据组件 id 返回操作上下文;找不到组件时返回 null。
context.write(data)使用完整的 JSON 字符串更新界面。
context.startStream()开始一次分段写入并返回写入器。
writer.writeChunk(chunk)写入一段字符串。
writer.close()结束本次分段写入。
context.clear()清除当前生成的界面内容。

a2ui 不提供 agent-id、session-id 或 bindmessage 属性。智能体会话和消息接收应由页面或 Agent Worker 管理,再把最终的 A2UI 指令交给组件显示。

为生成的图片着色和适配

A2UI Image / image 的属性映射到原生图片属性:

A2UI 属性原生属性行为
tintColortint-color颜色字符串或数据绑定;同时提供两种拼写时,显式 tint-color 优先。
fit: 'contain'mode="aspectFit"保持比例,完整显示图片。
fit: 'cover'mode="aspectFill"保持比例并裁剪以填满区域。
fit: 'fill'mode="scaleToFill"拉伸以填满区域。
modemode显式 mode 优先于 fit。

透明度相乘和 SVG 主题着色规则见 Image。更新保留相同类型的图片组件,并按位置复用模板项,减少重复加载并保留播放状态;组件类型改变时会重新创建。