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/shared-components.md.

共享组件规范

本页汇总卡片模板共用的内容与交互规范,并在文末说明公开 Primitives 的用法。设计约束不等于新增 Props;开发时以各模板页面和当前安装版本导出的 TypeScript 类型为准。

卡片内分割线

标准卡片内用于区分标题、内容、明细和列表项的分割线统一为 1px,颜色使用 neutral/transparent-1(var(--neutral-transparent-1))。

勾选框和协议

从 @doubao-dev/template/primitives 导入 Checkbox 和 Agreement。 这些单元不接受 style、className 或 children。

Checkbox

20px 勾选框,支持未选中、选中、禁用。通过 checked: boolean 和 onChange?: (checked: boolean, event: TouchEvent) => void 受控更新,disabled 默认为 false。 点击不会冒泡到外层卡片,禁用时不触发回调;组件不自动决定单选或多选规则。 PriceActionCardItem.checkbox 接受相同配置,配置后替换该项右侧操作按钮。

Agreement

非阻断式协议声明,通常放在按钮下方;text 默认是“点击下单代表同意”, links 是 { key?, text, onClick? }[],协议名称之间自动插入顿号。 说明文字使用辅助文本颜色,协议名称使用主文本颜色,13px 字号、20px 行高,最多两行,超出省略。 空协议列表不渲染。每条协议单独触发 onClick,业务负责跳转,不触发外层卡片点击。 使用共享 footer 的卡片可传 footer.agreement;不提供弹窗、勾选或自动授权行为。

<Agreement
  links={[
    { text: '电子运单契约条款', onClick: openContract },
    { text: '隐私政策', onClick: openPrivacy }
  ]}
/>

标题行

配置项可选值默认值
是否展示

show / hidden

show
箭头

arrow / none

none
行数

1 / 2;地图场景仅支持 1

1
  • 有箭头时,超长文本使用渐变蒙版隐藏,文字在箭头前渐隐,不显示省略号。
  • 无箭头时,超长文本在末尾显示省略号。

模板标题栏右侧入口通过 header.actionText、header.showAction 和 header.onActionClick 配置。标准标题栏需要展示“价格已过期”等静态警告状态时传 header.statusText,右侧会显示 24px 的 warning 标签且不触发操作点击;同时传入 actionText 时,优先显示 statusText。CheckoutCard 商品或行程条目是否展示箭头通过 productItems[].showChevron 配置。

双字段

属性规则
颜色默认使用灰色辅助文本
分隔符圆点(·)
容器高度20
第二字段可选;不配置时不展示

当空间不足时,先隐藏“第二字段 + 圆点”;第一字段仍然超长时,再在末尾显示省略号。

标签

标签用于表达活动、官方、限时和分类等结论性信息,不用于展示价格、时间、规格等事实性信息。

属性规则
截断不截断标签内容;超出容器最大宽度时隐藏整个标签
多标签横向排列,间距 4
容器高度26
数量上限建议不超过 4 个
语义颜色用途
marketing橙色限时、特价、活动等营销信息
neutral灰色常规及信任感信息

行动按钮区

卡片支持主按钮、次按钮、双按钮、播放、开关和文字按钮。双按钮采用“左次右主”,每张卡片最多使用一个主按钮。

属性按钮规则
尺寸

lg 用于底部按钮并填满可用宽度;md 用于卡内按钮,宽度 80~100

响应规则

lg 填满可用宽度;气泡宽度小于 350 时,md 自适应且最大宽度为 80

边距内边距固定,不随内容压缩
字数建议 6 个汉字以内
超长兜底优先缩小字号,最小字号为 11;仍超出时显示省略号
交互状态常态、按压态、悬浮态、加载态、不可点击态
  • 操作结果立即生效且可随时撤销时使用开关;需要跳转或二次确认时使用按钮。
  • 悬浮态只在支持指针输入的设备上生效,移动端无需实现。
  • 加载态下应锁定开关或按钮,避免重复操作导致状态不同步。
  • 卡片底部主、次按钮分别使用 footer.primaryActionButton 和 footer.secondaryActionButton;ContentCard 列表项还支持按钮、开关和播放控件。

图片

属性规则
比例

1:1(默认)或 4:3

基准宽度

1:1 模式下为 80

响应规则气泡宽度小于 350 时,图片等比缩放到 60

Primitives

Primitives 是不含完整卡片外壳的业务展示组件,通过子入口导入:

import { Title, Tag, Icon, OptionGroup, Price, Stepper } from '@doubao-dev/template/primitives';

这些组件不支持 className 和 style,外观由模板统一管理。Primitives 不声明或暴露组件级 CSS 变量,可以直接使用已有全局主题 token。

Title

  • text 接受字符串、数字或片段数组。片段使用 { text, tone?: 'default' | 'highlight' };默认黑色,highlight 为豆包蓝,可高亮标题中的指定部分。整段高亮可传单个高亮片段,不需要顶层 tone。
  • maxLines 支持 1 | 2,默认 1。超出行数时在最后一行末尾渐隐,不展示省略号。
  • showArrow 默认 true,传 false 隐藏箭头;组件宽度由业务容器决定。
  • 箭头紧跟实际文字末尾,两行时跟随第二行末字;超长时保留箭头并渐隐其前方文字。
  • loading 显示最大宽度为 40% 的扫光占位。

Tag

  • text 接受字符串或数字;tone 支持橙色 marketing 与灰色 neutral,默认 neutral。authority 已废弃,仅保留兼容,显示效果与 neutral 相同。
  • 标签固定高度 20px;横向排列时标签间距 4px、容器高度 26px。
  • 标签内容不收缩或截断,业务容器负责测量或通过换行裁切隐藏放不下的整枚标签,不能只裁切文字。

Icon

  • name 当前仅支持 add,默认尺寸为 14px × 14px。
  • 图标尺寸和布局由模板统一管理;add 使用 neutral-50 并自动适配主题。
  • Icon 只负责展示;需要可点击的添加控件时,使用 ContentCardItem.action: { type: 'add', onClick }。

OptionGroup

  • items 是唯一内容入口,不支持 children;每项使用唯一的 value,并可配置 title、disabled 和独立 onClick。
  • size="md"(默认)高 44px,由内容撑开并自动换行,支持 icon;size="lg" 高 62px,按栏等分并自动换行,支持 subtitle。
  • columns 仅用于 lg,默认每行 3 栏,间距固定为 8px;单行选项平均填满可用宽度,换行后各行保持相同栏宽和列位置。
  • selectionMode="single"(默认)时,value 与 onChange 使用单个字符串或数字;multiple 时使用值数组,maxSelected={2} 可限制双选。业务需要根据 onChange 更新受控 value。
  • 选择变化时先触发 onChange,再触发该 item 的 onClick。达到多选上限后点击未选项不触发 onChange,但仍触发 onClick;已选项仍可取消。禁用项不触发事件。

多选接入示例见 CompositeCard。

Stepper

  • Stepper 是受控的数量调节组件;value 为当前数量,点击加减按钮后通过 onChange(nextValue, event) 返回下一数量,业务需更新 value。
  • min 默认 0,max 可选;到达边界时对应按钮变为不可点击。每次增减 1,不会越过边界。
  • 整体宽 86px、高 24px;加减按钮各 24px,数值区域宽 38px。可直接使用,也可通过 ContentCardItem.action: { type: 'stepper', value, min, max, onChange } 使用。
  • 数值区域左右各留 4px;数值超出可用宽度时单行省略,不会撑宽组件。
  • 将同一列表项的 action.type 从 add 切换为 stepper 时,控件保持右侧加号位置并向左展开。显示类型由业务显式控制,value 为 0 时也不会自动切换成 Add。

Price

  • value 接受字符串或数字;需要保留前导零或末尾小数位时传字符串。
  • currency 默认 ¥,空字符串可隐藏币种;prefix / suffix 设置前后缀,description 设置辅助说明,originalPrice 设置带删除线的原价。
  • tone="highlight" 使用豆包蓝,默认色跟随主题。
  • prefixTone 支持 default | highlight | muted,分别对应主文字色、豆包蓝和 --neutral-70 次级灰色;不传时前缀与价格值颜色一致。
  • loading 显示最大宽度为 60% 的扫光占位。