# @bigcommerce/checkout-sdk 中文文档

规范地址：https://npmcn.com/package/%40bigcommerce/checkout-sdk/

版本：1\.997\.1
npm 元数据更新时间：2026-11-03T13:06:54.502Z
中文译文更新时间：2026-11-08T02:05:58.863Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bigcommerce/checkout-sdk
原文对照：https://npmcn.com/package/%40bigcommerce/checkout-sdk/?lang=original
项目主页：https://github.com/bigcommerce/checkout-sdk-js
源码仓库：https://github.com/bigcommerce/checkout-sdk-js

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

- 包体积（解压后）：69.9 MB，823 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：24
- 运行依赖：25 个
- 首次发布：2018-08-08T06:41:53.417Z
- 最新版本发布：2026-11-03T13:06:54.341Z
- 近 30 天下载量：16176（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：1695（近 12 个月 281 个）

## 中文简介

大商业检查 JavaScript SDK

## 安装

```sh
npm install @bigcommerce/checkout-sdk
```

也可以使用：`pnpm add @bigcommerce/checkout-sdk`、`yarn add @bigcommerce/checkout-sdk`、`bun add @bigcommerce/checkout-sdk`

## README

# @ bigcommerce/ checkout-sdk (中文(简体) )

检查JS SDK为您提供了工具,您可以自行为BigCommerce商店建造出账解决方案.

SDK有一个方便的应用程序接口,用于启动并完成出站流程. 在接口后,它处理所有与我们 Storefront API 和其他支付SDK 的必要互动. 这样你就可以专心创造出一种对于你的企业来说是独一无二的离职体验.

## 目录

-   [特征](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-features)
-   [开始](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-getting-started)
-   [安装](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-installation)
    -   [使用国家防范机制一揽子计划](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-using-npm-package)
    -   [使用 CDN 網址](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-using-cdn-url)
-   [所需资源](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-requirements)
    -   [浏览器支持](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-browser-support)
    -   [框架](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-framework)
    -   [(简体中文)](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-cors)
-   [使用量](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-usage)
    -   [初始化实例](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-initialize-instance)
        -   [装入检出](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-load-checkout)
    -   [在客户签名](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-sign-in-customer)
        -   [无密码签名](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-passwordless-sign-in)
    -   [继续做客](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-continue-as-guest)
    -   [设置运输细节](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-set-shipping-details)
        -   [设置传送地址](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-set-shipping-address)
        -   [设置航运选项](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-set-shipping-option)
    -   [设置计费细节](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-set-billing-details)
    -   [使用优惠券或礼品证书](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-apply-coupon-or-gift-certificate)
    -   [执行垃圾邮件保护检查](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-execute-spam-protection-check)
    -   [提交付款和订单](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-submit-payment-and-order)
        -   [装入付款方法](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-load-payment-methods)
        -   [初始化支付方法](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-initialize-payment-method)
        -   [提交顺序](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-submit-order)
        -   [最后确定顺序](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-finalize-order)
    -   [装入顺序](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-load-order)
    -   [订阅更改](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-subscribe-to-changes)
    -   [取消请求](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-cancel-requests)
-   [问题](https://npmcn.com/package/%40bigcommerce/checkout-sdk/FAQS.md)
-   [API 参考](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-api-reference)
-   [另见](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-see-also)
-   [页:1](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-notes)
-   [更新存储前端图形QL 方案](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-updating-the-storefront-graphql-schema)
-   [捐款](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-contribution)
-   [许可证](https://npmcn.com/package/%40bigcommerce/checkout-sdk/#readme-license)

## 特征

这个 [检查JS SDK](https://developer.bigcommerce.com/api-docs/cart-and-checkout/checkout-sdk) 是一个用于我们的客户端 JavaScript 库 [存储前端取出 API](https://developer.bigcommerce.com/api-reference/cart-checkout/storefront-checkout-api)它提供了完成离职程序所需的所有方法,例如:

-   在客户中签名并开始退出程序
-   设置装运、计费和其他所需信息
-   支付订单并完成结账程序

图书馆还提供与所有付费方法的整合,由 [优化一页取出](https://support.bigcommerce.com/articles/Public/Optimized-Single-Page-Checkout),例如:

-   付费快递
-   脑树
-   平方边
-   亚马逊
-   克拉纳
-   付账后

利用这个库结合您最喜欢的UI框架,可以为一商店构建一个点名检查UI,可以附加附加功能. 有了大商业的公开检查,我们提供 **联合来文** 作为我们的 [参考执行](https://github.com/bigcommerce/checkout-js) 在 React 中写着的检查结果,以启动您.

## 开始

校对:Soup 我们创建了以下教程来帮助您开始学习.

-   [打开退出快速启动](https://developer.bigcommerce.com/stencil-docs/customizing-checkout/open-checkout-quick-start) 在快速开始的教程中, 我们将配置我们的开发环境, 并修改代码为大商场的开放检查叉.
-   [安装自定义检查](https://developer.bigcommerce.com/stencil-docs/customizing-checkout/installing-custom-checkouts) - 文章将概述如何包装自定义的取出文件,并通过控制面板安装自定义取出.

## 安装

### 使用国家防范机制一揽子计划

您可以使用 [无](https://www.npmjs.com/get-npm)。 。 。 .

```sh
npm install --save @bigcommerce/checkout-sdk
```

### 使用 CDN 網址

您也可以通过引用 CDN URL 来使用此库 .

```
https://checkout-sdk.bigcommerce.com/v1/loader.js
```

使用上面的脚本 URL 的主要好处是,您的应用程序可以自动接收我们提供的后向兼容的更新和bug修正,而无需手动进行升级.

上面的剧本装入后, `checkoutKitLoader` 实例将在 `window` 并可以使用它来加载应用程序所需的模块。 即:

```js
const module = await checkoutKitLoader.load('checkout-sdk');
const service = module.createCheckoutService();
```

目前,有三个单元可供公众使用:

-   **报出- sdk**:这是包含套件所有公共出口的主要模块.
-   **退出按钮**: 此子模块一旦创建出推车(即:推车页面),就可以用于初始化商店前端的取出按钮.
-   **嵌入式检查退出**:这个子模块可用于将我们最优化的"一页取出"嵌入到非本地的店面(即:Wordpress).

请参看下文的使用指南,以了解关于其中每一项的更多信息.

## 所需资源

### 浏览器支持

我们释放了ES5的图书馆,所以你不必做额外的转录才能使用. 但是,你确实要求 [承诺多填充](https://github.com/stefanpenner/es6-promise) 如果您需要支持更旧的浏览器,例如 IE11.

另一方面,CDN版本已经包含了在IE11中工作所必需的多填充.

### 框架

库为框架不可知论. 换句话说,您可以使用任意的UI框架或库.

### (简体中文)

由于我们的 Storefront Web API 目前不支持 CORS, 您将无法在 BigCommerce 商店外使用库 .

## 使用量

以下是如何使用此库的指南.

### 初始化实例

首先,你必须创建一个 `CheckoutService` 举个例子.

```js
import { createCheckoutService } from '@bigcommerce/checkout-sdk';

const service = createCheckoutService();
```

#### 装入检出

一旦有实例,您应该装入当前检出,并向客户提交信息.

```js
const checkoutId = '0cfd6c06-57c3-4e29-8d7a-de55cc8a9052';
const state = await service.loadCheckout(checkoutId);

console.log(state.data.getCheckout());
```

取出对象包含各种关于取出过程的信息,如推车,总和等. . 一旦数据被加载,可以通过调用状态对象提供的获取器来取回.

```js
console.log(state.data.getCart());
console.log(state.data.getBillingAddress());
console.log(state.data.getShippingAddress());
```

此外,还可以访问商店的取出配置. 配置对象包含与取出相关的各种设置的信息,例如存储的默认货币等.

```js
console.log(state.data.getConfig());
```

### 在客户签名

在向客户收集其他离职信息之前,应当先请其报名. 一旦他们被签入,离职状态将包含他们的个人细节,例如他们的住址.

```js
const state = await service.signInCustomer({ email: 'foo@bar.com', password: 'password123' });

console.log(state.data.getCustomer());
```

或者,您可以要求客户继续作为客人。 请注意,在此情况下,电子邮件会被存储 作为计费地址的一部分,也可以通过推车对象访问.

```js
const state = await service.continueAsGuest({ email: 'foo@bar.com' });

console.log(state.data.getCart().email);
console.log(state.data.getBillingAddress().email);
```

#### 无密码签名

客户可以使用发送到其电子邮件地址的单一用途链接签名。 一旦他们点击了链接,他们就会被重新定位回商店,成为签约用户.

学着点 [退出服务# 发送签名电子邮件](https://npmcn.com/package/%40bigcommerce/checkout-sdk/docs/classes/CheckoutService.md#sendSignInEmail)

### 继续做客

如果您的退出设置允许, 您的客户可以继续作为来宾的退出( 不签名 ) .

```js
const state = await service.continueAsGuest({ email: 'foo@bar.com' });

console.log(state.data.getBillingAddress());
console.log(state.data.getCustomer());
```

学着点 [离职服务# 持续嘉宾](https://npmcn.com/package/%40bigcommerce/checkout-sdk/docs/classes/CheckoutService.md#continueasguest)

### 设置运输细节

#### 设置传送地址

要设置报到目的地,应当要求客户提供地址. 要做到这一点,你需要制作一套形式字段来收集他们的细节. 一组字段还包括由商家所配置的所有自定义字段.

```js
const fields = state.data.getShippingAddressFields();

fields.forEach(field => {
    console.log(field);
});
```

要设置发送地址,您可以整理所有地址域并构建一个请求的有效载荷.

```js
const address = {
    firstName: 'Test',
    lastName: 'Tester',
    address1: '12345 Testing Way',
    city: 'Some City',
    stateOrProvinceCode: 'CA',
    postalCode: '95555',
    countryCode: 'US',
    phone: '555-555-5555',
    email: 'test.tester@test.com'
};

const state = await service.updateShippingAddress(address);

console.log(state.data.getShippingAddress());
console.log(state.data.getShippingOptions());
```

#### 设置航运选项

地址一经提供,您就可以得到一份地址可用的运输选项清单以及每个选项的成本.

然后,您可以要求客户从列表中选择运输选项.

```js
const address = state.data.getShippingAddress();
const options = state.data.getShippingOptions();
const state = await service.selectShippingOption(options[address.id].id);

console.log(state.data.getSelectedShippingOption());
```

### 设置计费细节

为了完成结账过程,您还需要向客户收取账单地址.

```js
const state = await service.updateBillingAddress(address);

console.log(state.data.getBillingAddress());
```

### 使用优惠券或礼品证书

您也可以接受客户提供的任何优惠券代码或礼品证.

```js
const state = await service.applyCoupon('COUPON');

console.log(state.data.getOrder().coupon);
```

```js
const state = await service.applyGiftCertificate('GIFT');

console.log(state.data.getOrder().giftCertificate);
```

也可以允许客户去除之前应用的任何优惠券代码或礼品证.

```js
await service.removeCoupon('COUPON');
await service.removeGiftCertificate('GIFT');
```

### 执行垃圾邮件保护检查

也可以使bot保护能够防止bots和其他类型的自动滥用生成命令. 注意,启用此特性会增加检查出摩擦,可能影响转换. 因此,我们建议不保留这个特色 如果你的商店没有遇到bots.

```js
await service.executeSpamCheck();
```

学着点 [检查服务# 执行SpamCheck](https://npmcn.com/package/%40bigcommerce/checkout-sdk/docs/classes/CheckoutService.md#executespamcheck)。 。 。 .

### 提交付款和订单

#### 装入付款方法

在下订单之前,需要向客户收取付款细节. 为此,您必须首先向客户加载并提交可用的支付方法清单.

```js
const state = await service.loadPaymentMethods();

console.log(state.data.getPaymentMethods());
```

#### 初始化支付方法

之后,您应该初始化支付方法,以便他们可以接受支付细节.

```js
await service.initializePayment({ methodId: 'braintree' });
```

有些支付方法需要您提供额外的初始化选项。 例如,亚马逊公司需要一个容器ID来初始化它们的支付部件. 否则,它们将无法正常工作.

```js
await service.initializePayment({
    methodId: 'amazon',
    amazon: {
        container: 'walletWidget',
    },
});
```

#### 提交顺序

然后,你可以要求客户提供他们选择的支付方法所要求的支付细节. 如果成功执行该方法,您将创建命令并从而完成取出进程.

我们可能要求完成人力核查,然后才能处理付款,这将在这一步骤中处理.

```js
const payment = {
    methodId: 'braintree',
    paymentData: {
        ccExpiry: { month: 10, year: 20 },
        ccName: 'BigCommerce',
        ccNumber: '4111111111111111',
        ccType: 'visa',
        ccCvv: 123,
    },
};

const state = await service.submitOrder({ payment });

console.log(state.getOrder());

window.location.assign('/order-confirmation');
```

如果提交书成功,应当将客户重定向到订单确认页.

#### 最后确定顺序

此外,对于某些付款方法,可以要求客户在外部网站上输入其付款详情. 对于这些方法,您必须最终确定客户重定向到退出页面时的顺序,以便 完成取出流程。 在向客户提交任何离职信息之前,应在背景中这样做.

```js
await service.loadCheckout();

try {
    await service.finalizeOrderIfNeeded();

    window.location.assign('/order-confirmation');
} catch (error) {
    if (error.type !== 'order_finalization_not_required') {
        throw error;
    }
}

// Render the checkout view
```

同样,如果订单定稿成功,您应该将客户重新导向订单确认页.

### 装入顺序

一旦命令被创建,你就可以打电话取回它. 应在订单确认页上这样做,以便您向客户提交最后订单.

```js
const orderId = 123;
const state = await service.loadOrder(orderId);

console.log(state.data.getOrder());
```

### 订阅更改

您的用户界面应该对退出状态的改变作出反应 。 变更时,您应当向客户提供最新信息. 你可以通过订阅 退出状态.

订阅者每次州内出现变化都会被触发. 如果修改会影响您的视图,您应当重新提交,以反映最新的更新。 订阅者提供了一个状态对象,您可以用来获取特定的退出信息. 它还提供加载状态,出错细节等元信息.

```js
service.subscribe(state => {
    // Return the current checkout
    console.log(state.data.getCheckout());

    // Return an error object if unable to load checkout
    console.log(state.errors.getLoadCheckoutError());

    // Return `true` if in the process of loading checkout
    console.log(state.statuses.isLoadingCheckout());
});
```

如果您只对状态的某些部分感兴趣,可以通过向用户提供过滤功能来过滤无关的更改.

```js
const filter = state => state.data.getCart();

service.subscribe(state => {
    console.log(state.data.getCart())
}, filter);
```

如果需要,可以在订阅者之外获取同一状态对象.

```js
const state = service.getState();

console.log(state);
```

### 取消请求

如果您需要取消一项请求才能完成,您可以提供 `Timeout` 请求时的对象。 举例来说,一个使用的案例可能是执行一个在有变化时更新传输地址的用户界面——所以您想要中止任何待处理的请求,而只接受最新的请求.

```js
import { createTimeout } from '@bigcommerce/checkout-js-sdk';

const address = { countryCode: 'US' };
const timeout = createTimeout();

service.updateShippingAddress(address, { timeout });
timeout.complete(); // Aborts the update
```

## API 参考

我们提供了广泛的 [API 参考](https://npmcn.com/package/%40bigcommerce/checkout-sdk/docs/README.md)。 。 。 .

SDK提供的职能是:

-   [创建检查服务](https://npmcn.com/package/%40bigcommerce/checkout-sdk/docs/README.md#createcheckoutservice)
-   [创建检查出按钮启动器](https://npmcn.com/package/%40bigcommerce/checkout-sdk/docs/README.md#createcheckoutbuttoninitializer)
-   [创建嵌入式检查信箱](https://npmcn.com/package/%40bigcommerce/checkout-sdk/docs/README.md#createembeddedcheckoutmessenger)
-   [创建语言服务](https://npmcn.com/package/%40bigcommerce/checkout-sdk/docs/README.md#createlanguageservice)
-   [创建即时服务](https://npmcn.com/package/%40bigcommerce/checkout-sdk/docs/README.md#createcurrencyservice)
-   [创建跟踪器](https://npmcn.com/package/%40bigcommerce/checkout-sdk/docs/README.md#createsteptracker)
-   [嵌入检查](https://npmcn.com/package/%40bigcommerce/checkout-sdk/docs/README.md#embedcheckout)

## 另见

-   [联合来文](https://github.com/bigcommerce/checkout-js) - 这是我们使用JSSDK的检查结果的参考执行.
-   [存储前端 API](https://developer.bigcommerce.com/docs/storefront/cart-checkout/guide/rest-storefront) - Storefront checkout & Cart Web APIs的文档.

## 页:1

-   如果您在 Stencil 主题的取出页面上使用此库, 您一定有 [优化一页取出](https://support.bigcommerce.com/articles/Public/Optimized-Single-Page-Checkout/) 启用 。 否则, 您将无法预览您的更改 .
-   您只能在 HTTPS 页面上使用此库, 除非您正在本地开发 .
-   为了跟上最新变化,请点击 E [监视](https://github.com/bigcommerce/checkout-sdk-js/subscription) 按钮.

## 更新存储前端图形QL 方案

`packages/core/schema/storefront.graphql` 是一个销售的复制件 [存储前端](https://github.com/bigcommerce/storefront) 图QL SDL. 脚本类型和文档 `packages/core/src/generated-codegen` 由此产生(见 `packages/core/codegen.ts`),而非被承诺——它们在每个构建,插图和测试运行前都会被自动再生.

要刷新计划:

1.  复制 `src/main/resources/graphql/autogenerated/schema.graphql` 从存储前端寄存器进入 `packages/core/schema/storefront.graphql`。 。 。 .
    
2.  修复无效 `@cacheControl` 范围值——适用上游SDL `@cacheControl(scope: Public)` 当 enum 值是 `PUBLIC`,严格验证拒绝:
    
    ```sh
    sed -i '' 's/scope: Public/scope: PUBLIC/g' packages/core/schema/storefront.graphql
    ```
    
3.  重新生成类型 :
    
    ```sh
    npm run codegen
    ```
    

## 捐款

我们积极维护并增加图书馆的新功能,以支持我们的官方出票(Optimized出票). 但我们也接受社区的贡献.

如欲捐款,请参考 [捐款指南](https://npmcn.com/package/%40bigcommerce/checkout-sdk/CONTRIBUTING.md)。 。 。 .

## 许可证

麻省理工学院

## 常见问题

### @bigcommerce/checkout-sdk 是什么？

大商业检查 JavaScript SDK

### 如何安装 @bigcommerce/checkout-sdk？

在项目目录运行 npm install @bigcommerce/checkout-sdk，或使用 pnpm add / yarn add / bun add。

### @bigcommerce/checkout-sdk 支持 TypeScript 吗？

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

### @bigcommerce/checkout-sdk 支持 ESM 还是 CommonJS？

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

### @bigcommerce/checkout-sdk 需要什么版本的 Node\.js？

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

### @bigcommerce/checkout-sdk 可以商用吗？

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

### @bigcommerce/checkout-sdk 的下载量有多少？

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

### @bigcommerce/checkout-sdk 还在维护吗？

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