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

# 共享组件规范

本页汇总卡片模板共用的内容与交互规范，并在文末说明公开 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`；不提供弹窗、勾选或自动授权行为。

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

## 标题行


| 配置项 | 可选值 | 默认值 |
| --- | --- | --- |
| 是否展示 | <code>show</code> / <code>hidden</code> | `show
` |
| 箭头 | <code>arrow</code> / <code>none</code> | `none
` |
| 行数 | <code>1</code> / <code>2</code>；地图场景仅支持 <code>1</code> | `1
` |


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

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

## 双字段


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


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

## 标签

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


| 属性 | 规则 |
| --- | --- |
| 截断 | 不截断标签内容；超出容器最大宽度时隐藏整个标签 |
| 多标签 | 横向排列，间距 4 |
| 容器高度 | 26 |
| 数量上限 | 建议不超过 4 个 |



| 语义 | 颜色 | 用途 |
| --- | --- | --- |
| `marketing
` | 橙色 | 限时、特价、活动等营销信息 |
| `neutral
` | 灰色 | 常规及信任感信息 |


## 行动按钮区

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


| 属性 | 按钮规则 |
| --- | --- |
| 尺寸 | <code>lg</code> 用于底部按钮并填满可用宽度；<code>md</code> 用于卡内按钮，宽度 80～100 |
| 响应规则 | <code>lg</code> 填满可用宽度；气泡宽度小于 350 时，<code>md</code> 自适应且最大宽度为 80 |
| 边距 | 内边距固定，不随内容压缩 |
| 字数 | 建议 6 个汉字以内 |
| 超长兜底 | 优先缩小字号，最小字号为 11；仍超出时显示省略号 |
| 交互状态 | 常态、按压态、悬浮态、加载态、不可点击态 |


- 操作结果立即生效且可随时撤销时使用开关；需要跳转或二次确认时使用按钮。
- 悬浮态只在支持指针输入的设备上生效，移动端无需实现。
- 加载态下应锁定开关或按钮，避免重复操作导致状态不同步。
- 卡片底部主、次按钮分别使用 `footer.primaryActionButton` 和 `footer.secondaryActionButton`；`ContentCard` 列表项还支持按钮、开关和播放控件。

## 图片


| 属性 | 规则 |
| --- | --- |
| 比例 | <code>1:1</code>（默认）或 <code>4:3</code> |
| 基准宽度 | <code>1:1</code> 模式下为 80 |
| 响应规则 | 气泡宽度小于 350 时，图片等比缩放到 60 |


## Primitives

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

```tsx
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](/apps-plugin/docs/templates/composite-card.md)。

### 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% 的扫光占位。
