2.10.0
中文
Ant Design X Vue

English

简体中文

English

简体中文

Theme

A2UI v0.9 ​

中文：A2UI v0.9

v0.9 is the recommended protocol: every command carries version: 'v0.9' and uses explicit createSurface / updateComponents / updateDataModel / deleteSurface. See the Introduction for the protocol overview.

The eight demos below use v0.9 commands and mirror the interaction scenarios, data, and state transitions of React @ant-design/x-card 2.10. They keep the Vue XCard API (:on-action, useXCardField, registerCatalog) instead of copying React's Bubble + XMarkdown marketing shell.

Examples ​

Basic usage ​

选择日期和咖啡后确认订单
Basic usage

Coffee booking: register a local catalog, choose a date and coffee, then confirm. Success deletes the booking Surface and creates a result card with the coffee, date, and price.

Progressive ​

每批 2 个商品，通过 updateComponents 渐进追加
Progressive

After the welcome text streams in, eight products load in four batches. A loading-indicator Surface tracks progress while repeated updateComponents calls expand the product Surface.

Streaming ​

文本流式输出后，推荐卡片按进度逐步出现
Streaming

AI food recommendations: intro text streams first, then progress and four restaurants are written into the dataModel. Completion turns streaming off and shows the final summary.

Nested interaction ​

展开目录、选择文件，详情与手风琴面板共享 dataModel
Welcome to Project File Browser! Browse the project structure below. Click on files to view details, expand folders to explore nested contents.
Nested interaction

File tree, file detail, and accordion panels share one Surface. Selecting a file writes /browser/selectedFile; details and the selected state update together, and panel content is read from /browser/panels.

Multi-card sync ​

商品、购物车、订单摘要共享同一份 /cart 数据
Welcome to Smart Shopping Cart! 🛒 Browse products, add them to your cart, and see real-time price calculations. Experience the power of multi-surface collaboration!
Multi-card sync

A three-column product list, cart, and order summary share /cart. Add, quantity changes, removal, discounts, shipping, and checkout are all supported; checkout swaps in a success card.

搜索、分类、价格区间和评分共同写入 /filter/filters
Welcome to Product Search! 🔍 Find the perfect product by filtering by category, price, and rating. Results will update in real-time as you adjust filters.
Filter search

Ten products support keyword, multi-category, price-range, and minimum-rating filters. Filters are written to /filters; the result list refreshes from the same data after 300ms.

Form validation ​

逐步校验信息，最后生成注册结果卡片
Form validation

Multi-step registration: basic info → security → result. Fields use useXCardField and write through the injected onDataChange; final submission replaces the Surface with a success card.

Action context resolve ​

填写表单后点击提交，观察 onAction 回调中 context 的变化
onAction 回调日志（path 引用已解析）：

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

Action context resolve

Typing writes into the dataModel. A submit button may send an empty context; Card resolves { path } entries in action.event.context. The log keeps the latest four callbacks so the resolved values are visible.

API ​

Bind :on-action in templates — it is a prop, not an emit.

XCard.Box ​

Box is the container that owns Card instances and dispatches commands. Place XCard.Card in the default slot.

PropDescriptionTypeDefault
commandsA2UI command objects(A2UICommand_v0_9 | XAgentCommand_v0_8)[][]
componentsImplementation map; names must start with an uppercase letterRecord<string, Component>-
onActionFired when a card triggers an action(payload: ActionPayload) => void-

XCard.Card ​

Renders a single Surface.

PropDescriptionTypeDefault
idSurface ID, matching surfaceId in commandsstring-

Custom components receive:

  • onAction(name, context): Card then runs versioned extractDataUpdates and resolves path refs in the action context
  • onDataChange(path, value): writes the current surface dataModel directly

ActionPayload ​

PropertyDescriptionTypeDefault
nameEvent namestring-
surfaceIdThe surfaceId that triggered the actionstring-
contextContext from the component, with path references resolvedRecord<string, any>-

Action context path resolution ​

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

Path reference format ​

Use { path: string } to bind dataModel values in the action config:

json
{
  "id": "submit-btn",
  "component": "Button",
  "action": {
    "event": {
      "name": "agent:send_context_text",
      "context": {
        "username": { "path": "/form/username", "label": "Username" },
        "email": { "path": "/form/email", "label": "Email" }
      }
    }
  }
}

Resolution result ​

json
{
  "username": { "value": "John", "label": "Username" },
  "email": { "value": "john@example.com", "label": "Email" }
}

Note:

  • Only values that are themselves { path: "xxx" } are converted
  • Actual values passed by the component (for example { value: "actual_value" }) are not rewritten
  • Other properties (such as label) are kept; only path is replaced with value

A2UICommand_v0_9 ​

XAgentCommand_v0_9 is an alias of A2UICommand_v0_9.

CreateSurfaceCommand ​

Create a new Surface.

PropertyDescriptionTypeDefault
versionVersion number'v0.9'-
createSurface.surfaceIdSurface IDstring-
createSurface.catalogIdComponent catalog URL or local identifierstring-

UpdateComponentsCommand ​

Update components on a Surface.

PropertyDescriptionTypeDefault
versionVersion number'v0.9'-
updateComponents.surfaceIdSurface IDstring-
updateComponents.componentsComponent listBaseComponent_v0_9[]-

BaseComponent_v0_9 ​

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

UpdateDataModelCommand ​

Update the data model.

PropertyDescriptionTypeDefault
versionVersion number'v0.9'-
updateDataModel.surfaceIdSurface IDstring-
updateDataModel.pathData pathstring-
updateDataModel.valueData valueany-

DeleteSurfaceCommand ​

Delete a Surface.

PropertyDescriptionTypeDefault
versionVersion number'v0.9'-
deleteSurface.surfaceIdSurface IDstring-

PathValue ​

ts
interface PathValue {
  path: string
}

Catalog ​

ts
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 ​

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

Catalog helpers ​

ts
registerCatalog(catalog: Catalog): void
loadCatalog(catalogId: string): Promise<Catalog>
validateComponent(catalog: Catalog, componentName: string, componentProps: Record<string, any>): boolean
clearCatalogCache(): void

useXCardField ​

A Vue-only composable for field write-back and validation (used by the form-validation demo).

ts
const field = useXCardField({
  path: '/form/email',
  onDataChange, // injected by Card
  rules: [{ required: true }, { pattern: /.+@.+/, message: 'Invalid email' }],
})
field.setValue(next)
field.validate()
field.error.value

validateFieldValue(value, rules) is also exported.