Cap 浮窗模式（Floating Mode）实战：用一个 data 属性按需隐藏 CAPTCHA 并按需运行 proof-of-work

网络安全应用安全后端【免费下载链接】capFree, open-source and self-hosted CAPTCHA alternative to reCAPTCHA. Privacy-first and powered by proof-of-work and instrumentation challenges.项目地址https://gitcode.com/gh_mirrors/cap13/cap点击查看免费下载Cap 是一个免费、开源、可自托管的 reCAPTCHA 替代方案以 proof-of-work 与 instrumentation 挑战为核心。浮窗模式floating mode 是 Cap 官方指南之一它让页面在用户按下触发按钮之前完全隐藏 CAPTCHA点击后才弹出浮窗并立即运行 proof-of-work 挑战从而在保持安全性的同时最小化对正常用户的打扰。读完本文你将掌握data-cap-floating三个 data 属性的完整用法、CDN 与 standalone 服务器两种引入方式以及从源码层理解浮窗显示、定位、求解与自动隐藏的完整实现链路。浮窗模式解决什么问题常规嵌入模式下cap-widget元素会直接渲染在页面 DOM 中CAPTCHA 从页面加载那一刻起就可见。对于表单密集、交互路径长的页面这既占用视觉空间也让正常用户在提交前被迫面对一次验证。浮窗模式的思路是按需展示CAPTCHA 默认不可见display: none不干扰页面布局用户点击指定的触发元素如按钮时浮窗以绝对定位弹出并立即调用capWidget.solve()开始计算 proof-of-work求解完成后浮窗自动隐藏并通过转发点击事件的方式让原触发按钮的后续逻辑如表单提交继续执行。从源码看这一切只依赖一个核心入口在触发元素上添加data-cap-floating属性其值为目标cap-widget元素的 CSS selector。这就是官方文档所说的仅需一个 data attribute即可启用。最小可运行示例以下来自 docs/th/guide/floating.md 的完整示例可直接复制到 HTML 页面使用cap-widget idfloating onsolveconsole.log(token: ${event.detail.token}) >script srchttps://cdn.jsdelivr.net/npm/cap-widget/script script srchttps://cdn.jsdelivr.net/npm/cap-widget/cap-floating.min.js/scriptcap-widget即 npm 上的发布包widget/src/package.json 中name: cap.js/widget别名cap-widget同步发布main指向cap.min.jscap-floating.min.js则是浮窗脚本的压缩产物。方式二standalone 服务器自托管部署时standalone 服务器会从上游缓存上述资产并通过固定路由对外提供script srchttps://server url/assets/widget.js/script script srchttps://server url/assets/floating.js/script其中/widget.js与/floating.js两条路由的实现在 standalone/src/assets.js服务器启动时从缓存主机拉取cap.js/widget与其中的cap-floating.min.js存入数据库键名asset:widget.js、asset:floating.js再以text/javascript类型返回。若资产尚未缓存完成路由会返回 503 并在日志提示检查资产抓取错误因此自托管场景下建议在部署完成后确认资产缓存成功。脚本顺序有讲究先加载主库cap.min.js再加载cap-floating.min.js。浮窗脚本内部通过document.querySelector(selector)查找组件并调用其solve()方法且通过capWidget.addEventListener(solve, ...)监听求解事件只有主库先就位、cap-widget自定义元素注册完成浮窗脚本才能正确工作。三个 data 属性完整参考官方文档定义了三个属性完整参数表如下属性作用取值范围 / 默认值data-cap-floating要控制的cap-widget元素的 CSS selector任意合法 selector如#floating、.cap-widget必须能匹配到已渲染的 Cap 组件data-cap-floating-position浮窗相对触发元素的位置top浮窗显示在触发元素上方或bottom显示在下方不设置时默认topdata-cap-floating-offset浮窗与触发元素之间的间距数字字符串单位 px默认8从源码实现看widget/src/src/cap-floating.jsdata-cap-floating-offset使用parseInt(..., 10) || 8解析因此传入非数字或 0 都会回退到默认值 8pxdata-cap-floating-position除top外的任意值包括不设置都会走top分支只有显式传入bottom才采用下方定位。源码级原理点击、定位、求解与自动隐藏的完整链路浮窗模式的全部逻辑集中在约 130 行的 cap-floating.jsIIFE 结构打包产物为 cap-floating.min.js构建脚本见 widget/build.js。理解它有助于排查自定义场景下的定位与事件问题。1. 初始化与动态 DOM 支持const init (root) { setupElement(root); root.querySelectorAll([data-cap-floating]).forEach(setupElement); }; init(document.body); new MutationObserver((mutations) { // 对新增元素节点再次执行 init }).observe(document.body, { childList: true, subtree: true });初始化遍历document.body下所有带data-cap-floating属性的元素同时挂载MutationObserver监听 DOM 增删。这意味着通过框架异步渲染、或后续动态插入的触发按钮也会被自动识别无需手动重新初始化——这是浮窗脚本在 SPA/框架场景下依然可用的关键设计。setupElement首先校验 selector找不到元素或该元素没有solve方法时立即抛错上文提到的错误信息即来自此处随后把capWidget.style.display设为none完成初始隐藏。2. 点击拦截与事件转发element.addEventListener( click, (e) { if (bypass) { bypass false; return; } e.stopImmediatePropagation(); e.preventDefault(); showWidget(element, capWidget); // 监听 solve成功后写入属性并 500ms 后重放点击 ... }, true, // 捕获阶段 );首次点击时监听器在捕获阶段拦截事件stopImmediatePropagationpreventDefault防止点击直接触发表单提交等默认行为转而弹出浮窗并启动求解。求解成功后把 token 写入触发元素element.setAttribute(data-cap-token, detail.token)标记进度element.setAttribute(data-cap-progress, done)设置bypass true后延迟 500ms 调用element.click()重放点击此时监听器因 bypass 直接放行后续默认行为如表单提交、路由跳转得以继续。这套拦截—求解—重放机制保证了对原有按钮逻辑的透明兼容你不需要为浮窗改造按钮的业务代码只需读取data-cap-token或data-cap-progressdone属性即可拿到验证结果。3. 浮窗显示与定位Object.assign(capWidget.style, { display: block, position: absolute, zIndex: 99999, opacity: 0, transform: scale(0.98), ... transition: opacity 0.15s, margin-top 0.2s, transform 0.2s, });浮窗弹出时被设为绝对定位、高z-index99999初始opacity: 0、scale(0.98)随后 5ms 内过渡到完全可见scale(1)、opacity: 1形成轻微放大渐入动画隐藏时则反向缩小渐出最后display: none见hideWidget。定位计算值得注意position: absolute相对于最近的定位祖先capWidget.offsetParent解析而getBoundingClientRect()返回的是视口相对坐标因此源码中同时取得触发元素与容器的rect后做差值换算把视口坐标转成容器相对坐标水平居中triggerRect.left (triggerRect.width - capWidget.offsetWidth) / 2再夹紧到[2, window.innerWidth - capWidget.offsetWidth]避免浮窗溢出视口top位置idealTop triggerRect.top - capWidget.offsetHeight - offset夹紧到不小于 0bottom位置idealTop triggerRect.bottom offset夹紧到不超过window.innerHeight - capWidget.offsetHeight。由此可以推断浮窗不会因屏幕边缘而被裁切上下位置都做了视口边界保护data-cap-floating-offset精确控制浮窗与按钮的间距。4. 按需触发 proof-of-workshowWidget的最后一行是capWidget.solve()。对照主库实现widget/src/src/cap.jssolve()内部会读取data-cap-api-endpoint作为 API 基址缺省时若配置了CAP_CUSTOM_FETCH则回退到/见 cap.js获取 challenge 后调度 proof-of-work含 WASM/hashwx 等多路计算池进行求解求解成功后dispatchEvent(solve, { token })并写入cap-widget的token属性cap.js。这也解释了浮窗模式的核心价值proof-of-work 只在用户真正点击触发元素后才开始计算既不在页面加载时消耗资源也避免了 CAPTCHA 常驻可见的体验负担。若组件自身已处于求解中#solving为真solve()会直接返回避免重复计算。常见使用场景与注意事项表单防滥用把浮窗按钮绑定到提交按钮配合data-cap-progressdone判断验证是否完成未验证时点击只会弹窗并启动计算不会提交。多触发元素共用一个组件多个按钮的data-cap-floating指向同一个 selector 即可浮窗脚本为每个触发元素独立注册监听与 token 写入。SPA 动态渲染得益于MutationObserver动态插入的按钮无需额外初始化代码。定位优先考虑页面滚动状态getBoundingClientRect()返回视口坐标滚动后点击会按当前滚动位置重新定位若页面有横向滚动条水平夹紧逻辑会保证浮窗不超出可视区域。自托管部署时注意资产缓存时序standalone 服务器首次启动可能尚未抓取完floating.js此时/floating.js会返回 503请检查 standalone/src/assets.js 的缓存逻辑与服务器日志。相关资源泰文版浮窗模式指南docs/th/guide/floating.md英文版docs/guide/floating.md浮窗脚本源码与压缩产物widget/src/src/cap-floating.js、widget/src/cap-floating.min.jsCap 主库实现solve()、事件分发widget/src/src/cap.jsstandalone 服务器资产路由/assets/widget.js、/assets/floating.jsstandalone/src/assets.js构建与发布流程含cap-floating.min.js的压缩步骤widget/build.js赞分享网络安全应用安全后端【免费下载链接】capFree, open-source and self-hosted CAPTCHA alternative to reCAPTCHA. Privacy-first and powered by proof-of-work and instrumentation challenges.项目地址https://gitcode.com/gh_mirrors/cap13/cap点击查看免费下载相关推荐Cap 浮动模式Floating Mode实战指南用单个 data 属性按需隐藏并触发工作量证明 CAPTCHACap 浮动模式Floating Mode实战指南用单个 data 属性按需隐藏并触发工作量证明 CAPTCHA Cap 是一款免费、开源、可自托管的 C网络安全应用安全后端Cap 浮动模式Floating Mode完整指南隐藏式按需触发一个 data-cap-floating 属性搞定Cap 浮动模式Floating Mode完整指南隐藏式按需触发一个 data cap floating 属性搞定 导读 浮动模式是 Cap 开源自托网络安全应用安全后端Cap 浮动模式Floating Mode集成指南按需触发工作量的无头 CAPTCHA 方案Cap 浮动模式Floating Mode集成指南按需触发工作量的无头 CAPTCHA 方案 Cap 是开源、可自托管的 reCAPTCHA 替代方案其网络安全应用安全后端上一篇告别繁琐切换用fzf打造终端里的Alfred式快速跳转下一篇HumanLayer无障碍访问确保审批界面符合WCAG标准的可访问性设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考