@composy/captcha-vue

@composy/captcha-vue

@composy/captcha-core 的 Vue 3 适配层，提供 LCaptcha、Captcha 组件和 useCaptcha 组合式 API。核心验证逻辑仍由 CaptchaValidator 管理，组件卸载时会自动销毁实例。

安装

pnpm add @composy/captcha-vue

依赖：Vue ^3.5.32（peer）、@composy/captcha-core 和 vue-demi。

组件用法

内嵌模式

<script setup lang="ts">
import { LCaptcha } from '@composy/captcha-vue'
</script>

<template>
  <LCaptcha
    type="math-captcha"
    :mock="true"
    :width="320"
    :height="160"
    @success="token => console.log(token)"
  />
</template>

弹窗模式

<script setup lang="ts">
import { ref } from 'vue'
import { LCaptcha } from '@composy/captcha-vue'

const visible = ref(false)
</script>

<template>
  <button type="button" @click="visible = true">开始验证</button>
  <LCaptcha
    v-model:visible="visible"
    mode="dialog"
    type="slider"
    :mock="true"
    @failure="error => console.error(error.message)"
  />
</template>

Captcha 是 LCaptcha 的透传包装组件，两者 props、事件和 expose 方法一致。

当业务已经有 BFF 或自建挑战服务时，可通过 provider 传入 Core 的 CaptchaChallengeProvider，并用 clientId/scene 传递初始化上下文；refresh() 会取消过期请求，服务端应使用 provider 收到的 requestId 做幂等与重放保护。

Props 与事件

两种组件都支持 type、plugins、provider、endpoints、clientId、scene、mode、theme、lang、width、height、maxRetry、timeout、trackBehavior、mock、telemetry、sound、visible 以及各题型配置（如 slider、jigsaw、mathCaptcha、colorSelect）。

模板 ref 暴露：refresh()、reset()、switchType(type)、getState()、whenReady()、 getConfig()、getChallenge()、isDestroyed()、open()、close()、getInstance()。

useCaptcha

import { ref } from 'vue'
import { useCaptcha } from '@composy/captcha-vue'

const container = ref<HTMLElement | null>(null)
const captcha = useCaptcha({
  container,
  options: { type: 'color-select', mock: true },
})

captcha.refresh()

interface UseCaptchaOptions {
  container: Ref<HTMLElement | null>
  options?: Partial<CaptchaOptions>
}

interface UseCaptchaReturn {
  instance: Ref<CaptchaValidator | null>
  state: Ref<CaptchaState>
  refresh(): void
  reset(): void
  switchType(type: CaptchaType): void
  open(): void
  close(): void
  whenReady(): Promise<void>
  getConfig(): CaptchaOptions | null
  getChallenge(): CaptchaInitResponse | null
  isDestroyed(): boolean
  destroy(): void
}

样式与主题

适配层只提供容器，不重复注入核心样式。核心 DOM 使用 ldesign-captcha* 类名；颜色、尺寸、间距、圆角和字体依赖 LDesign color/size 生成的 --ld-* / --ld-color-* / --ld-px-* token，请在挂载组件前加载全局 token 样式。

构建与验证

pnpm run type-check
pnpm run test:run
pnpm run lint:check
pnpm run build

构建使用 @composy/builder（rolldown），并生成 dist、es、esm、lib 四类发布产物。

权威配置位于 .ldesign/builder.config.ts、.ldesign/tsconfig.json、.ldesign/tsconfig.cjs.json 和 .ldesign/eslint.config.js。包根的 tsconfig*.json 与 eslint.config.js 仅作为兼容入口。postbuild 会归一化并检查发布字段引用的文件，dist/index.min.js 保持浏览器压缩产物。

License

MIT © LDesign Team