自定义组件目录¶
通过定义 自定义目录 来扩展 A2UI，这些目录将你自己的组件与标准 A2UI 组件包含在一起。
为什么使用自定义目录？¶
A2UI 标准目录提供了通用的 UI 元素（按钮、文本字段等），但你的应用程序可能需要专门的组件：
- 特定领域的小部件: 股票行情显示器、医疗图表、CAD 查看器
- 第三方集成: Google 地图、支付表单、聊天小部件
- 品牌特定组件: 自定义日期选择器、产品卡片、仪表板
自定义目录 是组件的集合，可以包括： - 标准 A2UI 组件（Text, Button, TextField 等） - 你的自定义组件（GoogleMap, StockTicker 等） - 第三方组件
你向客户端应用程序注册整个目录，而不是单个组件。这允许代理和客户端就一组共享的、扩展的组件达成一致，同时保持安全性和类型安全。
自定义目录如何工作¶
- 客户端定义目录: 你创建一个列出标准组件和自定义组件的目录定义。
- 客户端注册目录: 你向客户端应用程序注册目录（及其组件实现）。
- 客户端宣布支持: 客户端通知代理它支持哪些目录。
- 代理选择目录: 代理为给定的 UI 界面选择一个目录。
- 代理生成 UI: 代理使用该目录中的组件按名称生成
surfaceUpdate消息。
定义自定义目录¶
TODO: 为每个平台添加定义自定义目录的详细指南。
Web (Lit / Angular): - 如何定义包含标准和自定义组件的目录 - 如何向 A2UI 客户端注册目录 - 如何实现自定义组件类
Flutter: - 如何使用 GenUI 定义自定义目录 - 如何注册自定义组件渲染器
查看工作示例： - Lit 示例 - Angular 示例 - Flutter GenUI 文档
代理端：使用自定义目录中的组件¶
一旦目录在客户端注册，代理就可以在 surfaceUpdate 消息中使用其中的组件。
代理通过 beginRendering 消息中的 catalogId 指定要使用的目录。
TODO: 添加以下示例： - 代理如何选择目录 - 代理如何引用目录中的自定义组件 - 目录版本控制如何工作
数据绑定和操作¶
自定义组件支持与标准组件相同的数据绑定和操作机制：
- 数据绑定: 自定义组件可以使用 JSON Pointer 语法将属性绑定到数据模型路径
- 操作: 自定义组件可以发出代理接收并处理的操作
安全注意事项¶
在创建自定义目录和组件时：
- 允许列表组件: 仅在你的目录中注册你信任的组件
- 验证属性: 始终验证来自代理消息的组件属性
- 清理用户输入: 如果组件接受用户输入，请在处理之前对其进行清理
- 限制 API 访问: 不要向自定义组件公开敏感 API 或凭据
TODO: 添加详细的安全最佳实践和代码示例。