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

# 券卡

`CouponCard` 展示优惠券金额、门槛、来源及使用操作，通过 `items` 数量自动选择布局。

## 示例

```tsx
import { CouponCard, type CouponCardItem } from '@doubao-dev/template';

const items: CouponCardItem[] = [
  {
    key: 'ride-coupon',
    value: 20,
    unit: '元',
    condition: '满20.01可用',
    sourceName: '出行服务',
    title: '快车立减券',
    validityText: '有效期至 2026.12.31 23:59',
    actionText: '立即用',
    onActionClick: () => console.log('use ride coupon')
  }
];

export default function RideCouponCard() {
  return <CouponCard items={items} />;
}
```

双券和多券使用同一套字段，例如折扣券使用 `value: 8.5, unit: '折'`。优惠券使用成功后，由业务更新对应项的 `disabled: true` 和 `actionText: '已使用'`。

## Props

| Prop      | 类型                            | 说明               |
| --------- | ----------------------------- | ---------------- |
| `items`   | `CouponCardItem[]`            | 券列表，默认空数组；为空时不展示 |
| `onClick` | `(event: TouchEvent) => void` | 卡片根节点点击回调        |

`CouponCardItem`：

| 字段              | 类型                             | 说明                                     |
| --------------- | ------------------------------ | -------------------------------------- |
| `key`           | `string \| number`             | 稳定标识，默认使用数组下标                          |
| `value`         | `string \| number`             | 必填，券面金额或折扣值                            |
| `unit`          | `string`                       | 默认 `元`，可传 `折` 或空字符串                    |
| `condition`     | `string`                       | 使用门槛                                   |
| `sourceName`    | `string`                       | 券来源名称                                  |
| `title`         | `string`                       | 券标题，仅单券展示                              |
| `validityText`  | `string`                       | 有效期说明，仅单券展示                            |
| `actionText`    | `string`                       | 默认 `立即用`，空字符串隐藏按钮                      |
| `disabled`      | `boolean`                      | 默认 `false`；不可用时整体透明度 50%，券与按钮均不响应点击    |
| `loading`       | `boolean`                      | 默认 `false`；复用 Button 加载态，按钮宽度不变并禁止重复点击 |
| `onClick`       | `(event: TouchEvent) => void`  | 券内容点击回调                                |
| `onActionClick` | `(event?: TouchEvent) => void` | 操作按钮点击回调                               |

## 布局与事件

- 单券：高 80px，宽度填满父容器，最大 400px；左侧金额与门槛，中间来源、标题及有效期，右侧操作按钮。
- 双券：高 80px，两张等宽，间距 8px，每张最大 200px；展示金额、门槛、来源和操作按钮。
- 三张及以上：高 112px，间距 4px，每张宽 96–150px；空间不足时保持单行并横向滚动。
- 所有文案最多一行，超出省略；数字使用 SF Pro，中文使用系统字体。
- 操作按钮不触发券或根节点的 `onClick`；券配置独立 `onClick` 后也不向根节点冒泡。未配置券回调时，券内容点击可触发根节点回调。
- `loading` 由业务控制，只影响操作按钮，复用 Button 的转圈加载态并保留文案占位；不将整张券置为不可用态。
- 不提供 `children`、`style`、`className` 或自定义操作节点；不附加标题栏、底部操作区。
