@doubao-apps/template

Doubao Apps Widget 模板库，用于快速开发卡片类 widget。模板把标题栏、内容区、信息区和操作区组合成稳定的卡片结构，开发者在 defineWidget 里选择模板并传入业务数据即可。

推荐一个 widget 直接返回一张模板卡片，不额外包裹无意义的 view / scroll-view：

import { defineWidget } from '@doubao-apps/framework';
import { ContentCard, type ContentCardItem } from '@doubao-apps/template';

const items: ContentCardItem[] = [
  {
    key: 'a',
    title: '主标题',
    subtitle: '4199 元 | 商品描述',
    thumbnail: <image src="https://example.com/product.png" mode="aspectFill" />
  }
];

export default defineWidget({
  render() {
    return (
      <ContentCard
        items={items}
        header={{
          actionText: '更多',
          onActionClick: () => console.log('more')
        }}
        footer={{
          secondaryActionButton: {
            text: '查看更多',
            onClick: () => console.log('view more')
          },
          primaryActionButton: {
            text: '立即下单',
            onClick: () => console.log('submit')
          }
        }}
      />
    );
  }
});

通用约定

• header 配置标题栏右侧操作，类型为 TemplateCardHeaderProps，包含 actionText / showAction / onActionClick。
• footer 配置底部操作区，类型为 TemplateCardFooterProps，包含 primaryActionButton / secondaryActionButton。只传一个按钮时占据整行。
• header、footer 和内容区相互独立。footer 不会影响 items 展示数量，内容区也不负责渲染 header/footer。
• children 只接管内容区；模板仍保留卡片外壳、header 和 footer。
• className / style / onClick 作用在卡片根节点。
• 样式使用组件根 class 内声明的 --doubao-* CSS 变量，不把模板变量挂到 :root。

ContentCard

通用列表卡，由标题栏、列表内容和底部操作区组成，适合商品、服务、内容入口等可重复条目。

import { ContentCard } from '@doubao-apps/template';

<ContentCard
  items={[
    {
      title: '蓝牙降噪耳机 Pro',
      subtitle: '799 元 | 主动降噪 | 现货',
      thumbnail: <image src="https://example.com/product.png" mode="aspectFill" />,
      action: {
        type: 'button',
        text: '下单',
        onClick: () => console.log('order')
      }
    },
    {
      title: '便携冲牙器',
      subtitle: '189 元 | 三档水压 | 今日达'
    }
  ]}
  footer={{
    primaryActionButton: {
      text: '立即下单'
    }
  }}
/>

说明：

• title / subtitle 支持字符串、数字或自定义节点。字符串和数字使用模板默认单行样式。
• thumbnail 是列表项左侧缩略视觉内容，可传图片、图标或自定义节点。
• action 是列表项右侧操作区，支持 { type: 'button' }、{ type: 'switch' }、{ type: 'playback' } 或自定义节点。
• children 会替换列表内容区，不包含 header/footer。

PriceActionCard

价格操作卡，由多条"价格 + 信息 + 右侧按钮"组成，适合报价、权益、服务方案等结果列表。

import { PriceActionCard } from '@doubao-apps/template';

<PriceActionCard
  items={[
    {
      price: '¥128',
      badgeText: '推荐',
      infoRows: [{ text: '专车接送' }, { text: '免费等待 30 分钟' }],
      actionText: '预订',
      onActionClick: () => console.log('select')
    }
  ]}
  footer={{
    primaryActionButton: {
      text: '查看全部报价'
    }
  }}
/>

说明：

• items 用于配置价格列表，每条最多展示前 2 行 infoRows。
• actionText 为空时不展示列表项右侧按钮。
• footer 使用通用底部操作区，不再使用旧的 footerActionText。

CheckoutCard

通用提单卡，由商品摘要、提单信息、费用汇总和底部操作区组成，适合下单确认、支付确认等场景。

import { CheckoutCard } from '@doubao-apps/template';

<CheckoutCard
  productItems={[
    {
      title: '双人下午茶套餐',
      spec: '含 2 杯饮品 + 2 款甜点',
      price: '¥68',
      quantity: '1'
    },
    {
      title: '榛果拿铁',
      spec: '少糖 | 热饮',
      price: '¥28',
      quantity: '2',
      showChevron: false
    }
  ]}
  infoItems={[
    { label: '提单门店', value: '朝阳大悦城店' },
    { label: '预计时间', value: '今天 15:30', valueExtra: '请到店自取' }
  ]}
  feeItems={[
    { label: '包装费', value: '¥2' },
    { label: '服务费', value: '¥0' }
  ]}
  discountText="共优惠 ¥12"
  totalPrice="¥126"
  footer={{
    secondaryActionButton: { text: '修改' },
    primaryActionButton: { text: '提交订单' }
  }}
/>

说明：

• productItems 支持单个或多个商品。单项字段复用商品摘要能力，包括 title、spec、imageSrc、image、pricePrefix、price、quantity、showChevron、onClick。
• infoItems 配置提单信息列表。
• feeItems、discountText、totalLabel、totalPrice 配置费用汇总。
• 底部按钮使用 footer.primaryActionButton / footer.secondaryActionButton。

TicketOrderCard

票务提单卡，由航程信息、订单信息、费用汇总和底部操作区组成，适合机票、火车票等出行确认场景。

import { TicketOrderCard } from '@doubao-apps/template';

<TicketOrderCard
  routeItems={[
    {
      title: '北京 - 上海',
      description: '7月1日 周三 08:00-10:10 MU5101 经济舱'
    },
    {
      title: '上海 - 北京',
      description: '7月3日 周五 19:20-21:35 MU5162 经济舱'
    }
  ]}
  infoItems={[
    { label: '乘机人', value: '张三' },
    { label: '联系电话', value: '138****8888' }
  ]}
  feeItems={[
    { label: '机票', value: '¥1064' },
    { label: '机建燃油', value: '¥440' }
  ]}
  totalLabel="合计"
  totalPrice="¥1504"
  footer={{
    secondaryActionButton: { text: '修改' },
    primaryActionButton: { text: '提交' }
  }}
/>

说明：

• routeItems 配置航程列表，单项可通过 showChevron={false} 隐藏标题右侧箭头。
• totalContent 可以接管合计区域，优先级高于 totalLabel / totalPrice。
• 底部按钮使用通用 footer。

TransitCard

交通票务列表卡，由多条出发、中转、到达和价格信息组成，适合展示机票、火车票、大巴等推荐列表。

import { TransitCard } from '@doubao-apps/template';

<TransitCard
  items={[
    {
      title: '北京南 - 上海虹桥',
      departureMain: '08:00',
      departureSub: '北京南',
      transferTop: '直达',
      arrivalMain: '12:32',
      arrivalDayOffset: '+1',
      arrivalSub: '上海虹桥',
      price: '¥553'
    }
  ]}
  footer={{
    primaryActionButton: {
      text: '查看更多车次'
    }
  }}
/>

说明：

• items 会全量展示，模板不做"最多 4 条"的截断。
• title、transfer、price 接收 ReactNode，适合需要自定义整块区域的场景。
• departureMain、departureSub、transferTop、transferBottom、arrivalMain、arrivalDayOffset、arrivalSub 接收字符串或数字。

AskHumanCard

人工确认选项卡，由一组选项组成，适合让用户在多个候选项中确认选择。

import { AskHumanCard } from '@doubao-apps/template';

<AskHumanCard
  items={[
    { text: '朝阳大悦城店 | 0.8km' },
    { text: '三里屯太古里店 | 2.1km' },
    { text: '国贸商城店 | 3.4km' },
    {
      text: '都不是',
      showArrow: 'right',
      onClick: () => console.log('skip')
    }
  ]}
/>

说明：

• items 配置选项列表，每项可用 text 或 children。
• items[].showArrow 支持 'left'、'right'、'none'，默认不展示；跳过、固定跳转等入口也通过 items 表达。