共享组件规范
本页汇总卡片模板共用的内容与交互规范,并在文末说明公开 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;不提供弹窗、勾选或自动授权行为。
标题行
| 配置项 | 可选值 | 默认值 |
|---|---|---|
| 是否展示 |
| show |
| 箭头 |
| none |
| 行数 |
| 1 |
- 有箭头时,超长文本使用渐变蒙版隐藏,文字在箭头前渐隐,不显示省略号。
- 无箭头时,超长文本在末尾显示省略号。
模板标题栏右侧入口通过 header.actionText、header.showAction 和 header.onActionClick 配置。标准标题栏需要展示“价格已过期”等静态警告状态时传 header.statusText,右侧会显示 24px 的 warning 标签且不触发操作点击;同时传入 actionText 时,优先显示 statusText。CheckoutCard 商品或行程条目是否展示箭头通过 productItems[].showChevron 配置。
双字段
| 属性 | 规则 |
|---|---|
| 颜色 | 默认使用灰色辅助文本 |
| 分隔符 | 圆点(·) |
| 容器高度 | 20 |
| 第二字段 | 可选;不配置时不展示 |
当空间不足时,先隐藏“第二字段 + 圆点”;第一字段仍然超长时,再在末尾显示省略号。
标签
标签用于表达活动、官方、限时和分类等结论性信息,不用于展示价格、时间、规格等事实性信息。
| 属性 | 规则 |
|---|---|
| 截断 | 不截断标签内容;超出容器最大宽度时隐藏整个标签 |
| 多标签 | 横向排列,间距 4 |
| 容器高度 | 26 |
| 数量上限 | 建议不超过 4 个 |
| 语义 | 颜色 | 用途 |
|---|---|---|
marketing | 橙色 | 限时、特价、活动等营销信息 |
neutral | 灰色 | 常规及信任感信息 |
行动按钮区
卡片支持主按钮、次按钮、双按钮、播放、开关和文字按钮。双按钮采用“左次右主”,每张卡片最多使用一个主按钮。
| 属性 | 按钮规则 |
|---|---|
| 尺寸 |
|
| 响应规则 |
|
| 边距 | 内边距固定,不随内容压缩 |
| 字数 | 建议 6 个汉字以内 |
| 超长兜底 | 优先缩小字号,最小字号为 11;仍超出时显示省略号 |
| 交互状态 | 常态、按压态、悬浮态、加载态、不可点击态 |
- 操作结果立即生效且可随时撤销时使用开关;需要跳转或二次确认时使用按钮。
- 悬浮态只在支持指针输入的设备上生效,移动端无需实现。
- 加载态下应锁定开关或按钮,避免重复操作导致状态不同步。
- 卡片底部主、次按钮分别使用
footer.primaryActionButton和footer.secondaryActionButton;ContentCard列表项还支持按钮、开关和播放控件。
图片
| 属性 | 规则 |
|---|---|
| 比例 |
|
| 基准宽度 |
|
| 响应规则 | 气泡宽度小于 350 时,图片等比缩放到 60 |
Primitives
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% 的扫光占位。