@doubao-dev/template

中文文档
0.10.0发布于 2026/11/16TypeScriptESM + CJS近 30 天下载 4911
中文使用文档
文档目录4 节
  1. 安装与使用
  2. 选择模板
  3. 使用约定
  4. 模板构建检查

@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:支持字符串、数字、直接传入的 primitive Tag / Title。
  • ContentCardItem.thumbnail、CheckoutCardProductItem.image:支持直接传入的 <image /> 或 <svg />,也可使用对应 URL 字段。
  • ContentCardItem.action 仅支持标准操作配置;TransitCardItem.price 支持标准价格配置、字符串或数字;中转信息使用 transferTop / transferBottom。
  • CompositeCard 的 transit、content、option-group section 复用上述内容规则;仅 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 加载的样式或脚本动态注入的样式。

版本与发布记录

@doubao-dev/template 共发布 92 个版本,首次发布于 2026/07/16;过去 12 个月发布了 92 个版本。

版本发布日期距今
0.10.0latest2026/11/16今天
0.9.0-canary-d8c42c341-202611160659122026/11/16今天
0.9.0-canary-b615bb20c-202611151228102026/11/15今天
0.9.0-canary-925bd0dad-202611141212122026/11/141 天前
0.9.0-canary-39d9ef1e7-202611131214382026/11/132 天前
0.9.0-canary-942cf82c7-202611130826482026/11/132 天前

其他发布通道:release-fix-0.1.1 → 0.1.1,release-fix-0.2.1 → 0.2.1,release-fix-0.2.2 → 0.2.2,release-fix-0.4.1 → 0.4.1,release-fix-0.4.2 → 0.4.2,release-fix-0.5.1 → 0.5.1。

关于 @doubao-dev/template 的常见问题

如何安装 @doubao-dev/template?

在项目目录运行 npm install @doubao-dev/template,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@types/react(^18.0.0)、@lynx-js/types(^4.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@doubao-dev/template 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@doubao-dev/template 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@doubao-dev/template 可以商用吗?

@doubao-dev/template 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@doubao-dev/template 的下载量有多少?

根据 npm 官方下载统计,@doubao-dev/template 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,911 次,日均约 164 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@doubao-dev/template 还在维护吗?

最新版本 0.10.0 发布于 2026/11/16(今天);至今共发布 92 个版本,其中过去 12 个月发布了 92 个;首次发布于 2026/07/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。