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

# 组合卡

`CompositeCard` 用于一个完整业务语义需要组合多个模板模块，或需要定制内容区、但没有完全匹配的专用模板时。它管理标准卡片外壳、标题栏和底部操作区；内容区可以按顺序组合行程、内容列表、选项组或业务组件。

## 示例

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

const sections: CompositeCardSection[] = [
  {
    type: 'transit',
    props: {
      items: [
        {
          key: 'G1-20260916',
          title: 'G1 · 9月16日 · 二等座',
          departureMain: '07:00',
          departureSub: '北京南',
          transferTop: '4小时36分',
          arrivalMain: '11:36',
          arrivalSub: '上海虹桥',
          price: '¥553'
        }
      ]
    }
  },
  {
    type: 'content',
    props: {
      items: [
        {
          key: 'passenger-title',
          subtitle: '选择乘车人（多选）'
        }
      ]
    }
  },
  {
    type: 'option-group',
    props: {
      selectionMode: 'multiple',
      maxSelected: 2,
      items: [
        { value: 'wang', title: '王一山' },
        { value: 'zheng', title: '郑天' },
        { value: 'add', title: '添加', icon: 'add' }
      ],
      value: ['wang'],
      onChange: (nextValues) => console.log(nextValues)
    }
  }
];

export default function TrainBookingCard() {
  return (
    <CompositeCard
      sections={sections}
      footer={{
        primaryActionButton: {
          text: '确认预订',
          onClick: () => console.log('confirm booking')
        }
      }}
    />
  );
}
```

自定义内容区示例（`ShipmentContent` 是业务维护的组件，内部可使用自己的样式）：

```tsx
import { CompositeCard } from '@doubao-dev/template';
import ShipmentContent from './shipment-content';

export default function ShipmentCard() {
  return (
    <CompositeCard
      header={{ placement: 'floating' }}
      sections={[{ type: 'custom', content: <ShipmentContent /> }]}
      footer={{ secondaryActionButton: { text: '查看全部包裹', onClick: () => {} } }}
    />
  );
}
```

## 主要 Props

| Prop       | 类型                         | 必填 | 说明                 |
| ---------- | -------------------------- | -- | ------------------ |
| `header`   | `CompositeCardHeaderProps` | 否  | 标准标题栏或浮层标题栏及右侧操作入口 |
| `sections` | `CompositeCardSection[]`   | 是  | 按顺序展示的单层模块数组       |
| `footer`   | `TemplateCardFooterProps`  | 否  | 底部主、次操作按钮          |
| `onClick`  | `(event) => void`          | 否  | 点击卡片根节点时触发         |

### CompositeCardSection

| `type`         | `props` 类型                        | 说明                       |
| -------------- | --------------------------------- | ------------------------ |
| `transit`      | `Pick<TransitCardProps, 'items'>` | 行程列表模块                   |
| `content`      | `Pick<ContentCardProps, 'items'>` | 信息列表模块，只渲染内容区域，不产生嵌套卡片外壳 |
| `option-group` | `OptionGroupProps`                | 单选或多选选项组                 |
| `custom`       | `content: ReactElement`           | 业务维护的内容组件，卡片外壳和操作区仍由模板管理 |

## 使用说明

- `sections` 是单层有序数组，接受 `transit`、`content`、`option-group` 和 `custom`。`custom` 通过 `content` 传入一个业务组件，不使用 section `children`。
- Widget 使用 `CompositeCard` 时，构建检查会提示核对组合后的整体效果是否符合豆包卡片设计规范；若静态识别到 `custom`，同一条提示还会要求核对自定义内容及其样式。此提醒不表示当前卡片违规，也不阻断构建。
- `header.placement` 默认是 `default`，渲染独立的 40px 标题栏。设为 `floating` 时标题栏覆盖在首个内容区左上角，不占据纵向空间；可通过 `header.title` 和 `header.iconSrc` 指定浮层品牌文案和图标，不传时使用应用插件信息。
- section 不提供独立标题字段。普通标题、说明或信息条目使用 `content` section 表达。
- `content.props.items` 与 `ContentCard.items` 一致，但只复用内容区域，不渲染 `ContentCard` 的标题栏、底部操作区或卡片外壳。
- `transit` 和 `content` section 只接受对应卡片的 `items`；`option-group` section 接受完整的 `OptionGroupProps`，可继续使用选项组的回调。
- 只有 `custom.content` 支持业务组件与其内部样式。业务样式应限定在该组件内部，不覆盖模板类名、卡片外壳、标题栏或 footer。其他 section 仍不接受任意 JSX、`children`、布局参数或 wrapper 样式。
- 构建检查可识别直接传入、从当前文件导入的 `custom.content` 组件，并放行其依赖链内的样式文件；Widget 入口和无关依赖的样式仍会提示 `widget.styles`。动态或跨模块组装的 section 可能无法静态识别，不能把没有 warning 当作边界已通过验证。
- 模块保留原有内容留白、内部布局和窄屏策略。`OptionGroup` 的组合容器补充左右 12px、下方 16px 的留白，上方不额外留白。
- 列表项原有回调和具名内容字段仍可使用；`transit.props.items` 支持多个行程。
- `items` 为空的 section 会连同间距一起收起；运行时遇到未知 `type` 时不会展示。
- `sections` 不支持运行中插入、删除或重排，因此不要求业务配置 section key。
