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/templates/index.md.

卡片模板

卡片模板把 MCP Tool 返回的结构化结果,渲染成豆包对话流中符合设计规范的卡片。@doubao-dev/template 已经把标题栏、内容区和操作区组合成完整结构;在 Widget 中选择合适的模板并传入业务数据即可,无需从头编写卡片布局。

设计稿:豆包应用插件组件库

快速开始

安装模板库:

pnpm add @doubao-dev/template

在 Widget 入口组件中直接返回模板组件:

import { ContentCard } from '@doubao-dev/template';

export default function ServiceCard() {
  return (
    <ContentCard
      items={[
        {
          key: 'service-001',
          title: '上门保洁',
          subtitle: '最快今天 14:00 上门'
        }
      ]}
    />
  );
}

模板选型速查表

请先根据业务场景选择模板,再进入对应页面查看配置说明和完整示例。

场景具体场景推荐模板
通用场景商品、服务、内容入口等通用信息列表信息卡 - ContentCard
非交通类报价、权益或服务方案价格操作卡 - PriceActionCard
商品或服务订单确认确认订单卡 - CheckoutCard
优惠券展示与使用券卡 - CouponCard
交通票务相关航班、火车等班次与价格列表交通列表卡 - TransitCard
需要问询用户需要用户补充信息或选择下一步问询卡 - AskHumanCard
地图相关路线预估、叫车状态或位置详情地图卡 - MapCard
复合业务一个业务语义需要组合多个模板已知模块组合卡 - CompositeCard

标题、信息字段、标签、按钮和图片的内容约束,以及 Primitives 的使用方式,见共享组件规范。

使用约定

  • 一个 Widget 对应一张卡片:入口组件直接返回模板组件,不要再包裹 view 或 scroll-view。
  • 导入路径:模板组件和类型来自 @doubao-dev/template;需要 View Data、状态或生命周期 Hooks 时,从 @doubao-dev/framework 导入对应 API。
  • 传稳定的 key:列表项不要依赖数组下标,避免数据更新时复用错误的视图。
  • 图片必须可在运行时访问:本地图片放入业务项目的 src/assets,静态 import 后传入;不要传相对路径字符串。
  • 必须使用模板:先根据业务场景选择模板并使用其公开 Props;对话流 Widget 最外层必须直接返回模板组件,不得自行拼装卡片或外包 view / scroll-view。现有模板无法满足时,通过开发者平台提交反馈。
  • 分别配置标题栏和底部操作区:header 控制标题栏右侧入口,footer.primaryActionButton 和 footer.secondaryActionButton 控制底部按钮。单按钮占据整行;header、footer 与内容区独立,footer 不影响 items 展示数量。
  • 样式由模板统一管理:卡片、列表项和 Primitives 均不提供 className / style,也不暴露组件级 CSS 变量;onClick 作用在卡片根节点。

具体 Props 以项目已安装版本导出的 TypeScript 类型为准。

模板不支持 children。ReactNode / ReactElement 内容槽位不代表可以传任意 JSX:文本槽位仅允许字符串、数字或直接传入的 Tag / Title,媒体槽位仅允许直接传入的 <image /> / <svg />。Kit 构建期静态检查会对可识别的违规内容、样式入口和 Widget 根节点输出 [卡片检查] warning,不改变运行时渲染或阻断构建;未出现 warning 不代表所有动态内容都已通过检查。具体字段以各卡型的公开 Props 为准。