# @hcaptcha/react-native-hcaptcha 中文文档

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

版本：4\.1\.0
npm 元数据更新时间：2026-07-20T18:15:31.354Z
中文译文更新时间：2026-11-17T17:52:30.723Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：501 kB，44 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \*，react-native \*，react-native-webview \>=9\.0\.1
- 首次发布：2021-01-29T02:32:56.051Z
- 最新版本发布：2026-07-20T18:15:30.998Z
- 近 30 天下载量：299913（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 5 个）

## 中文简介

h Captcha 本地反应库(Android和iOS)

## 安装

```sh
npm install @hcaptcha/react-native-hcaptcha
```

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

## README

[![npm](https://img.shields.io/npm/v/@hcaptcha/react-native-hcaptcha)](https://www.npmjs.com/package/@hcaptcha/react-native-hcaptcha) [![ci](https://github.com/hCaptcha/react-native-hcaptcha/actions/workflows/tests.yaml/badge.svg)](https://github.com/hCaptcha/react-native-hcaptcha/actions/workflows/tests.yaml)

# 反应-内生-头痛

h Captcha 为反应原生(Android和iOS)所包装

## 安装

1.  安装软件包 :

-   利用国家预防机制 `npm install @hcaptcha/react-native-hcaptcha`
-   使用 Yarn `yarn add @hcaptcha/react-native-hcaptcha`

2.  导入包 : `import ConfirmHcaptcha from '@hcaptcha/react-native-hcaptcha';`

博览会和反应本地化的完整示例以及调试指南都在其中 [保安员,md](https://npmcn.com/package/%40hcaptcha/react-native-hcaptcha/MAINTAINER.md)

## 演示

见现场演示 [点心](https://snack.expo.io/rTUn6wTjW)。 。 。 .

## 使用量

见 [实例。 应用](https://npmcn.com/package/%40hcaptcha/react-native-hcaptcha/Example.App.js) (c) 以完全行之有效的范例执行的回购为例.

对于熟悉hCaptcha JS API的用户,呼叫 `show()` 在此包装中触发 `hcaptcha.execute()` 电话.

这意味着,如果您是企业用户,配置了99.9%的被动或纯被动的站点密钥,则不需要额外工作来获得预期的行为:要么显示视觉挑战,要么立即通过网络返回一个符号 `onMessage`,按照您的配置.

此外,请注意以下可通过下列方式返回的特别信件串: `onMessage` 页:1 [错误大小写](https://docs.hcaptcha.com/configuration#error-codes)

事件由 `onMessage` 与 `success === true` 将是一个密码.

实际上,你应该总是提供 `onMessage`。没有它,您的应用程序将不会收到符号、错误或取消事件.

### 基本模式使用

```js
import React, { useRef } from 'react';
import ConfirmHcaptcha from '@hcaptcha/react-native-hcaptcha';

export default function Example() {
  const captchaRef = useRef(null);

  const onMessage = (event) => {
    if (!event?.nativeEvent?.data) {
      return;
    }

    if (event.success) {
      const token = event.nativeEvent.data;
      event.markUsed?.();
      captchaRef.current?.hide();
      return;
    }

    if (event.nativeEvent.data === 'challenge-closed') {
      captchaRef.current?.hide();
    }
  };

  return (
    <ConfirmHcaptcha
      ref={captchaRef}
      siteKey="your-site-key"
      baseUrl="https://hcaptcha.com"
      onMessage={onMessage}
    />
  );
}
```

### 核查有效载荷 `verifyParams`

使用 `verifyParams` 请求数据 `hcaptcha.setData(...)` 在每次核查之前.

```js
<ConfirmHcaptcha
  ref={captchaRef}
  siteKey="your-site-key"
  baseUrl="https://hcaptcha.com"
  onMessage={onMessage}
  verifyParams={{
    rqdata: enterpriseRqdata,
    phonePrefix: '44',
    phoneNumber: '+44123456789',
  }}
/>
```

高级遗产 `rqdata`, (中文(简体) ), `phonePrefix`,以及 `phoneNumber` 道具还能用,不过 `verifyParams` 优先,对于新的守则应优先.

### 用户行程( 企业)

旅程捕捉在卡普查水平上进行 `userJourney={true}`。 。 。 .

默认情况下, Captcha 实例与 `userJourney={true}` 将:

-   将当前共享的旅行缓冲器附在其核查有效载荷上,作为 `userjourney`
-   启动首次使用的行程运行时间
-   启用自动全应用的触摸抓取, 至少一个 `userJourney` captcha 实例已挂载

使用 `initJourneyTracking()` 当您想要:

-   在卡布查组件挂起前开始跟踪行程
-   登记用于自动屏幕跟踪的 React 导航容器
-   启用运行时间调试/调试钩
-   禁用自动触摸抓取方式 `touchCapture: false` ,同时保留用户余行

```js
import ConfirmHcaptcha, {
  initJourneyTracking,
  registerJourneyNavigationContainer,
} from '@hcaptcha/react-native-hcaptcha';

initJourneyTracking({
  touchCapture: true,
});

// If you use React Navigation, register the container once the ref exists.
registerJourneyNavigationContainer(navigationRef);

<ConfirmHcaptcha
  ref={captchaRef}
  siteKey="your-site-key"
  baseUrl="https://hcaptcha.com"
  onMessage={onMessage}
  userJourney={true}
/>
```

如果您已经持有一个导航容器 查看器的时间, 您可以直接通过 :

```js
initJourneyTracking({
  navigationContainerRef: navigationRef,
});
```

如果您想要使用包含行程的内置组件 :

```js
import { Hcaptcha, initJourneyTracking } from '@hcaptcha/react-native-hcaptcha';

initJourneyTracking();

<Hcaptcha
  siteKey="your-site-key"
  url="https://hcaptcha.com"
  onMessage={onMessage}
  userJourney={true}
/>
```

如果你想的话 `userJourney` 验证有效载荷和导航跟踪,但不希望自动的全应用触控捕获:

```js
initJourneyTracking({
  navigationContainerRef: navigationRef,
  touchCapture: false,
});
```

自动抓取当前记录 :

-   反应导航屏幕转换
-   基本水龙头
-   基本拖动手势
-   从轴向主触控运动推断出类似滚动的手势

自动旅行故意抓取 **没有** 记录 :

-   文本输入内容
-   搜索查询
-   文本长度或输入字符
-   作为控制标识符的可见按钮文本

### 内置组件使用

如果您想要自己管理周围的用户界面, 请使用内置组件 :

```js
import { Hcaptcha } from '@hcaptcha/react-native-hcaptcha';

<Hcaptcha
  siteKey="your-site-key"
  url="https://hcaptcha.com"
  onMessage={onMessage}
/>
```

### 处理发放后过期寿命周期

这个扩展是一个轻量级的包装器,目前并不试图以与网络JS API相同的方式管理验证后状态,例如使用到期回调.

特别是,如果你这样做 **没有** 计划通过提交后端立即消耗返回的密码,您应该启动一个定时器,让您的应用程序状态知道,当新的密码到期时需要它.

默认情况下,该值为120秒. 所以,一个 `expired` 错误将被释放到 `onMessage` 如果你没有打电话 `event.markUsed()`。 。 。 .

一旦你用过卡普查的纪念品,就打电话 `markUsed` 对象在 `onMessage`数字 :

```js
  const onMessage = event => {
    if (event && event.nativeEvent.data) {
      if (event.nativeEvent.data === 'open') {
        // hCaptcha shown
      } else if (event.success) {
        captchaForm.current.hide();
        const token = event.nativeEvent.data;
        // utilize token and call markUsed once you are done with it
        event.markUsed();
      } else if (event.nativeEvent.data === 'challenge-closed') {
        captchaForm.current.hide();
      } else {
        // handle rest errors
      }
    }
  };

  const captchaForm = useRef(null);

  return (
    <ConfirmHcaptcha
      ref={captchaForm}
      siteKey={siteKey}
      languageCode="en"
      onMessage={onMessage}
    />
  );
```

### 处理错误并重试

如果你的应用遇到一个 `error` 事件,您可以通过调用重设 hCaptcha SDK 流量 `event.reset()` 进行另一次核查.

`event.reset()` 重建当前道具上的验证有效载荷,以及当前在重试前的缓冲行程.

SDK 自动重试加载 `api.js` 在短暂的失败之后。 如果一切尝试都失败了, `script-error` 发送通过 `onMessage`。 。 。 .

15秒钟 `loading timeout` 电文不停止初始化,不应作为终端装载故障处理.

## 依赖关系

1.  [反应-本地-网络视图](https://github.com/react-native-community/react-native-webview)

## 以iOS为基础

### 所需框架/图书馆

您的应用程序必须链接以下框架/ 库 :

-   libswift 微博Kit.tbd
-   JavaScript Core. 框架

### 翻转版本

您必须拥有最新版本的 Flapper 来构建此应用程序 。 如果您最近升级了 React Natural , 您的 Flipper 版本可能已经过时 。 这将引起编译错误 .

您的 Podfile 应该更新到类似的东西:

```
  # Enables Flipper.
  #
  # Note that if you have use_frameworks! enabled, Flipper will not work and
  # you should disable these next few lines.
  use_flipper!({ 'Flipper-Folly' => '2.5.3', 'Flipper' => '0.87.0', 'Flipper-RSocket' => '1.3.1' })
  post_install do |installer|
    flipper_post_install(installer)
  end
```

如果您遇到与 Flipper 相关的构建时错误 .

## 本地化

确定您传递的值 `languageCode` 是用户在您的应用程序中设置的, 如果您允许他们覆盖系统默认值 .

否则,您应该通过首选设备 locale,例如从 `getLocales()` 如果使用的话 [反应-本地化-本地化](https://github.com/zoontek/react-native-localize)。 。 。 .

## 页:1

-   UI默认为JS SDK的"隐形"模式,即不显示复选框.
-   如果您需要测试显示挑战模式, 请在 hCaptcha 仪表板中将您的站点键设置为“ 永远挑战” 模式 .
-   你们可以 `import { Hcaptcha } from '@hcaptcha/react-native-hcaptcha';` 自己定制UI.

## 捕捉洞

-   打电话 `initJourneyTracking()` 早点做一次 初始化前发生的事件没有被捕获.
-   默认启用自动全应用程序触摸抓取, 而至少有一个 captcha 实例带有 `userJourney={true}` 已挂载.
-   自动触摸抓取使用 React Industrial 的公开 `AppRegistry.setWrapperComponentProvider(...)` API (英语).
-   这个SDK在初始化后通过截取未来呼叫而由已注册的包装提供者组成 `setWrapperComponentProvider(...)`。 。 。 .
-   React Introduct不会暴露在SDK初始化之前已经注册的包装提供者的获取器. 如果另一个库先安装了包装提供者, 请打电话 `initJourneyTracking()` 更早或使用时间 `touchCapture: false` 避免冲突.
-   如果你开始 `touchCapture: false`,此 SDK 故意不补丁 `AppRegistry`。如果另一个库在禁用窗口中注册了包装提供者,而您随后可以重新启用触摸抓取,则hCaptcha无法自动恢复先前的提供者。 如果您可以稍后切换到抓取, 请先初始化 h Captcha 或者保留 `touchCapture` 开始启用.
-   导航抓取仅在您注册反应导航容器时自动进行 `initJourneyTracking({ navigationContainerRef })` 或者说 `registerJourneyNavigationContainer(ref)`。 。 。 .
-   `userJourney={true}` 控制当前缓冲行程是否附在卡普查的核查请求上。 也可以默认自动触摸抓取,除非您使用 `initJourneyTracking({ touchCapture: false })`。 。 。 .
-   旅行缓冲器是应用全球的,并在同一过程中通过Captcha实例共享。 这是针对单一应用程序、单一用户的故意行为.
-   `ConfirmHcaptcha.stopEvents()` 清除共享缓冲出行并解开 `ConfirmHcaptcha` 实例,从旅行附件到明确重新配置为止,例如: `userJourney` 关了 继续.
-   全球旅行捕捉可以在 `stopEvents()` 如果行程跟踪被初始化,所以后期的应用事件可能仍然会为其他消费者在共享缓冲中积累.
-   成功的核查清除了缓冲之行. 错误和取消流量没有 .
-   自动控制标识符是最佳的,更喜欢非内容元数据,如 `nativeID`, (中文(简体) ), `testID`,以及 `accessibilityLabel`如果不存在,事件可能会回到本地视图标记或 `"unknown"`。 。 。 .

## 外交部电话支助

SDK支持MFA(多功能认证)流的手机前缀和电话号码参数. 您可以通过这些参数作为道具:

```js
// Using phone prefix (country code without '+')
<ConfirmHcaptcha
  siteKey="your-site-key"
  phonePrefix="44"
  onMessage={onMessage}
/>

// Using phone number (full E.164 format)
<ConfirmHcaptcha
  siteKey="your-site-key"
  phoneNumber="+44123456789"
  onMessage={onMessage}
/>
```

对于新代码,倾向于:

```js
<ConfirmHcaptcha
  siteKey="your-site-key"
  baseUrl="https://hcaptcha.com"
  verifyParams={{
    phonePrefix: '44',
    phoneNumber: '+44123456789',
  }}
  onMessage={onMessage}
/>
```

## 属性

| **名称** | **类型** | **说明** |
| :-- | :-- | :-- |
| 站点键 _(必须)_ | 字符串 | H Captcha 网站键 |
| 大小 | 字符串 | 部件的大小, 可以是“ 隐形” 、 “ 约束” 或“ 正常” . `checkbox` 并被接受为用于 `normal`。默认:“隐形” |
| 新闻 | 函数(见 [这里](https://github.com/react-native-webview/react-native-webview/blob/master/src/WebViewTypes.ts#L299)(中文(简体) ) | 要求。 在收到回复、错误或用户取消时运行. |
| 语言代码 | 字符串 | HCaptcha 的默认语言; 覆盖电话默认 。 可以找到一个完整的支持语言及其代码列表 [这里](https://docs.hcaptcha.com/languages/) |
| 显示记录 | 布尔 | 在 hCaptcha 网络内容加载时是否显示加载指标 |
| 可分块连接 | 布尔 | 允许用户在使用触摸加载器上载时取消 hcaptcha |
| 装入指标颜色 | 字符串 | 活动指示器的颜色 |
| 背景颜色 | 字符串 | 将应用于主要 HTML 元素的背景颜色代码 |
| 主题 | 字符串\\\\\\ 对象 | 主题可以是"光","暗","相接"或自定义主题对象(参见 Entertainment Docs) |
| rqdata 数据 | 字符串 | **折旧**: 使用 `rqdata` 内 `HCaptchaVerifyParams` 换句话说 将在以后的释放中移除。 见企业文件. |
| 校验 | 对象 | 验证有效载荷覆盖 `hcaptcha.setData(...)` 就在核查前 支助 `rqdata`, (中文(简体) ), `phonePrefix`,以及 `phoneNumber`。 。 。 . |
| 用户行程 | 布尔 | 何时 `true`,将当前共享行程缓冲器作为核查有效载荷 `userjourney`。它也可以在默认情况下自动抓取 `userJourney` 已安装 Captcha 实例 。 使用 `initJourneyTracking({ touchCapture: false })` 以保持用户的行走功能,而无需自动触摸捕获. |
| 哨兵 | 布尔 | 启用 hCaptcha 错误报告, 包括 API 装载失败 。 设定为 `false` 以禁用(见企业编号). |
| jsSrc 函数 | 字符串 | Api.js的url (英语). 默认 : [https://js.hcaptcha.com/1/api.js (中文(简体) )](https://js.hcaptcha.com/1/api.js) (只有在使用第一当事方托管功能的情况下才进行管理。 ) |
| 结束点 | 字符串 | JS Ajax要求替代API终点。 默认 : [https://api.hcaptcha.com (中文(简体) )](https://api.hcaptcha.com/) (只有在使用第一当事方托管功能的情况下才进行管理。 ) |
| 报告api | 字符串 | 点 hCaptcha Bug 报告请求到替代 API 端点. 默认 : [https://accounts.hcaptcha.com 互联网档案馆的存檔,存档日期2013-12-02](https://accounts.hcaptcha.com/) (只有在使用第一当事方托管功能的情况下才进行管理。 ) |
| 资产主机 | 字符串 | 点装入 hCaptcha 资产到用户定义的资产位置, 用于代理 。 默认 : [https://newassets.hcaptcha.com (中文(简体) )](https://newassets.hcaptcha.com/) (只有在使用第一当事方托管功能的情况下才进行管理。 ) |
| 幽灵 | 字符串 | 点装入 hCaptcha 挑战图像到用户定义的图像位置, 用于代理 。 默认 : [https://imgs.hcaptcha.com (中文(简体) )](https://imgs.hcaptcha.com/) (只有在使用第一当事方托管功能的情况下才进行管理。 ) |
| 东道主 | 字符串 | h Captcha SDK 主机标识符. 无效值表示由 SDK 生成 |
| url 密码 _(仅内含组件)_ | 字符串 | 在您的 hCaptcha 上定义的 url 域 。 你一般不需要改变这一点. |
| 样式 _(仅内含组件)_ | 视图样式( 见 [这里](https://reactnative.dev/docs/view-style-props)(中文(简体) ) | 网页视图样式 |
| 基数Url _(仅包括模式部分)_ | 字符串 | 在您的 hCaptcha 上定义的 url 域 。 你一般不需要改变这一点. |
| 被动键 _(仅包括模式部分)_ | 布尔 | 指示被动模式是否启用; 当为真时, 模式将完全不显示 |
| 有背弃 _(仅包括模式部分)_ | 布尔 | 定义模式背景是否显示(默认正确)。 若为 `hasBackdrop=false`, (中文(简体) ), `backgroundColor` 将仅在 hCaptcha 视觉挑战出现后适用. |
| 方向 | 字符串 | 这明确了挑战的"取向". 可能是这样 `portrait`, (中文(简体) ), `landscape`默认 : `portrait` |
| 电话前缀 | 字符串 | 可选电话国家呼叫代码(不含"+"),如"44". 用于外交部流动. |
| 电话号码 | 字符串 | E.164格式的可选完整电话号码("+44123"),用于外交部. |

## 旅行API

### `initJourneyTracking(options?)`

为应用进程安装自动行程收藏一次 .

选项 :

-   `navigationContainerRef`: 可选反应导航容器 拒绝立即注册
-   `touchCapture`: 可选布尔, 默认为 `true`时 `false`,保持用户行程启用但禁用自动全应用程序触控抓取
-   `debug`: 可选布尔来记录已发射的行程事件到 `console.debug`
-   `onStats`: 测试或应用仪器中运行时诊断的可选回调

### `registerJourneyNavigationContainer(ref)`

注册或替换用于自动屏幕跟踪的React Navigation容器.

### `ConfirmHcaptcha.stopEvents()`

清除当前共享的行程缓冲并解析 `ConfirmHcaptcha` 从旅行附件到明确重新配置。 一个简单的重新启用的方法就是切换 `userJourney` 关了 继续.

## 状态

功能齐全,但近期内将进行额外的释放.

同一主要释放物内的变化预计将会是添加剂,即不破裂.

## 许可证

MIT许可证. (C) 2021 h Captcha.

校对:Soup (麻省理工学院许可证)

## 常见问题

### @hcaptcha/react-native-hcaptcha 是什么？

h Captcha 本地反应库\(Android和iOS\)

### 如何安装 @hcaptcha/react-native-hcaptcha？

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

### @hcaptcha/react-native-hcaptcha 支持 TypeScript 吗？

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

### @hcaptcha/react-native-hcaptcha 支持 ESM 还是 CommonJS？

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

### @hcaptcha/react-native-hcaptcha 可以商用吗？

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

### @hcaptcha/react-native-hcaptcha 的下载量有多少？

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

### @hcaptcha/react-native-hcaptcha 还在维护吗？

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

