# @doubao-dev/template 中文文档

规范地址：https://npmcn.com/package/%40doubao-dev/template/

版本：0\.10\.0
npm 元数据更新时间：2026-11-16T07:22:56.829Z
中文译文更新时间：2026-11-16T07:23:52.366Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40doubao-dev/template
原文对照：https://npmcn.com/package/%40doubao-dev/template/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：371 kB，114 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@types/react ^18\.0\.0，@lynx-js/types ^4\.0\.0
- 首次发布：2026-07-16T12:42:46.737Z
- 最新版本发布：2026-11-16T07:22:56.559Z
- 近 30 天下载量：4911（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：92（近 12 个月 92 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @doubao-dev/template
```

也可以使用：`pnpm add @doubao-dev/template`、`yarn add @doubao-dev/template`、`bun add @doubao-dev/template`

## README

# @doubao-dev/template

Doubao Apps 的 Widget 卡片模板。选择卡片类型后，通过结构化 Props 传入业务数据、操作和回调。

## 安装与使用

在已有 Doubao Apps 项目中安装：

```sh
pnpm add @doubao-dev/template
```

Widget 入口组件直接返回模板：

```tsx
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](https://open.doubao.com/apps-plugin/docs/templates/content-card) |
| 报价与方案选择 | [PriceActionCard](https://open.doubao.com/apps-plugin/docs/templates/price-action-card) |
| 优惠券展示与使用 | [CouponCard](https://open.doubao.com/apps-plugin/docs/templates/coupon-card) |
| 下单、支付确认 | [CheckoutCard](https://open.doubao.com/apps-plugin/docs/templates/checkout-card) |
| 交通票务列表 | [TransitCard](https://open.doubao.com/apps-plugin/docs/templates/transit-card) |
| 地图、位置和叫车信息 | [MapCard](https://open.doubao.com/apps-plugin/docs/templates/map-card) |
| 人工确认选项 | [AskHumanCard](https://open.doubao.com/apps-plugin/docs/templates/ask-human-card) |
| 多种内容组成一张卡片 | [CompositeCard](https://open.doubao.com/apps-plugin/docs/templates/composite-card) |

标题、标签、价格、选项、数量调节、勾选框和协议声明见 [Primitives](https://open.doubao.com/apps-plugin/docs/templates/shared-components#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、展示限制和回调行为统一维护在[卡片模板文档](https://open.doubao.com/apps-plugin/docs/templates/)，具体类型以项目安装版本为准。

## 模板构建检查

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？

在项目目录运行 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 和提交记录判断。

