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, and this page is available as Markdown at /apps-plugin/docs/templates/composite-card.md.

组合卡

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

示例

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 是业务维护的组件,内部可使用自己的样式):

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类型必填说明
headerCompositeCardHeaderProps否标准标题栏或浮层标题栏及右侧操作入口
sectionsCompositeCardSection[]是按顺序展示的单层模块数组
footerTemplateCardFooterProps否底部主、次操作按钮
onClick(event) => void否点击卡片根节点时触发

CompositeCardSection

typeprops 类型说明
transitPick<TransitCardProps, 'items'>行程列表模块
contentPick<ContentCardProps, 'items'>信息列表模块,只渲染内容区域,不产生嵌套卡片外壳
option-groupOptionGroupProps单选或多选选项组
customcontent: 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。