Slider Captcha 技术文档

2026-02-04 05:15:46作者：幸俭卉

1. 安装指南

1.1 依赖项

需要引入 font-awesome 图标库

1.2 引入资源文件

在HTML文件的<head>标签中添加CSS样式表：

<link href="https://cdn.bootcss.com/font-awesome/5.7.2/css/all.min.css">
<link href="./src/slidercaptcha.css">

在页面底部</body>标签前添加JavaScript文件：

<script src="./src/longbow.slidercaptcha.js"></script>

2. 项目使用说明

2.1 基础使用

在HTML中添加一个容器元素：

<div id="captcha"></div>

初始化滑块验证码：

<script>
    sliderCaptcha({
        id: 'captcha'
    });
</script>

2.2 高级配置

sliderCaptcha({
    id: 'captcha',
    width: 280,          // 背景图宽度
    height: 150,         // 背景图高度
    sliderL: 42,         // 拼图宽度
    sliderR: 9,          // 拼图突出半径
    offset: 5,           // 验证误差容错偏差(默认5px)
    loadingText: '加载中...',
    failedText: '验证失败',
    barText: '向右滑动完成验证',
    repeatIcon: 'fa fa-redo',  // 刷新图标
    setSrc: function() {        // 图片加载路径
        return 'https://picsum.photos/?image=random';
    },
    onSuccess: function() {    // 验证成功回调
        console.log('验证成功');
    },
    onFail: function() {       // 验证失败回调
        console.log('验证失败');
    },
    onRefresh: function() {    // 刷新回调
        console.log('刷新验证码');
    }
});

3. 项目API使用文档

3.1 配置选项

参数名	类型	默认值	说明
width	整数	280	背景图片宽度
height	整数	150	背景图片高度
sliderL	整数	42	拼图宽度
sliderR	整数	9	拼图突出半径
offset	整数	5	验证误差容错偏差
loadingText	字符串	"Loading..."	图片加载时显示的文本
failedText	字符串	"Try again"	验证失败时显示的文本
barText	字符串	"Slide right to fill"	滑块准备拖动时显示的文本
repeatIcon	字符串	"fa fa-redo"	刷新图标(依赖font-awesome)
setSrc	函数	返回随机图片URL	设置图片加载路径
onSuccess	函数	null	验证成功回调函数
onFail	函数	null	验证失败回调函数
onRefresh	函数	null	刷新验证码回调函数

3.2 方法

var captcha = sliderCaptcha({ id: 'captcha' });
captcha.reset();  // 重置验证码

3.3 服务器端验证

客户端代码示例

verify: function(arr, url) {
    var ret = false;
    $.ajax({
        url: url,
        data: JSON.stringify(arr),
        async: false,
        cache: false,
        type: 'POST',
        contentType: 'application/json',
        dataType: 'json',
        success: function(result) {
            ret = result;
        }
    });
    return ret;
}

.NET Core WebApi 示例

[Route("api/[controller]")]
[ApiController]
[AllowAnonymous]
public class CaptchaController : ControllerBase
{
    [HttpPost]
    public bool Post([FromBody]List<int> datas)
    {
        var sum = datas.Sum();
        var avg = sum * 1.0 / datas.Count;
        var stddev = datas.Select(v => Math.Pow(v - avg, 2)).Sum() / datas.Count;
        return stddev != 0;
    }
}

Java SpringBoot 示例

@RestController
@RequestMapping("/sliderCaptcha")
public class SliderCaptchaController {
    @PostMapping("/isVerify")
    public boolean isVerify(List<Integer> datas) {
        int sum = datas.stream().mapToInt(Integer::intValue).sum();
        double avg = sum * 1.0 / datas.size();
        double sum2 = datas.stream().mapToDouble(data -> Math.pow(data - avg, 2)).sum();
        double stddev = sum2 / datas.size();
        return stddev != 0;
    }
}