刮刮乐验证码 (ScratchCaptcha)

这是一个基于 HTML5 Canvas 的沉浸式验证组件。用户通过模拟真实的“刮奖”行为完成人机验证，趣味性强，难以被脚本模拟。

玩法说明

组件包含两种随机出现的玩法模式，用户无需学习，依提示操作即可：

1. 玩法一（找奖金）：

   • 用户刮开涂层。
   • 直接寻找显示奖金金额的数字。
   • 点击所有中奖项即可通过。

2. 玩法二（对数字）：

   • 用户刮开涂层。
   • 查看顶部的“中奖号码”。
   • 在下方区域寻找与中奖号码一致的“我的号码”。

注意：所有交互均在安全沙箱中进行，系统会自动判断用户是否刮开了足够面积以及点击了正确的目标。

基础用法

const captcha = new WlzShield.ScratchCaptcha({
    containerId: '#captch-box',
    width: 340,
    height: 640
});

在线体验

尝试刮开下方的涂层完成验证：

配置参数 (API)

基础配置

参数名	类型	默认值	说明
containerId	string	-	必填。DOM 容器 ID (如 #captcha-box)。
challengeUrl	string	'/api/challenge'	后端验证接口地址。
width	number	340	组件宽度。
height	number	640	组件高度。
lang	string	'zh'	自动

样式配置

参数名	类型	默认值	说明
maskColor	string	'#bdc3c7'	刮奖涂层的颜色。
radius	number	20	刮奖笔触的半径（粗细）。

规则配置

参数名	类型	默认值	说明
threshold	number	0.9	全局刮开面积比例阈值 (0~1)。
thresholdMode1	number	-	单独指定“玩法一”的刮开阈值，优先级高于 threshold。
thresholdMode2	number	-	单独指定“玩法二”的刮开阈值，优先级高于 threshold。

文案自定义 (可选)

您可以覆盖默认文案以适应您的品牌调性：

参数名	类型	默认值 (zh)	说明
textTitle	string	"点击刮刮乐"	顶部大标题
textRule1	string	"▲ 玩法一：刮开覆盖膜..."	玩法一说明
textRule2Win	string	"▼ 中奖号码"	玩法二：中奖号标题
textRule2My	string	"我的号码 ▼"	玩法二：我的号标题
tipDefault	string	"1. 刮开涂层..."	初始提示语
tipFound	string	"已找到所有中奖项..."	找到所有奖项提示

回调事件

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

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

自定义渲染 (高级)

如果您需要深度的品牌定制，可以使用以下高级渲染钩子：

new WlzShield.ScratchCaptcha({
    // ...其他配置

    // 自定义背景绘制（可绘制图片、渐变等）
    renderBackground: (ctx, w, h) => {
        // ctx 为 CanvasRenderingContext2D 对象
        ctx.fillStyle = '#ff0000';
        ctx.fillRect(0, 0, w, h);
    },

    // 自定义标题绘制
    renderTitle: (ctx, w, h) => {
        ctx.font = '20px Arial';
        ctx.fillText('品牌安全验证', 20, 50);
    }
});