update readme.md

readme.md

@@ -1,7 +1,8 @@
  这是一个滑块验证码的实现
 ## [在线体验](https://www.tianai.cloud)
 ## 验证码demo移步 [tianai-captcha-demo](https://gitee.com/tianai/tianai-captcha-demo)
-## 不说废话，直接上成品
+
+
 ![](image/1.png)
 ![](image/2.png)
 ![](image/3.png)
@@ -15,7 +16,9 @@
 
 ##  快速上手
 - 如果是SpringBoot开发者可直接使用SpringBoot快速启动器[tianai-captcha-springboot-starter](https://gitee.com/tianai/tianai-captcha-springboot-starter)
-1. 导入xml
+
+### 1. 导入xml
+
 ```xml
     <!-- maven 导入 -->
     <dependency>
@@ -24,46 +27,76 @@
         <version>1.2.7</version>
     </dependency>
 ```
-2. 使用 `SliderCaptchaTemplate`获取滑块验证码
+### 2. 使用 `SliderCaptchaTemplate`获取滑块验证码
+
 ```java
 public static void main(String[] args) throws InterruptedException {
     SliderCaptchaResourceManager sliderCaptchaResourceManager = new DefaultSliderCaptchaResourceManager();
     StandardSliderCaptchaTemplate sliderCaptchaTemplate = new StandardSliderCaptchaTemplate(sliderCaptchaResourceManager, true);
     // 生成滑块图片
     SliderCaptchaInfo slideImageInfo = sliderCaptchaTemplate.getSlideImageInfo();
-    // 获取背景图片的base64
-    String backgroundImage = slideImageInfo.getBackgroundImage();
-    // 获取滑块图片
-    slideImageInfo.getSliderImage();
-    
     System.out.println(slideImageInfo);
     
-    // 计算滑块到凹槽的百分比，用户存到缓存中供校验使用
+    // 负责计算一些数据存到缓存中，用于校验使用
+    // SliderCaptchaValidator负责校验用户滑动滑块是否正确和生成滑块到凹槽的百分比值
     SliderCaptchaValidator sliderCaptchaValidator = new BasicCaptchaTrackValidator();
-    // 滑块的百分比
+    // 计算滑块到凹槽的百分比，用户存到缓存中供校验使用
     float percentage = sliderCaptchaValidator.calcPercentage(slideImageInfo.getX(), SliderCaptchaInfo.getBgImageWidth());
-    
+	// 这个map数据应该存到缓存中，校验的时候需要用到该数据
-    // 校验
+    Map<String, Object> map = new HashMap<>(4);
-    
+    map.put("percentage", percentage);
-    // 用户传来的百分比和滑块的百分比校验是否正确，如果正确的话说明移动到了指定凹槽
+    // map中可添加自定义数据用于自定义逻辑校验
-    boolean check =sliderCaptchaValidator.checkPercentage(0.2f, percentage);
-    // 用户传来的行为轨迹和滑动百分比进行校验，(有了滑动行为轨迹校验，是对 checkPercentage(..)方法的增强,建议使用这个方法进行校验 )
-    check = sliderCaptchaValidator.valid(sliderCaptchaTrack, percentage);
-    
 }
 ```
-# 常用接口
+### 3. 使用`SliderCaptchaValidator`校验
-- 自定义 `SliderCaptchaValidator` 校验器
+
 ```java
-// 该接口负责对用户滑动验证码后传回的数据进行校验，比如滑块是否滑到指定位置，滑块行为轨迹是否正常等等
+SliderCaptchaValidator sliderCaptchaValidator = new BasicCaptchaTrackValidator();
-// 该接口的默认实现有 
+
-// SimpleSliderCaptchaValidator 校验用户是否滑到了指定缺口处
+// 用户传来的行为轨迹和进行校验 
-// BasicCaptchaTrackValidator 是对 SimpleSliderCaptchaValidator增强
+// - sliderCaptchaTrack为前端传来的滑动轨迹数据
-// BasicCaptchaTrackValidator是对SimpleSliderCaptchaValidator的增强 对滑动轨迹进行了简单的验证
+// - map 为生成验证码时缓存的map数据
-// 友情提示 因为BasicCaptchaTrackValidator 里面校验滑动轨迹的算法已经开源，有强制要求的建议重写该接口的方法，避免被破解
+boolean check = sliderCaptchaValidator.valid(sliderCaptchaTrack, map);
+// 如果只想校验用户是否滑到指定凹槽即可，也可以使用
+// - 参数1 用户传来的百分比数据
+// - 参数2 生成滑块是真实的百分比数据
+check =sliderCaptchaValidator.checkPercentage(0.2f, percentage);
 ```
-- 添加自定义图片资源
+
-    - 自定义图片资源大小为 590*360 格式为jpg
+# 常用接口
+
+### 生成带有混淆滑块的图片 
+
+```java
+SliderCaptchaResourceManager sliderCaptchaResourceManager = new DefaultSliderCaptchaResourceManager();
+StandardSliderCaptchaTemplate sliderCaptchaTemplate = new StandardSliderCaptchaTemplate(sliderCaptchaResourceManager, true);
+// 生成滑块图片
+SliderCaptchaInfo slideImageInfo = sliderCaptchaTemplate.getSlideImageInfo(GenerateParam.builder()
+                                        .sliderFormatName("jpeg")
+                                        .backgroundFormatName("png")
+                                        // 是否添加混淆滑块
+                                        .obfuscate(true)
+                                        .build());
+```
+
+### 生成webp格式的滑块图片
+
+```java
+SliderCaptchaResourceManager sliderCaptchaResourceManager = new DefaultSliderCaptchaResourceManager();
+StandardSliderCaptchaTemplate sliderCaptchaTemplate = new StandardSliderCaptchaTemplate(sliderCaptchaResourceManager, true);
+// 生成滑块图片
+SliderCaptchaInfo slideImageInfo = sliderCaptchaTemplate.getSlideImageInfo(GenerateParam.builder()
+                                        .sliderFormatName("webp")
+                                        .backgroundFormatName("webp")
+                                        // 是否添加混淆滑块
+                                        .obfuscate(false)
+                                        .build());
+```
+
+### 添加自定义图片资源
+
+- 自定义图片资源大小为 590*360 格式为jpg
+
 ```java
   ResourceStore resourceStore = sliderCaptchaResourceManager.getResourceStore();
   // 添加classpath目录下的 aa.jpg 图片      
@@ -72,12 +105,14 @@ public static void main(String[] args) throws InterruptedException {
   resourceStore.addResource(new Resource(URLResourceProvider.NAME, "http://www.xx.com/aa.jpg"));
   // 内置了通过url 和 classpath读取图片资源，如果想扩展可实现 ResourceProvider 接口，进行自定义扩展
 ```
-- 添加自定义模板资源
+### 添加自定义模板资源
-  - 系统内置了2套模板，可以到QQ群:1021884609 文件中获取更多模板或者自己制作模板
+
-  - 模板图片格式
+- 系统内置了2套模板，可以到QQ群:1021884609 文件中获取更多模板或者自己制作模板
-    - 滑块大小为 110*110 格式为png
+- 模板图片格式
-    - 凹槽大小为 110*110 格式为png
+  - 滑块大小为 110*110 格式为png
-    - 模板大小为 110*360 格式为png，该图为固定格式，是一张纯透明图片
+  - 凹槽大小为 110*110 格式为png
+  - 模板大小为 110*360 格式为png，该图为固定格式，是一张纯透明图片
+
 ```java
   ResourceStore resourceStore = sliderCaptchaResourceManager.getResourceStore();=
   Map<String, Resource> template1 = new HashMap<>(4);
@@ -94,8 +129,30 @@ public static void main(String[] args) throws InterruptedException {
     //为方便快速上手 系统本身自带了一张图片和两套滑块模板，如果不想用系统自带的可以不让它加载系统自带的
     // 第二个构造参数设置为false时将不加载默认的图片和模板
     SliderCaptchaTemplate sliderCaptchaTemplate = new DefaultSliderCaptchaTemplate(sliderCaptchaResourceManager, false);
+ ```
+
+### 自定义 `SliderCaptchaValidator` 校验器
+
+```java
+// 该接口负责对用户滑动验证码后传回的数据进行校验，比如滑块是否滑到指定位置，滑块行为轨迹是否正常等等
+// 该接口的默认实现有 
+// SimpleSliderCaptchaValidator 校验用户是否滑到了指定缺口处
+// BasicCaptchaTrackValidator 是对 SimpleSliderCaptchaValidator增强
+// BasicCaptchaTrackValidator是对SimpleSliderCaptchaValidator的增强 对滑动轨迹进行了简单的验证
+// 友情提示 因为BasicCaptchaTrackValidator 里面校验滑动轨迹的算法已经开源，有强制要求的建议重写该接口的方法，避免被破解
 ```
-- 扩展，对`StandardSliderCaptchaTemplate`增加了缓存模块
+
+### 自定义 `ResourceProvider` 实现自定义文件读取策略， 比如 oss之类的
+
+```java
+  // 实现了 ResourceProvider 后
+  SliderCaptchaResourceManager sliderCaptchaResourceManager = new DefaultSliderCaptchaResourceManager();
+  StandardSliderCaptchaTemplate sliderCaptchaTemplate = new StandardSliderCaptchaTemplate(sliderCaptchaResourceManager, true);
+  // 注册
+  sliderCaptchaResourceManager.registerResourceProvider(new CustomResourceProvider());
+```
+### 扩展，对`StandardSliderCaptchaTemplate`增加了缓存模块
+
 ```java
 public static void main(String[] args) throws InterruptedException {
     // 使用 CacheSliderCaptchaTemplate 对滑块验证码进行缓存，使其提前生成滑块图片
@@ -115,13 +172,5 @@ public static void main(String[] args) throws InterruptedException {
     System.out.println(slideImageInfo);
 }
 ```
-- 自定义 `ResourceProvider` 实现自定义文件读取策略， 比如 oss之类的
 
-```java
-  // 实现了 ResourceProvider 后
-  SliderCaptchaResourceManager sliderCaptchaResourceManager = new DefaultSliderCaptchaResourceManager();
-  StandardSliderCaptchaTemplate sliderCaptchaTemplate = new StandardSliderCaptchaTemplate(sliderCaptchaResourceManager, true);
-  // 注册
-  sliderCaptchaResourceManager.registerResourceProvider(new CustomResourceProvider());
-```
 # qq群: 1021884609