# @duffel/components 中文文档

规范地址：https://npmcn.com/package/%40duffel/components/

版本：3\.17\.0
npm 元数据更新时间：2026-06-26T16:27:00.753Z
中文译文更新时间：2026-11-12T23:59:03.292Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40duffel/components
原文对照：https://npmcn.com/package/%40duffel/components/?lang=original
项目主页：https://github.com/duffelhq/duffel-components#readme
源码仓库：https://github.com/duffelhq/duffel-components

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

- 包体积（解压后）：5 MB，257 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.\*
- 运行依赖：12 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2021-07-22T15:21:27.473Z
- 最新版本发布：2026-06-24T12:45:04.770Z
- 近 30 天下载量：247438（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：269（近 12 个月 11 个）

## 中文简介

用 Duffel 构建旅行产品的组件库 .

## 安装

```sh
npm install @duffel/components
```

也可以使用：`pnpm add @duffel/components`、`yarn add @duffel/components`、`bun add @duffel/components`

## README

# @ duffel/ 组件

这个软件包是一个组件库,用于帮助您使用 [达菲尔 API](https://duffel.com/docs)。 。 。 .

## 开始

将组件整合到您的网站上有三种不同的方式。 这取决于你使用的是什么技术。 我们将使用辅助部件作为例子,但同样的步骤将适用于其他部件.

### 整合React 组件

1.  安装软件包 :
    
    ```sh
    yarn add @duffel/components
    # -- or --
    npm i @duffel/components
    ```
    
2.  从 `@duffel/components`
    
    ```javascript
    import { DuffelAncillaries } from "@duffel/components";
    ```
    
3.  将部件装入所需的道具
    
    ```jsx
    <DuffelAncillaries
      offer={offerFromYourBackend} // The offer object from your backend
      seat_maps={seatMapsFromYourBackend}
      services={["bags", "seats"]}
      passengers={[...]}
      onPayloadReady={console.log}
    />
    ```
    

### 整合 HTML 自定义元素

如果您没有使用React,但仍处于节点环境中,您可以:

1.  安装软件包 :
    
    ```sh
    yarn add @duffel/components
    # -- or --
    npm i @duffel/components
    ```
    
2.  导入组件渲染函数和事件听众 `@duffel/components/custom-elements`
    
    ```javascript
    import {
      renderDuffelAncillariesCustomElement,
      onDuffelAncillariesPayloadReady,
    } from "@duffel/components/custom-elements";
    ```
    
3.  在您的 HTML 中包含自定义元素
    
    ```html
    <duffel-ancillaries></duffel-ancillaries>
    ```
    
4.  调用带有正确属性的渲染函数来渲染自定义元素 :
    
    ```javascript
    renderDuffelAncillariesCustomElement({
      offer: offerFromYourBackend,
      seat_maps: seatMapsFromYourBackend,
      services: ["bags", "seats"],
      passengers: [...],
    });
    ```
    
5.  为组件触发的事件设置听众 :
    
    ```javascript
    onDuffelAncillariesPayloadReady((data, metadata) => {
      console.table(data);
      console.table(metadata);
    });
    ```
    

### 没有节点的自定义元素集成

如果您不在节点环境中,不能依赖npm安装软件包,我们通过我们的CDN提供. 这是如何整合:

1.  包含脚本标签
    
    ```html
    <!--
      Replace VERSION with the desired version.
      You can find them all on https://www.npmjs.com/package/@duffel/components?activeTab=versions
    
      Replace COMPONENT with the desired component you'd like to use.
      You can find the components available in the `./cdn-dist` directory after running `yarn build-and-publish --dry-run`
    
      For example, for the duffel ancillaries component on version 3.3.1, use:
      https://assets.duffel.com/components/3.3.1/duffel-ancillaries.js
    -->
    
    <script src="https://assets.duffel.com/components/VERSION/COMPONENT.js"></script>
    ```
    
2.  在 HTML 中包含自定义元素标记 :
    
    ```html
    <duffel-ancillaries></duffel-ancillaries>
    ```
    
3.  将组件装入所需数据。 您可以安全地调用此功能所需的次数, 例如, 当乘客数据变化时 .
    
    ```javascript
    const duffelAncillariesElement = document.querySelector("duffel-ancillaries");
    
    duffelAncillariesElement.render({
      offer: offerFromYourBackend,
      seat_maps: seatMapsFromYourBackend,
      services: ["bags", "seats"],
      passengers: [...],
    });
    ```
    
4.  聆听组件上的“ 在 Payload Ready” 事件 . `event.detail.data` 包含您需要发送到 Duffel API 以创建命令的有效载荷 .
    
    ```javascript
    const duffelAncillariesElement =
      document.querySelector("duffel-ancillaries");
    
    duffelAncillariesElement.addEventListener("onPayloadReady", (event) =>
      console.log("onPayloadReady\n", event.detail),
    );
    ```
    

## 财务问题

### 是否有融合指南?

-   [将辅助部件纳入您的预订流程](https://duffel.com/docs/guides/ancillaries-component)。 。 。 .
-   [将客户卡表整合到您的退出页面](https://duffel.com/docs/guides/paying-with-customer-cards)。 。 。 .

很快会有更多导游来.

这个 `examples` 文件夹是快速启动并看到每个组件充分运行的示例的好方法.

### 通过 npm 可用哪些组件 ?

React 组件列表可见于 `src/index.ts`。如果您正在使用自定义元素,您可以在其中找到所有渲染函数和事件听众 `src/custom-elements.ts`。 。 。 .

### 通过CDN可提供哪些组件?

请检查 `entryPoints` 内 `config/esbuild.base.config.js`。它列出了我们将构建的所有组件,并上传到CDN.

## 常见问题

### @duffel/components 是什么？

用 Duffel 构建旅行产品的组件库 \.

### 如何安装 @duffel/components？

在项目目录运行 npm install @duffel/components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @duffel/components 支持 TypeScript 吗？

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

### @duffel/components 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @duffel/components 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.\*。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @duffel/components 可以商用吗？

@duffel/components 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @duffel/components 的下载量有多少？

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

### @duffel/components 还在维护吗？

最新版本 3\.17\.0 发布于 2026/06/24（4 个月前）；至今共发布 269 个版本，其中过去 12 个月发布了 11 个；首次发布于 2021/07/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。