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: 添加详细的安全最佳实践和代码示例。

下一步