X Card

npm install @ant-design/x-card

import {
  XCard,
  registerCatalog,
  loadCatalog,
  validateComponent,
  clearCatalogCache,
} from '@ant-design/x-card';
import type {
  XAgentCommand_v0_9,
  XAgentCommand_v0_8,
  ActionPayload,
  Catalog,
  CatalogComponent,
} from '@ant-design/x-card';

// 子组件
XCard.Box; // 容器：接收命令，持有 Catalog 映射
XCard.Card; // 渲染器：按 id 渲染单个 Surface

XCard.Box
├── 持有：catalogMap、surfaceCatalogMap
├── 分发：commands → 所有 XCard.Card 子组件
├── 汇聚：所有 Card 的 onAction 事件
└── XCard.Card (id="surface-a")
│   ├── 持有：组件树、数据模型、commandVersion
│   └── 处理：数据绑定解析、Action 触发
└── XCard.Card (id="surface-b")
    └── ...

interface BoxProps {
  commands?: (XAgentCommand_v0_9 | XAgentCommand_v0_8)[];
  /** 组件名称必须以大写字母开头 */
  components?: Record<string, React.ComponentType<any>>;
  onAction?: (payload: ActionPayload) => void;
  children?: React.ReactNode; // 应包含 XCard.Card 元素
}

interface CardProps {
  id: string; // 要渲染的 surfaceId
}

interface ActionPayload {
  name: string; // 来自 action.event.name
  surfaceId: string; // 触发动作的 Surface
  /**
   * 组件传递的上下文，已自动解析 path 引用
   *
   * 对于 action.event.context 中使用 { path: "xxx" } 格式的字段：
   * - X-Card 会自动将其解析为 { value: "实际值" } 格式
   * - 其他属性（如 label）会被保留
   *
   * 示例输入配置：
   *   { username: { path: "/form/username", label: "用户名" } }
   *
   * 示例解析后 context：
   *   { username: { value: "张三", label: "用户名" } }
   */
  context: Record<string, any>;
}

import React, { useState } from 'react';
import { XCard, registerCatalog } from '@ant-design/x-card';
import type { XAgentCommand_v0_9, ActionPayload, Catalog } from '@ant-design/x-card';

// 1. 定义并注册本地 Catalog
const myCatalog: Catalog = {
  catalogId: 'local://my_catalog.json',
  components: {
    Text: {
      type: 'object',
      properties: { text: { type: 'string' }, variant: { type: 'string' } },
      required: ['text'],
    },
    Button: {
      type: 'object',
      properties: { text: { type: 'string' }, action: {} },
      required: ['text'],
    },
  },
};
registerCatalog(myCatalog);

// 2. 自定义组件实现
const Text: React.FC<{ text: string; variant?: string }> = ({ text, variant }) => (
  <p className={`text-${variant ?? 'body'}`}>{text}</p>
);

const Button: React.FC<{ text: string; onAction?: (ctx: any) => void; action?: any }> = ({
  text,
  onAction,
  action,
}) => <button onClick={() => onAction?.(action?.event?.context ?? {})}>{text}</button>;

// 3. 构建命令（来自 Agent 流）
const commands: XAgentCommand_v0_9[] = [
  {
    version: 'v0.9',
    createSurface: {
      surfaceId: 'welcome',
      catalogId: 'local://my_catalog.json',
    },
  },
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'welcome',
      components: [
        { id: 'root', component: 'Column', children: ['title', 'btn'] },
        { id: 'title', component: 'Text', text: { path: '/user/name' }, variant: 'h1' },
        {
          id: 'btn',
          component: 'Button',
          text: '开始',
          action: { event: { name: 'start', context: {} } },
        },
      ],
    },
  },
  {
    version: 'v0.9',
    updateDataModel: {
      surfaceId: 'welcome',
      path: '/user/name',
      value: 'Alice',
    },
  },
];

// 4. 渲染
export default function App() {
  const [cmdQueue, setCmdQueue] = useState<XAgentCommand_v0_9[]>(commands);

  const handleAction = (payload: ActionPayload) => {
    console.log('Action:', payload.name, payload.context);
    // 根据 Agent 响应追加新命令
    setCmdQueue((prev) => [...prev /* 新命令 */]);
  };

  return (
    <XCard.Box commands={cmdQueue} components={{ Text, Button }} onAction={handleAction}>
      <XCard.Card id="welcome" />
    </XCard.Box>
  );
}