# @evervault/react 中文文档

规范地址：https://npmcn.com/package/%40evervault/react/

版本：2\.34\.0
npm 元数据更新时间：2026-10-29T13:36:21.985Z
中文译文更新时间：2026-11-14T01:35:55.268Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：3.3 MB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18\.0\.0
- 首次发布：2020-02-20T14:42:03.417Z
- 最新版本发布：2026-10-29T13:36:21.319Z
- 近 30 天下载量：247316（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：78（近 12 个月 15 个）

## 中文简介

Evervault SDK 反应包

## 安装

```sh
npm install @evervault/react
```

也可以使用：`pnpm add @evervault/react`、`yarn add @evervault/react`、`bun add @evervault/react`

## README

[![Evervault](https://evervault.com/evervault.svg)](https://evervault.com/)

# Evervault 反应.js SDK

这个 [Evervault (英语)](https://evervault.com/) React.js SDK是用于加密客户端数据的工具包. 使用 Evervault React.js SDK 意味着您的客户数据永远不会不加密他们的设备.

## 开始

在开始Evervault React SDK之前,您需要 [创建账户](https://app.evervault.com/register) 和一个团队.

## 文档

见"埃弗沃" [React.js SDK 文档](https://docs.evervault.com/sdks/reactjs)。 。 。 .

## 安装

我们的反应.js SDK通过 [无](https://www.npmjs.com/),并可以使用您的首选软件包管理器安装.

```bash
# Using npm
npm install @evervault/react

# Using yarn
yarn add @evervault/react
```

## 初始化 SDK

安装后, 将 React.js SDK 初始化, 使用您的团队和 App ID 在 [Evervault 板盘](https://app.evervault.com/)。 。 。 .

使用 `<EvervaultProvider>` 作为您的应用程序的提供者.

```jsx
import { EvervaultProvider } from "@evervault/react";
import ChildComponent from "../ChildComponent";
export default function App() {
  return (
    <EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
      <ChildComponent />
    </EvervaultProvider>
  );
}
```

## 加密字符串

一旦你添加 `<EvervaultProvider>`,可以使用 `useEvervault()` 钩住它的孩子。 这个 `useEvervault()` 钩子返回初始化实例 [Java 脚本 SDK](https://docs.evervault.com/sdks/javascript-sdk),包括 `encrypt()` 函数.

```jsx
import { useState } from "react";
import { useEvervault } from "@evervault/react";

export default function ChildComponent() {
  const evervault = useEvervault();
  const [message, setMessage] = useState("");

  const handleSubmit = async (e) => {
    e.preventDefault();
    const encryptedMessage = await evervault.encrypt(message);
    alert(encryptedMessage);
  };

  return (
    <form onSubmit={handleSubmit}>
      <input value={message} onChange={(e) => setMessage(e.target.value)} />
      <button>Submit</button>
    </form>
  );
}
```

* * *

# 参考文献

## `<EvervaultProvider />`

这个 `EvervaultProvider` 组件曝光 `useEvervault()` 钩入任何嵌入式组件.

```jsx
<EvervaultProvider teamId="<TEAM_ID>" appId="<APP_ID>">
  <App />
</EvervaultProvider>
```

### 道具

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `teamId` | 字符串 | 您团队的独有标识 。 在团队设置中发现. |
| `appId` | 字符串 | 您的 App 独有的标识符, 可见于 App 设置 . |

* * *

## `useEvervault()`

这个 `useEvervault` 儿童可以使用钩子 `EvervaultProvider`,并返回已初始化的 Evervault 实例 [Java 脚本 SDK](https://docs.evervault.com/sdks/javascript-sdk)。返回对象所包含的功能之一是 `encrypt()`,它可以传递任何纯文本数据结构.

```jsx
const evervault = useEvervault();
```

* * *

### `evervault.encrypt(data)`

使用 [Evervault 加密](https://docs.evervault.com/security/evervault-encryption)Evervault Strings可以用于我们所有的产品。 可在返回的值上访问 `useEvervault()` 钩. 要使用React.js SDK加密数据,只需通过一个 `String` 或一个 `Object` 输入 `evervault.encrypt()` 函数.

加密数据可以传递到您的服务器,并正常存储在数据库中. Evervault的其他服务也可以使用.

```jsx
const evervault = useEvervault();

const encrypted = await evervault.encrypt("Hello, world!");
```

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| 数据 | `Object`, (中文(简体) ), `Array`, (中文(简体) ), `String`, (中文(简体) ), `Number`, (中文(简体) ), `File` 或者说 `Blob` | 数据要加密 . |

* * *

## `<EvervaultInput />`

使用 [Evervault 输入](https://docs.evervault.com/products/inputs) 安全收集加密的持卡人数据。 Evervault Introductions服务于从Evervault的PCI兼容基础设施直接取回的iFrame,这可以将您的PCIDS兼容范围降低到最简单的形式(SAQ A).

Evervault 输入也支持 [主题](https://docs.evervault.com/products/inputs/#themes) 和自定义样式,这样您就可以自定义输入在您的用户界面中的样子.

### 道具

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `onChange` | 函数 | 当提交文件更改时,该函数被调用. |
| `onInputsLoad` | 函数 | 当服务输入的 iFrame 装入时调用函数 . |
| `config` | 字符串 QQ 对象 | 主题字符串(支持:默认,最小或材质),或自定义样式的配置对象. |
| `config.theme` | 字符串 | 输入的基础样式 。 目前支持默认,最小和物质. |
| `config.height` | 字符串 | Evervault 输入框的高度 . |
| `config.primaryColor` | 字符串 | 主题颜色. |
| `config.labelColor` | 字符串 | 用于输入标签的颜色 CSS 属性 . |
| `config.inputBorderColor` | 字符串 | 用于输入的边框颜色 CSS 属性 . |
| `config.inputTextColor` | 字符串 | 用于输入的颜色 CSS 属性 . |
| `config.inputBackgroundColor` | 字符串 | 彩色 CSS 属性适用于 \*pose CSS 假元素,用于输入. |
| `config.inputBorderRadius` | 字符串 | 边界辐射CSS财产用于输入. |
| `config.inputHeight` | 字符串 | 用于输入的高度 CSS 属性 . |
| `config.cardNumberLabel` | 字符串 | 输入卡号的标签 |
| `config.expirationDateLabel` | 字符串 | 过期日期输入的标签 |
| `config.securityCodeLabel` | 字符串 | 安全代码输入的标签 |
| `config.expirationDatePlaceholder` | 字符串 | 过期日期输入的占位符 |
| `config.invalidCardNumberLabel` | 字符串 | 无效卡号上显示的消息 |
| `config.invalidExpirationDateLabel` | 字符串 | 无效过期日显示的消息 |
| `config.invalidSecurityCodeLabel` | 字符串 | 在无效的安全代码上显示的消息 |
| `config.fontUrl` | 字符串 | 用 Google 字体 API 装入自定义字体 |
| `config.fontFamily` | 字符串 | 设置字体的字体家族 Url |
| `config.inputFontSize` | 字符串 | 设置输入属性的字体大小属性 |
| `config.inputBoxShadow` | 字符串 | 设置输入属性的框阴影属性 |
| `config.labelFontSize` | 字符串 | 设置标签属性的字体大小属性 |
| `config.labelWeight` | 字符串 | 设置标签属性的字体加权属性 |
| `config.disableCVV` | 布尔 | 从输入中删除 CVV 字段, 只显示卡数和过期字段 |
| `config.disableExpiry` | 布尔 | 从输入中删除过期字段, 只显示卡数和 CVV 字段 |

### 获取卡片数据

要访问加密的卡片数据,必须经过 `onChange` 处理者。 此功能在卡片数据更新后随即被调用,并通过一个带有加密卡片细节以及验证信息的对象.

```jsx
function Payment() {
  const handleChange = ({ encryptedCard, isValid }) => {
    if (isValid) {
      console.log(encryptedCard);
    }
  };

  return <EvervaultInput onChange={handleChange} />;
}
```

#### 更改召回参数

在Change回调时,将传递以下对象作为参数.

```js
{
  "encryptedCard": {
    "type": "visa_credit",
    "number": "ev:encrypted:abc123",
    "cvc": "ev:encrypted:def456",
    "expMonth": "01",
    "expYear": "23"
    "lastFour": "1234"
  },
  "isValid": true,
  "isPotentiallyValid": true,
  "isEmpty": false,
  "error": {
    "type": "invalid_pan",
    "message": "The credit card number you entered was invalid"
  }
}
```

### 本地化

IFrame 可以在初始化时通过提供一组标签进行本地化 [配置](https://docs.evervault.com/sdks/reactjs#input-props-config)。 。 。 .

```jsx
const config = {
  cardNumberLabel: 'Numéro de carte:',
  expirationDateLabel: 'Date d'expiration:',
  securityCodeLabel: 'Code de sécurité:'
}

<EvervaultInput onChange={handleChange} config={config} />
```

### 自定义字体

自定义字体可以从 Google 下载 [字体 API](https://fonts.google.com/) 编辑 `font-family` 设定与 `fontFamily` 配置参数

```jsx
const config = {
  fontUrl: 'https://fonts.googleapis.com/css2?family=Poppins:wght@100;800&display=swap',
  fontFamily: 'Poppins, sans-serif',
  inputFontSize: '20px',
  inputBoxShadow: '2px 2px 2px 1px rgba(0, 0, 255, .2)',
  labelFontSize: '13px',
  labelWeight: '400'
}

<EvervaultInput onChange={handleChange} config={config} />
```

### iFrame 装入状态

如果您需要等待服务输入器的 iFrame 来加载, 才能进行一些动作, 您可以使用 `onInputsLoad` 道具召回 :

```jsx
<EvervaultInput
  onInputsLoad={() => {
    console.log("Inputs has loaded!");
  }}
/>
```

## `<Card />`

**默认.** 即时出山出会.

```jsx
<Card />
```

**与 `preload`。 。 。 .** 把卡藏起来 然后打电话 `show()` 何时通过裁判 用户到达支付步骤。 牌坐后退步时有用.

```jsx
const cardRef = useRef(null);

<Card ref={cardRef} preload />;

// Later.
cardRef.current?.show();
```

## `<EvervaultReveal />`

使用 [埃弗沃尔启示录](https://docs.evervault.com/products/inputs#reveal) 显示加密卡 详细信息,在安全的 iFrame 中以纯文本显示用户的加密卡片细节 埃弗沃尔. 在使用"启示录"之前,首先需要创建回放来解密卡片细节; Reveal 期望从中继器接收出作为 JSON 对象的卡片数据,其方案如下.

说明: 您创建的终点必须设置适用的 CORS 信头, 以便 可以从输入 iFrame 访问。 否则你的要求就会失败!

```json
{
  "cardNumber": "string | number",
  "cvv": "string | number",
  "expiry": "string | number"
}
```

一旦你找到返回加密卡片数据的终点,你将需要创建一个 [Evervault 输入中继器](https://docs.evervault.com/products/inbound-relay) 这将解密 加密的卡片数据通过它,在它到达iFrame之前. 一旦你创造了 您可以将组件添加到您的 React app 中.

```jsx
export default function Reveal() {
  const request = {
    url: "https://example-com.relay.evervault.com",
    method: "GET",
    headers: {
      Authorization: "Bearer ey...",
    },
  };

  return (
    <main>
      <EvervaultReveal request={request}></EvervaultReveal>
    </main>
  );
}
```

唯一需要的领域是 `request` 中选择一个支持所有相同字段的对象 [Javascript 请求对象](https://developer.mozilla.org/en-US/docs/Web/API/Request)。URL必须是 Evervault 输入 重播您先前配置的 .

### 道具

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `onRevealLoad` | 函数 | 当服务于Revaal 的 iFrame 装入时,该函数被称为函数 . |
| `onRevealError` | 函数( 错误) | 当服务于Reveal错误的iFrame时,它被称为以错误为第一个参数的函数. |
| `onCopy` | 函数 | 当用户在 Reveal 组件内单击复制按钮时调用函数 . |
| `config` | 字符串 QQ 对象 | 主题字符串(支持:默认,最小或材质),或自定义样式的配置对象. |
| `config.height` | 字符串 | Evervault 输入框的高度 . |
| `config.fontUrl` | 字符串 | 用 Google 字体 API 装入自定义字体 |
| `config.fontFamily` | 字符串 | 设置字体的字体家族 Url |
| `config.revealFontSize` | 字符串 | 设置显示文本字段的字体大小属性 |
| `config.revealFontWeight` | 字符串 | 设置显示文本字段的字体加权属性 |
| `config.revealTextColor` | 字符串 | 设置显示文本字段的字体颜色属性 |

## 捐款

GitHub 上欢迎错误报告和拉取请求 [https://github.com/evervault/evervault-resact. (原始内容存档于2018-09-29)](https://github.com/evervault/evervault-react)。 。 。 .

## 反馈

问题还是反馈? [告诉我们](mailto:support@evervault.com)。 。 。 .

## 常见问题

### @evervault/react 是什么？

Evervault SDK 反应包

### 如何安装 @evervault/react？

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

### @evervault/react 支持 TypeScript 吗？

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

### @evervault/react 支持 ESM 还是 CommonJS？

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

### @evervault/react 可以商用吗？

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

### @evervault/react 的下载量有多少？

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

### @evervault/react 还在维护吗？

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