卡片模板
卡片模板把 MCP Tool 返回的结构化结果,渲染成豆包对话流中符合设计规范的卡片。@doubao-dev/template 已经把标题栏、内容区和操作区组合成完整结构;在 Widget 中选择合适的模板并传入业务数据即可,无需从头编写卡片布局。
设计稿:豆包应用插件组件库
快速开始
安装模板库:
在 Widget 入口组件中直接返回模板组件:
模板选型速查表
请先根据业务场景选择模板,再进入对应页面查看配置说明和完整示例。
| 场景 | 具体场景 | 推荐模板 |
|---|---|---|
| 通用场景 | 商品、服务、内容入口等通用信息列表 | 信息卡 - 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 为准。