Ant Design X

A2UI v0.9

Ant Design X

A2UI v0.9

API

通用属性参考：通用属性

BoxProps

Box 组件作为容器，用于管理 Card 实例和命令分发。

属性	说明	类型	默认值	版本
children	子元素	React.ReactNode	-	-
components	自定义组件映射，组件名称必须以大写字母开头	Record<string, React.ComponentType<any>>	-	-
commands	A2UI 命令对象	A2UICommand_v0_9 \| XAgentCommand_v0_8	-	-
onAction	Card 内部组件触发 action 时的回调函数	(payload: ActionPayload) => void	-	-

CardProps

Card 组件用于渲染单个 Surface。

属性	说明	类型	默认值	版本
id	Surface ID，对应命令中的 surfaceId	string	-	-

ActionPayload

action 事件的数据结构。

属性	说明	类型	默认值	版本
name	事件名称	string	-	-
surfaceId	触发该 action 的 surfaceId	string	-	-
context	组件传递的上下文，已解析 path 引用	Record<string, any>	-	-

Action Context 中的 Path 引用解析

当组件触发 action 时，X-Card 会自动解析 context 中的 path 引用为实际值。

Path 引用格式

在 action 配置中使用 { path: string } 格式绑定 dataModel 中的值：

json

{
  "id": "submit-btn",
  "component": "Button",
  "action": {
    "event": {
      "name": "agent:send_context_text",
      "context": {
        "username": { "path": "/form/username", "label": "用户名" },
        "email": { "path": "/form/email", "label": "邮箱" }
      }
    }
  }
}

解析结果

当用户点击按钮触发 action 时，onAction 回调收到的 context 会被自动解析：

json

{
  "username": { "value": "张三", "label": "用户名" },
  "email": { "value": "test@example.com", "label": "邮箱" }
}

注意：

仅当 context 中的值本身是 { path: "xxx" } 格式时才进行转换
组件传递的实际值（如 { value: "实际值" }）不会被错误转换
保留其他属性（如 label），只将 path 替换为 value

A2UICommand_v0_9

v0.9 版本的命令类型，支持以下命令：

CreateSurfaceCommand

创建新的 Surface。

属性	说明	类型	默认值	版本
version	版本号	'v0.9'	-	-
createSurface.surfaceId	Surface ID	string	-	-
createSurface.catalogId	组件目录 URL 或本地标识	string	-	-

UpdateComponentsCommand

更新 Surface 上的组件。

属性	说明	类型	默认值	版本
version	版本号	'v0.9'	-	-
updateComponents.surfaceId	Surface ID	string	-	-
updateComponents.components	组件列表	BaseComponent_v0_9[]	-	-

BaseComponent_v0_9

typescript

interface BaseComponent_v0_9 {
  id: string;
  component: string;
  child?: string;
  children?: string[];
  [key: string]: any | PathValue;
}

UpdateDataModelCommand

更新数据模型。

属性	说明	类型	默认值	版本
version	版本号	'v0.9'	-	-
updateDataModel.surfaceId	Surface ID	string	-	-
updateDataModel.path	数据路径	string	-	-
updateDataModel.value	数据值	any	-	-

DeleteSurfaceCommand

删除 Surface。

属性	说明	类型	默认值	版本
version	版本号	'v0.9'	-	-
deleteSurface.surfaceId	Surface ID	string	-	-

PathValue

数据绑定路径对象。

typescript

interface PathValue {
  path: string;
}

Catalog

组件目录定义。

typescript

interface Catalog {
  $schema?: string;
  $id?: string;
  title?: string;
  description?: string;
  catalogId?: string;
  components?: Record<string, CatalogComponent>;
  functions?: Record<string, any>;
  $defs?: Record<string, any>;
}

CatalogComponent

Catalog 中的组件定义。

typescript

interface CatalogComponent {
  type: 'object';
  allOf?: any[];
  properties?: Record<string, any>;
  required?: string[];
  [key: string]: any;
}

Catalog 相关方法

registerCatalog

注册本地 catalog。

typescript

registerCatalog(catalog: Catalog): void

loadCatalog

加载 catalog（支持远程 URL 或本地注册的 schema）。

typescript

loadCatalog(catalogId: string): Promise<Catalog>

validateComponent

验证组件是否符合 catalog 定义。

typescript

validateComponent(catalog: Catalog, componentName: string, componentProps: Record<string, any>): boolean

clearCatalogCache

清除 catalog 缓存。

typescript

clearCatalogCache(): void

基础

使用 XCard 实现 A2UI v0.9 协议的基础示例。演示了如何使用 XAgentCommand_v0_9 命令配合本地 catalog.json 来创建咖啡预订场景的交互卡片。v0.9 版本引入了更简洁的命令结构和 catalog 机制。

渐进式

使用 XCard 实现 A2UI v0.9 协议的渐进式加载示例。演示了如何分批次加载产品数据，并通过 updateComponents 命令渐进式更新组件，配合加载指示器展示加载进度，实现流畅的加载体验。

流式渲染

使用 XCard 实现 A2UI v0.9 协议的流式内容与实时更新示例。演示了 AI 推荐结果的流式展示、组件逐步加载动画和加载进度指示，配合 catalog 机制。

嵌套交互

使用 XCard 实现 A2UI v0.9 协议的复杂交互与嵌套组件示例。演示了可展开的详情卡片、树形文件浏览器和手风琴折叠面板，配合 catalog 机制。

多卡片同步

使用 XCard 实现 A2UI v0.9 协议的多卡片协同与状态同步示例。演示了购物车场景中多个 Surface 之间的数据共享、跨卡片通信和实时价格计算，配合 catalog 机制。

筛选搜索

使用 XCard 实现 A2UI v0.9 协议的动态数据筛选与搜索示例。演示了如何使用 antd 组件配合 catalog 机制实现实时搜索、多条件筛选和结果动态更新。

表单验证

使用 XCard 实现 A2UI v0.9 协议的表单验证与错误处理示例。演示了如何使用 antd Form 组件配合 catalog 机制实现实时验证、错误状态管理和多步骤表单流程。

填写表单后点击提交，观察 onAction 回调中 context 的变化

onAction 回调日志（path 引用已解析）：

暂无日志，请填写表单后提交

Action Context 解析

演示 X-Card 在触发 action 时自动解析 context 中的 path 引用为实际值。

当组件触发 action 时（如提交表单），X-Card 会自动将 action 配置中的 { path: "xxx" } 格式转换为 { value: "实际值" } 格式，方便外部直接使用解析后的值。

API

通用属性参考：通用属性

BoxProps

Box 组件作为容器，用于管理 Card 实例和命令分发。

属性	说明	类型	默认值	版本
children	子元素	React.ReactNode	-	-
components	自定义组件映射，组件名称必须以大写字母开头	Record<string, React.ComponentType<any>>	-	-
commands	A2UI 命令对象	A2UICommand_v0_9 \| XAgentCommand_v0_8	-	-
onAction	Card 内部组件触发 action 时的回调函数	(payload: ActionPayload) => void	-	-

CardProps

Card 组件用于渲染单个 Surface。

属性	说明	类型	默认值	版本
id	Surface ID，对应命令中的 surfaceId	string	-	-

ActionPayload

action 事件的数据结构。

属性	说明	类型	默认值	版本
name	事件名称	string	-	-
surfaceId	触发该 action 的 surfaceId	string	-	-
context	组件传递的上下文，已解析 path 引用	Record<string, any>	-	-

Action Context 中的 Path 引用解析

当组件触发 action 时，X-Card 会自动解析 context 中的 path 引用为实际值。

Path 引用格式

在 action 配置中使用 { path: string } 格式绑定 dataModel 中的值：

json

{
  "id": "submit-btn",
  "component": "Button",
  "action": {
    "event": {
      "name": "agent:send_context_text",
      "context": {
        "username": { "path": "/form/username", "label": "用户名" },
        "email": { "path": "/form/email", "label": "邮箱" }
      }
    }
  }
}

解析结果

当用户点击按钮触发 action 时，onAction 回调收到的 context 会被自动解析：

json

{
  "username": { "value": "张三", "label": "用户名" },
  "email": { "value": "test@example.com", "label": "邮箱" }
}

注意：

仅当 context 中的值本身是 { path: "xxx" } 格式时才进行转换
组件传递的实际值（如 { value: "实际值" }）不会被错误转换
保留其他属性（如 label），只将 path 替换为 value

A2UICommand_v0_9

v0.9 版本的命令类型，支持以下命令：

CreateSurfaceCommand

创建新的 Surface。

属性	说明	类型	默认值	版本
version	版本号	'v0.9'	-	-
createSurface.surfaceId	Surface ID	string	-	-
createSurface.catalogId	组件目录 URL 或本地标识	string	-	-

UpdateComponentsCommand

更新 Surface 上的组件。

属性	说明	类型	默认值	版本
version	版本号	'v0.9'	-	-
updateComponents.surfaceId	Surface ID	string	-	-
updateComponents.components	组件列表	BaseComponent_v0_9[]	-	-

BaseComponent_v0_9

typescript

interface BaseComponent_v0_9 {
  id: string;
  component: string;
  child?: string;
  children?: string[];
  [key: string]: any | PathValue;
}

UpdateDataModelCommand

更新数据模型。

属性	说明	类型	默认值	版本
version	版本号	'v0.9'	-	-
updateDataModel.surfaceId	Surface ID	string	-	-
updateDataModel.path	数据路径	string	-	-
updateDataModel.value	数据值	any	-	-

DeleteSurfaceCommand

删除 Surface。

属性	说明	类型	默认值	版本
version	版本号	'v0.9'	-	-
deleteSurface.surfaceId	Surface ID	string	-	-

PathValue

数据绑定路径对象。

typescript

interface PathValue {
  path: string;
}

Catalog

组件目录定义。

typescript

interface Catalog {
  $schema?: string;
  $id?: string;
  title?: string;
  description?: string;
  catalogId?: string;
  components?: Record<string, CatalogComponent>;
  functions?: Record<string, any>;
  $defs?: Record<string, any>;
}

CatalogComponent

Catalog 中的组件定义。

typescript

interface CatalogComponent {
  type: 'object';
  allOf?: any[];
  properties?: Record<string, any>;
  required?: string[];
  [key: string]: any;
}

Catalog 相关方法

registerCatalog

注册本地 catalog。

typescript

registerCatalog(catalog: Catalog): void

loadCatalog

加载 catalog（支持远程 URL 或本地注册的 schema）。

typescript

loadCatalog(catalogId: string): Promise<Catalog>

validateComponent

验证组件是否符合 catalog 定义。

typescript

validateComponent(catalog: Catalog, componentName: string, componentProps: Record<string, any>): boolean

clearCatalogCache

清除 catalog 缓存。

typescript

clearCatalogCache(): void

基础

使用 XCard 实现 A2UI v0.9 协议的基础示例。演示了如何使用 XAgentCommand_v0_9 命令配合本地 catalog.json 来创建咖啡预订场景的交互卡片。v0.9 版本引入了更简洁的命令结构和 catalog 机制。

渐进式

使用 XCard 实现 A2UI v0.9 协议的渐进式加载示例。演示了如何分批次加载产品数据，并通过 updateComponents 命令渐进式更新组件，配合加载指示器展示加载进度，实现流畅的加载体验。

流式渲染

使用 XCard 实现 A2UI v0.9 协议的流式内容与实时更新示例。演示了 AI 推荐结果的流式展示、组件逐步加载动画和加载进度指示，配合 catalog 机制。

嵌套交互

使用 XCard 实现 A2UI v0.9 协议的复杂交互与嵌套组件示例。演示了可展开的详情卡片、树形文件浏览器和手风琴折叠面板，配合 catalog 机制。

多卡片同步

使用 XCard 实现 A2UI v0.9 协议的多卡片协同与状态同步示例。演示了购物车场景中多个 Surface 之间的数据共享、跨卡片通信和实时价格计算，配合 catalog 机制。

筛选搜索

使用 XCard 实现 A2UI v0.9 协议的动态数据筛选与搜索示例。演示了如何使用 antd 组件配合 catalog 机制实现实时搜索、多条件筛选和结果动态更新。

表单验证

使用 XCard 实现 A2UI v0.9 协议的表单验证与错误处理示例。演示了如何使用 antd Form 组件配合 catalog 机制实现实时验证、错误状态管理和多步骤表单流程。

填写表单后点击提交，观察 onAction 回调中 context 的变化

onAction 回调日志（path 引用已解析）：

暂无日志，请填写表单后提交

Action Context 解析

演示 X-Card 在触发 action 时自动解析 context 中的 path 引用为实际值。

当组件触发 action 时（如提交表单），X-Card 会自动将 action 配置中的 { path: "xxx" } 格式转换为 { value: "实际值" } 格式，方便外部直接使用解析后的值。