# @brexhq/brex-js 中文文档

规范地址：https://npmcn.com/package/%40brexhq/brex-js/

版本：4\.2\.0
npm 元数据更新时间：2026-07-30T19:13:43.849Z
中文译文更新时间：2026-11-08T14:52:35.195Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40brexhq/brex-js
原文对照：https://npmcn.com/package/%40brexhq/brex-js/?lang=original
源码仓库：https://github.com/brexhq/brex-js

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

- 包体积（解压后）：51.8 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0
- 首次发布：2025-04-17T18:03:14.221Z
- 最新版本发布：2026-07-30T19:13:43.685Z
- 近 30 天下载量：11550（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 6 个）

## 中文简介

一个JavaScript SDK,用于将Brex发行的卡片元素整合到网络应用中. 这个库为显示敏感的卡片信息提供了安全而基于iframe的组件.

## 安装

```sh
npm install @brexhq/brex-js
```

也可以使用：`pnpm add @brexhq/brex-js`、`yarn add @brexhq/brex-js`、`bun add @brexhq/brex-js`

## README

# @ brexhq/ brex- js (英语)

一个JavaScript SDK,用于将Brex发行的卡片元素整合到网络应用中. 这个库为显示敏感的卡片信息提供了安全而基于iframe的组件.

## 快速启动

```javascript
import Brex from '@brexhq/brex-js';

// Initialize Brex
const brex = Brex();
const elements = brex.elements();

// Create a card number display element
const cardNumber = elements.create('issuingCardNumberDisplay', {
  issuingCard: 'your_issuing_card_id',
  ephemeralKeySecret: 'your_ephemeral_key'
});

// Mount it to a container
cardNumber.mount('#card-number-container');

// Listen for events
cardNumber.on('complete', () => {
  console.log('Card number is ready');
});
```

## 可用元素

库提供了显示卡片信息的若干要素:

-   `issuingCardNumberDisplay`: 显示牌号
-   `issuingCardCvcDisplay`: 显示 CVC/ 安全代码
-   `issuingCardExpiryDisplay`: 显示过期日期
-   `issuingCardPinDisplay`: 显示 PIN
-   `issuingCardCopyButton`: 创建复制卡片细节的按钮

## 样式元素

您可以使用支持的样式属性自定义元素的外观 :

```javascript
const element = elements.create('issuingCardNumberDisplay', {
  issuingCard: 'your_issuing_card_id',
  ephemeralKeySecret: 'your_ephemeral_key',
  style: {
    fontSize: '16px',
    fontFamily: 'Arial, sans-serif',
    color: '#333333',
    fontWeight: 'normal',
    letterSpacing: 'normal',
    lineHeight: '1.5',
    padding: '10px'
  }
});

// Update styles later
element.update({
  fontSize: '18px',
  color: '#000000'
});
```

## 复制按钮

复制按钮元素允许用户复制卡片细节:

```javascript
const copyButton = elements.create('issuingCardCopyButton', {
  issuingCard: 'your_issuing_card_id',
  ephemeralKeySecret: 'your_ephemeral_key',
  toCopy: 'number' // 'number', 'cvc', 'expiry', or 'pin'
});

copyButton.mount('#copy-button-container');
copyButton.on('copied', () => {
  console.log('Card number copied');
});
```

## 事件处理

所有要素都支持以下活动:

-   `complete`: 当元素被完全装入时起火
-   `loading`: 当元素被装入时已开火
-   `error`: 出错时已开火
-   `copied`: 内容被复制时被点燃(用于复制按钮)

```javascript
element.on('complete', () => {
  console.log('Element is ready');
});

element.on('error', () => {
  console.log('Something went wrong');
});
```

## 预装请求者 iframe( 可选)

在幕后现场, `Brex(...).elements()` 挂载隐藏的“ 请求者” 框 第一次 `create()` 名为. iframe 需要下载并解析其 在获取敏感细节之前拥有捆绑, 它可以添加~1-2秒 到用户等待卡 PAN 出现在第一视图时.

如果您的用户界面提前知道卡片视图即将到来( 例如, a) 用户刚刚导航到钱包/卡路由,您可以拨打 `prewarm()` 提前挂载请求者 iframe , 以便其靴子从用户的 关键路径 :

```javascript
import Brex from '@brexhq/brex-js';

const elements = Brex().elements();

// Some time before the user actually opens a card. Idempotent and cheap.
elements.prewarm();

// Later — when the user opens the card. The requester is already
// mounted, so this skips the iframe-boot step and goes straight to
// fetching card details.
const cardNumber = elements.create('issuingCardNumberDisplay', {
  issuingCard: 'your_issuing_card_id',
  ephemeralKeySecret: 'your_ephemeral_key',
});
cardNumber.mount('#card-number-container');
```

注释:

-   **《同上》**: 调用 `prewarm()` 多次只挂载一帧. 安全不受每个组成部分的影响.
-   **没有卡片数据发送**数字 : `prewarm()` 不取参数并发送否 `issuingCard`, (中文(简体) ), `ephemeralKeySecret`,或任何其他用户/卡标识符. 仅 `create()` 这样做.
-   **只有客户端**: 将框架附加到 `document.body`; 通话期间 SSR会投出.
-   **后无 `create()`**:如果请求者已经挂载,则随后 `prewarm()` 电话什么都不做,也不放过任何事件.

在使用仪器时(见下文),升温前释放出单个仪器 `requesterPrewarmed` 事件可以测量 iframe 需要多长时间 进入真正的用户状态.

## 仪器(可选)

Brex可以发射生命周期事件 覆盖请求者 Iframe握手 可见元素 iframes, 以及它们之间的后Message回转。 使用 这是用来测量SDK的计时 并转发到你的RUM/遥测管.

```javascript
import Brex from '@brexhq/brex-js';

const brex = Brex({
  environment: 'production',
  // Called for every lifecycle event. Keep it cheap.
  onEvent: (event) => {
    // event = { type, timestamp, key?, elementType?, issuingCard?, metadata? }
    datadogRum.addAction('brex_js_event', event);
  },
  // Optional: also mirror events to console.debug. Default false.
  debug: process.env.NODE_ENV !== 'production',
});
```

排放事件类型包括:

-   请求者 iframe : `requesterPrewarmed` (仅在 `prewarm()` 称为, `requesterCreated`, (中文(简体) ), `requesterReady`, (中文(简体) ), `requesterPortTransferred`, (中文(简体) ), `requestCardDetailsSent`, (中文(简体) ), `cardDetailsReceived`, (中文(简体) ), `cardDetailsForwarded`
-   可见元素 iframe : `elementCreated`, (中文(简体) ), `elementReady`, (中文(简体) ), `elementPortTransferred`, (中文(简体) ), `elementMounted`, (中文(简体) ), `elementUnmounted`, (中文(简体) ), `elementDestroyed`
-   错误 : `elementError`

每次活动都包含一个 `timestamp`,并在适用的情况下,iframe `key`, (中文(简体) ), `elementType`,以及消费者提供的 `issuingCard` 关系.

这个 `timestamp` 实值 `performance.timeOrigin + performance.now()` (高比率) 绝对时间戳与 `Date.now()`) (中文(简体) ). SDK使用 Iframes 软件 引擎盖下——每个机身都有自己的 `performance.timeOrigin`,那么简单 `performance.now()` 值在父窗口之间不具有可比性 还有Iframes。 添加中 `timeOrigin` 生成您可以横切的值 王国。 在同一领域,减去两个乘以的印记产生同样的效果 结果是 `performance.now()` 算术(来源取消). 见 [MDN: 在上下文之间同步时间](https://developer.mozilla.org/en-US/docs/Web/API/Performance/timeOrigin#synchronizing_time_between_contexts)。 。 。 .

**电子密钥和卡片细节无论如何都不会包含在内 载荷.**

如果没有 `onEvent` 也没有 `debug` 提供, SDK 使用不开放发射器 并且不产生运行时间费用.

## 完整示例

以下是一个完整的例子,说明如何显示所有卡片信息:

```javascript
import Brex from '@brexhq/brex-js';

const brex = Brex();
const elements = brex.elements();

// Common configuration
const config = {
  issuingCard: 'your_issuing_card_id',
  ephemeralKeySecret: 'your_ephemeral_key',
  style: {
    fontSize: '16px',
    fontFamily: 'Arial, sans-serif',
    color: '#333333'
  }
};

// Create elements
const cardNumber = elements.create('issuingCardNumberDisplay', config);
const cardCvc = elements.create('issuingCardCvcDisplay', config);
const cardExpiry = elements.create('issuingCardExpiryDisplay', config);
const cardPin = elements.create('issuingCardPinDisplay', config);

// Mount elements
cardNumber.mount('#card-number-container');
cardCvc.mount('#card-cvc-container');
cardExpiry.mount('#card-expiry-container');
cardPin.mount('#card-pin-container');

// Add copy buttons
const copyNumber = elements.create('issuingCardCopyButton', {
  ...config,
  toCopy: 'number'
});
copyNumber.mount('#copy-number-button');

// Event handling
cardNumber.on('complete', () => console.log('Card number ready'));
copyNumber.on('copied', () => console.log('Card number copied'));
```

必需的 HTML :

```html
<div id="card-number-container"></div>
<div id="copy-number-button">Copy</div>
<div id="card-cvc-container"></div>
<div id="card-expiry-container"></div>
<div id="card-pin-container"></div>
```

## 常见问题

### @brexhq/brex-js 是什么？

一个JavaScript SDK,用于将Brex发行的卡片元素整合到网络应用中\. 这个库为显示敏感的卡片信息提供了安全而基于iframe的组件\.

### 如何安装 @brexhq/brex-js？

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

### @brexhq/brex-js 支持 TypeScript 吗？

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

### @brexhq/brex-js 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @brexhq/brex-js 可以商用吗？

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

### @brexhq/brex-js 的下载量有多少？

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

### @brexhq/brex-js 还在维护吗？

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