AGenUI 22个内置组件完整清单:从布局到交互的 Generative UI 组件全用法指南
AGenUI 22个内置组件完整清单:从布局到交互的 Generative UI 组件全用法指南
AGenUI 是面向 iOS / Android / HarmonyOS 的原生 A2UI 渲染器(Native A2UI Renderer),支持高性能流式生成式 UI(Generative UI)。它内置 22 个常用组件:其中 18 个来自 A2UI 标准协议目录,另有 RichText、Lottie、Web、Carousel、Table 等扩展组件,另有 Markdown 和 Chart 两个特色组件。本文带你一次性掌握全部内置组件的用法。
内置组件总览清单
| 分类 | 组件 |
|---|---|
| 📐 布局类 | Column、Row、List、Card、Tabs、Divider、Modal |
| ✍️ 内容类 | Text、RichText、Markdown、Image、Icon、Video、AudioPlayer、Lottie、Web、Carousel |
| 🖱️ 交互类 | Button、TextField、CheckBox、ChoicePicker、Slider、DateTimeInput |
| 📊 数据类 | Table、Chart |
A2UI 的核心思想是结构与数据分离:updateComponents 描述组件树、布局与样式,updateDataModel 提供数据内容,动态内容通过 {"path": "..."} 绑定。每个组件的 component 字段就是上面清单中的类型名,id 用于在同一个 surface 内互相引用。
18 个 A2UI 协议组件用法
以下 18 个组件对应 A2UI 标准基础目录(参考 basic_catalog.json),也是所有 A2UI 渲染器都会实现的"最大公约数"。
布局类:搭好页面骨架
Column/Row— 纵向 / 横向排列子组件。常用属性:justify(start / center / end / spaceBetween 等)、align(start / center / end / stretch)。List— 列表,支持静态children,也可用{"path": "/data/items", "componentId": "item模板"}由数据驱动动态渲染。Card— 卡片容器,child只接受单个组件 id。Tabs— 标签页,tabs数组中每项包含title(可绑定)与child。Divider— 分隔线,axis可选horizontal/vertical。Modal— 弹窗,trigger指定触发组件,content指定弹窗内容组件。
{"id": "root", "component": "Column", "children": ["title", "card1"], "align": "center"}
{"id": "card1", "component": "Card", "child": "inner"}
内容类:承载信息
Text— 文本,variant支持h1~h5/body/caption七种层级。Image— 图片,variant支持icon/avatar/smallFeature/mediumFeature/largeFeature/header,fit支持cover/contain等。Icon— 内置图标,共 40+ 个预设图标(search、settings、heart、star等),name支持动态绑定。Video— 视频,直接绑定url。AudioPlayer— 音频播放器,可附带description说明。RichText— 富文本(扩展组件),支持<a>、<b>、<font>、<img>等 HTML 标签,linksEnable默认开启。Carousel— 图片轮播(扩展组件),content为图片 URL 数组,autoplay默认false,draggable默认true。
交互类:收集用户输入
Button— 按钮,child为按钮内单个组件(通常是 Text);action支持functionCall(调用内置函数,如openUrl)或event(上报事件)。TextField— 文本输入,variant支持shortText/longText/number/obscured(密码)。CheckBox— 复选框,value绑定布尔值。ChoicePicker— 选择器,variant区分单选mutuallyExclusive与多选multipleSelection。Slider— 滑动条,指定min/max,value绑定当前值。DateTimeInput— 日期时间选择,enableDate/enableTime分别控制。
{"id": "btn1", "component": "Button", "child": "btn_text", "variant": "primary",
"action": {"event": {"name": "submit", "context": {"formId": "form1"}}}}
AGenUI 扩展组件:4+2 进阶能力
4 个高频扩展组件
除了 18 个标准组件,AGenUI 目录额外注册了 RichText、Lottie、Web、Carousel、Table 等扩展组件(见 agenui_catalog.json):
Lottie— Lottie 动画,url支持http、res://、file:///三种来源,autoPlay与loop默认均为true。Web— 内嵌网页,source既可以是 URL 也可以是 HTML 字符串。Table— 表格,columns与rows均支持数据绑定,非常适合展示结构化数据。
{"id": "tb1", "component": "Table", "columns": {"path": "/data/columns"}, "rows": {"path": "/data/rows"}}
2 个特色组件
Markdown— Markdown 渲染组件,支持常见 Markdown 语法,并支持流式增量追加,是 AI 对话场景的首选。Chart— 统一图表组件,通过chartType选择bar/line/donut/bar_grouped四种图表类型。
自定义组件:内置之外还能加什么
内置组件不够用时,三个平台都开放了注册机制,可以把任意原生组件接入 A2UI 协议:
- iOS:ComponentRegister.swift 中通过
register(type, creator)注册工厂,内置组件实现均在 Component/Impl 目录; - Android:ComponentRegistry.java 通过
registerComponent(type, factory)注册,并内置注解处理器processor/辅助生成注册代码; - HarmonyOS:组件类型常量定义在 a2ui_component_types.h。
组件用法速查与学习路径
- 先看组件清单:component-catalog.md 是完整的组件目录,包含每个组件的属性签名与全部样式约束。
- 再玩示例协议:samples/protocols 下提供 12 个真实场景(天气预报、航班时刻、电影推荐、停车推荐等),每个场景包含
updateComponents.json+updateDataModel.json和渲染效果图,是最直观的用法参考。 - 上手体验:按 QuickStart 跑起 Playground,各平台示例工程位于 playground/ 目录。
- 进阶设计:写组件时参考 component-design.md 与 data-binding.md,了解数据绑定与视觉规范。
💡 小贴士:A2UI 组件的样式采用统一的 CSS 子集(如
background-color、border-radius、flex-grow),字号建议遵循统一字阶(标题 40px / 正文 32px / 标签 24px),跨端表现更一致。
掌握了这份 AGenUI 内置组件清单,你就可以放心地让 AI 生成的 JSON 描述变成流畅的跨端原生界面了 🚀




