数据绑定¶

数据绑定使用 JSON Pointer 路径（RFC 6901）将 UI 组件连接到应用状态。这使 A2UI 能够高效地为大型数据数组定义布局，或显示更新的内容而无需从头重新生成。

结构与状态¶

A2UI 分离：

UI 结构（组件）：界面的外观
应用状态（数据模型）：它显示的数据

这支持：响应式更新、数据驱动的 UI、可重用模板和双向绑定。

数据模型¶

每个界面都有一个保存状态的 JSON 对象：

{
  "user": {"name": "Alice", "email": "alice@example.com"},
  "cart": {
    "items": [{"name": "Widget", "price": 9.99, "quantity": 2}],
    "total": 19.98
  }
}

JSON Pointer 路径¶

语法：

/user/name - 对象属性
/cart/items/0 - 数组索引（从零开始）
/cart/items/0/price - 嵌套路径

示例：

{"user": {"name": "Alice"}, "items": ["Apple", "Banana"]}

/user/name → "Alice"
/items/0 → "Apple"

字面量与路径值¶

字面量（固定）：

{"id": "title", "component": {"Text": {"text": {"literalString": "欢迎"}}}}

数据绑定（响应式）：

{"id": "username", "component": {"Text": {"text": {"path": "/user/name"}}}}

当 /user/name 从 "Alice" 更改为 "Bob" 时，文本自动更新为 "Bob"。

响应式更新¶

绑定到数据路径的组件在数据更改时自动更新：

{"id": "status", "component": {"Text": {"text": {"path": "/order/status"}}}}

初始： /order/status = "处理中..." → 显示 "处理中..."
更新： 发送带有 status: "已发货" 的 dataModelUpdate → 显示 "已发货"

无需组件更新——只需数据更新。

动态列表¶

使用模板渲染数组：

{
  "id": "product-list",
  "component": {
    "Column": {
      "children": {"template": {"dataBinding": "/products", "componentId": "product-card"}}
    }
  }
}

数据：

{"products": [{"name": "Widget", "price": 9.99}, {"name": "Gadget", "price": 19.99}]}

结果： 渲染两个卡片，每个产品一个。

作用域路径¶

在模板内部，路径作用域限定为数组项：

{"id": "product-name", "component": {"Text": {"text": {"path": "/name"}}}}

对于 /products/0，/name 解析为 /products/0/name → "Widget"
对于 /products/1，/name 解析为 /products/1/name → "Gadget"

添加/删除项目会自动更新渲染的组件。

输入绑定¶

交互式组件双向更新数据模型：

组件	示例	用户操作	数据更新
TextField	`{"text": {"path": "/form/name"}}`	输入 "Alice"	`/form/name` = "Alice"
CheckBox	`{"value": {"path": "/form/agreed"}}`	勾选框	`/form/agreed` = true
MultipleChoice	`{"selections": {"path": "/form/country"}}`	选择 "Canada"	`/form/country` = ["ca"]

最佳实践¶

1. 使用细粒度更新 - 仅更新已更改的路径：

{"dataModelUpdate": {"path": "/user", "contents": [{"key": "name", "valueString": "Alice"}]}}

2. 按领域组织 - 分组相关数据：

{"user": {...}, "cart": {...}, "ui": {...}}

3. 预计算显示值 - 智能体在发送前格式化数据（货币、日期）：

{"price": "$19.99"}  // 而不是: {"price": 19.99}