---
title: Vue SDK
---

# Vue SDK

CaptchaLa CAPTCHA 的官方 Vue 3 元件 — 發佈於 [`@captcha-la/vue`](https://www.npmjs.com/package/@captcha-la/vue)。

## 線上範例

::: tip 📦
[demo-v1.captcha.la/vue](https://demo-v1.captcha.la/vue/) — 可執行的範例，涵蓋四種產品模式。
原始碼：[Captcha-La/vue-example](https://github.com/Captcha-La/vue-example)。
:::

## 安裝

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

Peer dependency：`vue@^3.2.0`。

## 快速開始

```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) {
  // Send result.token to your server for validation.
  console.log('pass_token:', result.token)
}

function handleError(error) {
  console.error('verification failed:', error)
}
</script>
```

## Props

| Prop | 型別 | 預設值 | 說明 |
|------|------|---------|-------------|
| `appKey` | `string` | *必填* | CaptchaLa 應用程式金鑰 |
| `serverToken` | `string` | - | 一次性、由伺服器簽發的 challenge token。當應用程式設定 `server_token_required=true` 時為必填。 |
| `product` | `'popup' \| 'float' \| 'embed' \| 'bind'` | `'popup'` | 顯示模式 |
| `action` | `string` | `'default'` | 動作識別字串（例如 `login`、`register`、`checkout`） |
| `lang` | `string` | `'zh-CN'` | 語言代碼（`zh-CN`、`en`、`ja`、…） |
| `bindTo` | `string \| HTMLElement` | - | 要綁定的元素選擇器或節點（僅用於 `product="bind"`） |

## 事件

| 事件 | Payload | 說明 |
|-------|---------|-------------|
| `success` | `{ token, type, action }` | 驗證成功 |
| `error` | `error` | 驗證失敗 |
| `close` | — | CAPTCHA 關閉 |
| `ready` | — | CAPTCHA 就緒 |

## 方法（透過 `ref`）

```vue
<template>
  <Captchala ref="captchaRef" app-key="your-app-key" />
  <button @click="captchaRef?.verify()">Verify</button>
</template>

<script setup>
import { ref } from 'vue'
const captchaRef = ref()
</script>
```

| 方法 | 說明 |
|--------|-------------|
| `verify()` | 觸發驗證 |
| `reset()` | 重置 CAPTCHA 狀態 |
| `destroy()` | 銷毀實例 |
| `bindTo(selector)` | 綁定至元素（用於 `bind` 模式） |
| `setLang(lang)` | 即時切換語言 |

## 生產環境：`serverToken` 模式

對於高價值流程（登入、註冊、支付），我們建議採用 **伺服器簽發 token 流程**。
後端透過 `POST /v1/server/challenge/issue` 簽發一次性 `server_token`（TTL 5 分鐘），
再交給瀏覽器使用：

```vue
<template>
  <Captchala
    v-if="serverToken"
    :server-token="serverToken"
    app-key="pk_your_public_app_key"
    action="login"
    @success="onSuccess"
  />
</template>

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

const serverToken = ref()

onMounted(async () => {
  const r = await fetch('/api/captcha-token')   // your own backend
  serverToken.value = (await r.json()).server_token
})

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

完整的後端合約請見 [API 參考](/zh-TW/api-reference)。

## 相關連結

- [npm](https://www.npmjs.com/package/@captcha-la/vue) · [GitHub](https://github.com/Captcha-La/vue) · [範例](https://github.com/Captcha-La/vue-example)
- [Web SDK 概覽](/zh-TW/web-sdk) · [API 參考](/zh-TW/api-reference)