@captcha-la/react

English · 简体中文

Captchala 验证码 React 官方组件 —— 为你的 React 应用提供智能 CAPTCHA 防护。

安装

npm install @captcha-la/react
# or
yarn add @captcha-la/react
# or
pnpm add @captcha-la/react

快速上手

组件方式

import { Captchala } from '@captcha-la/react'

function App() {
  const handleSuccess = (result) => {
    console.log('验证成功')
    console.log('Token:', result.token)
    // 把 token 提交到你自己的后端校验
  }

  return (
    <Captchala
      appKey="your-app-key"
      product="popup"
      onSuccess={handleSuccess}
      onError={(err) => console.error(err)}
    />
  )
}

Hook 方式

import { useCaptchala } from '@captcha-la/react'

function LoginForm() {
  const { ready, verify } = useCaptchala({
    appKey: 'your-app-key',
    product: 'bind',
    action: 'login'
  })

  const handleSubmit = async (e) => {
    e.preventDefault()

    try {
      const result = await verify()
      console.log('Token:', result.token)
      // 继续提交表单
    } catch (err) {
      console.error('验证失败:', err)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" placeholder="Email" />
      <input type="password" placeholder="Password" />
      <button type="submit" disabled={!ready}>
        登录
      </button>
    </form>
  )
}

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | appKey | string | 必填 | Captchala 应用 key | | serverToken | string | - | 服务端签发的一次性 challenge token。当应用配置 server_token_required=true 时必填，详见下方 生产环境：使用 serverToken。 | | product | 'popup' \| 'float' \| 'embed' \| 'bind' | 'popup' | 显示模式 | | action | string | 'default' | 业务场景标识 (例如 'login'、'register'、'checkout') | | lang | string | 'zh-CN' | 语言代码 ('zh-CN'、'en'、'ja' 等) | | onSuccess | (result) => void | - | 验证成功回调 | | onError | (error) => void | - | 验证失败回调 | | onClose | () => void | - | 关闭回调 | | onReady | () => void | - | 就绪回调 | | className | string | - | 容器 class | | style | CSSProperties | - | 容器 inline style |

通过 ref 调用方法

import { useRef } from 'react'
import { Captchala, CaptchalaRef } from '@captcha-la/react'

function App() {
  const captchaRef = useRef<CaptchalaRef>(null)

  const handleManualVerify = () => {
    captchaRef.current?.verify()
  }

  return (
    <>
      <Captchala ref={captchaRef} appKey="your-key" />
      <button onClick={handleManualVerify}>触发验证</button>
    </>
  )
}

| 方法 | 说明 | |------|------| | verify() | 手动触发验证 | | reset() | 重置验证码状态 | | destroy() | 销毁验证码实例 | | bindTo(selector) | 绑定到指定元素（仅 'bind' 模式） |

useCaptchala Hook

const {
  ready,      // boolean - SDK 已就绪
  loading,    // boolean - SDK 加载中
  error,      // Error | null - 加载错误
  verify,     // () => Promise<CaptchalaResult> - 触发验证
  reset,      // () => void - 重置状态
  bindTo,     // (selector) => void - 绑定到元素
  appendTo    // (selector) => void - 追加到元素
} = useCaptchala(options)

显示模式

Popup 模式（默认）

点击按钮弹出验证对话框。

<Captchala appKey="your-key" product="popup" />

Float 模式

浮动面板形式的验证码。

<Captchala appKey="your-key" product="float" />

Embed 模式

直接嵌入页面的验证码。

<Captchala appKey="your-key" product="embed" />

Bind 模式（配合 Hook）

最适合表单提交：用户提交时再触发验证。

function Form() {
  const { ready, verify } = useCaptchala({
    appKey: 'your-key',
    product: 'bind'
  })

  const handleSubmit = async () => {
    const result = await verify()
    // result.token 即验证 token
  }

  return <button onClick={handleSubmit} disabled={!ready}>提交</button>
}

生产环境：使用 serverToken

生产环境（注册 / 登录 / 支付等）推荐使用 服务端签发的一次性 token。 后端持有 app_secret，调用 POST /v1/server/challenge/issue（带 X-App-Key + X-App-Secret）签发一次性 server_token（TTL 5 分钟，单次消费）， 再下发给前端，浏览器拿到后用 serverToken 渲染组件：

import { useState, useEffect } from 'react'
import { Captchala } from '@captcha-la/react'

function LoginPage() {
  const [serverToken, setServerToken] = useState<string>()

  useEffect(() => {
    // 你自己的后端代理 /v1/server/challenge/issue
    fetch('/api/captcha-token')
      .then(r => r.json())
      .then(d => setServerToken(d.server_token))
      .catch(console.error)
  }, [])

  if (!serverToken) return <div>Loading...</div>

  return (
    <Captchala
      serverToken={serverToken}
      appKey="pk_your_public_app_key"
      action="login"
      onSuccess={(r) => console.log('pass_token:', r.token)}
    />
  )
}

后端示例（Express / Node.js）：

// server.js — 在你自己的 /api/captcha-token handler 里调用
app.get('/api/captcha-token', async (req, res) => {
  const r = await fetch('https://apiv1.captcha.la/v1/server/challenge/issue', {
    method: 'POST',
    headers: {
      'X-App-Key': process.env.CAPTCHALA_APP_KEY,
      'X-App-Secret': process.env.CAPTCHALA_APP_SECRET,
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'action=login&ttl=300'
  })
  const { data } = await r.json()
  res.json({ server_token: data.server_token })
})

注意事项：

• 永远不要把 X-App-Secret 放进浏览器代码。
• 每个 server_token 只能用一次，每次挂载组件前都要重新生成。
• 老应用如果 server_token_required=false，仍然可以只用公开 appKey 模式。

服务端校验

收到 onSuccess 返回的 token 后，在你的服务端做最终校验：

// 你的后端
const response = await fetch('https://api.captcha.la/v1/risk/consume', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-App-Key': 'your-app-key',
    'X-App-Secret': 'your-app-secret'
  },
  body: JSON.stringify({ token })
})

const result = await response.json()
if (result.code === 0 && result.data.valid) {
  // token 有效，放行后续业务
}

TypeScript 支持

完整 TypeScript 类型已内置：

import {
  Captchala,
  useCaptchala,
  type CaptchalaProps,
  type CaptchalaResult,
  type CaptchalaRef,
  type UseCaptchalaOptions
} from '@captcha-la/react'

开源协议

MIT，详见 LICENSE。

链接

• 官网
• 文档
• Dashboard