For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/frontend-development/widget.md.

卡片(Widget)开发

Widget 是展示在豆包对话中的轻量视图,适合承载 MCP Tool 返回的结构化结果、确认操作和下一步入口。一个完整的出卡链路包括 Widget 注册、业务实体协议、MCP Tool 与 Widget 绑定,以及 Widget 对 View Data 的渲染。

开发流程

按下面的顺序开发和检查:

  1. 在 src/app.config.ts 注册 Widget 入口和稳定的 widget_id;
  2. 根据展示场景选择模板,在 Widget 代码中把 View Data 映射为模板 Props;
  3. 在 manifest.yaml 声明 MCP Tool 输出的实体类型,并通过 tool_card_binding 绑定 widget_id;
  4. 让 MCP Tool 按协议返回 structuredContent.entities;
  5. 在 Web 模拟器中预览 Widget,再检查 MCP Tool、实体和出卡协议组成的完整链路;

选择和安装模板

当前文档版本的 @doubao-dev/template 提供以下模板。实际开发时,以项目已安装版本导出的组件和 TypeScript 类型为准:

模板适合的场景
ContentCard商品、服务、内容入口等通用列表
PriceActionCard报价、权益、服务方案等带价格和操作的列表
CheckoutCard商品或服务的下单、支付确认
TransitCard航班、列车、大巴等交通方案列表
MapCard路线预估、叫车状态、位置详情
CompositeCard在一个业务语义中组合多个模板已知模块
AskHumanCard让用户在多个候选项中确认选择

模板选型、通用约定和各模板完整示例见卡片模板。

项目尚未安装模板包时执行:

pnpm add @doubao-dev/template

模板以 npm 包和 TypeScript 类型提供,不需要下载源码。模板的可用 Props 以已安装包的类型声明为准,实际渲染和交互在 Web 模拟器中预览。

注册 Widget

在 src/app.config.ts 中声明 Widget。id 是 Manifest 和调试工具引用的 widget_id,必须在应用内全局唯一, 发布后不应随意修改。重复 ID 会导致构建失败,需要为对应入口配置不同的 id。

import { defineAppConfig } from '@doubao-dev/framework/config';

export default defineAppConfig({
  appId: 'your-app-id',
  name: '订单服务',
  widgets: [
    {
      entry: 'widgets/order-card/index',
      id: 'order-card',
      name: '订单结果卡片',
      border: true
    }
  ]
});

entry 对应 src/widgets/order-card/index.tsx。如果使用字符串简写,框架会根据入口推导 id;需要与 Manifest 长期绑定时,建议显式声明 id。

把 View Data 映射到模板

Manifest 不负责把业务字段逐一映射到模板 Props。字段选择、格式化、空态和点击行为都应在 Widget 的 TypeScript 代码中完成。

import { useViewData } from '@doubao-dev/framework';
import { navigateTo } from '@doubao-dev/framework/api';
import { ContentCard } from '@doubao-dev/template';

interface OrderEntity {
  entity_id?: string;
  title?: string;
  summary?: string;
  image_url?: string;
}

export default function OrderCard() {
  const order = useViewData<OrderEntity>() ?? {};

  if (!order.entity_id || !order.title) {
    return <ContentCard items={[{ key: 'empty', title: '暂无可展示的订单信息' }]} />;
  }

  return (
    <ContentCard
      items={[
        {
          key: order.entity_id,
          title: order.title,
          subtitle: order.summary,
          onClick: () =>
            navigateTo({
              url: `/pages/order-detail/index?orderId=${encodeURIComponent(order.entity_id)}`
            }),
          thumbnailSrc: order.image_url
        }
      ]}
    />
  );
}

映射时重点处理:

  • 为模板列表项提供稳定的 key;
  • 对可选字段提供空态或省略策略;
  • 在进入模板前完成金额、日期和状态等业务格式化;
  • 需要响应宿主数据更新时使用 useViewData<T>();
  • Widget 根节点直接返回模板,避免增加没有必要的布局容器;

上面的 onClick 展示了一条完整的前端联动路径:Widget 从 View Data 读取稳定业务 ID,用户点击模板项后通过 navigateTo 打开 Page,并只在 URL 中传递定位业务对象所需的参数。

配置出卡协议

下面的 Manifest 片段表示:query_order MCP Tool 返回 order 实体时,使用 order-card Widget 渲染。

tools:
  query_order:
    login_type: no_login
    output:
      kind: entities
      entity_types: [order]

entities:
  order:
    schema:
      entity_id:
        type: string
        is_entity_id: true
      entity_type:
        type: string
        llm_visible: false
      title:
        type: string
      summary:
        type: string
      image_url:
        type: string
        llm_visible: false
    tool_card_binding:
      query_order: order-card

MCP Tool 成功结果使用 MCP ToolResult 结构:

{
  "content": [{ "type": "text", "text": "已找到订单。" }],
  "structuredContent": {
    "entities": [
      {
        "entity_id": "order_001",
        "entity_type": "order",
        "title": "咖啡订单",
        "summary": "拿铁咖啡 · 中杯 · 热饮"
      }
    ]
  },
  "isError": false
}

能够出卡需要同时满足:

  • MCP Tool 在 Manifest 中声明 output.kind: entities,并包含返回的实体类型;
  • ToolResult 的业务数据位于 structuredContent.entities;
  • 每个实体都包含匹配的 entity_type 和被 is_entity_id: true 标记的稳定业务 ID;
  • tool_card_binding 的 key 是实际 MCP Tool 名,value 是 app.config.ts 中注册的 widget_id;
  • Widget 代码能够处理实体实际返回的字段和空值;

tool_card_binding 只决定“使用哪个 Widget”,不声明模板名称,也不承担字段到 UI 的映射。

预览与验证

Widget 需要分别验证视图和出卡链路:

验证范围重点检查
Widget 视图View Data 映射、空态、样式和点击行为
完整出卡链路ToolResult、实体类型、Manifest、tool_card_binding 和最终卡片数据

出现“MCP Tool 已执行但没有卡片”时,先检查 ToolResult 和 Manifest;卡片已出现但内容或样式错误时,再检查 Widget 的字段映射和 Lynx 样式。调试工具显示请求已发送,不代表卡片已经完成渲染,最终以 Web 模拟器中的实际结果为准。

开发服务启动、Widget 选择、测试数据注入和链路日志查看方式见开发工具文档。

完成检查

  • app.config.ts 中的 Widget id、Manifest 中的 tool_card_binding 和调试目标使用同一个值;
  • ToolResult 的 structuredContent.entities 与 Manifest schema 一致;
  • Widget 能处理必填字段缺失、可选字段为空和宿主数据更新;
  • 模板项点击后能够打开目标 Page,路由参数可以被目标 Page 读取;
  • 已在 Web 模拟器中验证实际渲染,并完成 MCP Tool 到 Widget 的完整出卡链路验证;