@doubao-dev/template
Doubao Apps 的 Widget 卡片模板。选择卡片类型后,通过结构化 Props 传入业务数据、操作和回调。
安装与使用
在已有 Doubao Apps 项目中安装:
pnpm add @doubao-dev/template
Widget 入口组件直接返回模板:
import { ContentCard } from '@doubao-dev/template';
export default function ProductCard() {
return (
<ContentCard
items={[{ key: 'headphones', title: '蓝牙耳机', subtitle: '支持主动降噪' }]}
footer={{
primaryActionButton: { text: '查看详情', onClick: () => console.log('view details') }
}}
/>
);
}
将示例数据和回调替换为项目业务逻辑。通常无需再包一层 view 或 scroll-view。
选择模板
按业务场景选择模板,点击链接查看对应的在线文档。
| 场景 | 模板文档 |
|---|---|
| 商品、服务、内容列表 | ContentCard |
| 报价与方案选择 | PriceActionCard |
| 优惠券展示与使用 | CouponCard |
| 下单、支付确认 | CheckoutCard |
| 交通票务列表 | TransitCard |
| 地图、位置和叫车信息 | MapCard |
| 人工确认选项 | AskHumanCard |
| 多种内容组成一张卡片 | CompositeCard |
标题、标签、价格、选项、数量调节、勾选框和协议声明见 Primitives。
Checkbox、Agreement 从 @doubao-dev/template/primitives 导入。
PriceActionCardItem.checkbox 配置右侧勾选框,替换该项操作按钮;不传时保持按钮布局。
所有使用共享 footer 的卡片可通过 footer.agreement 配置按钮下方的协议声明。
使用约定
- 对话流 Widget 必须使用平台模板。组合多个已知模块或定制内容区时使用
CompositeCard的sections,卡片外壳、header 和 footer 仍由模板管理;不通过children自定义整张卡片布局。 header、内容区和footer独立配置;onClick作用于卡片根节点。- 模板和 Primitives 不声明或暴露组件级 CSS 变量,可以直接使用已有的全局主题 token。
完整示例、Props、展示限制和回调行为统一维护在卡片模板文档,具体类型以项目安装版本为准。
模板构建检查
Web 和 Lynx 的 JSX 构建流程会对可静态确定的违规节点输出 [卡片检查] warning,包含文件、行列和字段路径,不改变运行时渲染,也不阻断构建。
已注册的 widget 入口最外层必须直接渲染模板卡片,不能套 <view>、<scroll-view> 或 fragment,也不能返回卡片数组。该规则以 widget.root 提示,普通页面不受此根节点检查影响。检查支持默认导出组件、defineWidget({ render })、当前文件的组件/渲染函数和条件分支;跨文件实现及无法解析的动态调用会跳过,不能据此认为根节点已通过验证。
ContentCardItem.title / subtitle / description、TransitCardItem.title:支持字符串、数字、直接传入的 primitiveTag/Title。ContentCardItem.thumbnail、CheckoutCardProductItem.image:支持直接传入的<image />或<svg />,也可使用对应 URL 字段。ContentCardItem.action仅支持标准操作配置;TransitCardItem.price支持标准价格配置、字符串或数字;中转信息使用transferTop / transferBottom。CompositeCard的transit、content、option-groupsection 复用上述内容规则;仅custom.content可传入业务组件,业务组件不能塞入其他受控槽位。- 文本槽位类型为
string | number | ReactElement,媒体槽位类型为ReactElement。类型只约束值的类别;具体元素白名单由构建检查根据 import 来源校验。
检查支持公共/内部包导入、别名、命名空间、当前文件常量、对象成员、对象/数组展开、条件表达式及表达式形式的 map 回调。跨文件数据、动态函数返回值、复杂数据流和无法解析的展开内容会跳过;不对这些值宣称检查通过。检查允许空值或条件表达式不展示内容。
卡片、列表项和 footer 不提供 style / className,构建检查会对这些字段提示 warning。Primitives 同样不提供 style / className。宿主背景色和模板内部布局仍由模板管理。
卡片不能通过导入自定义样式文件覆盖模板。构建检查沿已注册 Widget 的模块依赖链检查 CSS、SCSS、Sass、Less、Stylus 文件(含 CSS Modules),对直接引入、共享组件间接引入和构建器可解析的动态引入输出 widget.styles warning。CompositeCard 中静态可识别的 custom.content 业务组件及其依赖链可维护内容区样式,但不能覆盖模板外壳、header、footer 或模板类名;Widget 入口和无关依赖的样式仍会报警。平台模板、组件及框架包自身的样式依赖放行;仅由普通 Page 引入的样式不告警。此检查基于构建模块图,无法证明样式选择器没有覆盖模板,也不覆盖运行时通过 URL 加载的样式或脚本动态注入的样式。