智能复选框 (CheckboxCaptcha)

仿 Cloudflare Turnstile 风格的轻量级组件。用户通常只需点击一下复选框即可完成验证。

交互流程

1. 用户点击复选框。
2. 组件显示“验证中...”，并在此期间在后台进行环境安全检测。
3. 验证通过后，自动显示绿色对勾；若失败，提示用户刷新重试。

基础用法

const checkbox = new WlzShield.CheckboxCaptcha({
    containerId: '#login-captcha',
    width: 300,
    height: 60,
});

在线体验

您可以直接在这里体验智能复选框的交互效果：

样式定制

组件支持高度的样式定制，以完美融入您的 UI 设计系统。

new WlzShield.CheckboxCaptcha({
    containerId: '#captch-box',
    challengeUrl: '/api/verify',
    // 样式配置
    width: 300,                  // 宽度 (支持数字或 '100%')
    height: 60,                  // 高度
    backgroundColor: '#f9f9f9',  // 背景色
    textColor: '#333333',        // 文字颜色
    borderColor: '#cccccc',      // 边框颜色
    progressBarColor: '#3b82f6', // 加载圆环颜色
    borderRadius: 8              // 圆角大小
});

配置参数 (API)

基础配置

参数名	类型	默认值	说明
containerId	string	-	必填。DOM 容器 ID (如 #captcha-box)。
challengeUrl	string	'/api/challenge'	后端验证接口地址。
width	number|string	300	组件宽度。支持数字(px)或百分比字符串(如 '100%')。
height	number	60	组件高度。
lang	string	'zh'	自动

样式与配置

参数名	类型	默认值	说明
backgroundColor	string	'#ffffff'	背景颜色。
textColor	string	'#222222'	文字颜色。
borderColor	string	'#e0e0e0'	边框颜色。
borderRadius	number	14	圆角大小。
progressBarColor	string	'#000000'	加载中圆环的颜色。

提示

当 height 发生变化时，组件内部的图标和文字大小会自动根据比例缩放 (scale)，无需手动调整字体大小。

实例方法

setReset()

当您的业务逻辑需要重置验证码时（例如：用户提交表单后，后端报错提示密码错误，此时需要重置验证码以便用户再次尝试），可调用此方法。

// 1. 保存实例引用
const myCaptcha = new WlzShield.CheckboxCaptcha({...});

// 2. 在需要的时候调用
function handleFormError() {
    // 重置为 "我是人类" 的初始状态
    myCaptcha.setReset();
}

回调事件

事件名	参数	说明
onSuccess	(data: object) => void	验证成功时触发。data 包含后端返回的校验凭证。
onFailure	(data: object) => void	验证失败时触发（如网络错误、校验不通过）。
onError	(error: Error) => void	组件内部发生脚本错误或配置错误时触发。

new WlzShield.CheckboxCaptcha({
    // ...
    onSuccess: (data) => {
        // data 包含后端返回的完整响应
        console.log('验证成功:', JSON.stringify(data));
    },
    onFailure: (data) => {
        // data 包含后端返回的完整响应
        console.error('验证失败:', JSON.stringify(data));
    },
    onError: (err) => {
        // 捕获脚本错误或网络配置错误
        console.error('系统错误:', err);
    }
})