多端滑块验证码插件 zxj-slide-verify 使用指南

插件地址：DCloud 插件市场 - 多端滑块验证码组件
支持 H5、微信/支付宝小程序、Android/iOS App、鸿蒙，Canvas 按端自动选用稳定方案。

---

一、为什么背景图、缺口图、缺口 Y 轴要后端返回？

滑块验证码要同时解决两件事：防机器 和 和具体用户/操作绑定。所以图片和缺口位置不能前端自己“拍脑袋”生成，必须由后端统一生成并下发。

1. 后端生成并绑定会话

• 背景图（backgroundImg）
  每次验证都是一次新的“题目”。后端随机选一张图（或按规则生成），在图上随机挖一个缺口，把这张背景图和本次验证的会话（或手机号、请求标识） 存起来。前端只负责展示和收集用户滑动的结果。

• 缺口图（sliderImg）
  就是被挖下来的那一小块图。缺口图和背景图必须来自同一次生成，否则对不上。所以缺口图也只能由后端在“挖缺口”时一并生成，以 base64 等形式和背景图一起返回给前端。

• 缺口 Y 轴（blockY / captchaY）
  缺口在背景图上的垂直位置是后端挖图时定的。前端需要知道这个 Y，才能把缺口块画在正确的高度，用户看到的拼图才能严丝合缝。同时，后端自己知道“正确答案的 X 坐标”是多少，用户提交的 left 之后会跟这个正确答案做容差比对。

2. 和“当前登录手机号”等绑定是什么意思？

典型流程是：

1. 用户输入手机号，点击“获取验证码”或“登录”。
2. 后端为这个手机号 + 这次请求生成一套滑块数据：背景图、缺口图、缺口 Y、以及内部保存的“正确 X”。
3. 前端展示这套图，用户滑动，把得到的 left（和手机号、验证码等）一起提交。
4. 后端校验：
   • 这张图是不是我发给这个手机号/这次会话的？
   • 用户滑的 left 和正确答案是否在允许误差内？

这样就能把“滑块验证”和“谁在登录、哪一次操作”绑在一起，防止 A 的验证结果被 B 用、或同一张图被重复刷。

小结：背景图、缺口图、缺口 Y 都由后端返回，是为了由服务端出题、服务端判题，并和具体用户/会话绑定，前端只负责展示和上报滑动结果。

---

二、插件简介与特性

• 多端：H5、微信/支付宝小程序、Android/iOS App、鸿蒙。
• Canvas 方案：H5 用 type="2d"，App/鸿蒙/小程序用 canvas-id + createCanvasContext，按端自动选，减少兼容问题。
• 布局：支持 maxWidthRpx 在弹窗内限宽，支持 refreshScale() 在弹窗打开后重新计算缩放。
• 可联动业务：暴露 reset、setSuccess、setFail、refreshScale，方便和登录、表单提交等流程配合。

---

三、安装与基本用法

将 slide-verify.vue 放到工程中（如 components/slide-verify/），按需引入。

<template>
  <SlideVerify
    ref="slideRef"
    :background-img="captchaData.backgroundImg"
    :slider-img="captchaData.sliderImg"
    :block-y="captchaData.captchaY"
    :show-error-mask="showErrorMask"
    slider-text="按住滑块，拖动到合适位置"
    @success="onSuccess"
    @refresh="onRefresh"
  />
</template>

<script setup>
import SlideVerify from '@/components/slide-verify/slide-verify.vue'

const slideRef = ref(null)
const captchaData = ref({ backgroundImg: '', sliderImg: '', captchaY: 70 })
const showErrorMask = ref(false)

const onSuccess = (left) => {
  console.log('滑动结束，x 坐标(取整):', left)
  // 将 left 传给后端校验
}

const onRefresh = () => {
  // 重新请求验证码接口，更新 captchaData
}

// 验证失败时
slideRef.value?.setFail?.()
showErrorMask.value = true

// 刷新/重试时
showErrorMask.value = false
slideRef.value?.reset?.()
</script>

---

四、参数说明（Props）

属性	类型	默认值	说明
w	Number	500	画布宽度(px)
h	Number	250	画布高度(px)
blockX	Number	155	拼图块逻辑 x（一般由后端给出）
blockY	Number	70	拼图块垂直位置，与后端返回的 captchaY 一致
sliderText	String	按住滑块，拖动到合适位置	滑块提示文案
backgroundImg	String	‘’	背景图 base64 或 data URL
sliderImg	String	‘’	拼图块图 base64 或 data URL
showErrorMask	Boolean	false	是否显示“验证失败”遮罩
errorText	String	验证失败，请根据提示重新操作	失败提示文案
maxWidthRpx	Number	0	最大宽度(rpx)，弹窗内可传 536 等避免超出

使用要点：

• backgroundImg、sliderImg、blockY 从你的验证码接口里取，和上文“后端返回”对应。
• 弹窗里用建议设 maxWidthRpx（如 536），避免宽度溢出。

---

五、事件（Events）

事件名	说明	回调参数
success	用户松手完成滑动	left: number（取整后的 x 坐标）
refresh	用户点击刷新图标	-

• success：在这里把 left 和手机号、验证码等一并提交给后端校验。
• refresh：在这里重新调验证码接口，拿到新的 backgroundImg、sliderImg、captchaY 等，再更新 captchaData。

---

六、方法（ref 调用）

方法	说明
reset()	重置滑块与画布，并重新绘制当前 backgroundImg/sliderImg
refreshScale()	重新计算缩放（如弹窗打开后调用）
setSuccess()	设为成功状态（绿色）
setFail()	设为失败状态（红色）

• 后端校验失败：slideRef.value?.setFail?.()，并设 showErrorMask = true，让用户重滑或点刷新。
• 用户点刷新或你主动重试：先 showErrorMask = false，再 slideRef.value?.reset?.()，必要时重新请求验证码接口再 refreshScale()。

---

七、弹窗内使用建议

弹窗内建议限宽 + 打开后刷新缩放，避免超出或比例不对：

<SlideVerify
  ref="slideRef"
  :max-width-rpx="536"
  :background-img="captchaData.backgroundImg"
  :slider-img="captchaData.sliderImg"
  :block-y="captchaData.captchaY"
  @success="onSuccess"
  @refresh="onRefresh"
/>

弹窗打开后调用：

slideRef.value?.refreshScale?.()

---

八、小结

• 为什么后端返回背景图、缺口图、缺口 Y：由后端出题、判题，并和手机号/会话绑定，防止伪造和复用。
• 插件：多端统一、Canvas 按端适配、支持弹窗限宽与缩放刷新，通过 props/事件/ref 方法即可和现有登录流程无缝对接。

如有需要可到 插件详情页 下载或查看最新文档与评论。