Ant Design X

A2UI v0.8

Ant Design X

A2UI v0.8

API

Common props ref: Common Props

BoxProps

Box component serves as a container to manage Card instances and command dispatching.

Property	Description	Type	Default	Version
children	Child elements	React.ReactNode	-	-
components	Custom component mapping, component names must start with uppercase letters	Record<string, React.ComponentType<any>>	-	-
commands	A2UI command object	A2UICommand_v0_9 \| XAgentCommand_v0_8	-	-
onAction	Callback function when action is triggered inside Card	(payload: ActionPayload) => void	-	-

CardProps

Card component is used to render a single Surface.

Property	Description	Type	Default	Version
id	Surface ID, corresponding to surfaceId in commands	string	-	-

ActionPayload

Data structure for action events.

Property	Description	Type	Default	Version
name	Event name	string	-	-
surfaceId	The surfaceId that triggered the action	string	-	-
context	Context passed by component, with path references resolved	Record<string, any>	-	-

Action Context Path Reference Resolution

When a component triggers an action, X-Card automatically resolves path references in the context to actual values.

Path Reference Format (v0.8)

In v0.8, action configuration uses array format to define path binding:

json

{
  "id": "submit-btn",
  "component": {
    "Button": {
      "action": {
        "name": "agent:send_context_text",
        "context": [
          { "key": "username", "value": { "path": "/form/username" } },
          { "key": "email", "value": { "path": "/form/email" } }
        ]
      }
    }
  }
}

Resolution Result

When user clicks the button to trigger action, the context received by onAction callback is automatically resolved:

json

{
  "username": { "value": "John" },
  "email": { "value": "john@example.com" }
}

Note:

Only values in { path: "xxx" } format in the context are converted
Actual values passed by component are not incorrectly converted

XAgentCommand_v0_8

Command type for v0.8 version, supporting the following commands:

SurfaceUpdateCommand

Update components on a Surface.

Property	Description	Type	Default	Version
surfaceUpdate.surfaceId	Surface ID	string	-	-
surfaceUpdate.components	Component list	ComponentWrapper_v0_8[]	-	-

ComponentWrapper_v0_8

Component wrapper structure for v0.8 version.

typescript

interface ComponentWrapper_v0_8 {
  id: string;
  component: {
    [componentType: string]: {
      child?: string;
      children?: string[] | ExplicitList;
      [key: string]: any | PathValue | LiteralStringValue;
    };
  };
}

ExplicitList

typescript

interface ExplicitList {
  explicitList: string[];
}

DataModelUpdateCommand

Update data model (v0.8 format).

Property	Description	Type	Default	Version
dataModelUpdate.surfaceId	Surface ID	string	-	-
dataModelUpdate.contents	Data content list	Array<{ key: string; valueMap: Array<{ key: string; valueString: string }> }>	-	-

BeginRenderingCommand

Begin rendering.

Property	Description	Type	Default	Version
beginRendering.surfaceId	Surface ID	string	-	-
beginRendering.root	Root component ID	string	-	-

DeleteSurfaceCommand

Delete a Surface.

Property	Description	Type	Default	Version
deleteSurface.surfaceId	Surface ID	string	-	-

PathValue

Data binding path object.

typescript

interface PathValue {
  path: string;
}

LiteralStringValue

Literal string value object (v0.8 specific).

typescript

interface LiteralStringValue {
  literalString: string;
}

API

Common props ref: Common Props

BoxProps

Box component serves as a container to manage Card instances and command dispatching.

Property	Description	Type	Default	Version
children	Child elements	React.ReactNode	-	-
components	Custom component mapping, component names must start with uppercase letters	Record<string, React.ComponentType<any>>	-	-
commands	A2UI command object	A2UICommand_v0_9 \| XAgentCommand_v0_8	-	-
onAction	Callback function when action is triggered inside Card	(payload: ActionPayload) => void	-	-

CardProps

Card component is used to render a single Surface.

Property	Description	Type	Default	Version
id	Surface ID, corresponding to surfaceId in commands	string	-	-

ActionPayload

Data structure for action events.

Property	Description	Type	Default	Version
name	Event name	string	-	-
surfaceId	The surfaceId that triggered the action	string	-	-
context	Context passed by component, with path references resolved	Record<string, any>	-	-

Action Context Path Reference Resolution

When a component triggers an action, X-Card automatically resolves path references in the context to actual values.

Path Reference Format (v0.8)

In v0.8, action configuration uses array format to define path binding:

json

{
  "id": "submit-btn",
  "component": {
    "Button": {
      "action": {
        "name": "agent:send_context_text",
        "context": [
          { "key": "username", "value": { "path": "/form/username" } },
          { "key": "email", "value": { "path": "/form/email" } }
        ]
      }
    }
  }
}

Resolution Result

When user clicks the button to trigger action, the context received by onAction callback is automatically resolved:

json

{
  "username": { "value": "John" },
  "email": { "value": "john@example.com" }
}

Note:

Only values in { path: "xxx" } format in the context are converted
Actual values passed by component are not incorrectly converted

XAgentCommand_v0_8

Command type for v0.8 version, supporting the following commands:

SurfaceUpdateCommand

Update components on a Surface.

Property	Description	Type	Default	Version
surfaceUpdate.surfaceId	Surface ID	string	-	-
surfaceUpdate.components	Component list	ComponentWrapper_v0_8[]	-	-

ComponentWrapper_v0_8

Component wrapper structure for v0.8 version.

typescript

interface ComponentWrapper_v0_8 {
  id: string;
  component: {
    [componentType: string]: {
      child?: string;
      children?: string[] | ExplicitList;
      [key: string]: any | PathValue | LiteralStringValue;
    };
  };
}

ExplicitList

typescript

interface ExplicitList {
  explicitList: string[];
}

DataModelUpdateCommand

Update data model (v0.8 format).

Property	Description	Type	Default	Version
dataModelUpdate.surfaceId	Surface ID	string	-	-
dataModelUpdate.contents	Data content list	Array<{ key: string; valueMap: Array<{ key: string; valueString: string }> }>	-	-

BeginRenderingCommand

Begin rendering.

Property	Description	Type	Default	Version
beginRendering.surfaceId	Surface ID	string	-	-
beginRendering.root	Root component ID	string	-	-

DeleteSurfaceCommand

Delete a Surface.

Property	Description	Type	Default	Version
deleteSurface.surfaceId	Surface ID	string	-	-

PathValue

Data binding path object.

typescript

interface PathValue {
  path: string;
}

LiteralStringValue

Literal string value object (v0.8 specific).

typescript

interface LiteralStringValue {
  literalString: string;
}

Basic

Basic example of implementing A2UI v0.8 protocol with XCard. Demonstrates how to use XAgentCommand_v0_8 commands to create an interactive card for a coffee booking scenario.

Progressive

Progressive loading example of implementing A2UI v0.8 protocol with XCard. Demonstrates how to load product data in batches and progressively update components using surfaceUpdate commands to achieve smooth loading animations.

Streaming

Streaming content and real-time updates example implementing A2UI v0.8 protocol with XCard. Demonstrates streaming display of AI recommendation results, progressive component loading animations, and loading progress indicators.

Nested Interaction

Complex interaction and nested components example implementing A2UI v0.8 protocol with XCard. Demonstrates expandable detail cards, tree file browser, and accordion folding panels.

Multi Card Sync

Multi-card coordination and state synchronization example implementing A2UI v0.8 protocol with XCard. Demonstrates data sharing between multiple Surfaces, cross-card communication, and real-time price calculation in a shopping cart scenario.

Filter Search

Dynamic data filtering and search example implementing A2UI v0.8 protocol with XCard. Demonstrates how to use antd components for real-time search, multi-condition filtering, and dynamic result updates.

Form Validation

Form validation and error handling example implementing A2UI v0.8 protocol with XCard. Demonstrates how to use antd Form components for real-time validation, error state management, and multi-step form workflows.

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

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

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

Action Context Resolve

Demonstrates X-Card automatically resolving path references in action context to actual values (v0.8 version).

v0.8 uses array format for path binding: action.context = [{ key, value: { path } }].

Basic

Basic example of implementing A2UI v0.8 protocol with XCard. Demonstrates how to use XAgentCommand_v0_8 commands to create an interactive card for a coffee booking scenario.

Progressive

Progressive loading example of implementing A2UI v0.8 protocol with XCard. Demonstrates how to load product data in batches and progressively update components using surfaceUpdate commands to achieve smooth loading animations.

Streaming

Streaming content and real-time updates example implementing A2UI v0.8 protocol with XCard. Demonstrates streaming display of AI recommendation results, progressive component loading animations, and loading progress indicators.

Nested Interaction

Complex interaction and nested components example implementing A2UI v0.8 protocol with XCard. Demonstrates expandable detail cards, tree file browser, and accordion folding panels.

Multi Card Sync

Multi-card coordination and state synchronization example implementing A2UI v0.8 protocol with XCard. Demonstrates data sharing between multiple Surfaces, cross-card communication, and real-time price calculation in a shopping cart scenario.

Filter Search

Dynamic data filtering and search example implementing A2UI v0.8 protocol with XCard. Demonstrates how to use antd components for real-time search, multi-condition filtering, and dynamic result updates.

Form Validation

Form validation and error handling example implementing A2UI v0.8 protocol with XCard. Demonstrates how to use antd Form components for real-time validation, error state management, and multi-step form workflows.

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

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

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

Action Context Resolve

Demonstrates X-Card automatically resolving path references in action context to actual values (v0.8 version).

v0.8 uses array format for path binding: action.context = [{ key, value: { path } }].