# @captchafox/react 中文文档

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

版本：1\.13\.0
npm 元数据更新时间：2026-06-30T09:47:28.352Z
中文译文更新时间：2026-11-09T02:18:58.026Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：25 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \>=16\.8\.0，react-dom \>=16\.8\.0
- 首次发布：2023-03-23T19:08:29.372Z
- 最新版本发布：2026-06-30T09:47:28.047Z
- 近 30 天下载量：995039（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 4 个）

## 中文简介

[![NPM version](https://img.shields.io/npm/v/@captchafox/react.svg)](https://www.npmjs.com/package/@captchafox/react)

## 安装

```sh
npm install @captchafox/react
```

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

## README

# @ captchafox/ 反应

[![NPM version](https://img.shields.io/npm/v/@captchafox/react.svg)](https://www.npmjs.com/package/@captchafox/react)

## 安装

使用您喜欢的软件包管理器安装库

```sh
npm install @captchafox/react
```

```sh
yarn add @captchafox/react
```

```sh
pnpm add @captchafox/react
```

```sh
bun add @captchafox/react
```

## 使用量

```tsx
import { CaptchaFox } from '@captchafox/react';

function Example() {
  return <CaptchaFox sitekey="sk_11111111000000001111111100000000" />;
}
```

### 道具

| **Prop** | **类型** | **说明** | **需求** |
| --- | --- | --- | --- |
| 站台密钥 | `string` | 部件的站点密钥 | ✅ |
| 朗语 | `string` | 部件应显示的语言 。 默认自动检测它. |  |
| 模式 | `inline|popup|hidden` | 部件应显示在 . |  |
| 开始 | `none|auto|focus` | 核查开始时的控制。 默认为 `none`。 。 。 . |  |
| 主题 | `light` | `dark` | [`ThemeDefinition`](https://docs.captchafox.com/theming#custom-theme) | 部件的主题 。 默认为光. |  |
| 无 | `string` | 随机生成的非ce. |  |
| i18n (英语) | `object` | 自定义i18n配置. |  |
| 隐藏 | `boolean` | 隐藏关闭按钮并阻止用户关闭部件模式. |  |
| 认证 | `function` | 在成功核实后,以响应符号调用. |  |
| 失败 | `function` | 在核查失败后打电话. |  |
| 错误 | `function` | 当错误发生时调用 . |  |
| 结束 | `function` | 当挑战结束时召唤. |  |
| 关闭 | `function` | 当挑战结束时打电话来. |  |

### 使用验证回调

```jsx
import { CaptchaFox, CAPTCHA_RESPONSE_KEY } from '@captchafox/react';

function Example() {
  const handleVerify = (token: string) => {
    // do something with the token here (e.g. submit the form)
    const formData = {
      // your form data
      [CAPTCHA_RESPONSE_KEY]: token
    };
  };

  return <CaptchaFox sitekey="sk_11111111000000001111111100000000" onVerify={handleVerify} />;
}
```

### 与实例互动

```jsx
import { useRef } from 'react'
import { CaptchaFox, CaptchaFoxInstance } from '@captchafox/react'

function Example() {
    const captchaRef = useRef<CaptchaFoxInstance | null>(null);

    const triggerAction = async () => {
        // execute the captcha
        try {
            const token = await captchaRef.current?.execute()
        } catch {
            // unsuccessful verification
        }
    }

    return (
        <CaptchaFox
            sitekey="sk_11111111000000001111111100000000"
            ref={captchaRef}
        />
        <button onClick={triggerAction}>Action</button>
    )
}
```

您可以在 [GitHub 仓库](https://github.com/CaptchaFox/javascript-integrations/tree/main/examples/react)。 。 。 .

## 常见问题

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

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

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

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

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

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

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

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

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

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

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

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