# @cardknox/react-ifields 中文文档

规范地址：https://npmcn.com/package/%40cardknox/react-ifields/

版本：2\.2\.86
npm 元数据更新时间：2026-03-16T18:54:54.515Z
中文译文更新时间：2026-11-09T05:10:04.319Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：132 kB，6 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2022-03-14T21:14:09.950Z
- 最新版本发布：2026-03-16T18:54:54.312Z
- 近 30 天下载量：9701（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 1 个）

## 中文简介

Cardknox i 字段的反应组件

## 安装

```sh
npm install @cardknox/react-ifields
```

也可以使用：`pnpm add @cardknox/react-ifields`、`yarn add @cardknox/react-ifields`、`bun add @cardknox/react-ifields`

## README

# 反应- ifields

## Cardknox i 字段的反应组件

* * *

## 卡克诺克

Cardknox是开发商方便的支付网关集成供应商,用于存储、在线或移动交易

**沙盒 :** [https://www.cardknox.com/sandbox/ 页面存档备份,存于互联网档案馆](https://www.cardknox.com/sandbox/)

**i 字段:** [https://www.cardknox.com/ifields/ 页面存档备份,存于互联网档案馆](https://www.cardknox.com/ifields/)

使用此组件需要沙盒或活账户

* * *

## 使用量

需要2个基本道具来进行这个操作.

#### 1\. 类型

I Fields支持三种付款数据:

-   信用卡
-   简历
-   阿彻

```
    <IField type={CARD_TYPE} />
```

该财产的可能价值是:

-   纸牌
-   简历
-   ach (单位:千美元)

可从组件中导入

```
import { CARD_TYPE, CVV_TYPE, ACH_TYPE } from '@cardknox/react-ifields';
```

#### 2\. 账户

递给你 [i 字段密钥](https://www.cardknox.com/ifields/) 改为 **账户** 这样的道具 :

```
export default class App extends React.Component {
  state = {
    account = {
      xKey: "{Your iFields key}",
      xSoftwareName: "{The name of your app}",
      xSoftwareVersion: "{Your app's version}"
    }
  }
  render() {
    return <IField account={this.state.account} />
  }
}
```

* * *

## 活动

有2个生命周期事件和7个用户事件.

* * *

### 生命周期事件

#### 1\. 装入

于 `iframe` 已装入

```
    <IField onLoad={this.onLoad} />
```

#### 2\. 托肯语

当从 i 字段收到一个符号时会释放

```
    <IField onToken={this.onToken} />
```

* * *

### 用户事件

用户事件是指用户与其互动时从iFields传递的事件.

现有活动是:

1.  单击
2.  dbl 点击
3.  焦点
4.  模糊
5.  投入
6.  变动
7.  密钥压
8.  已更新( 仅使用 CVV)
9.  来文 \*

\* 提交活动的作用略有不同,见下文.

#### 更新事件

除了提交之外,上述活动都是在一次活动中收集的 `update`。 。 。 .

事件有效载荷在 `e.data`。数据中还包含事件类型,以便您可以筛选出您不需要的事件 `switch` 这样的声明:

```
export default class App extends React.Component {
  render() {
    return <IField onUpdate={this.onUpdate} />
  }
  onUpdate = (data) => {
    switch (data.event) {
      case 'input':
        console.log("input event received");
        break;
      case 'click':
        console.log("click event received");
        break;
      default:
        break;
    }
  }
}
```

#### 提交事件

当用户从 iFrame 内部提交窗体( 按下 Enter 键)时,此事件会被触发.

此事件与其他用户事件不同.

-   仅在 proc 情况下此事件才会被释放 `options.autoSubmit` 这是真的.
-   此事件不调用 `onUpdate`。 。 。 .
-   此事件没有传递数据 .

```
export default class App extends React.Component {
  state = {
    options: {
      autoSubmit: true
    }
  }
  render() {
    return <IField options={this.state.options} onSubmit={this.onSubmit} />
  }
  onSubmit = () => {
    //submit to server
  }
}
```

也可以让组件自动为您提交表格 _提交_ 从 iFrame 被触发。 若为 `autoSubmitFormId` 设置在选项道具上,组件将调用带有该标识的元素。 这对于依赖窗体元素处理提交文件的较小的应用程序有用.

```
export default class App extends React.Component {
  state = {
    options: {
      autoSubmit: true,
      autoSubmitFormId: 'form'
    }
  }
  render() {
    return <form id="form">
        <IField options={this.state.options} />
      </form>
  }
}
```

### 错误

还有一个错误事件可以订阅.

```
export default class App extends React.Component {
  render() {
    return <IField onError={this.onError} />
  }
  onError = (data) => {
    console.error("IFrame errored", data);
  }
}
```

* * *

## 行动

关于这一构成部分,还有3个行动

### 焦点

`focusIfield`

此动作会在调用时将焦点设定为 ifield

### 清除

`clearIfield`

此动作将在调用时清除 ifield 的数据

### 获取托肯

`getToken`

此动作会在调用时为 ifield 装入符号 .

```
export default class App extends React.Component {
  iFieldRef = React.createRef();
  render() {
    return <IField ref={this.iFieldRef} />
  }
  focus = () => {
    this.iFieldRef.current.focusIfield();
  }
  clear = () => {
    this.iFieldRef.current.clearIfield();
  }
  getToken = () => {
    this.iFieldRef.current.getToken();
  }
}
```

## 道具

| 名称 | 类型 | 说明 | 有效数值 |
| --- | --- | --- | --- |
| 类型 | 字符串 | i 字段类型 | 
-   纸牌
-   简历
-   ach (单位:千美元)

 |
| 账户 | 账户 |  |  |
| 选项 | 选项 |  |  |
| 三维 | [三维](https://npmcn.com/package/%40cardknox/react-ifields/#readme-ThreeDS) |  |  |
| 发行者 | 字符串 | 发卡人 | 仅用于 cvv i 字段 |
| 登录 | 函数 | 打电话的时候 `iframe` 负载 |  |
| 更新时 | 函数 <更新事件数据\> 翻译: | I 字段更新后调用 |  |
| 投递 | 函数 | 当用户按 Enter 键时调用 `iframe` |  |
| 脚本 | 函数 <调试数据\> 翻译: | 当i Field 收到一个符号时调用 |  |
| 错误 | 函数 <数据出错\> 翻译: | 在获取符号时调用 |  |

### 账户

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| x 键 | 字符串 | i 字段密钥 |
| x软件Name | 字符串 | 软件名称 |
| x软件版本 | 字符串 | 软件版 |

### 选项

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 启用日志 | 布尔 | 打开和关闭控制台. |
| 自动格式 | 布尔 | 打开和关闭 。 仅用于 i 字段 _纸牌_ 类型。 见 _自动格式分隔符_。 。 。 . |
| 自动格式分隔符 | 字符串 | 用于自动格式卡号的字符串 _自动格式_ 打开。 默认值为 " (空间). |
| 块非数字输入 | 布尔 | 块非数字字符输入 。 仅用于 i 字段 _纸牌_ 类型。 这不妨碍 _自动格式分隔符_。 。 。 . |
| 自动投递 | 布尔 | 一旦数据有效,就应立即取出该令牌。 此设置还将开启在提交数据时捕获从 iFrame 内部触发的提交事件 . |
| 自动提交格式 | 字符串 | 如果自动投递是真实的, 可以设置窗体元素的ID, 组件会触发 _提交_ 在 iFrame 中触发提交时的窗体. |
| 占位符 | 字符串 | 拟用作 _占位符_ 输入字段的文本. |
| i 战地风格 | 对象 | 用于样式 iFields 输入元素的样式对象。 此对象被指定为 **HTMLElement. (原始内容存档于2017-09-29). 样式**。 。 。 . |

### 三维

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 启用3DS | 布尔 | 打开和关闭 3DSsecure |
| 环境 | 字符串 | \`制造'或\`生产'  
这些值可以从软件包中导入 |
| handle3DS 报表 | 函数 | 处理 3DS 结果的回调 |

有关3D-安全与i 字段的完整文件见 [这里](https://docs.cardknox.com/cardknox-products/ifields#ifields-with-3d-secure-authentication)

### 更新事件数据

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 卡片长度 | 数目 | 卡片 i Field 中的数据长度  
只从卡片 i Field 返回更新事件 |
| 事件 | 字符串 | 活动名称. |
| 时空 | 布尔 | I 字段是否为空 . |
| 是瓦利德语 | 布尔 | IField中的数据是否有效. |
| 发行者 | 字符串 | 发卡人  
仅从卡片 i Field 返回更新事件 . |
| 长度 | 布尔 | I 字段数据长度  
注意: 对于卡 i Fields,这包括格式化字符. 使用 `cardNumberlength` 以获取实际数据长度. |
| iField 变换 | 布尔 | I 字段值是否改变 . |

### 调试数据

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| x 键 | 字符串 | 标志 |
| xTokenType 类型 | 字符串 | 无论卡,CVV,还是ACH |

### 数据出错

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 结果 | 字符串 | 这将永远有价值 `error` |
| 错误 | 字符串 | 包含错误消息 |
| xTokenType 类型 | 字符串 | 无论卡,CVV,还是ACH |

  
  
  

* * *

**i 字段版本 :** [2.15.2309.2601 (中文(简体) )](https://cdn.cardknox.com/ifields/2.15.2309.2601/ifield-sample.htm)

## 常见问题

### @cardknox/react-ifields 是什么？

Cardknox i 字段的反应组件

### 如何安装 @cardknox/react-ifields？

在项目目录运行 npm install @cardknox/react-ifields，或使用 pnpm add / yarn add / bun add。

### @cardknox/react-ifields 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cardknox\_\_react-ifields 是否存在。

### @cardknox/react-ifields 支持 ESM 还是 CommonJS？

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

### @cardknox/react-ifields 可以商用吗？

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

### @cardknox/react-ifields 的下载量有多少？

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

### @cardknox/react-ifields 还在维护吗？

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