# @gr4vy/secure-fields-react 中文文档

规范地址：https://npmcn.com/package/%40gr4vy/secure-fields-react/

版本：2\.13\.0
npm 元数据更新时间：2026-11-03T15:30:49.381Z
中文译文更新时间：2026-11-16T21:29:38.331Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：111 kB，80 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=17\.0\.0，react-dom \>=17\.0\.0
- 首次发布：2022-08-12T16:02:50.301Z
- 最新版本发布：2026-11-03T15:30:49.222Z
- 近 30 天下载量：47804（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：99（近 12 个月 33 个）

## 中文简介

Gr4vy主持安全场,提供高级主题,PCI遵守,事件处理等等.

## 安装

```sh
npm install @gr4vy/secure-fields-react
```

也可以使用：`pnpm add @gr4vy/secure-fields-react`、`yarn add @gr4vy/secure-fields-react`、`bun add @gr4vy/secure-fields-react`

## README

# 反应的安全字段

![NPM Version](https://img.shields.io/npm/v/@gr4vy/secure-fields-react?color=green) [![GitHub license](https://img.shields.io/github/license/Naereen/StrapDown.js.svg)](https://github.com/gr4vy/secure-fields/blob/main/LICENSE) [![Changelog](https://img.shields.io/badge/changelog-dimgrey?logo=npm&logoColor=white)](https://github.com/gr4vy/secure-fields/blob/main/CHANGELOG.md)

在您的 React app 中添加安全域 .

使用 [`@gr4vy/secure-fields`](https://npmcn.com/package/%40gr4vy/secure-fields) 在非反应应用程序中.

## 使用量

通过命令行,将这个软件包安装如下.

```bash
npm install @gr4vy/secure-fields-react --save-prod
# yarn add @gr4vy/secure-fields-react
```

## 开始吧

要使用安全字段,请导入 `SecureFields` 提供方组件并用它包裹您的应用程序,确保您通过必要的配置道具和任何事件处理器.

```jsx
require('@gr4vy/secure-fields-react/lib/style.css') // default styles
// import '@gr4vy/secure-fields-react/lib/style.css'

const { SecureFields } = require("@gr4vy/secure-fields-react")
// import { SecureFields } from "@gr4vy/secure-fields-react"

<SecureFields
  gr4vyId='[GR4VY_ID]'
  environment='sandbox'
  sessionId='[SESSION_ID]'
  // For stored payment methods (optional):
  // paymentMethod={{ id: '[PAYMENT_METHOD_ID]', scheme: [PAYMENT_METHOD_SCHEME] }}
  // Deprecated:
  // paymentMethodId='[PAYMENT_METHOD_ID]' // uuid of a stored payment method
  debug
  font="Lato"
  // autoAdvance={{ enabled: true, fieldOrder: ['number', 'expiryDate', 'securityCode'] }}
  onReady={(data) => console.log('Secure Fields loaded', data)}
  onCardVaultSuccess={() => console.log('Card tokenization successful')}
  onCardVaultFailure={(data) => console.error('Card tokenization failed', data)}
>
  <Form />
</SecureFields>
```

> **说明**替换 `[GR4VY_ID]` 财务报告和审定财务报表 `[SESSION_ID]` 以您本人的身份 和会话编号 [检查会话 API](https://gr4vy.com/docs/reference#tag/Checkout-Sessions)。 。 。 .

| Propa 名称 | 说明 |
| --- | --- |
| `gr4vyId` | 你的Gr4vy身份证. |
| `environment` | 你的Gr4vy环境。 也可以这样 `sandbox` 或者说 `production`。 。 。 . |
| `sessionId` | 会话ID. |
| `paymentMethod` | 可选对象 `{ id: string, scheme: string }` 用于存储支付方法. |
| `paymentMethodId` | 存储支付方法的可选uuid. **折旧**:此道具不再被推荐使用,并将在未来发布中被移除. 请使用 `paymentMethod` 换句话说. |
| `debug` | 启用/ 禁用调试模式 . |
| `font` | 装入自定义字体 [谷歌字体](https://fonts.google.com/) 用于内部输入。 您可以将字体家族以及样式或权重定义为字符串(例如"Lato:400,600"). 要使用已装入的字体,请添加正确的 `fontFamily` 属性到样式时的对象. |
| `onReady` | 一个事件处理器,可以监听安全字段的安全装入. 它会听 [`READY`](https://docs.gr4vy.com/guides/payments/secure-fields/events) 并接受回调函数. |
| `onFormChange` | 一个事件处理器,听取安全字段的变化。 它会听 [`FORM_CHANGE`](https://docs.gr4vy.com/guides/payments/secure-fields/events) 并接受回调函数. |
| `onCardVaultSuccess` | 事件处理器,可以监听卡片数据安全地被封存. 它会听 [`CARD_VAULT_SUCCESS`](https://docs.gr4vy.com/guides/payments/secure-fields/events) 并接受回调函数. |
| `onCardVaultFailure` | 一个在存储任何卡片数据时监听任何故障的事件处理器 。 它会听 [`CARD_VAULT_FAILURE`](https://docs.gr4vy.com/guides/payments/secure-fields/events) 并接受回调函数. |
| `validateOn` | 设置字段显示校验错误时 : `'blur'` (默认),一旦用户离开一个字段,或 `'submit'`,一次 `secureFields.validate()` 名为. 设定为挂载; 后期的更改被忽略 。 见 [验证](https://npmcn.com/package/%40gr4vy/secure-fields-react/#readme-validation)。 。 。 . |
| `autoAdvance` | 当当前字段的值完整且有效时,允许自动提前将焦点自动移动到下一个字段. 接受 `{ enabled: boolean, fieldOrder?: Array<FieldType> }`。见 [UX 选项](https://docs.gr4vy.com/guides/payments/secure-fields/ux-options#auto-advance) 更多细节. |

### 创建窗体

内部 `SecureFields` 您现在可以使用每个安全字段组件创建自己的卡表 .

此外,a `useSecureFields` 可用勾钩来获取配置的安全字段实例 曾经 `submit()` 牌单,并检查是否 `debug` 是否启用.

```js
const {
  CardNumber,
  ExpiryDate,
  SecurityCode,
} = require('@gr4vy/secure-fields-react')

// Alternatively:
// import {
//   CardNumber,
//   ExpiryDate,
//   SecurityCode
// } from "@gr4vy/secure-fields-react"

const Form = () => {
  const { secureFields } = useSecureFields()

  const handleSubmit = () => {
    secureFields.submit()
  }

  return (
    <>
      <label htmlFor="cc-number">Card number</label>
      <CardNumber />

      <label htmlFor="cc-expiry-date">Expiry date</label>
      <ExpiryDate />

      <label htmlFor="cc-security-code">Security code</label>
      <SecurityCode />

      <button onClick={handleSubmit}>Submit</button>
    </>
  )
}
```

您也可随卡数据一同收集其他信息. 我们目前支持增加一个邮政编码字段,可使用 `Field` 组件,通过特定 `type` 和其余的选择.

```js
const { Field } = require('@gr4vy/secure-fields-react')

<label htmlFor="postal-code">Postal code</label>
<Field
  type="postalCode"
  pattern="[A-Z][0-9]\s[0-9][A-Z]{2}" // optional, defaults to 5 characters minimum
/>
```

### 验证

打电话 `secureFields.validate()` 以同时标记每个无效字段,包括用户从未触及过的空字段,例如用户点击"Pay"时。 使用 `complete` 属性从 `onFormChange` 如果表格没有准备好,请停止提交.

```jsx
const App = () => {
  const [complete, setComplete] = useState(false)

  return (
    <SecureFields
      // ...
      validateOn="submit" // optional
      onFormChange={(data) => setComplete(data.complete)}
    >
      <Form complete={complete} />
    </SecureFields>
  )
}

const Form = ({ complete }) => {
  const { secureFields } = useSecureFields()

  const handleSubmit = () => {
    secureFields.validate()
    if (secureFields.method === 'card' && !complete) return
    secureFields.submit()
  }

  // ...
}
```

与 `validateOn="submit"`,直到 `validate()` 名为. 之后,错误更新为用户类型.

每一领域 `onFormChange` 数据也报告 `touched` (至少被打碎或鉴定一次)和 `dirty` (通过打入或浏览器自动填充,值至少改变一次).

## 外地组件

现有的安全字段组件是: `CardNumber`, (中文(简体) ), `ExpiryDate`, (中文(简体) ), `SecurityCode` 财务报告和审定财务报表 `Field`。您可以通过下列道具来定制每个道具.

| Propa 名称 | 说明 |
| --- | --- |
| `placeholder` | 输入占位符文本 . |
| `pattern` | 字段值应该匹配的图案,被定义为字符串(正则表达式). 仅用于邮政编码字段. |
| `styles` | CSS 规则的一个对象,用来给 iframe 内部的输入样式 。 见 [样式](https://docs.gr4vy.com/guides/payments/secure-fields/theming) 更多信息. |
| `onBlur` | 将事件处理器附加到输入中, 听取模糊事件 。 通过回调的数据包括: `id` 代表字段类型(例如:. `expiryDate`) (中文(简体) ). |
| `onFocus` | 将事件处理器附加到输入中,为焦点活动收听. 通过回调的数据包括: `id` 代表字段类型(例如:. `expiryDate`) (中文(简体) ). |
| `onInput` | 将事件处理器附加到输入中,倾听输入事件。 通过回调的数据包括: `id` 代表字段类型(例如:. `expiryDate`)和一些有用的卡验证信息,例如当前方案(例如. `visa`)和安全代码标签(例如. `CVV`) (中文(简体) ). |
| `onRedact` | 将事件处理器附加到输入中, 监听 `redacted` 事件(当字段值被遮住时开火,或者自动通过 `maskInput` 或方案通过 `redactValue()`) (中文(简体) ). |
| `onUnredact` | 将事件处理器附加到输入中, 监听 `unredacted` 事件(当字段值解开时,自动或程序通过 `unredactValue()`) (中文(简体) ). |
| `autoFocus` | 装入时自动聚焦字段 . |
| `maskInput` | 启用输入掩码 。 接受 `true` 默认遮盖,或对象 `character` (假冒字符,默认) `•`, (中文(简体) ), `showLastFour` (保持最后四个数字可见, `CardNumber` 仅被忽略 `SecurityCode`),以及 `maskOnInput` (实时任务). 仅存于 `CardNumber` 财务报告和审定财务报表 `SecurityCode`。 。 。 . |
| `onCardDetailsChanged` | 将事件处理器附加到输入中, 监听 `card-details-changed` 活动。 当API确认输入的BIN的卡片细节,包括确认的卡片细节时,即被解除 `scheme`。仅可在 `CardNumber`。 。 。 . |
| `showSchemeIcons` | 在卡号字段内显示卡片方案图标。 图标作为用户类型进行实时更新,并在API确认方案时被完善. 接受 `true` 以显示方案和额外方案图标,或用于接受颗粒控制的对象:  
  
二. 支助 `scheme`: (boolean) 显示检测到的方案  
二. 支助 `additionalSchemes`: (boolean) 显示同名图标  
二. 支助 `placeholders`: (boolean) 检测前显示 Visa/Mastercard/Amex  
  
最多显示3个图标——确保输入足够宽以容纳. 仅存于 `CardNumber`。 。 。 . |

每个外地构成部分支助 `ref` 这暴露了 `clear()`, (中文(简体) ), `redactValue()`,以及 `unredactValue()` 方法。 。 .

```jsx
import { useRef } from 'react'
import { CardNumber } from '@gr4vy/secure-fields-react'

const CardNumberWithClear = () => {
  const cardNumberRef = useRef(null)

  return (
    <>
      <CardNumber ref={cardNumberRef} maskInput />
      <button type="button" onClick={() => cardNumberRef.current?.clear()}>
        Clear
      </button>
      <button
        type="button"
        onClick={() => cardNumberRef.current?.redactValue()}
      >
        Mask
      </button>
      <button
        type="button"
        onClick={() => cardNumberRef.current?.unredactValue()}
      >
        Unmask
      </button>
    </>
  )
}
```

## 单击以支付

点击支付是在线支付更好的方式 — — 其特点是基于安全的远程商业行业标准的先进支付技术.

### 先决条件

遵循指示 [点击以支付 Merchant 设置](https://docs.gr4vy.com/guides/payments/secure-fields/click-to-pay#merchant-setup)。 。 。 .

### 正在添加点击到 Pay

安全字段配置完毕后,您就可以开始在退出时添加 Click to Pay .

首先,添加 `ClickToPay` 组件到您的窗体, 以便安全字段可以让 Click to Pay 。 确保将所需选项作为道具传递给它.

然后,添加一个登录表单,让用户访问他们的 Click to Pay 存储的卡片,然后用 `ClickToPaySignIn` 组件.

此外,增加一个复选框,允许一个尚未注册的客户确定是否要与 Click to Pay 分享他们的卡片数据.

最后,确保卡片输入与 `CardForm` 组件.

```js
import { ClickToPay, ClickToPaySignIn, CardForm } from '@gr4vy/secure-fields-react'

...

const { secureFields } = useSecureFields()

<ClickToPay
  dpaLocale="en_AU"
  cardBrands={['mastercard', 'visa', 'american-express']}
  email="john@example.com"
  mobileNumber={{
    countryCode: '61',
    phoneNumber: '491570159',
  }}
  consentCheckbox="#click-to-pay-consent-checkbox"
/>

<ClickToPaySignIn
  onVisibilityChange={(visible: boolean) => {
    console.log('Sign in UI visibility changed. Visible', visible)
  }}
>
  <label>Access your Click to Pay stored cards</label>
  <input type="text" className="click-to-pay-email-phone" ref={phoneOrEmailRef} />
  <button
    className="px-4 py-2 text-white bg-blue-500 rounded-md hover:bg-blue-600"
    onClick={() => secureFields?.clickToPay?.signIn({ email: phoneOrEmailRef?.current?.value })}
  >Continue</button>
</ClickToPaySignIn>

<CardForm>
  <label htmlFor="cc-number">Card number</label>
  <CardNumber styles={styles} />

  <label htmlFor="cc-expiry-date">Expiry date</label>
  <ExpiryDate styles={styles} />

  <label htmlFor="cc-security-code">Security code</label>
  <SecurityCode styles={styles} />
</CardForm>

<div>
  <input type="checkbox" id="click-to-pay-consent-checkbox" />
  <label htmlFor="click-to-pay-consent-checkbox">Store my card with Click to Pay</label>
</div>
```

这个 `ClickToPay` 组件接受下列道具:

| Propa 名称 | 说明 |
| --- | --- |
| `srcDpaId` | 政治部识别员。 这是您 Digital Pay 应用程序( DPA) 的独有标识符, 它是在登入时生成的 . |
| `dpaName` | 登记的政治部的法定名称. |
| `cardBrands` | 商家所接受的卡片计划列表. 我们目前支持 `mastercard`, (中文(简体) ), `maestro`, (中文(简体) ), `visa`, (中文(简体) ), `amex`, (中文(简体) ), `discover` |
| `consentCheckbox` | 引用“选入”的同意复选框元素. |
| `learnMoreLink` | 参考学习更多联系要素. |
| `email` | 用户电子邮件用于访问 Click to Pay . |
| `mobileNumber` | 用于访问 Click to Pay 的用户电话号码 。 要求的格式是 `{ countryCode: string, phoneNumber: string }` |
| `dynamicDataType` | 用于卡片数据的密码图或令牌类型. 见 [主卡文档](https://developer.mastercard.com/unified-checkout-solutions/documentation/sdk-reference/parameters/#payment-options) 更多信息。 可能值为 `NONE` 财务报告和审定财务报表 `CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM`默认为 `CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM`。 。 。 . |

### 点击以支付全局事件

以下道具可用于 `SecureFields` 组件,以收听特定的 Click to Pay 事件.

| Propa 名称 | 说明 |
| --- | --- |
| `onClickToPayInitialized` | 一个可以监听 Click to Pay 的安全初始化的事件处理器 。 它会听 [`CLICK_TO_PAY_INITIALIZED`](https://docs.gr4vy.com/guides/payments/secure-fields/events#global-events) 事件,并接受带有 `clickToPay` 作为论据. |
| `onClickToPayReady` | 事件处理器, 用于监听 Click to Pay 准备 。 它会听 [`CLICK_TO_PAY_READY`](https://docs.gr4vy.com/guides/payments/secure-fields/events#global-events) 事件并接受带有对象的回调功能 `{ buyerExists: boolean }`。 。 。 . |
| `onClickToPaySignOut` | 一个事件处理器,可以监听用户退出 Click to Pay 。 它会听 [`CLICK_TO_PAY_SIGN_OUT`](https://docs.gr4vy.com/guides/payments/secure-fields/events#global-events) 并接受回调函数. |
| `onClickToPayError` | 事件处理器, 用于监听 Click to Pay 所抛出的任何错误 。 它会听 [`CLICK_TO_PAY_ERROR`](https://docs.gr4vy.com/guides/payments/secure-fields/events#global-events) 中,并接受一个带有错误类型的回调函数(QQ 'RETRIES EXED' 中的 “ CODE INVALID” ) . |
| `onClickToPayCancel` | 一个事件处理器, 它可以监听用户关闭/ 取消 Click to Pay 。 它会听 [`CLICK_TO_PAY_CANCEL`](https://docs.gr4vy.com/guides/payments/secure-fields/events#global-events) 并接受回调函数. |
| `onClickToPayCheckoutWithNewCard` | 事件处理器,可以收听用户使用新卡报到. 它会听 [`CLICK_TO_PAY_CHECKOUT_WITH_NEW_CARD`](https://docs.gr4vy.com/guides/payments/secure-fields/events#global-events) 并接受回调函数. |
| `onClickToPayUnableToLoadDpa` | 无法装入提供的 DPA 。 它会听 [`CLICK_TO_PAY_UNABLE_TO_LOAD_DPA`](https://docs.gr4vy.com/guides/payments/secure-fields/events#global-events) 并接受回调函数. |
| `onMethodChange` | 用于用户选择不同方法的事件处理器( 既不是) `card` 或者说 `click-to-pay`) (中文(简体) ). 它会听 [`METHOD_CHANGE`](https://docs.gr4vy.com/guides/payments/secure-fields/events#global-events) ,并接受带有选定方法的回调函数. |

### 更新退出选项

初始化后更新“ 点击支付” 退出选项。 当交易金额在用户提交前发生变化(例如手推车更新)时,此功能是有用的.

```js
const { secureFields } = useSecureFields()

secureFields.clickToPay.updateCheckoutOptions({
  transactionAmount: 9.99,
  transactionCurrencyCode: 'AUD',
})
```

选项与先前设定的值合并,这样可以更新单个字段而不会丢失其余部分.

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `transactionAmount` | `number` | 交易金额. |
| `transactionCurrencyCode` | `string` | 交易货币代码. |

## 常见问题

### @gr4vy/secure-fields-react 是什么？

Gr4vy主持安全场,提供高级主题,PCI遵守,事件处理等等\.

### 如何安装 @gr4vy/secure-fields-react？

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

### @gr4vy/secure-fields-react 支持 TypeScript 吗？

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

### @gr4vy/secure-fields-react 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gr4vy/secure-fields-react 可以商用吗？

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

### @gr4vy/secure-fields-react 的下载量有多少？

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

### @gr4vy/secure-fields-react 还在维护吗？

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

