JSPM – @aetherlib/g-captcha@1.0.1

Package Exports

@aetherlib/g-captcha
@aetherlib/g-captcha/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@aetherlib/g-captcha) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@aetherlib/g-captcha

采用 go-captcha 的 React SDK 封装，提供组件模式与 Hook 模式两种接入方式。

本版本要求 react@19 与 react-dom@19。

推荐用法

全局配置通过 CaptchaProvider 注入，单次验证由 Captcha 或 useCaptcha().verify() 触发。

import { useRef } from 'react';
import { Captcha, CaptchaProvider, useCaptcha } from '@aetherlib/g-captcha';

export default () => {
  const ref = useRef();
  const { verify, holder } = useCaptcha();

  return (
    <CaptchaProvider
      api={{ basePath: 'http://127.0.0.1:3321' }}
      locale={{ buttonText: '点击验证' }}
      theme={{ primaryColor: '#111827', borderRadius: 12 }}
    >
      {holder}

      <Captcha ref={ref} type="auto" onSuccess={(data) => console.log(data)}>
        <button onClick={() => ref.current?.verify()}>组件模式</button>
      </Captcha>

      <button
        onClick={async () => {
          const data = await verify({ type: 'slide-text' });
          console.log(data);
        }}
      >
        Hook 模式
      </button>
    </CaptchaProvider>
  );
};

CaptchaProvider

属性	说明	类型	默认值
api	全局接口配置	`ApiConfig`	-
locale	全局多语言文案	`LocaleTexts`	-
theme	全局主题变量	`ThemeTokens`	-
zIndex	弹层层级	`number`	`9999`

Captcha

属性	说明	类型	默认值
onFail	校验失败回调	`(msg: string) => void`	-
onSuccess	校验成功回调	`(data: any) => void`	-
onCancel	用户主动关闭回调	`() => void`	-
type	验证码类型，支持 `auto`、`click-text`、`click-shape`、`slide-text`、`slide-region`、`rotate`	`CaptchaType`	`auto`
api	当前实例的接口配置覆盖	`ApiConfig`	-
locale	当前实例的文案覆盖	`LocaleTexts`	-
theme	当前实例的主题覆盖	`ThemeTokens`	-
config	当前实例的验证码配置	`CaptchaConfig`	-
className	容器类名	`string`	-
style	容器样式	`CSSProperties`	-

useCaptcha

useCaptcha() 不再接收初始化参数，返回：

字段	说明	类型
verify	按次触发验证码，可覆盖当前调用的 `type/config/api/locale/theme` 与回调	`(options?: CaptchaVerifyOptions) => Promise<any>`
holder	必须渲染在当前 React 树中的承载节点	`ReactNode`

import { CaptchaProvider, useCaptcha } from '@aetherlib/g-captcha';

export default () => {
  const { verify, holder } = useCaptcha();

  return (
    <CaptchaProvider api={{ basePath: 'http://foo.com' }}>
      {holder}
      <button
        onClick={async () => {
          const data = await verify({
            type: 'auto',
            locale: { userCancel: 'Canceled by user' },
            theme: { primaryColor: '#111827' },
          });
          console.log(data);
        }}
      >
        verify
      </button>
    </CaptchaProvider>
  );
};

CaptchaConfig

属性	说明	类型	默认值
width	宽度	`number`	-
height	高度	`number`	-
thumbWidth	缩略图宽度	`number`	-
thumbHeight	缩略图高度	`number`	-
verticalPadding	垂直方向内边距	`number`	-
horizontalPadding	水平方向内边距	`number`	-
showTheme	是否显示主题外框	`boolean`	-
title	标题	`string`	-
iconSize	图标大小	`number`	-
scope	滑动和旋转生效范围	`number`	-
buttonText	按钮文字	`string`	-
dotSize	点选模式区域大小	`number`	-

LocaleTexts

属性	说明
clickTitle	点选模式标题，默认 `请在下图依次点击`
slideTitle	滑块/旋转模式标题，默认 `请拖动滑块完成拼图`
confirmButton	点选确认按钮，默认 `确认`
buttonText	触发按钮文案，默认 `点击按键进行验证`
userCancel	用户取消提示，默认 `用户取消`
loading	加载中文案，默认 `加载中...`

ThemeTokens

属性	说明	默认值
primaryColor	主题色	`#347eff`
backgroundColor	弹窗背景色	`#ffffff`
textColor	文本颜色	`#333333`
borderColor	边框颜色	`#e2e2e2`
borderRadius	圆角大小	`4`

二次验证（S2S）

前端完成验证后，onSuccess(data) 回调中的 data 会包含一个 second_key。你应该将此参数随表单提交到业务后台，再由业务后台向验证码服务端发起二次验证：

curl -X GET \
  https://您的验证码域名/api/v1/captchas/states/{second_key} \
  -H "Authorization: Bearer <API_KEY>"

如果返回 {"valid": true} 则代表验证通过，可以放行业务逻辑。