跳到正文
本页内容

组件与结构

理解 A2UI v0.9 的扁平组件模型、ID 引用、数据绑定与增量更新。

更新: 2026/8/24 审校: HIA2UI 编辑组 v0.9.1

组件与结构

A2UI 使用扁平组件对象列表描述 Surface。组件通过 ID 引用子组件,因此 Agent 可以流式添加或替换单个定义,不必重新生成深层嵌套树。

v0.9 组件列表

{
  "version": "v0.9.1",
  "updateComponents": {
    "surfaceId": "main",
    "components": [
      {"id":"root","component":"Column","children":["greeting","actions"]},
      {"id":"greeting","component":"Text","text":"你好","variant":"h2"},
      {"id":"actions","component":"Row","children":["cancel","confirm"],"justify":"end"},
      {"id":"cancel-label","component":"Text","text":"取消"},
      {"id":"cancel","component":"Button","child":"cancel-label","action":{"event":{"name":"cancel"}}},
      {"id":"confirm-label","component":"Text","text":"确认"},
      {"id":"confirm","component":"Button","child":"confirm-label","variant":"primary","action":{"event":{"name":"confirm"}}}
    ]
  }
}

其中一个组件按约定使用 root ID。每个组件都有唯一 id、字符串 component 类型,以及所选 Catalog 定义的属性。

固定与动态子组件

固定子组件列表是 ID 数组:

{"id":"toolbar","component":"Row","children":["back","title","menu"]}

对于数据驱动列表,ChildList 还支持 v0.9 公共类型定义的模板结构。应按准确 Schema 校验,不能继续复制 v0.8 的 explicitListdataBinding 示例。

字面值与绑定值

动态属性既可以是字面值,也可以是 JSON Pointer 路径:

{"id":"fixed","component":"Text","text":"欢迎"}
{"id":"bound","component":"Text","text":{"path":"/user/name"}}

数据模型的 /user/name 改变时,渲染器更新绑定组件。宿主还应限制可写路径,并校验值类型与大小。

增量更新

updateComponents 中的新 ID 会添加定义;相同 ID 会替换定义。停止显示某个子组件时,更新父组件的子项列表。删除完整 Surface 使用 deleteSurface,并应释放全部关联状态。

因此组件 ID 必须稳定。替换组件时也应提供完整的新定义,不能假设省略属性会自动合并。

Catalog 边界

基础 Catalog 提供常用布局、文本、媒体、输入和容器组件。宿主可以协商自定义 Catalog,引入图表或地图等产品组件。渲染器必须拒绝协商 Catalog 之外的类型与属性。

继续阅读组件参考消息参考和官方 v0.9.1 协议