# Template 模板 Props 参考

所有模板从 `@doubao-dev/template` 导入。本文件记录当前版本支持的模板 Props 与行为约束。

约定：

- `TemplateText = string | number`，`TemplateKey = string | number`。
- `TemplateCardHeaderProps`：`actionText?: string` · `showAction?: boolean` · `onActionClick?: (event) => void`。
- `TemplateCardFooterProps`：`primaryActionButton?: TemplateCardFooterActionButton` · `secondaryActionButton?: TemplateCardFooterActionButton` · `className?` · `style?`。
- `TemplateCardFooterActionButton`：`text?` · `disabled?` · `loading?` · `throttle?` · `onClick?`。
- `header`、`footer` 和内容区相互独立。footer 不会影响 `items` 展示数量。
- 只使用各模板和列表项明确声明的公开字段。
- 部分模板和列表项为兼容旧项目保留了已废弃的 `children`。旧代码仍可运行，但生成或修改代码时不要继续使用，应改用当前模板的结构化字段或具名 `ReactNode` 字段；没有匹配字段时不要自行拼装结构。
- `className` / `style` / `onClick` 作用在卡片根节点。
- 图片资源传运行时可访问 URL；本地图片放到业务项目 `src/assets` 后静态 `import` 再传入。

---

## Title — 标题展示组件

`import { Title, type TitleMaxLines, type TitleProps, type TitleValue } from '@doubao-dev/template/primitives'`

`Title` 用于卡片内容中的一行或两行标题排版，不是独立卡片模板。

| Prop | 类型 | 说明 |
|------|------|------|
| `text` | `string \| number` | 标题内容 |
| `maxLines` | `1 \| 2` | 最大行数，默认 `1`；超出后省略 |
| `showArrow` | `boolean` | 是否展示右侧箭头，默认 `true` |
| `loading` | `boolean` | 展示扫光占位 |
| `className` / `style` | `string` / `CSSProperties` | 根节点自定义样式 |

---

## Tag — 标签展示组件

`import { Tag, type TagProps, type TagTone, type TagValue } from '@doubao-dev/template/primitives'`

`Tag` 用于卡片内容中的营销、权威或常规辅助标签，不是独立卡片模板。

| Prop | 类型 | 说明 |
|------|------|------|
| `text` | `string \| number` | 标签内容，不截断 |
| `tone` | `'marketing' \| 'authority' \| 'neutral'` | 标签色调，默认 `authority` |
| `className` / `style` | `string` / `CSSProperties` | 根节点自定义样式 |

多个标签由业务容器横向排列，标签间距为 4px，容器高度为 26px；标签内容不会收缩或截断，空间不足时由业务容器隐藏放不下的整枚标签。

---

## Price — 价格展示组件

`import { Price, type PricePrefixTone, type PriceProps, type PriceTone, type PriceValue } from '@doubao-dev/template/primitives'`

`Price` 用于卡片内容中的价格排版，不是独立卡片模板。

| Prop | 类型 | 说明 |
|------|------|------|
| `value` | `string \| number` | 价格值；字符串保留前导零和末尾小数位 |
| `currency` | `string` | 币种符号，默认 `¥`；空字符串隐藏 |
| `prefix` / `suffix` | `string` | 价格前缀 / 后缀 |
| `prefixTone` | `'default' \| 'highlight' \| 'muted'` | 前缀主文字色 / 营销红 / `--neutral-70`；不传时跟随价格色调 |
| `description` | `string` | 价格后的辅助信息 |
| `originalPrice` | `string \| number` | 原价，以删除线展示 |
| `tone` | `'default' \| 'highlight'` | 默认色或营销强调色 |
| `loading` | `boolean` | 展示扫光占位 |
| `className` / `style` | `string` / `CSSProperties` | 根节点自定义样式 |

---

## ContentCard — 列表卡

`import { ContentCard, type ContentCardItem, type ContentCardProps, type TemplateExtraAction, type TemplateCardHeaderProps, type TemplateCardFooterProps } from '@doubao-dev/template'`

| Prop | 类型 | 说明 |
|------|------|------|
| `header` | `TemplateCardHeaderProps` | 标题栏配置 |
| `items` | `ContentCardItem[]` | 列表数据，全量展示 |
| `footer` | `TemplateCardFooterProps` | 底部操作区配置 |
| `children` | `ReactNode` | 已废弃，仅兼容旧代码；接管列表内容区域 |

`ContentCardItem`：`key?` · `title?: ReactNode`（字符串/数字最多一行；两行标题传 `<Title maxLines={2} />`）· `subtitle?: ReactNode`（字符串/数字最多一行）· `description?: ReactNode`（字符串/数字最多一行）· `thumbnailSrc?: string` · `thumbnail?: ReactNode`（优先于 `thumbnailSrc`）· `action?: TemplateExtraAction | ReactNode` · `children?: ReactNode`（已废弃，仅兼容旧代码；接管当前列表项）· `onClick?` · `className?` · `style?`

`TemplateExtraAction`：

- `{ type: 'button', text, disabled?, loading?, onClick? }`
- `{ type: 'switch', checked, disabled?, onChange? }`（受控）
- `{ type: 'playback', playing, progress?, disabled?, onToggle? }`（受控；`progress` 范围 `0~1`）

---

## PriceActionCard — 价格操作卡

`import { PriceActionCard, type PriceActionCardItem, type PriceActionCardInfoRow, type PriceActionCardProps } from '@doubao-dev/template'`

| Prop | 类型 | 说明 |
|------|------|------|
| `header` | `TemplateCardHeaderProps` | 标题栏配置 |
| `items` | `PriceActionCardItem[]` | 价格列表 |
| `footer` | `TemplateCardFooterProps` | 底部操作区配置 |
| `children` | `ReactNode` | 已废弃，仅兼容旧代码；接管列表内容区域 |

`PriceActionCardItem`：`key?` · `price?: TemplateText` · `badgeText?: TemplateText` · `infoRows?: PriceActionCardInfoRow[]`（最多前 2 行）· `actionText?` · `children?: ReactNode`（已废弃，仅兼容旧代码；接管当前列表项）· `onClick?` · `onActionClick?` · `className?` · `style?`

`PriceActionCardInfoRow`：`key?` · `text: TemplateText`

---

## CheckoutCard — 提单卡（通用电商）

`import { CheckoutCard, type CheckoutCardProductItem, type CheckoutCardInfoItem, type CheckoutCardFeeItem, type CheckoutCardProps } from '@doubao-dev/template'`

| Prop | 类型 | 说明 |
|------|------|------|
| `header` | `TemplateCardHeaderProps` | 标题栏配置 |
| `productItems` | `CheckoutCardProductItem[]` | 商品摘要，支持单/多个 |
| `infoItems` | `CheckoutCardInfoItem[]` | 提单信息列表 |
| `feeItems` | `CheckoutCardFeeItem[]` | 费用明细，优惠信息也通过该属性传入 |
| `totalLabel` / `totalPrice` | `string` / `TemplateText` | 合计标签 / 合计价格 |
| `footer` | `TemplateCardFooterProps` | 底部操作区配置 |

`CheckoutCardProductItem` 继承商品摘要 props，并增加 `key?`。常用字段：`title?` · `tagText?: TemplateText`（展示在标题前）· `tagTone?: 'default' | 'highlight'`（默认 `default`）· `spec?` · `imageSrc?` · `image?: ReactNode` · `pricePrefix?` · `price?: TemplateText` · `quantity?: TemplateText` · `showChevron?` · `onClick?`

`CheckoutCardInfoItem`：`key?` · `label: string` · `value: TemplateText` · `valueExtra?: TemplateText`。两项使用相同样式，并与左侧 label 的首行对齐。

`CheckoutCardFeeItem`：`key?` · `label: string` · `value: TemplateText`

`feeItems` 作为单行整体与 `totalLabel` / `totalPrice` 共同布局；空间不足时合计整体换到第二行，两组各自超宽时单行省略，汇总区域最多两行。

---

## TicketOrderCard — 票务提单卡（已废弃）

> 请使用 `CheckoutCard`。`TicketOrderCard` 仅为兼容现有代码保留。

`import { TicketOrderCard, type TicketOrderCardRouteItem, type TicketOrderCardInfoItem, type TicketOrderCardFeeItem, type TicketOrderCardProps } from '@doubao-dev/template'`

| Prop | 类型 | 说明 |
|------|------|------|
| `header` | `TemplateCardHeaderProps` | 标题栏配置 |
| `routeItems` | `TicketOrderCardRouteItem[]` | 航程列表 |
| `infoItems` | `TicketOrderCardInfoItem[]` | 订单信息 |
| `feeItems` | `TicketOrderCardFeeItem[]` | 费用明细 |
| `totalLabel` / `totalPrice` | `TemplateText` | 合计标签 / 价格 |
| `totalContent` | `ReactNode` | 合计区自定义内容，优先于 label+price |
| `footer` | `TemplateCardFooterProps` | 底部操作区配置 |

`TicketOrderCardRouteItem`：`key?` · `title?: TemplateText` · `tagText?: TemplateText`（展示在标题前）· `tagTone?: 'default' | 'highlight'`（默认 `default`）· `description?: TemplateText` · `showChevron?` · `onClick?`

`TicketOrderCardInfoItem`：`key?` · `label?` / `labelContent?: ReactNode` · `value?` / `valueContent?: ReactNode` · `valueExtra?` / `valueExtraContent?: ReactNode`

`TicketOrderCardFeeItem`：`key?` · `label?: TemplateText` · `value?: TemplateText` · `content?: ReactNode`

---

## TransitCard — 交通票务列表卡

`import { TransitCard, type TransitCardItem, type TransitCardPrice, type TransitCardProps, type TransitCardTag } from '@doubao-dev/template'`

| Prop | 类型 | 说明 |
|------|------|------|
| `header` | `TemplateCardHeaderProps` | 标题栏配置 |
| `items` | `TransitCardItem[]` | 行程列表，全量展示 |
| `footer` | `TemplateCardFooterProps` | 底部操作区配置 |

`TransitCardItem`：`key?` · `title?: ReactNode` · `departureMain?` / `departureSub?: TemplateText` · `transfer?: ReactNode` / `transferTop?` / `transferBottom?: TemplateText` · `arrivalMain?` / `arrivalDayOffset?` / `arrivalSub?: TemplateText` · `price?: TransitCardPrice | ReactNode` · `tag?: TransitCardTag` · `onClick?` · `className?` · `style?`

`TransitCardPrice`：`value: string | number` · `currency?: string`（默认 `¥`）· `prefix?: string` · `prefixTone?: 'default' | 'highlight' | 'muted'`（不传时跟随价格色调）· `tone?: 'default' | 'highlight'`。生成新代码时只使用结构化价格配置。

`price` 传数字时作为 `Price.value` 并使用默认币种；传字符串时按首个币种符号拆为 `prefix + currency + value`，没有币种符号时整串作为 `value` 且 `currency=""`。标量价格使用 Price 的默认 `tone`。

`TransitCardTag`：`text: string | number` · `tone?: 'marketing' | 'neutral'`（默认 `marketing`）。标签展示在价格下方；不传 `tag` 时保持单价格布局。

---

## AskHumanCard — 人工确认选项卡

`import { AskHumanCard, type AskHumanCardItem, type AskHumanCardProps } from '@doubao-dev/template'`

| Prop | 类型 | 说明 |
|------|------|------|
| `items` | `AskHumanCardItem[]` | 选项列表 |
| `variant` | `'suggestion' \| 'jump'` | 选项行为语义；默认 `suggestion`，单个或两个固定跳转按钮用 `jump` |
| `className` / `style` | `string` / `CSSProperties` | 卡片根节点自定义样式 |
| `onClick` | `(event) => void` | 卡片根节点点击 |

`AskHumanCardItem`：`key?` · `text?: TemplateText` · `loading?` · `showArrow?: 'left' | 'right' | 'none'` · `onClick?` · `className?` · `style?`

跳过、固定跳转等入口也通过 `items` 表达；`showArrow` 支持 `'left'`、`'right'`、`'none'`，默认不展示。单个全宽操作按钮用
`variant="jump"` 和一个 `items` 项表达。