slide-captcha-web 使用说明

验证码组件，支持滑块、旋转、拼图、点选。已打包提供 ESM 和 CJS 两种格式，并包含样式文件。

• ESM: dist/slide-captcha.es.js
• CJS: dist/slide-captcha.cjs.js
• CSS: dist/slide-captcha-web.css

安装

使用你喜欢的包管理器安装：

# pnpm
pnpm add slide-captcha-web

# npm
npm i slide-captcha-web

# yarn
yarn add slide-captcha-web

快速上手

1. 在页面中准备一个容器元素：

<div id="captcha-box"></div>

2. 在代码中引入组件与样式，并进行初始化：

// TypeScript / ESM
import { SlideCaptcha, type CaptchaBuildConfig, type CaptchaStyleBuildConfig } from "slide-captcha-web";
import "slide-captcha-web/style.css";

const config: CaptchaBuildConfig = {
  // 绑定验证码的容器（CSS 选择器或元素或 DomEl）
  bindEl: "#captcha-box",
  // 后端生成验证码接口
  requestCaptchaDataUrl: "/captcha-api/generate-slide-captcha",
  // 后端验证验证码接口
  validCaptchaUrl: "/captcha-api/verify-slide-captcha",
  // 可选：请求头
  requestHeaders: { "Content-Type": "application/json;charset=UTF-8" },
  // 可选：验证成功/失败回调
  validSuccess: (res, _c, slideCaptcha) => {
    console.log("Captcha passed!", res);
    slideCaptcha?.destroyWindow?.();
  },
  validFail: (res, _c, slideCaptcha) => {
    console.log("Captcha failed!", res);
    slideCaptcha?.reloadCaptcha?.();
  },
  // 可选：自定义关闭/刷新按钮行为
  btnCloseFun: (_e, slideCaptcha) => slideCaptcha?.destroyWindow?.(),
  btnRefreshFun: (_e, slideCaptcha) => slideCaptcha?.reloadCaptcha?.(),
  // 可选：是否将 Date 自动转为时间戳（默认 true）
  timeToTimestamp: true,
};

// 可选：样式覆盖
const style: CaptchaStyleBuildConfig = {
  // 不设置则使用内置默认样式；可按需覆盖
  // 示例：自定义移动边框颜色
  moveTrackMaskBorderColor: "#0298f8",
  // 示例：文案国际化
  i18n: {
    tips_success: "验证成功,耗时%s秒",
    tips_error: "验证失败，请重新尝试!",
    slider_title: "拖动滑块完成拼图",
    disable_title: "拖动滑块完成拼图",
    concat_title: "拖动滑块完成拼图",
    rotate_title: "拖动滑块完成拼图",
    image_click_title: "请依次点击:",
    tips_4001: "请求参数有误，请检查后重新尝试!",
    slider_title_size: "13px",
    concat_title_size: "13px",
    disable_title_size: "13px",
    rotate_title_size: "13px",
    image_click_title_size: "13px",
  },
};

new SlideCaptcha(config, style).show();

• 使用 JS 而非 TS 时，去掉类型标注即可。
• 组件初始化后会自动请求验证码并显示弹层；关闭/刷新在底部按钮，也可通过传入的回调控制。

在 Node/CommonJS 环境引入

如果你的打包环境仍使用 CommonJS：

const { SlideCaptcha, CaptchaBuildConfig, CaptchaStyleBuildConfig } = require("slide-captcha-web");
require("slide-captcha-web/style.css");

剩余用法与上文一致。

配置项（CaptchaConfig）

• bindEl: string | HTMLElement | DomEl（必填）
  • 绑定验证码弹层的容器，支持 CSS 选择器、原生元素或库内的 DomEl。
• requestCaptchaDataUrl: string（必填）
  • 生成验证码的后端接口地址。
• validCaptchaUrl: string（必填）
  • 校验验证码的后端接口地址。
• requestHeaders?: Record<string, string>
  • 发送请求时附加的请求头，默认会补充 Content-Type: application/json;charset=UTF-8。
• validSuccess?: (res, c?, slideCaptcha?) => void
  • 验证成功回调。默认会在控制台打印提示并关闭弹层。
• validFail?: (res, c?, slideCaptcha?) => void
  • 验证失败回调。默认会自动刷新验证码。
• btnCloseFun?: (e, slideCaptcha?) => void
  • 自定义关闭行为。
• btnRefreshFun?: (e, slideCaptcha?) => void
  • 自定义刷新行为。
• timeToTimestamp?: boolean
  • 是否在发送验证数据前，将对象中的 Date 字段转为时间戳（默认 true）。

样式定制（style，可选）

可覆盖的典型字段：

• bgUrl?: string
  • 覆盖弹层背景图。
• moveTrackMaskBgColor?: string
• moveTrackMaskBorderColor?: string
• i18n: 文案与字号等（见上方示例）。

如不传 style，将使用内置默认样式。