Captcha 验证码

avue-captcha 提供本地交互式验证码。它适用于前端体验校验，不能替代服务端的风控、令牌签发与二次校验。

基础用法

通过 v-model 获取验证状态，验证成功、失败和刷新时可分别处理业务逻辑。

效果预览可直接操作下方示例

正在加载示例…

<template>
  <el-space wrap style="margin-bottom: 16px">
    <el-radio-group v-model="type">
      <el-radio-button v-for="item in types" :key="item.value" :label="item.value">
        {{ item.label }}
      </el-radio-button>
    </el-radio-group>
    <el-button @click="captchaRef?.reset()">重置验证码</el-button>
  </el-space>

  <avue-captcha
    ref="captchaRef"
    v-model="passed"
    :type="type"
    :target-text="['诚', '信']"
    :background-image="backgroundImage"
    :code-length="4"
    code-characters="23456789ABCDEFGHJKLMNPQRSTUVWXYZ"
    @success="handleSuccess"
    @fail="handleFail"
  />

  <p>验证状态：{{ passed ? '已通过' : '未通过' }}</p>
</template>

<script setup>
import { ref } from 'vue'
import { ElMessage } from 'element-plus'

const captchaRef = ref()
const passed = ref(false)
const type = ref('slider')
const types = [
  { label: '滑动拼图', value: 'slider' },
  { label: '文字点选', value: 'text' },
  { label: '算术验证', value: 'math' },
  { label: '旋转校正', value: 'rotate' },
  { label: '图标点选', value: 'icon' },
  { label: '顺序点选', value: 'sequence' },
  { label: '拖拽匹配', value: 'drag' },
  { label: '字母数字', value: 'code' },
  { label: '轨迹滑动', value: 'path' }
]
const backgroundImage = 'data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 400"%3E%3Cdefs%3E%3ClinearGradient id="g" x1="0" x2="1" y1="0" y2="1"%3E%3Cstop stop-color="%235b9dff"/%3E%3Cstop offset="1" stop-color="%23c3e7ff"/%3E%3C/linearGradient%3E%3C/defs%3E%3Crect width="800" height="400" fill="url(%23g)"/%3E%3Ccircle cx="130" cy="95" r="55" fill="%23fff" fill-opacity=".18"/%3E%3Ccircle cx="650" cy="310" r="90" fill="%23fff" fill-opacity=".15"/%3E%3C/svg%3E'

function handleSuccess() {
  ElMessage.success('验证通过')
}

function handleFail({ message }) {
  ElMessage.warning(message)
}
</script>

验证类型

type 支持 slider、text、math、rotate、icon、sequence、drag、code、path。不同类型会使用对应的配置，例如文字点选使用 targetText，算术题可通过 mathQuestion、mathAnswer 与 mathOptions 指定题目。

Attributes

参数	说明	类型	默认值
modelValue / v-model	是否验证通过	boolean	false
type	验证类型	string	slider
width	验证区域宽度，推荐数字或百分比	number / string	320
height	验证场景高度，最小按 96px 处理	number	160
pieceSize / tolerance	拼图尺寸与校验容差	number	42 / 6
sliderTargetCount	拼图目标数量	number	2
rotateStep	旋转验证每次旋转的角度	number	30
image / backgroundImage	背景图片地址	string	''
backgroundSize / backgroundPosition	背景图显示方式	string	cover / center
targetText / textPool / textOptionCount	文字点选目标、候选池和候选数量；前两项均可传字符串或数组	string 或 array / number	空目标 / 内置字池 / 8
targetIcon / iconPool / iconOptionCount	图标点选目标、候选池和候选数量	string / array / number	空目标 / 内置图标池 / 6
sequenceLength	顺序点选数量	number	3
dragTolerance	拖拽匹配容差	number	16
mathQuestion / mathAnswer / mathOptions	算术题题目、答案和候选项；答案支持数字或字符串	string / number 或 string / array	空题目 / 未定义 / []
mathOptionCount	自动生成的算术候选项数量	number	4
codeLength / codeCharacters / codeCaseSensitive	字母数字验证码配置	number / string / boolean	4 / 23456789ABCDEFGHJKLMNPQRSTUVWXYZ / false
disabled	是否禁用	boolean	false
autoRefresh / refreshDelay	失败后是否自动刷新及延迟时间（ms）	boolean / number	true / 900

Events

事件名	说明	参数
update:modelValue	同步是否通过	boolean
change	验证状态变化	{ value, type }
success	验证通过	{ type }
fail	验证失败	{ type, message }
refresh	刷新验证内容	{ type }

Methods

通过组件 ref 调用。

方法名	说明
refresh	刷新验证码内容
reset	重置验证状态和验证码内容
verify	主动校验答案，仅适用于 math 和 code 类型；参数为答案或输入的验证码

安全提示

前端验证码的结果可被篡改。生产环境应由服务端生成挑战、校验用户行为并在校验成功后签发一次性凭证。

backgroundImage 优先于 image。当前验证码在本地生成随机挑战，verify(value) 通过 success / fail / change 反馈结果，不返回校验 Promise 或布尔结果。refresh() 与 reset() 都会重新生成内容并清空通过状态；组件没有插槽。