# tianai-captcha-vue

**Repository Path**: sivan-proj/tianai-captcha-vue

## Basic Information

- **Project Name**: tianai-captcha-vue
- **Description**: 基于tianai-captcha SDK封装的的Vue组件，可直接在Vue项目中使用
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-03-10
- **Last Updated**: 2025-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tianai-captcha-vue

基于tianai-captcha SDK封装的的Vue组件，可直接在Vue项目中使用。

### 使用说明

官方文档地址：[TIANAI-CAPTCHA](http://doc.captcha.tianai.cloud/)

1. 将`src`目录下的文件复制到你的项目中。

   > **注意**：组件默认读取的验证码资源文件路径为`./src/assets/captcha`。如需修改读取路径可通过组件的`ressourcePath`属性自定义；请勿更改`captcha`目录下的文件名称和路径，否则组件可能无法正常初始化。

2. 在你的Vue项目中引入并使用该组件，下面提供一个在登录时显示验证码的示例：

   ```html
   <template>
     <captcha
       class="captcha"
       v-model="showCaptcha"
       :enabled="enabled"
       :ressourcePath="ressourcePath"
       :genUrl="genUrl"
       :checkUrl="checkUrl"
       :logo="logo"
       :bg="bg"
       :btn="btn"
       :moveTrackBgColor="moveTrackBgColor"
       :moveTrackBorderColor="moveTrackBorderColor"
       @success="handleSuccess"
       @fail="handleFail"
       @refresh="handleRefresh"
       @close="handleClose"
     />
   
     <!-- 具体的操作 -->
     <button @click="onClickLogin">登录</button>
   </template>
   
   <script setup>
   import axios from "axios";
   import captcha from "@/components/Captcha/index.vue";
   
   // 后端接口的根地址，如 http://localhost:8080
   const baseUrl = import.meta.env.VITE_API_URL;
   
   const showCaptcha = ref(false); // 控制验证码显示
   const enabled = ref(true); // 是否启用验证码
   const ressourcePath = ref("./src/assets/captcha"); // 验证码资源文件路径
   const genUrl = ref(`${baseUrl}/captcha/gen`); // 生成验证码接口地址
   const checkUrl = ref(`${baseUrl}/captcha/check`); // 验证验证码接口地址
   
   const logo = ref(null); // logo图片地址
   const bg = ref(undefined); // 背景图片地址
   const btn = ref(undefined); // 滑动按钮图片地址
   const moveTrackBgColor = ref(undefined); // 滑动按钮背景色
   const moveTrackBorderColor = ref(undefined); // 滑动按钮边框色
   
   // 验证码ID，用于后端校验
   const captchaId = ref("");
   
   // 登录表单
   const loginForm = ref({
     username: "admin",
     password: "admin",
   });
   
   // 具体的登录逻辑...
   const login = () => {
     axios({
       headers: { captchaId: captchaId.value }, // 添加验证码ID到请求头中，供后端接口校验
       method: "post",
       url: `${baseUrl}/login`, // 登录接口地址
       data: loginForm.value,
     }).then((res) => {
       console.log("登录成功");
     });
   };
   
   // 点击登录按钮时触发
   const onClickLogin = () => {
     showCaptcha.value.show = true; // 显示验证码
   };
   
   // 获取验证码开关
   const getCaptchaEnabled = () => {
     axios({
       method: "get",
       url: `${baseUrl}/captcha/enabled`, // 获取验证码开关接口地址
     }).then((res) => {
       enabled.value = res.data;
     });
   };
   
   // 验证码校验成功处理
   const handleSuccess = (res, c, tac) => {
     console.log("验证成功", res, c, tac);
     captchaId.value = res.data?.captchaId; // 获取后端返回的captchaId
     login(); // 执行具体的登录逻辑
   };
   
   const handleFail = (res, c, tac) => {
     console.log("验证失败", res, c, tac);
   };
   
   const handleRefresh = (el, tac) => {
     console.log("刷新验证码", el, tac);
   };
   
   const handleClose = (el, tac) => {
     console.log("关闭验证码", el, tac);
   };
   
   // 初始化页面时获取验证码开关
   onMounted(() => {
     getCaptchaEnabled();
   });
   </script>
   
   <style>
   .captcha {
     position: fixed;
     top: 50%;
     left: 50%;
     transform: translate(-50%, -50%);
     background-color: #fff;
     z-index: 999;
   }
   </style>
   ```

### 组件API

   #### 属性

| 属性名               | 类型    | 默认值                 | 描述                                                         |
| :------------------- | :------ | :--------------------- | :----------------------------------------------------------- |
| enabled              | Boolean | true                   | 是否启用验证码，关闭后直接通过验证，不显示验证码             |
| modelValue           | Boolean | false                  | 是否显示验证码，启用验证时生效                               |
| ressourcePath        | String  | './src/assets/captcha' | 验证码资源文件路径                                           |
| genUrl               | String  | ''                     | 生成验证码接口地址，要符合 tianai-captcha 默认验证码生成接口规范 |
| checkUrl             | String  | ''                     | 验证验证码接口地址，要符合 tianai-captcha 默认验证码校验接口规范 |
| logo                 | String  | null                   | logo图片地址，为 null 则不显示                               |
| bg                   | String  | undefined              | 背景图片地址                                                 |
| btn                  | String  | undefined              | 滑动按钮图片地址                                             |
| moveTrackBgColor     | String  | undefined              | 滑动按钮背景色                                               |
| moveTrackBorderColor | String  | undefined              | 滑动按钮边框色                                               |

   #### 事件

| 事件名            | 参数          | 描述                                                         |
| :---------------- | :------------ | :----------------------------------------------------------- |
| success           | (res, c, tac) | 验证成功回调函数，`res` 为接口返回数据，`c` 和 `tac` 为验证码相关对象 |
| fail              | (res, c, tac) | 验证失败回调函数，`res` 为接口返回数据，`c` 和 `tac` 为验证码相关对象 |
| refresh           | (el, tac)     | 刷新按钮回调函数，`el` 为绑定的 div 标签，`tac` 为验证码实例 |
| close             | (el, tac)     | 关闭按钮回调函数，`el` 为绑定的 div 标签，`tac` 为验证码实例 |
| update:modelValue | (newValue)    | 绑定值变化时触发，`newValue` 为新的绑定值，用于同步验证码显示状态 |

   #### 方法

以下方法仅限在组件内部调用，无法在父组件调用

| 方法名        | 参数 | 描述           |
| :------------ | :--- | :------------- |
| init          | /    | 初始化验证码   |
| reloadCaptcha | /    | 重新加载验证码 |
| destroyWindow | /    | 销毁验证码窗口 |