更新记录

1.1.1（2026-10-12） 下载此版本

1. 同步 README 使用说明、Props 和示例代码，统一补充 theme 用法
2. 本次仅文档更新，不改变组件运行行为和 1.1.0 暗色适配逻辑

1.1.0（2026-10-12） 下载此版本

1. 新增 theme 属性（light / dark，默认 light），由外部传入主题
2. 暗色模式下默认适配弹窗主体背景、标题、提示文字和底部滑动条
3. 自定义 wrapColor 时仍优先使用外部值，默认 light 行为不变

1.0.0（2026-08-31） 下载此版本

1. 首次发布：滑块拼图验证码组件，支持自定义验证图片、滑块大小与颜色、遮罩与主体颜色
2. 验证误差范围可调（between），支持底部滑动条及底部滑块自定义
3. 文案支持外部传入（title/tips/closeText），方便国际化展示，未传入时使用内置默认文案
4. 支持成功（success）、失败（error）、关闭（close）事件，以及 show/hide 实例方法

平台兼容性

uni-app(5.24)

其他

Drag Verify 滑动验证码

一款基于 uni-app（Vue3）的滑块拼图验证码组件。通过拖动滑块到指定位置完成人机校验，支持自定义验证图片、滑块样式、验证误差范围、底部滑动条，以及文案国际化配置，开箱即用。

🚀 功能特性

• ✅ 滑块拼图验证：拖动滑块与图片缺口位置匹配即通过，验证误差范围可调（between）
• ✅ 自定义验证图片：通过 verifyImg 传入任意图片，不传使用组件内置默认图
• ✅ 文案可配置（国际化）：标题、提示、关闭按钮文案均可传入，未传入时使用内置默认文案
• ✅ 样式可配置：滑块大小/颜色、遮罩色、主体背景色、底部滑块大小/颜色均可配置
• ✅ 底部滑动条：可开关底部滑动条（showBottomSlider）
• ✅ 完整事件：验证成功（success）、验证失败（error）、弹窗关闭（close）
• ✅ 实例方法：show() 打开验证弹窗、hide() 主动关闭
• ✅ 主题模式：支持 theme="light" / "dark"，由外部传入主题
• ✅ 多端适配：触摸事件支持移动端，鼠标事件支持 H5 桌面端

📦 安装引入

1. 将 uni_modules/drag-verify 整个目录复制到项目的 uni_modules 目录下；
2. 开启 easycom 时可直接使用 <drag-verify> 标签，无需手动引入；
3. 若未开启 easycom，可在页面中手动引入：

<script setup>
import DragVerify from "@/uni_modules/drag-verify/components/drag-verify/drag-verify.vue";
</script>

🚀 快速开始

<template>
  <view>
    <button @click="openVerify">点击验证</button>

    <drag-verify
      ref="dragVerifyRef"
      :theme="theme"
      title="安全验证"
      tips="请将滑块拖到指定位置完成验证"
      close-text="关闭"
      @success="successHandle"
      @error="errorHandle"
      @close="closeHandle"
    />
  </view>
</template>

<script setup>
import { ref } from "vue";

const dragVerifyRef = ref(null);
const theme = "dark"; // light / dark

// 打开验证弹窗
function openVerify() {
  dragVerifyRef.value?.show();
}

// 验证通过
function successHandle(msg) {
  console.log("验证通过：", msg);
}

// 验证失败（组件会自动重新初始化，可再次尝试）
function errorHandle(msg) {
  console.log("验证失败：", msg);
}

// 弹窗关闭
function closeHandle(msg) {
  console.log("弹窗关闭：", msg);
}
</script>

🔧 Props 属性配置

📡 事件

各事件的回调参数均为固定字符串，非对象，可直接使用或打印。

ℹ️ 验证成功时事件顺序：组件自动关闭弹窗，先触发 close 再触发 success；点击右上角关闭则仅触发 close。close 每次只触发一次。如需在 close 回调中执行跳转等副作用，请留意其先于 success 执行。

🎯 组件方法

通过 ref="dragVerifyRef" 获取组件实例后调用：

<script setup>
import { ref } from "vue";

const dragVerifyRef = ref(null);

// 打开验证弹窗
function openVerify() {
  dragVerifyRef.value?.show();
}

// 关闭验证弹窗（内部走关闭逻辑，会触发 close 事件）
function closeVerify() {
  dragVerifyRef.value?.hide();
}
</script>

Vue3 <script setup> 下使用 ref 获取组件实例；调用 hide() 内部实际执行关闭逻辑，同样会触发 close 事件。

🌍 国际化说明

组件标题、提示、关闭按钮文案支持外部传入，配合业务方 i18n 实现多语言展示：

<!-- 传入国际化文案 -->
<drag-verify
  :title="t('verify.title')"
  :tips="t('verify.tips')"
  :close-text="t('common.close')"
/>

文案优先级（从高到低）：

1. props 传入的 title / tips / closeText
2. 组件内置默认中文文案

🎨 样式自定义

组件为弹窗式全屏展示，内置样式类可在外部覆盖：

⚠️ 覆盖方式：组件样式为 scoped，外部页面直接写同名类选择器无法命中组件内部元素，需使用 :deep() 穿透或写入全局（非 scoped）样式：

<style lang="scss" scoped>
:deep(.zmdrag-verify-wrap) {
  background-color: #f5f5f5;
}
</style>

⚠️ 使用注意事项

1. 调用方式：组件默认隐藏，需通过 ref.show() 打开验证弹窗
2. 验证原理：纯前端校验，滑块位置与随机缺口在 between 容差内即通过，如需后端强校验请在 success 事件后自行请求服务端
3. 验证图片：建议使用与缺口风格一致的图片；传入网络图片需保证可访问；使用默认图时请勿删除插件 static/Verify.jpg
4. 误差范围：between 越大越容易通过，建议根据实际使用场景调整（默认 10px）
5. 平台兼容：触摸事件支持 App/H5/小程序，鼠标拖拽（PC）仅 H5 生效；组件使用 document 仅在 H5 鼠标事件中调用，其他端不受影响
6. nvue 平台：组件使用 rpx/px 混合布局与 scoped scss，建议在 app-vue/H5/小程序中使用，nvue 需自行验证
7. 失败反馈：验证失败会自动重新初始化滑块位置，同时弹出 tips 文案的 toast 提示
8. 避免与组件标签同名：页面（<script setup>）内不要定义与标签同名的局部变量或函数（如 dragVerify）。Vue 编译时局部变量优先于 easycom 组件，此时 <drag-verify> 会被解析成该局部函数，组件并未真正注册，调用 dragVerifyRef.value.show() 会报 dragVerifyRef.value?.show is not a function。请使用 openVerify、openDragVerify 等不与标签冲突的命名；若确需同名，则改为在页面中显式 import 组件，并通过局部注册的方式引入

📞 更新日志

v1.1.1（2026-10-12）

• 📝 同步 README 使用说明、Props 和示例代码，统一补充 theme 用法
• 本次仅文档更新，不改变组件运行行为和 1.1.0 暗色适配逻辑

v1.1.0（2026-10-12）

• 🆕 新增 theme 属性（light / dark，默认 light），由外部传入主题
• 🌓 暗色模式下默认适配弹窗主体背景、标题、提示文字和底部滑动条
• 兼容性：自定义 wrapColor 优先，默认 light 行为不变

v1.0.0（2026-08-31）

• 🎉 首个版本发布，支持：滑块拼图验证、自定义验证图片、滑块与弹窗样式配置、误差范围调节、底部滑动条、文案国际化配置、成功/失败/关闭事件与 show/hide 方法

祝您使用愉快！ 🎉