Skip to content

自定义组件目录

通过定义自定义目录来扩展 A2UI，这些目录包含你自己的组件以及标准 A2UI 组件。

为什么使用自定义目录？

A2UI 标准目录提供常见的 UI 元素（按钮、文本字段等），但你的应用可能需要专用组件：

  • 特定领域的组件：股票行情、医疗图表、CAD 查看器
  • 第三方集成：Google 地图、支付表单、聊天组件
  • 品牌特定组件：自定义日期选择器、产品卡片、仪表板

自定义目录是可以包含以下内容的组件集合： - 标准 A2UI 组件（Text、Button、TextField 等） - 你的自定义组件（GoogleMap、StockTicker 等） - 第三方组件

你向客户端应用注册整个目录，而不是单个组件。这允许智能体和客户端就共享的扩展组件集达成一致，同时保持安全性和类型安全。

自定义目录如何工作

  1. 客户端定义目录：你创建一个目录定义，列出标准和自定义组件。
  2. 客户端注册目录：你向客户端应用注册目录（及其组件实现）。
  3. 客户端宣布支持：客户端通知智能体它支持哪些目录。
  4. 智能体选择目录：智能体为给定的 UI 界面选择一个目录。
  5. 智能体生成 UI：智能体使用该目录中的组件按名称生成 surfaceUpdate 消息。

定义自定义目录

TODO：添加为每个平台定义自定义目录的详细指南。

Web（Lit / Angular）： - 如何定义包含标准和自定义组件的目录 - 如何向 A2UI 客户端注册目录 - 如何实现自定义组件类

Flutter： - 如何使用 GenUI 定义自定义目录 - 如何注册自定义组件渲染器

查看工作示例： - Lit 示例 - Angular 示例 - Flutter GenUI 文档

智能体端：使用自定义目录中的组件

一旦目录在客户端注册，智能体就可以在 surfaceUpdate 消息中使用其中的组件。

智能体通过 beginRendering 消息中的 catalogId 指定要使用的目录。

TODO：添加以下示例： - 智能体如何选择目录 - 智能体如何引用目录中的自定义组件 - 目录版本控制如何工作

数据绑定和操作

自定义组件支持与标准组件相同的数据绑定和操作机制：

  • 数据绑定：自定义组件可以使用 JSON Pointer 语法将属性绑定到数据模型路径
  • 操作：自定义组件可以发出智能体接收和处理的操作

安全考虑

创建自定义目录和组件时：

  1. 允许列表组件：仅在目录中注册你信任的组件
  2. 验证属性：始终验证来自智能体消息的组件属性
  3. 清理用户输入：如果组件接受用户输入，在处理之前清理它
  4. 限制 API 访问：不要向自定义组件暴露敏感的 API 或凭据

TODO：添加详细的安全最佳实践和代码示例。

下一步