# @thenextgateway/cashier\.sdk 中文文档

规范地址：https://npmcn.com/package/%40thenextgateway/cashier.sdk/

版本：2\.1\.1
npm 元数据更新时间：2026-11-02T15:43:39.099Z
中文译文更新时间：2026-11-02T16:34:13.196Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40thenextgateway/cashier.sdk
原文对照：https://npmcn.com/package/%40thenextgateway/cashier.sdk/?lang=original

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

- 包体积（解压后）：35.2 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@thenextgateway/core 2\.1\.1
- 首次发布：2026-08-07T12:50:50.233Z
- 最新版本发布：2026-11-02T15:43:38.838Z
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

浏览器SDK，用于嵌入和与TNG出纳通信。

## 安装

```sh
npm install @thenextgateway/cashier.sdk
```

也可以使用：`pnpm add @thenextgateway/cashier.sdk`、`yarn add @thenextgateway/cashier.sdk`、`bun add @thenextgateway/cashier.sdk`

## README

# @thenextgateway / cashier.sdk

浏览器SDK，用于嵌入和与TNG出纳通信。

## 开始使用

### 安装

```
npm install @thenextgateway/cashier.sdk @thenextgateway/core
```

### 使用

的新实例来使用收银员 `TNGCashier` 并传递应该呈现出纳员iframe的容器元素的ID、出纳员参数和一个配置对象。

保持对已创建实例的引用。收银员仍然需要手动初始化，并且实例充当跨帧通信的入口点。

```ts
import { TNGCashier } from "@thenextgateway/cashier.sdk";
import { TNG_TRANSACTION_TYPES, type CashierConfig } from "@thenextgateway/core";

const config: Partial<CashierConfig> = {
  iframeOrigin: "https://cashier.example.com",
  transactionType: TNG_TRANSACTION_TYPES.deposit,
  transactionId: "example-transaction-id",
  paymentMethodId: 1,
  amount: "10",
  currency: "EUR",
};

const cashier = new TNGCashier(
  "iframe-container-id",
  {
    instance: "example-instance",
    applicationId: "example-application-id",
  },
  config,
);

await cashier.initialize();
```

`iframeOrigin` 在构造时是必需的 `TNGCashier`． 对于参数, `instance` 总是必需的。提供至少一个 `application` 或者 `applicationId`.

### 跨帧消息类型

SDK通过浏览器与出纳通信 `postMessage` 事件。消息类型值的前缀为 `tng_` 因此可以将它们与页面上的其他框架消息区分开来。

如果您的应用程序直接侦听出纳消息或向外部发送消息 `TNGCashier`，使用 `CASHIER_MESSAGE_TYPES` 和 `CROSSFRAME_MESSAGE_TYPES` 出口 `@thenextgateway/core` 而不是硬编码字符串。

## 设置

### 收银员参数

| 场 | 类型 | 描述 |
| --- | --- | --- |
| `instance` | `string` | 实例标识符。 |
| `application` | `string` (可选) | 应用程序标识符。如果需要 `applicationId` 不见了。 |
| `applicationId` | `string` (可选) | 应用程序ID。如果需要 `application` 不见了。 |

### 配置字段

SDK构造函数接受 `Partial<CashierConfig>`. `iframeOrigin` 由SDK立即检查。其他必需的字段在初始化期间由收银员验证，可以在构造函数配置中提供，也可以稍后使用 `updateConfig`.

| 场 | 类型 | 描述 |
| --- | --- | --- |
| `iframeOrigin` | `string` | iframe的URL。必须与部署的出纳来源匹配。 |
| `transactionId` | `string` | 事务ID。只有在需要时才需要 `method` 步骤已关闭。 |
| `paymentMethodId` | `number` | 付款方式ID。只有在需要时才需要 `method` 步骤已关闭。 |
| `transactionType` | `TNGTransactionType` （`deposit` / `withdrawal`） | 事务类型。使用 `TNG_TRANSACTION_TYPES` 对于提供的值。 |
| `amount` | `string` | 例如，字符串格式的交易金额 `10` 或者 `9.99`． 如果配置了可选的数量步骤，则不需要，但可以设置默认值。 |
| `currency` | `string` | 例如，交易货币 `EUR`． 如果配置了可选的数量步骤，则不需要，但可以设置默认值。 |
| `redirectUrl` | `string` (可选) | 事务完成后要重定向到的URL。当没有提供时，收银员使用自己的“进程结束”静态页面。 |
| `attributes` | `TransactionAttribute[]` —包含键/值的对象数组 `{ key: "example", value: "example" }` | 处理时传递给服务器的自定义属性。 |
| `languageCode` | `string` (可选) | 在出纳中使用的语言代码。当没有提供时，收银员使用英语。 |
| `optionalSteps` | `OptionalProgressStep[]` - `method`， `amount`, `receipt` | 流中应该包含哪些可选步骤。 |
| `amountPresets` | `(string | number)[]` (可选) | 预设金额可选步骤。这些显示为可选择的选项。值解析为 `NaN` 将被忽略。 |
| `currencyOptions` | `string[]` (可选,如果 `currency` 提供) | 货币选项为金额可选步骤。 |
| `sessionId` | `string` (如果需要 `method` 可选步骤已开启) | 当方法选择发生在收银端时，初始化事务所需的会话ID。 |
| `customerId` | `string` (如果需要 `method` 可选步骤已开启) | 在收银端选择方法时初始化交易所需的客户ID。 |

### 初始化和通信方法

| 方法 | 参数(年代) | 返回 | 描述 |
| --- | --- | --- | --- |
| `initialize` | \- | `Promise<TNGCashier>` | 初始化收银员，包括加载iframe。返回承诺，该承诺可以通过对收银员对象的引用成功解析，也可以通过错误消息拒绝。 |
| `dispose` | \- | \- | 清除侦听器并删除iframe。 |
| `updateConfig` | `config`： `Partial<CashierConfig>` | \- | 更新收银员配置。 |
| `onConfigMissing` | `callback`： `(result: HostEventData) => void` | \- | 注册一个回调，当收银员由于缺少配置值而没有正确初始化时将调用该回调。返回的事件将包括哪些字段完全丢失的信息。 |
| `onTransactionStart` | `callback`： `(result: HostEventData) => void` | \- | 注册一个回调，当收银员在服务器端启动事务时将调用该回调。请注意，在该事件触发之前，仍然可以通过更新配置来更改支付方式。Sent Event将包含事务和方法对象。 |
| `onTransactionComplete` | `callback`： `(result: HostEventData) => void` | \- | 注册一个回调，当收银员在服务器端完成事务时将调用该回调。Sent Event将包含事务和方法对象。 |
| `onNavigate` | `callback`： `(result: HostEventData) => void` | \- | 注册一个回调函数，当收银员的当前步骤发生变化时将调用该函数。发送的事件将包含有关当前步骤的信息。 |
| `onClose` | `callback`： `(result: HostEventData) => void` | \- | 注册一个回调函数，当用户请求关闭操作时将调用该函数。 |
| `onError` | `callback`： `(result: HostEventData) => void` | \- | 注册一个回调，当事务因客户端抛出错误而失败时将调用该回调。请注意，这并不包括PSP端的错误，因为这些错误将在常规流程中处理并作为事务结果返回。发送的事件将包含有关错误的信息。 |
| `on` | `newListeners`： `Partial<HostGlobalListeners>` | \- | 一种用一个方法注册多个侦听器的方法。不删除现有侦听器，但替换指定的侦听器（如果存在）。 |
| `css` | `css` (可选): `string` | \- | 将给定的CSS样式全局应用于iframe。如果不带参数调用，则清除已使用此方法设置的所有样式。注意：如果多次调用，则只应用最后一组样式。 |
| `cssVars` | `vars`： `TNGCssVars` | \- | 将给定的CSS变量全局应用到iframe。如果多次调用，则只应用最后一组变量。 |
| `icons` | `iconSets`： `IconSet[]`， `aliases` (可选): `Dictionary<string[]>` | \- | 注册图标集和可选的别名。名称与收银台视图中出现的名称匹配的图标将取代默认图标。 |
| `stylesheets` | `stylesheets`： `StylesheetParams[]` | \- | 这里提供的样式表将被加载，以便在收银iframe中使用。 |

### 主题

收银员允许通过提供自定义CSS样式和CSS变量来进行主题化。

覆盖CSS的能力是无限的(通过 `css` 方法)，但建议您尝试使用 `cssVars` 方法获取最需要的覆盖。 这种方法允许设置CSS变量，改变全局调色板和字体，以及覆盖调色板之外的特定元素的颜色。

以下是一个示例，供参考 `TNGCssVars` 对象，该对象设置当前所有可能的变量。所有字段都是可选的，所有值都是CSS值。 对于按钮覆盖， `color` 是语义按钮的颜色和 `contrast` 当该颜色用作填充背景时，用于文本/图标。

```json
{
  "color": {
    "primary": {
      "default": "#f00",
      "light": "#222",
      "dark": "#444",
      "contrast": "#fff"
    },
    "danger": {
      "default": "#ff8c00",
      "light": "#ffa500",
      "dark": "#ff4500",
      "contrast": "#fff"
    },
    "success": {
      "default": "#0000ff",
      "light": "#add8e6",
      "dark": "#00008b",
      "contrast": "#fff"
    },
    "warning": {
      "default": "#ee82ee",
      "light": "#dda0dd",
      "dark": "#9400d3",
      "contrast": "#000"
    },
    "text": {
      "default": "#000",
      "light": "#222",
      "dark": "#444",
      "diffused": "#dadada"
    },
    "background": {
      "default": "#e0ffff",
      "light": "#fff",
      "dark": "#87cefa",
      "diffused": "#dadada"
    },
    "border": {
      "default": "#000",
      "light": "#222",
      "dark": "#444",
      "diffused": "#dadada"
    }
  },
  "font": {
    "base": "arial sans-serif",
    "secondary": "roboto sans-serif",
    "size": {
      "base": "16px",
      "2xs": "10px",
      "xs": "12px",
      "s": "14px",
      "m": "16px",
      "l": "18px",
      "xl": "20px",
      "2xl": "24px",
      "3xl": "32px",
      "4xl": "48px",
      "5xl": "64px"
    },
    "weight": {
      "light": "300",
      "normal": "400",
      "semiBold": "600",
      "bold": "700"
    }
  },
  "override": {
    "field": {
      "label": {
        "color": "darkblue",
        "size": "10px",
        "weight": "900"
      },
      "content": {
        "color": "red",
        "size": "20px",
        "weight": "700"
      },
      "placeholder": {
        "color": "orange"
      },
      "background": {
        "base": "yellow",
        "hover": "lightyellow",
        "active": "orange"
      },
      "validation": {
        "color": "magenta",
        "size": "15px",
        "weight": "100"
      },
      "icon": {
        "color": "darkgreen"
      }
    },
    "button": {
      "primary": {
        "color": "blue",
        "contrast": "yellow",
        "opacity": "1",
        "disabled": {
          "color": "lightgray",
          "contrast": "gray",
          "opacity": "0.5"
        },
        "focus": {
          "color": "darkblue",
          "contrast": "darkred",
          "opacity": "0.9"
        },
        "hover": {
          "color": "lightblue",
          "contrast": "orange",
          "opacity": "0.7"
        }
      }
    },
    "table": {
      "text": {
        "color": "red",
        "size": "30px",
        "weight": "900"
      },
      "border": {
        "color": "darkorange"
      },
      "background": {
        "even": "lightyellow",
        "odd": "lightgreen"
      }
    },
    "scrollbar": {
      "size": "10px",
      "thumb": {
        "color": {
          "base": "blue",
          "hover": "lightblue",
          "active": "darkblue"
        }
      },
      "track": {
        "color": {
          "base": "yellow",
          "hover": "orange",
          "active": "red"
        }
      }
    },
    "step": {
      "method": {
        "tile": {
          "width": "400px"
        }
      }
    }
  }
}
```

## 常见问题

### @thenextgateway/cashier\.sdk 是什么？

浏览器SDK，用于嵌入和与TNG出纳通信。

### 如何安装 @thenextgateway/cashier\.sdk？

在项目目录运行 npm install @thenextgateway/cashier\.sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@thenextgateway/core（2\.1\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @thenextgateway/cashier\.sdk 支持 TypeScript 吗？

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

### @thenextgateway/cashier\.sdk 支持 ESM 还是 CommonJS？

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

### @thenextgateway/cashier\.sdk 可以商用吗？

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

### @thenextgateway/cashier\.sdk 还在维护吗？

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