> 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.

# 卡片模板

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

设计稿：[豆包应用插件组件库](https://www.figma.com/design/78vXDeg7KRVVkTQNs9RWEj/%E8%B1%86%E5%8C%85%E5%B0%8F%E7%A8%8B%E5%BA%93?node-id=1-19810\&p=f\&t=BbJadKjltOjv3jfo-0)

## 快速开始

安装模板库：

```bash
pnpm add @doubao-dev/template
```

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

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

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

## 模板选型速查表

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


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


标题、信息字段、标签、按钮和图片的内容约束，以及 Primitives 的使用方式，见[共享组件规范](/apps-plugin/docs/templates/shared-components.md)。

## 使用约定

- **一个 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 为准。
