@captcha-la/vue

English · 简体中文

Captchala 验证码 Vue 3 官方组件 —— 为你的 Vue 应用提供智能 CAPTCHA 防护。

安装

npm install @captcha-la/vue
# or
yarn add @captcha-la/vue
# or
pnpm add @captcha-la/vue

快速上手

<template>
  <Captchala
    app-key="your-app-key"
    product="popup"
    @success="handleSuccess"
    @error="handleError"
  />
</template>

<script setup>
import { Captchala } from '@captcha-la/vue'

function handleSuccess(result) {
  console.log('验证成功')
  console.log('Token:', result.token)
  // 把 token 提交到你自己的后端校验
}

function handleError(error) {
  console.error('验证失败:', error)
}
</script>

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | appKey | string | 必填 | Captchala 应用 key | | serverToken | string | - | 服务端签发的一次性 challenge token。当应用配置 server_token_required=true 时必填，详见下方 生产环境：使用 serverToken。 | | product | 'popup' \| 'float' \| 'embed' \| 'bind' | 'popup' | 显示模式 | | action | string | 'default' | 业务场景标识 (例如 'login'、'register'、'checkout') | | lang | string | 'zh-CN' | 语言代码 ('zh-CN'、'en'、'ja' 等) |

事件

| 事件 | Payload | 说明 | |------|---------|------| | success | { token, type, action } | 验证成功时触发 | | error | error | 验证失败时触发 | | close | - | 验证码关闭时触发 | | ready | - | 验证码就绪时触发 |

通过 ref 调用方法

<template>
  <Captchala ref="captchaRef" app-key="your-app-key" />
  <button @click="handleVerify">触发验证</button>
</template>

<script setup>
import { ref } from 'vue'
import { Captchala } from '@captcha-la/vue'

const captchaRef = ref()

function handleVerify() {
  captchaRef.value?.verify()
}
</script>

| 方法 | 说明 | |------|------| | verify() | 手动触发验证 | | reset() | 重置验证码状态 | | destroy() | 销毁验证码实例 | | bindTo(selector) | 绑定到指定元素（仅 'bind' 模式） |

显示模式

Popup 模式（默认）

点击按钮弹出验证对话框。

<Captchala app-key="your-key" product="popup" />

Float 模式

浮动面板形式的验证码。

<Captchala app-key="your-key" product="float" />

Embed 模式

直接嵌入页面的验证码。

<Captchala app-key="your-key" product="embed" />

Bind 模式

将验证码绑定到已有按钮，点击该按钮时触发验证。

<template>
  <Captchala
    ref="captchaRef"
    app-key="your-key"
    product="bind"
    @success="handleSuccess"
  />
  <button id="submit-btn">提交</button>
</template>

<script setup>
import { ref, onMounted } from 'vue'

const captchaRef = ref()

onMounted(() => {
  captchaRef.value?.bindTo('#submit-btn')
})

function handleSuccess(result) {
  // 此时可以拿 result.token 提交表单
}
</script>

生产环境：使用 serverToken

生产环境（注册 / 登录 / 支付等）推荐使用 服务端签发的一次性 token。 后端持有 app_secret，调用 POST /v1/server/challenge/issue（带 X-App-Key + X-App-Secret）签发一次性 server_token（TTL 5 分钟，单次消费）， 再下发给前端。这样可以避免任何拿到公开 app_key 的人通过打码平台批量调用。

<template>
  <div v-if="!serverToken">Loading...</div>
  <Captchala
    v-else
    :server-token="serverToken"
    app-key="pk_your_public_app_key"
    action="login"
    @success="onSuccess"
  />
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { Captchala } from '@captcha-la/vue'

const serverToken = ref<string>()

onMounted(async () => {
  // 你自己的后端代理 /v1/server/challenge/issue
  const r = await fetch('/api/captcha-token')
  const d = await r.json()
  serverToken.value = d.server_token
})

function onSuccess(result: { token: string }) {
  console.log('pass_token:', result.token)
}
</script>

后端示例（Node.js / Express）：

// server.js — 在你自己的 /api/captcha-token handler 里调用
app.get('/api/captcha-token', async (req, res) => {
  const r = await fetch('https://apiv1.captcha.la/v1/server/challenge/issue', {
    method: 'POST',
    headers: {
      'X-App-Key': process.env.CAPTCHALA_APP_KEY,
      'X-App-Secret': process.env.CAPTCHALA_APP_SECRET,
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: 'action=login&ttl=300'
  })
  const { data } = await r.json()
  res.json({ server_token: data.server_token })
})

注意事项：

• 永远不要把 X-App-Secret 放进浏览器代码。
• 每个 server_token 只能用一次，每次挂载组件前都要重新生成。
• 老应用如果 server_token_required=false，仍然可以只用公开 appKey 模式。

服务端校验

收到 onSuccess 返回的 token 后，在你的服务端做最终校验：

// 你的后端
const response = await fetch('https://api.captcha.la/v1/risk/consume', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-App-Key': 'your-app-key',
    'X-App-Secret': 'your-app-secret'
  },
  body: JSON.stringify({ token })
})

const result = await response.json()
if (result.code === 0 && result.data.valid) {
  // token 有效，放行后续业务
}

TypeScript 支持

完整 TypeScript 类型已内置：

import { Captchala, type CaptchalaProps, type CaptchalaResult } from '@captcha-la/vue'

开源协议

MIT，详见 LICENSE。

链接

• 官网
• 文档
• Dashboard