# @basis-theory/web-elements 中文文档

规范地址：https://npmcn.com/package/%40basis-theory/web-elements/

版本：3\.5\.0
npm 元数据更新时间：2026-11-04T18:48:30.840Z
中文译文更新时间：2026-11-07T18:00:08.168Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.2 MB，19 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-01-23T17:56:09.422Z
- 最新版本发布：2026-11-04T18:48:30.643Z
- 近 30 天下载量：360824（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：98（近 12 个月 34 个）

## 中文简介

用于创建支付输入表的安全、符合PCI的元素

## 安装

```sh
npm install @basis-theory/web-elements
```

也可以使用：`pnpm add @basis-theory/web-elements`、`yarn add @basis-theory/web-elements`、`bun add @basis-theory/web-elements`

## README

# @basis-theory/web-要素

安全、符合PCI的iframe元素,用于在网络应用程序中收集敏感数据。 卡片数据从不触及您的服务器.

## 安装

### 无

```bash
npm install @basis-theory/web-elements@beta
```

### 线条

```bash
yarn add @basis-theory/web-elements@beta
```

### 光盘N

```html
<script src="https://js.basistheory.com/3.0.0-beta.2/web-elements/basis-theory.js"></script>
```

## 快速启动

```typescript
import BasisTheory from '@basis-theory/web-elements';

// Initialize (synchronous -- returns immediately)
const bt = BasisTheory('pk_test_...');

// Create elements
const cardNumberEl = bt.createElement('cardNumber', {
  placeholder: '4242 4242 4242 4242',
});
const expiryEl = bt.createElement('expiry', {
  placeholder: 'MM/YY',
});
const cvvEl = bt.createElement('cvv', {
  placeholder: '123',
});

// Mount to DOM (async -- creates secure iframes)
await Promise.all([
  cardNumberEl.mount('#card-number'),
  expiryEl.mount('#expiry'),
  cvvEl.mount('#cvv'),
]);

// Listen for validation changes
cardNumberEl.on('change', (event) => {
  console.log('Valid:', event.detail.isValid);
  console.log('Brand:', event.detail.cardBrand);
});

// Tokenize on form submission
const token = await bt.tokens.create({
  type: 'card',
  data: {
    number: cardNumberEl,
    expiration_month: expiryEl,
    expiration_year: expiryEl,
    cvc: cvvEl,
  },
});

console.log('Token ID:', token.id);
```

### CDN 使用量

```html
<script src="https://js.basistheory.com/3.0.0-beta.2/web-elements/basis-theory.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', async () => {
    const bt = BasisTheory('pk_test_...');

    const cardNumberEl = bt.createElement('cardNumber');
    const expiryEl = bt.createElement('expiry');
    const cvvEl = bt.createElement('cvv');

    await Promise.all([
      cardNumberEl.mount('#card-number'),
      expiryEl.mount('#expiry'),
      cvvEl.mount('#cvv'),
    ]);
  });
</script>
```

## 元素类型

| 类型 | `createElement` 键 | 说明 |
| --- | --- | --- |
| 卡片号码 | `'cardNumber'` | PAN 输入与 Luhn 验证和品牌检测 |
| 过期 | `'expiry'` | MM/YY 过期日输入 |
| 简历 | `'cvv'` | 卡片校验码输入 |
| 文本 | `'text'` | 通用安全文本输入(SSN,路由号等) |

### 共享选项

所有元素类型在 `createElement()` 财务报告和审定财务报表 `element.update()`数字 :

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `placeholder` | `string` | \- 说吧 | 输入为空时显示的占位符文字 |
| `ariaLabel` | `string` | 特定要素 | 屏幕阅读器的 ARIA 标签 |
| `disabled` | `boolean` | `false` | 禁用输入 |
| `readOnly` | `boolean` | `false` | 使输入只读 |

### 文本元素选项

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `validation` | `RegExp` | 模式值必须匹配才能有效 |
| `required` | `boolean` | 是否需要字段 |
| `maxLength` | `number` | 最大字符长度 |
| `password` | `boolean` | 作为密码字段的渲染器 |
| `inputMode` | `string` | 移动键盘提示( M)`'numeric'`, (中文(简体) ), `'tel'`页:1 |
| `mask` | `(RegExp | string)[]` | 字符逐字符输入掩码 |
| `transform` | `[RegExp, string]` | 符号化前应用的转换 |

### CVV 元素选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `showToggle` | `boolean` | `false` | 将显示/ 隐藏切换到字段内的按钮 |
| `conceal` | `boolean` | `true` | 隐藏 CVV 值。 设定为 `false` 以显出 `element.update()` |

## 方法

每个元素都暴露出相同的界面:

| 方法 | 签署 | 说明 |
| --- | --- | --- |
| `mount` | `(selector: string | HTMLElement) => Promise<void>` | 将框架附加到 DOM |
| `unmount` | `() => void` | 从 DOM 中删除框架 |
| `update` | `(options) => Promise<void>` | 更新挂载元素的选项 |
| `focus` | `() => void` | 重点输入 |
| `blur` | `() => void` | 模糊输入 |
| `clear` | `() => void` | 清除当前值 |
| `on` | `(event, listener) => () => void` | 订阅事件; 返回未订阅的函数 |

属性 : `id` (弦声), `type` (ElementType), (英语), `mounted` (boolean) (布尔语).

## 活动

| 活动 | 当火 |
| --- | --- |
| `ready` | 元素 iframe 已装入并交互 |
| `change` | 输入值变化 |
| `focus` | 元素获得焦点 |
| `blur` | 元素失去焦点 |
| `error` | 发生基础设施或 API 错误 |

### 更改事件有效载荷

所有要素都包括下列领域: `event.detail`数字 :

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `isValid` | `boolean` | 输入通过所有验证规则 |
| `isEmpty` | `boolean` | 输入为空 |
| `error` | `ValidationError | null` | 校验错误,或 `null` 如果有效的话 |
| `elementType` | `string` | 点火事件的元素类型 |
| `elementId` | `string` | 唯一元素 ID |
| `timestamp` | `number` | 无九时间戳( ms) |

这个 `cardNumber` 元素添加: `cardBrand`, (中文(简体) ), `last4`, (中文(简体) ), `bin`, (中文(简体) ), `cvvLengths`, (中文(简体) ), `potentialBrands`,以及 `matchStrength`。 。 。 .

```typescript
cardNumberEl.on('change', (event) => {
  const { isValid, cardBrand, last4 } = event.detail;
  console.log(`${cardBrand} ...${last4}`, isValid);
});
```

### 错误事件代码

| 代码 | 说明 |
| --- | --- |
| `MOUNT_ERROR` | 挂载元素 iframe 失败 |
| `POSTMESSAGE_TIMEOUT` | 播放后超时 |
| `IFRAME_LOAD_ERROR` | 元素 iframe 无法装入 |
| `INITIALIZATION_ERROR` | SDK 或协调器未初始化 |
| `API_ERROR` | 依据 理论 API 返回出错 |
| `NETWORK_ERROR` | 网络请求失败 |
| `VALIDATION_ERROR` | 输入失败的客户端验证 |
| `INVALID_CONFIGURATION` | 无效的 SDK 或元素选项 |
| `UNKNOWN_ERROR` | 意外错误 |

## SDK 选项

```typescript
const bt = BasisTheory('pk_test_...', {
  debug: false,            // Enable verbose debug logging
  themeMode: 'auto',       // 'light' | 'dark' | 'auto'
  theme: { /* ThemeTokens */ },
  darkTheme: { /* ThemeTokens */ },
  timeoutMs: 30000,        // PostMessage timeout (ms)
});
```

## 服务

### 符号

```typescript
// Create a token
const token = await bt.tokens.create({
  type: 'card',
  data: {
    number: cardNumberEl,
    expiration_month: expiryEl,
    expiration_year: expiryEl,
    cvc: cvvEl,
  },
});

// Retrieve a token
const retrieved = await bt.tokens.retrieve(token.id, {
  apiKey: sessionApiKey, // from an authorized session
});

// Update a token
await bt.tokens.update(token.id, {
  metadata: { source: 'updated' },
});

// Encrypt with client-side JWE
const encrypted = await bt.tokens.encrypt(
  { type: 'card', data: { number: cardNumberEl, cvc: cvvEl } },
  publicKeyPEM,
  'key-id-123'
);
```

### 符号化

```typescript
const result = await bt.tokenize({
  number: cardNumberEl,
  cvv: cvvEl,
  expiry: expiryEl,
});
```

### 符号意向

```typescript
const intent = await bt.tokenIntents.create({
  type: 'card',
  data: {
    number: cardNumberEl,
    expiration_month: expiryEl,
    expiration_year: expiryEl,
    cvc: cvvEl,
  },
});

const retrieved = await bt.tokenIntents.get(intent.id);
```

### 会议

```typescript
const session = await bt.sessions.create();
// Send session.nonce to your backend to authorize
// Backend returns an apiKey for elevated access

const token = await bt.tokens.retrieve(tokenId, {
  apiKey: sessionApiKey,
});
```

## 他们

初始化时通过设计符和运行时切换模式 :

```typescript
const bt = BasisTheory('pk_test_...', {
  themeMode: 'auto',
  theme: {
    colors: {
      primary: '#007bff',
      error: '#dc3545',
      success: '#28a745',
      text: { primary: '#1a1a1a', placeholder: '#6c757d' },
      background: { default: '#ffffff' },
      border: { default: '#dee2e6', focus: '#007bff' },
    },
    typography: {
      fontFamily: 'Inter, sans-serif',
      fontSize: { base: '16px' },
      fontWeight: { normal: '400' },
    },
    spacing: { sm: '8px', md: '12px', lg: '16px' },
    borders: {
      radius: { base: '6px' },
      width: { base: '1px' },
    },
  },
});

// Switch theme mode at runtime
await bt.updateThemeMode('dark');
```

## 类型脚本

货包船的完整类型定义. 主要出口:

```typescript
import type {
  BasisTheorySDK,
  Element,
  ElementType,
  ElementOptions,
  SDKOptions,
  ChangeEventDetail,
  CardNumberChangeEventDetail,
  ReadyEventDetail,
  ErrorEventDetail,
  ErrorCode,
  ValidationError,
  TokenizeResult,
  Session,
} from '@basis-theory/web-elements';
```

## 文档

完整文档: [https://developers.basistheory.com/docs/sdks/web/web-elements/ 页面存档备份,存于互联网档案馆](https://developers.basistheory.com/docs/sdks/web/web-elements/)

-   [开始](https://developers.basistheory.com/docs/sdks/web/web-elements/v3/getting-started)
-   [元素类型](https://developers.basistheory.com/docs/sdks/web/web-elements/v3/components)
-   [活动](https://developers.basistheory.com/docs/sdks/web/web-elements/v3/events)
-   [服务](https://developers.basistheory.com/docs/sdks/web/web-elements/v3/services)
-   [他们](https://developers.basistheory.com/docs/sdks/web/web-elements/v3/theming)
-   [迁移指南(v2到v3)](https://developers.basistheory.com/docs/sdks/web/web-elements/v3/migration)

## 许可证

阿帕奇 - 2.0

## 常见问题

### @basis-theory/web-elements 是什么？

用于创建支付输入表的安全、符合PCI的元素

### 如何安装 @basis-theory/web-elements？

在项目目录运行 npm install @basis-theory/web-elements，或使用 pnpm add / yarn add / bun add。

### @basis-theory/web-elements 支持 TypeScript 吗？

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

### @basis-theory/web-elements 支持 ESM 还是 CommonJS？

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

### @basis-theory/web-elements 可以商用吗？

@basis-theory/web-elements 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @basis-theory/web-elements 的下载量有多少？

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

### @basis-theory/web-elements 还在维护吗？

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