@gr4vy/secure-fields-react

中文文档
2.13.0发布于 2026/11/03MITTypeScriptCommonJS近 30 天下载 4.8万

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

中文使用文档
文档目录10 节
  1. 使用量
  2. 开始吧
  3. 创建窗体
  4. 验证
  5. 外地组件
  6. 单击以支付
  7. 先决条件
  8. 正在添加点击到 Pay
  9. 点击以支付全局事件
  10. 更新退出选项

反应的安全字段

NPM Version GitHub license Changelog

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

使用 @gr4vy/secure-fields 在非反应应用程序中.

使用量

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

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

开始吧

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

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。 。 。 .

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

创建窗体

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

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

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 和其余的选择.

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 如果表格没有准备好,请停止提交.

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字段值应该匹配的图案,被定义为字符串(正则表达式). 仅用于邮政编码字段.
stylesCSS 规则的一个对象,用来给 iframe 内部的输入样式 。 见 样式 更多信息.
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() 方法。 。 .

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 设置。 。 。 .

正在添加点击到 Pay

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

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

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

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

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

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

...

const { secureFields } = useSecureFields()

<ClickToPay
  dpaLocale="en_AU"
  cardBrands={['mastercard', 'visa', 'american-express']}
  email="[email protected]"
  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用于卡片数据的密码图或令牌类型. 见 主卡文档 更多信息。 可能值为 NONE 财务报告和审定财务报表 CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM默认为 CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM。 。 。 .

点击以支付全局事件

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

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

更新退出选项

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

const { secureFields } = useSecureFields()

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

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

选项类型说明
transactionAmountnumber交易金额.
transactionCurrencyCodestring交易货币代码.

版本与发布记录

@gr4vy/secure-fields-react 共发布 99 个版本,首次发布于 2022/08/13;过去 12 个月发布了 33 个版本。

版本发布日期距今
2.13.0latest2026/11/0313 天前
2.12.02026/11/0313 天前
2.11.22026/10/051 个月前
2.11.2--canary.1346.7573de9.0canary2026/10/051 个月前
2.11.2--canary.1339.789d550.02026/09/301 个月前
2.11.12026/09/251 个月前

关于 @gr4vy/secure-fields-react 的常见问题

@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 和提交记录判断。