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: "拖动滑块完成拼图",
        concat_title: "拖动滑块横向对齐拼图",
        rotate_title: "拖动滑块旋转对齐拼图",
        image_click_title: "请依次点击:",
        disable_title: "验证码已禁用",
        slider_title_size: "13px",
        concat_title_size: "13px",
        disable_title_size: "13px",
        rotate_title_size: "13px",
        image_click_title_size: "13px",
        tips_4001: "请求参数有误，请检查后重新尝试!",
    },
};

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

• React示例代码

function YourComponent() {
    const [showSlideCaptcha, setShowSlideCaptcha] = useState(false);
    const slideCaptchaInstance = useRef<SlideCaptcha>(null);

    function triggerLoginBySlider(fn: (validId: string) => Promise<void>) {
        if (slideCaptchaInstance.current === null) {
            const config: CaptchaBuildConfig = {
                bindEl: "#captcha-box",
                requestCaptchaDataUrl: "/captcha-api/generate-slide-captcha",
                validCaptchaUrl: "/captcha-api/verify-slide-captcha",
                validSuccess: (res, _c, slideCaptcha) => {
                    const {
                        data: {validId},
                    } = res as { data: { validId: string } };
                    slideCaptcha?.destroyWindow?.();
                    setShowSlideCaptcha(false);
                    fn(validId);
                },
                validFail: (_res, _c, slideCaptcha) => {
                    slideCaptcha?.reloadCaptcha?.();
                },
                btnRefreshFun: (_e, slideCaptcha) => {
                    slideCaptcha?.reloadCaptcha?.();
                },
                btnCloseFun: (_e, slideCaptcha) => {
                    slideCaptcha?.destroyWindow?.();
                    setShowSlideCaptcha(false);
                },
            };
            slideCaptchaInstance.current = new SlideCaptcha(config);
        }
        setShowSlideCaptcha(true);
        slideCaptchaInstance.current.show();
    }

    function doLogin(validId: string): Promise<void> {
        // Your login logic here
        return Promise.resolve();
    }

    return (
        <div>
            <div>
                {showSlideCaptcha ? <div className="loading">加载中...</div> : undefined}
                <button onClick={() => triggerLoginBySlider(doLogin)}>验证后登录</button>
            </div>
            <div className="flex justify-center items-center">
                <div id="captcha-box"/>
            </div>
        </div>
    );
}

• 使用 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，将使用内置默认样式。