Vue Verify Captcha

🔐 Vue 3 验证码组件库 - 支持滑块验证和点选验证

✨ 特性

• 🎯 滑块拼图验证 - 拖动滑块完成拼图验证
• 🖱️ 点选文字验证 - 按顺序点击文字完成验证
• 🎨 自定义样式 - 支持自定义尺寸、颜色等
• 📱 移动端支持 - 完美支持触摸事件
• 🔌 易于集成 - 简单的 API，快速集成到项目中
• 📦 TypeScript 支持 - 完整的类型定义

📦 安装

npm install vue-verify-captcha

或使用 yarn:

yarn add vue-verify-captcha

🚀 快速开始

全局注册

import { createApp } from 'vue'
import App from './App.vue'
import VueVerifyCaptcha from 'vue-verify-captcha'
import 'vue-verify-captcha/dist/style.css'

const app = createApp(App)
app.use(VueVerifyCaptcha)
app.mount('#app')

局部引入

<template>
  <div>
    <button @click="showCaptcha">显示验证码</button>
    <VueVerifyCaptcha
      ref="captchaRef"
      :api-config="apiConfig"
      captcha-type="blockPuzzle"
      mode="pop"
      @success="handleSuccess"
      @error="handleError"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { VueVerifyCaptcha } from 'vue-verify-captcha'
import 'vue-verify-captcha/dist/style.css'
import axios from 'axios'

const captchaRef = ref(null)

// API 配置
const apiConfig = {
  getUrl: '/api/captcha/get',
  checkUrl: '/api/captcha/check',
  request: axios // 传入 axios 实例
}

// 显示验证码
const showCaptcha = () => {
  captchaRef.value?.show()
}

// 验证成功
const handleSuccess = (data) => {
  console.log('验证成功', data)
  // data.captchaVerification 是验证凭证，传给后端
}

// 验证失败
const handleError = (error) => {
  console.log('验证失败', error)
}
</script>

📖 API 文档

Props

| 参数 | 说明 | 类型 | 必填 | 默认值 | |------|------|------|------|--------| | apiConfig | API 配置对象 | ApiConfig | 是 | - | | captchaType | 验证码类型 | 'blockPuzzle' | 'clickWord' | 是 | - | | mode | 显示模式 | 'pop' | 'fixed' | 否 | 'pop' | | title | 标题 | string | 否 | '请完成安全验证' | | imgSize | 图片尺寸 | { width: string, height: string } | 否 | { width: '310px', height: '155px' } | | barSize | 滑块条尺寸 | { width: string, height: string } | 否 | { width: '310px', height: '40px' } | | explain | 提示文字 | string | 否 | '向右滑动完成验证' |

ApiConfig

interface ApiConfig {
  getUrl: string        // 获取验证码的接口地址
  checkUrl: string      // 校验验证码的接口地址
  request?: any         // axios 实例或其他请求库实例
  config?: any          // 额外的请求配置
}

Events

| 事件名 | 说明 | 回调参数 | |--------|------|----------| | success | 验证成功时触发 | (data: { captchaVerification: string }) => void | | error | 验证失败时触发 | (error: any) => void | | ready | 验证码加载完成时触发 | () => void |

Methods

| 方法名 | 说明 | 参数 | |--------|------|------| | show | 显示验证码（仅 pop 模式） | - | | closeBox | 关闭验证码（仅 pop 模式） | - | | refresh | 刷新验证码 | - |

📝 使用示例

滑块拼图验证（弹窗模式）

<template>
  <div>
    <el-button @click="showCaptcha">点击验证</el-button>
    <VueVerifyCaptcha
      ref="captchaRef"
      :api-config="apiConfig"
      captcha-type="blockPuzzle"
      mode="pop"
      title="安全验证"
      :img-size="{ width: '310px', height: '155px' }"
      :bar-size="{ width: '310px', height: '40px' }"
      @success="onSuccess"
      @error="onError"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import axios from 'axios'

const captchaRef = ref(null)

const apiConfig = {
  getUrl: '/api/captcha/get',
  checkUrl: '/api/captcha/check',
  request: axios
}

const showCaptcha = () => {
  captchaRef.value?.show()
}

const onSuccess = (data) => {
  console.log('验证成功，凭证：', data.captchaVerification)
  // 将 data.captchaVerification 传给后端进行二次验证
}

const onError = (error) => {
  console.error('验证失败', error)
}
</script>

点选文字验证（固定模式）

<template>
  <div>
    <VueVerifyCaptcha
      :api-config="apiConfig"
      captcha-type="clickWord"
      mode="fixed"
      title="请依次点击文字"
      @success="onSuccess"
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'
import axios from 'axios'

const apiConfig = {
  getUrl: '/api/captcha/get',
  checkUrl: '/api/captcha/check',
  request: axios
}

const onSuccess = (data) => {
  console.log('验证成功', data)
}
</script>

自定义样式

<template>
  <VueVerifyCaptcha
    ref="captchaRef"
    :api-config="apiConfig"
    captcha-type="blockPuzzle"
    mode="pop"
    :img-size="{ width: '400px', height: '200px' }"
    :bar-size="{ width: '400px', height: '50px' }"
    explain="拖动滑块完成验证"
    @success="onSuccess"
  />
</template>

🔧 后端接口说明

获取验证码接口

请求：

GET /api/captcha/get?captchaType=blockPuzzle

响应：

{
  "repCode": "0000",
  "repData": {
    "originalImageBase64": "data:image/png;base64,...",
    "jigsawImageBase64": "data:image/png;base64,...",
    "token": "验证码token",
    "secretKey": "加密密钥"
  },
  "repMsg": "成功"
}

校验验证码接口

请求：

POST /api/captcha/check
Content-Type: application/json

{
  "captchaType": "blockPuzzle",
  "pointJson": "加密后的坐标数据",
  "token": "验证码token"
}

响应：

{
  "repCode": "0000",
  "repData": {
    "captchaVerification": "验证凭证"
  },
  "repMsg": "验证成功"
}

🔒 安全说明

1. 前端验证只是第一道防线，必须在后端进行二次验证
2. 验证成功后返回的 captchaVerification 应该传给后端
3. 后端应该验证 captchaVerification 的有效性
4. 建议使用 HTTPS 传输验证数据

🛠️ 开发

# 克隆项目
git clone https://github.com/yourusername/vue-verify-captcha.git

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📮 联系方式

• 作者：Your Name
• 邮箱：[email protected]
• 项目地址：https://github.com/yourusername/vue-verify-captcha

🙏 致谢

感谢所有为这个项目做出贡献的开发者！