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

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

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

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

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

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

- 包体积（解压后）：336 kB，92 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^16\.8\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^16\.8\.0 \|\| ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2025-02-19T17:57:45.990Z
- 最新版本发布：2026-11-04T18:48:35.034Z
- 近 30 天下载量：308555（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：81（近 12 个月 34 个）

## 中文简介

基础理论元素的反射组件 v3

## 安装

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

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

## README

# @ basis-理论/反应要素

与 Basid Theory Elements v3 反应用于收集敏感数据的组件. 安全 PCI 兼容 iframes 包裹为 React 组件 有钩子, refs,以及打出的事件处理器.

## 安装

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

`@basis-theory/web-elements` 是一个依赖,将自动安装.

反应16.8+,17,18,19得到支持.

## 快速启动

```tsx
import { useState, useRef } from 'react';
import {
  BasisTheoryProvider,
  CardNumberElement,
  ExpiryElement,
  CVVElement,
  useBasisTheory,
} from '@basis-theory/react-elements';

function PaymentForm() {
  const { bt, error } = useBasisTheory();
  const cardNumberRef = useRef(null);
  const expiryRef = useRef(null);
  const cvvRef = useRef(null);

  const [cardNumberValid, setCardNumberValid] = useState(false);
  const [expiryValid, setExpiryValid] = useState(false);
  const [cvvValid, setCvvValid] = useState(false);

  const allValid = cardNumberValid && expiryValid && cvvValid;

  if (error) return <div>Failed to load payment form.</div>;

  const handleSubmit = async (e) => {
    e.preventDefault();

    const token = await bt.tokens.create({
      type: 'card',
      data: {
        number: cardNumberRef.current,
        expiration_month: expiryRef.current,
        expiration_year: expiryRef.current,
        cvc: cvvRef.current,
      },
    });

    // Send token.id to your backend
    console.log('Token created:', token.id);
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardNumberElement
        ref={cardNumberRef}
        placeholder="4242 4242 4242 4242"
        onChange={(event) => setCardNumberValid(event.detail.isValid)}
      />
      <ExpiryElement
        ref={expiryRef}
        placeholder="MM/YY"
        onChange={(event) => setExpiryValid(event.detail.isValid)}
      />
      <CVVElement
        ref={cvvRef}
        placeholder="123"
        onChange={(event) => setCvvValid(event.detail.isValid)}
      />
      <button type="submit" disabled={!allValid}>Pay</button>
    </form>
  );
}

export default function App() {
  return (
    <BasisTheoryProvider apiKey="pk_test_...">
      <PaymentForm />
    </BasisTheoryProvider>
  );
}
```

## 构成部分

### 基础理论

初始化SDK,并通过React Context提供给子组件. 所有组件和 `useBasisTheory` 钩子必须是这个提供者的后代.

```tsx
<BasisTheoryProvider
  apiKey="pk_test_..."
  options={{
    debug: true,
    themeMode: 'auto',
    theme: { /* ThemeTokens */ },
  }}
  errorFallback={<div>Something went wrong.</div>}
>
  {children}
</BasisTheoryProvider>
```

| Prop | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `apiKey` | `string` | 对 | 公共 API 密钥( 启动于 `pk_`(中文(简体) ) |
| `options` | `SDKOptions` | 没有 | SDK 配置( 调试、 主题等) |
| `children` | `ReactNode` | 对 | 儿童成分 |
| `errorFallback` | `ReactNode` | 没有 | 如果初始化失败, 则倒置 UI |

### 卡片编号元素

有Luhn验证和品牌检测的安全卡号输入.

```tsx
<CardNumberElement
  ref={cardNumberRef}
  placeholder="4242 4242 4242 4242"
  ariaLabel="Card number"
  disabled={false}
  readOnly={false}
  onChange={(event) => console.log(event.detail.isValid)}
  onReady={(event) => console.log('Ready')}
  onFocus={(event) => console.log('Focused')}
  onBlur={(event) => console.log('Blurred')}
  onError={(event) => console.error(event.detail.code)}
  className="my-card-input"
  containerStyle={{ border: '1px solid #ccc' }}
/>
```

### 过期

安全过期日输入(MM/YY格式).

```tsx
<ExpiryElement
  ref={expiryRef}
  placeholder="MM/YY"
  onChange={(event) => console.log(event.detail.isValid)}
/>
```

### 简历

安全CVV/CVC输入. 当一个 `CardNumberElement` 在同一页(Visa/Mastercard3个数字,Amex4个数字).

```tsx
<CVVElement
  ref={cvvRef}
  placeholder="123"
  onChange={(event) => console.log(event.detail.isValid)}
/>
```

### 文本元素

任何敏感值(SSN,账号等)的通用安全文本输入.

```tsx
<TextElement
  ref={textRef}
  placeholder="###-##-####"
  mask={[/\d/, /\d/, /\d/, '-', /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/]}
  transform={[/-/g, '']}
  validation={/^\d{9}$/}
  password={false}
  inputMode="numeric"
  required={true}
  maxLength={11}
  onChange={(event) => console.log(event.detail.isValid)}
/>
```

### 纸牌元素

将卡号,过期,CVV合并成一元的统一卡元.

```tsx
<CardElement
  ref={cardRef}
  placeholder={{
    cardNumber: '4242 4242 4242 4242',
    expiryDate: 'MM/YY',
    cvc: '123',
  }}
  layout="auto"
  stackAt={400}
  iconPosition="right"
  onChange={(event) => console.log(event.detail.isValid)}
/>
```

### 共享元素道具

所有元素组件接受:

| Prop | 类型 | 说明 |
| --- | --- | --- |
| `placeholder` | `string` | 占位符文本 |
| `disabled` | `boolean` | 禁用输入 |
| `readOnly` | `boolean` | 输入只读 |
| `ariaLabel` | `string` | ARIA 无障碍标签 |
| `onReady` | `(event) => void` | 当元素是交互式时被发射 |
| `onChange` | `(event) => void` | 当值变化时被解除 |
| `onFocus` | `(event) => void` | 当要素得到重点时解除 |
| `onBlur` | `(event) => void` | 当元素失去焦点时发射 |
| `onError` | `(event) => void` | 以基础设施或 API 错误开火 |
| `className` | `string` | 容器分解的 CSS 类 |
| `containerStyle` | `CSSProperties` | 容器内嵌样式 |

## 钩子

### 使用基准理论

从下方的任何组件访问 SDK 实例 `BasisTheoryProvider`。 。 。 .

```tsx
import { useBasisTheory } from '@basis-theory/react-elements';

function MyComponent() {
  const { bt, error } = useBasisTheory();

  if (error) return <div>SDK failed to initialize.</div>;
  if (!bt) return <div>Loading...</div>;

  const handleTokenize = async () => {
    const token = await bt.tokens.create({
      type: 'card',
      data: { number: cardNumberRef.current },
    });
  };
}
```

回返 `{ bt: BasisTheorySDK | null, error: Error | null }`。 。 。 .

## 查找方法

所有元素校正都暴露出这些方法和属性:

| 方法/ 属性 | 类型 | 说明 |
| --- | --- | --- |
| `mount` | `(selector) => Promise<void>` | 挂载元素( 自动处理) |
| `unmount` | `() => void` | 删除元素 |
| `update` | `(options) => Promise<void>` | 更新元素选项 |
| `focus` | `() => void` | 集中投入 |
| `blur` | `() => void` | 模糊输入 |
| `clear` | `() => void` | 清除输入值 |
| `on` | `(event, listener) => () => void` | 订阅事件 |
| `complete` | `boolean` | 输入为有效且非空 |
| `empty` | `boolean` | 输入为空 |
| `valid` | `boolean` | 输入通道验证 |
| `id` | `string` | 唯一元素 ID |
| `type` | `string` | 元素类型 |
| `mounted` | `boolean` | 元素是否挂载 |

`CardNumberElementRef` 添加: `cardBrand`, (中文(简体) ), `last4`, (中文(简体) ), `bin`。 。 。 .

`CardElementRef` 添加: `cardBrand`, (中文(简体) ), `last4`, (中文(简体) ), `bin`, (中文(简体) ), `errors`, (中文(简体) ), `number`, (中文(简体) ), `expiryDate`, (中文(简体) ), `cvc`。 。 。 .

## 类型脚本

所有组件全部输入。 导入参考类型 `useRef`数字 :

```tsx
import { useRef } from 'react';
import type {
  CardNumberElementRef,
  CVVElementRef,
  ExpiryElementRef,
  TextElementRef,
  CardElementRef,
} from '@basis-theory/react-elements';

const cardNumberRef = useRef<CardNumberElementRef | null>(null);
const cvvRef = useRef<CVVElementRef | null>(null);
const expiryRef = useRef<ExpiryElementRef | null>(null);
```

事件处理器类型也可用:

```tsx
import type {
  ChangeEventDetail,
  CardNumberChangeEventDetail,
  CardElementChangeEventDetail,
  ReadyEventDetail,
  ErrorEventDetail,
  FocusEventDetail,
} from '@basis-theory/react-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/react-elements 是什么？

基础理论元素的反射组件 v3

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

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

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

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

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

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

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

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

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

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

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

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