网络安全应用安全后端【免费下载链接】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 替代方案其浮动模式Floating Mode允许把 CAPTCHA 组件完全隐藏直到用户按下触发按钮时才弹出并执行工作量证明proof-of-work挑战。本文以仓库文档 docs/zh/guide/floating.md 为核心结合 widget/src/src/cap-floating.js 等源码实现完整讲解属性配置、脚本引入方式、底层运行机制与动态页面适配帮助你在表单、按钮或自定义交互场景中按需触发 Cap 验证并正确回收 token。浮动模式解决什么问题默认的cap-widget组件会在页面加载后直接显示验证界面并可能立刻开始预解挑战。浮动模式改变了这一交互模型CAPTCHA 默认display: none完全隐藏页面首屏没有任何验证痕迹只有用户点击带data-cap-floating属性的触发元素时组件才会以浮层形式出现在按钮附近并调用solve()启动工作量证明。验证完成后浮层自动收回token 被写回触发元素整个流程对正常用户几乎无感知。这种模式尤其适合不希望首屏展示 CAPTCHA、追求表单清爽度的落地页需要在「提交」或「继续」按钮被点击后才启动验证的场景希望保持 HTML 结构简单、仅靠一个 data 属性接入的集成方式。快速开始一个 data 属性启用浮动模式按文档示例只需两步先放置一个cap-widget元素并指定 API 端点再在触发元素上添加data-cap-floating属性值为该 widget 的 CSS 选择器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-floating.min.js是cap-floating.js经 Terser 压缩后的产物构建脚本在 widget/build.js 中生成。方式二从自托管 Standalone 服务端引入若你部署了仓库中的 Standalone 服务端它会内置缓存并托管这两个静态资源见 standalone/src/assets.js 与路由 standalone/src/assets.jsscript srchttps://server url/assets/widget.js/script script srchttps://server url/assets/floating.js/script采用 Standalone 自托管时无需再依赖任何公共 CDN资源由服务端从cap.js/widget包缓存并统一提供适合对隐私与可用性要求更高的生产环境。完整部署方式见 docs/zh/guide/standalone/index.md。支持的属性与参数属性作用默认值/取值范围data-cap-floating要使用的cap-widget元素的 CSS 选择器如#floating必填无默认值data-cap-floating-position浮层相对触发元素的位置top默认/bottomdata-cap-floating-offset浮层与触发元素之间的间距像素8源码中通过parseInt(..., 10) || 8解析widget/src/src/cap-floating.js其中data-cap-floating是唯一必填属性缺失时脚本直接跳过该元素if (!capWidgetSelector) return;见 widget/src/src/cap-floating.js。如果选择器匹配不到元素或目标不是 Cap widget会抛出带有[cap floating]前缀的明确错误。源码级原理cap-floating.js 的运行机制浮动模式的全部逻辑集中在 widget/src/src/cap-floating.js约 130 行无任何外部依赖可拆解为四个部分。1. 初始化与动态监听脚本加载后立即对document.body执行init并注册一个MutationObserver监听childList与subtree变化widget/src/src/cap-floating.js。这意味着页面初始已有的[data-cap-floating]元素会被自动绑定之后由框架如 React、Vue动态插入的按钮也会被自动绑定无需手动重新初始化每次init都会先对传入节点本身调用setupElement再对其内部所有匹配元素逐一处理避免嵌套容器漏绑。2. 点击拦截与按需触发每个触发元素绑定捕获阶段的click监听器addEventListener(..., true)首次点击时通过e.stopImmediatePropagation()与e.preventDefault()拦截原生点击防止表单直接提交调用showWidget(element, capWidget)显示浮层并立即执行capWidget.solve()widget/src/src/cap-floating.js监听 widget 的solve事件收到 token 后将 token 写入触发元素的data-cap-token属性将data-cap-progressdone写入触发元素500ms 后设置bypass标志并重新触发一次element.click()让真实提交逻辑继续执行同时调用hideWidget收回浮层widget/src/src/cap-floating.js。bypass标志是避免「点击-拦截-再点击」死循环的关键第二次由脚本发起的点击会直接放行之后重置为false保证下一次用户手动点击仍走验证流程。3. 浮层显示动画与定位showWidget会通过Object.assign一次性覆盖 widget 的内联样式widget/src/src/cap-floating.jsposition: absolutezIndex: 99999浮层叠放在页面最上层初始opacity: 0、transform: scale(0.98)、marginTop: -4px5ms 后过渡到scale(1)/opacity: 1/marginTop: 0形成 150ms 淡入 200ms 位移/缩放的入场动画。定位计算的关键细节widget/src/src/cap-floating.js由于position: absolute是相对于最近的定位祖先offsetParent解析的而getBoundingClientRect()返回的是视口坐标源码用capWidget.offsetParent ?? document.documentElement的矩形做了坐标换算避免嵌套定位容器时浮层错位水平方向以触发元素中心对齐并钳制在2px到window.innerWidth - capWidget.offsetWidth之间防止溢出屏幕右侧positiontop时浮层出现在按钮上方triggerRect.top - 高度 - offset下限 0bottom时出现在按钮下方triggerRect.bottom offset上限不越过视口底部。4. 隐藏回收验证完成或用户离开后hideWidget分两段执行widget/src/src/cap-floating.js500ms 时先播放scale(0.98)opacity: 0的淡出动画700ms 时才真正display: none保证动画完整播完且不残留不可见节点。与 cap-widget 的协作solve 事件与 token 回收浮动脚本本身不参与工作量证明计算它只是cap-widget的调度者。真正的挑战流程由 widget/src/src/cap.js 中定义的cap-widget自定义元素完成solve()方法widget/src/src/cap.js负责拉取挑战、执行哈希计算、兑换并校验 token成功后dispatchEvent(solve, { token })widget/src/src/cap.js若此前已有预解speculative缓存的 token 且未过期会直接走#commitSpeculativeToken立即派发solve事件此时体验近乎零等待widget/src/src/cap.jswidget 内部会把 token 写入隐藏字段字段名默认cap-token可用data-cap-hidden-field-name修改widget/src/src/cap.js。因此浮动模式与普通模式在 token 回收上完全兼容你既可以在onsolve中读取event.detail.token也可以依赖脚本自动写入的data-cap-token属性或直接提交cap-token隐藏字段由你的服务端调用 siteverify 校验。校验接口与流程可参考 docs/zh/guide/capjs-core.md 与 docs/zh/guide/server.md。常见问题与排错浮层不出现且控制台报错[cap floating] xxx doesnt exist or isnt a Cap widget说明选择器匹配到的元素不存在或目标不是真正的cap-widget判断依据是元素是否具有solve方法见 widget/src/src/cap-floating.js。请检查id与选择器是否一致以及两个脚本是否都已按顺序引入。首次点击被吃掉按钮没有提交这是预期行为。脚本会先拦截点击完成验证验证通过后 500ms 内自动补发点击。若一直未提交请确认data-cap-api-endpoint指向的 Cap 服务端可达且返回了有效 token。浮层位置不对或溢出屏幕检查data-cap-floating-position只能取top/bottom并确认 widget 元素没有处于display: none的祖先容器中浮层定位依赖offsetParent与真实渲染尺寸。动态渲染的按钮没有反应正常情况由MutationObserver自动接管若按钮在 iframe 或 shadow root 中需要把脚本同样注入该文档环境。想微调间距使用data-cap-floating-offset传入像素值源码以parseInt解析非法值回退到默认8。相关资源官方文档docs/zh/guide/floating.md本文依据、英文版 docs/guide/floating.md浮动模式实现源码widget/src/src/cap-floating.js含压缩产物 widget/src/cap-floating.min.jswidget 主逻辑widget/src/src/cap.jscap-widget自定义元素、solve与事件派发构建流程widget/build.jscap.min.js与cap-floating.min.js的生成与压缩Standalone 资源托管standalone/src/assets.js/assets/widget.js与/assets/floating.js路由延伸阅读docs/zh/guide/standalone/index.md、docs/zh/guide/hashwx.md、docs/zh/guide/instrumentation.md赞分享网络安全应用安全后端【免费下载链接】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 开源自托网络安全应用安全后端高动态范围成像突破传统视觉感知的技术边界高动态范围成像突破传统视觉感知的技术边界 在数字图像处理领域高动态范围HDR成像技术代表了一种根本性的突破它重新定义了我们对图像质量和视觉真实性的理解网络安全应用安全后端上一篇如何在5分钟内快速部署强大的Wan2.2-TI2V-5B AI视频生成模型下一篇如何快速实现Angular视频嵌入Angular YouTube Embed完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考