# kite-captcha-vue

**Repository Path**: stary1993/kite-captcha-vue

## Basic Information

- **Project Name**: kite-captcha-vue
- **Description**: Kite Captcha 是一个功能丰富的行为验证码组件，支持滑动、旋转、拼图、文字点击等多种验证方式。该组件基于 Vue3 和 TypeScript 开发，具有良好的类型支持和国际化能力。
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: v0.2.1
- **Homepage**: https://www.npmjs.com/package/kite-captcha-vue
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2025-09-24
- **Last Updated**: 2025-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Vue, Captcha, uni-app, vue3

## README

# Kite Captcha Vue 组件

基于 tianai-captcha 的 Vue3 验证码组件，支持多种验证类型。

## 简介

Kite Captcha 是一个功能丰富的行为验证码组件，支持滑动、旋转、拼图、文字点击等多种验证方式。该组件基于 Vue3 和 TypeScript 开发，具有良好的类型支持和国际化能力。

## 功能特性

- 🎯 **多种验证类型**：
    - 滑动验证 (SLIDER)：用户需要拖动滑块完成拼图验证。
    - 旋转验证 (ROTATE)：用户需要旋转图片到正确位置完成验证。
    - 拼图验证 (CONCAT)：用户需要拖动滑块将图片拼接完整。
    - 文字点击验证 (WORD_IMAGE_CLICK)：用户需要根据提示点击图片中的指定文字。

- 🌍 **国际化支持**：内置多语言支持，可自行扩展。
- 🎨 **动画效果**：集成 animate.css 动画库。
- 📱 **响应式设计**：支持移动端触摸操作，等比例缩放。
- 🌙 **暗黑主题支持**：内置暗黑主题支持。

## 依赖说明

- Vue 3
- TypeScript
- animate.css
- vue-i18n

## 安装

```bash
npm install kite-captcha-vue
```

## 使用方法

### main.ts

```ts
// main.ts
import {createApp} from 'vue'

const app = createApp(App)

import App from './App.vue'
// 导入组件和 i18n
import {i18n, KiteCaptcha, KiteConfigProvider} from "kite-captcha-vue"

// 全局加载css样式
import 'kite-captcha-vue/dist/index.css'
// 全局加载验证码组件
app.component('KiteCaptcha', KiteCaptcha)
// 全局加载配置组件
app.component('KiteConfigProvider', KiteConfigProvider)
// 加载 i18n
app.use(i18n)
app.mount('#app')

```

### App.vue

```vue

<template>
  <div id="app">
    <div class="config-select">
      <label>类型：<select @change="changeType">
        <option value="SLIDER">滑块</option>
        <option value="ROTATE">旋转</option>
        <option value="CONCAT">拼接</option>
        <option value="WORD_IMAGE_CLICK">文字选点</option>
      </select>
      </label>
      <label>语言：<select @change="changeLang">
        <option value="zh_cn">简体中文</option>
        <option value="zh_tw">繁体中文</option>
        <option value="en">English</option>
        <option value="ja">日語</option>
        <option value="ko">한국어</option>

      </select>
      </label>
      <label>主题：<select @change="changeTheme">
        <option value="light">light</option>
        <option value="dark">dark</option>
      </select>
      </label>

    </div>
    <kite-config-provider :locale="locale" :theme="theme">
      <kite-captcha ref="captchaRef" v-model="matchingResultCode"
                    :render-data-api="renderDataApi"
                    :scale="1"
                    :show-close="true"
                    background-image="https://picsum.photos/1920/1080"
                    @matching-data="handleMatchingData"
                    @render-success="handleRenderSuccess">
      </kite-captcha>
    </kite-config-provider>

  </div>
</template>

<script lang="ts" setup>
  import {ref} from 'vue'
  import axios from 'axios'
  import {CaptchaMatchingData} from './index'


  // 响应式数据
  const genUrl = 'http://localhost:8088/captcha/behavior/gen'
  const checkUrl = 'http://localhost:8088/captcha/behavior/check'
  const captchaRef = ref()
  const type = ref('SLIDER')
  const matchingResultCode = ref(null)
  const locale = ref('zh_cn')
  const theme = ref('light')
  const mockData = async () => {
    try {
      // mock示例数据
      const module = await import(`./mock/${type.value.toLowerCase()}_render_data.json`)
      console.log('module', module)
      return module.default.captcha
    } catch (error) {
      console.error('Failed to load mock data:', error)
      // 返回默认数据或空对象
      return {}
    }
  }
  const renderDataApi = async () => {
    // mock
    return mockData()
    // 请求服务接口
    // const res = await axios.get(`${genUrl}?type=${type.value}`)
    // return res.data.captcha
  }
  const handleMatchingData = async (data: CaptchaMatchingData) => {
    console.log('matching-data', data)
    const res = await axios.post(`${checkUrl}`, data)
    matchingResultCode.value = res.data.code
  }

  const handleRenderSuccess = (val: boolean) => {
    console.log('render-success', val)
  }
  const changeLang = (event: Event) => {
    const target = event.target as HTMLSelectElement;
    locale.value = target.value
  }
  const changeTheme = (event: Event) => {
    const target = event.target as HTMLSelectElement;
    theme.value = target.value
  }
  const changeType = (event: Event) => {
    const target = event.target as HTMLSelectElement;
    type.value = target.value
    captchaRef.value?.refresh()
  }
</script>

<style>
  #app {
    text-align: center;
    width: 50%;
    margin: 0 auto;
    font-size: 12px;
    user-select: none;
    -ms-user-select: none;
    -moz-user-select: none;
    -webkit-user-select: none;
  }

  .config-select {
    display: flex;
    justify-content: center;
    align-items: center;
    margin-bottom: 20px;
  }

  select {
    margin-right: 10px;
  }
</style>


```

> 渲染示例数据：https://gitee.com/stary1993/kite-captcha-vue/tree/dev/src/mock

> 具体示例：https://gitee.com/stary1993/kite-captcha-demo

## API

### 属性

| 属性名                  | 类型            | 默认值                                        | 描述                                                         |
| ----------------------- | --------------- | --------------------------------------------- | ------------------------------------------------------------ |
| v-model                 | `number|string` | -                                             | v-model绑定值，用于接收验证结果状态码                        |
| scale                   | `number`        | 1                                             | 缩放比例                                                     |
| loadingAnimation        | `string`        | 'slide'                                       | 加载动画类型，可选值：`'slide'` `'bounce'` `'fade'` `'lightSpeed'` `'zoom'` |
| showClose               | `boolean`       | true                                          | 是否显示关闭按钮                                             |
| backgroundImage         | `string`        | -                                             | 背景图片                                                     |
| renderDataApi           | `Function`      | -                                             | 获取验证码数据的异步函数                                     |
| matchingResultCodeProps | `Map`           | { expired: 4000, failed: 4001, success: 200 } | 验证结果状态码配置<br/> `expired`表示已过期<br/> `failed`表示验证失败<br/> `success`表示验证成功<br/> |

### 对外暴露的方法

| 方法名  | 参数 | 描述           |
| ------- | ---- | -------------- |
| refresh | -    | 重新加载验证码 |

### 事件

| 事件名         | 参数                  | 描述               |
| -------------- | --------------------- | ------------------ |
| render-success | `boolean`             | 验证码渲染成功回调 |
| matching-data  | `CaptchaMatchingData` | 返回验证轨迹数据   |

#### `CaptchaMatchingData`
``````ts
interface CaptchaMatchingData {
  id: string;
  data: MatchingData;
}
interface MatchingData {
  /**
   * 背景图片宽度
   */
  bgImageWidth: number;

  /**
   * 背景图片高度
   */
  bgImageHeight: number;

  /**
   * 滑块图片宽度
   */
  sliderImageWidth: number;

  /**
   * 滑块图片高度
   */
  sliderImageHeight: number;

  /**
   * 轨迹点列表
   */
  trackList: CaptchaTrack[];
  /**
   * 开始滑动时间
   * 格式: yyyy-MM-dd HH:mm:ss.SSS
   */
  startSlidingTime: string;
  /**
   * 轨迹点扩展数据
   */
  data?: any;
  /**
   * 结束滑动时间
   * 格式: yyyy-MM-dd HH:mm:ss.SSS
   */
  endSlidingTime: string;
}
interface CaptchaTrack {
  /**
   * 轨迹点X坐标
   */
  x: number;

  /**
   * 轨迹点Y坐标
   */
  y: number;
  /**
   * 轨迹点时间
   */
  t: number;
  /**
   * 轨迹点类型
   */
  type: 'move' | 'down' | 'up' | 'click';
}
``````



### 插槽

| 插槽名    | 描述        |
|--------|-----------|
| title  | 自定义头部标题内容 |
| footer | 自定义底部内容   |

## Config Provider 全局配置

Config Provider 被用来提供全局的配置选项，让你的配置能够在全局都能够被访问到。

### i18n 配置

通过 Config Provider 来配置多语言，让你的应用可以随时切换语言。

> 组件使用 vue-i18n 进行国际化支持，可配置以下语言键值：

```json
{
    "captcha": {
        "dragSlider": "拖动滑块完成拼图",
        "clickTips": "请依次点击：",
        "success": "验证成功，耗时{sec}秒",
        "failed": "验证失败，请重新尝试",
        "expired": "验证码被黑洞吸走了",
        "refreshTips": "刷新",
        "closeTips": "关闭",
        "infoTips": "欢迎使用验证码"
    }
}
```

#### <a href="#appvue">使用方法</a>

### 自定义主题

通过 Config Provider 来自定义主题，内置暗黑主题。

```scss
$theme: (
        primary: #aaaaaa,
        shadow: #1a1a1a,
        error: #ff5252,
        success: #69f0ae,
        track: #2d2d2d,
        btn: #333333,
        word-click: #448aff,
        move-track-mask-border: #448aff,
        move-track-mask-bg: rgba(68, 138, 255, 0.3)
);
```

#### <a href="#appvue">使用方法</a>

### API

####  属性

| 属性名 | 类型     | 默认值  | 描述                                                         |
| ------ | -------- | ------- | ------------------------------------------------------------ |
| locale | `string` | 'zh_cn' | 配置国际化，<a href='https://gitee.com/stary1993/kite-captcha-vue/tree/dev/src/locale/lang'>内置语言</a> |
| theme  | `string` | 'light' | 配置主题，<a href='https://gitee.com/stary1993/kite-captcha-vue/tree/dev/src/themes'>内置主题</a> |

## 服务端集成

需要配合后端验证码服务使用，推荐使用 [kite-captcha-boot-starter（基于`tianai-captcha` `v1.4.1`）](https://gitee.com/stary1993/kite-boot/kite-captcha-boot-starter)，需要的<a href='https://gitee.com/stary1993/kite-captcha-vue/issues'>留言</a>。

> 若使用`tianai-captcha`最新版本的话，自行转换渲染数据以及轨迹数据。

后端需要提供以下接口：

1. 验证码生成接口
2. 验证码校验接口

## 作者

stary1993@[Gitee](https://gitee.com/stary1993)

## 许可证

MIT