前端组件

验证组件是一个标准 Web Component（<cap-widget>），一行 <script> 引入，任何框架都能用。

引入

<script src="https://capcat.ai/widget/cap.js"></script>

TIP

该文件由 Capcat 官方托管（capcat.ai），不依赖第三方 CDN，国内外访问都稳定。

表单方式（零 JavaScript）

组件放在 <form> 内时，会自动注入隐藏的 cap-token 字段并随表单一起提交：

<form action="/submit" method="POST">
  <cap-widget data-cap-api-endpoint="https://api.capcat.ai/<site-key>/"></cap-widget>
  <button type="submit">提交</button>
</form>

JavaScript 方式（SPA / 自定义流程）

监听 solve 事件拿到 token，自行决定何时发送：

const widget = document.querySelector("cap-widget");
widget.addEventListener("solve", (e) => {
  const token = e.detail.token;
  // 把 token 发给你的服务端、解锁提交按钮等
});

常用属性

属性	说明
data-cap-api-endpoint	验证服务地址，格式 https://api.capcat.ai/<site-key>/（site key 在控制台创建站点时获得），必填
data-cap-theme	设为 auto，组件自动贴合页面已有样式——见自动主题
data-cap-branding	设为 hidden 去掉组件角落的 Capcat 角标——见隐藏角标（付费套餐）
data-cap-worker-count	求解使用的 Web Worker 数量，默认按设备核数

样式定制

组件渲染在 Shadow DOM 内，页面 CSS 不会意外破坏它。定制走两条受支持的通道——自动主题与 --cap-* CSS 变量，二者可自由组合。

自动主题

加上 data-cap-theme="auto"，组件自动从页面采样外观，一行 CSS 都不用写：

<cap-widget data-cap-theme="auto" data-cap-api-endpoint="..."></cap-widget>

采样内容：

• 字体、字号与正文色——按组件所在位置的继承链取值，字号跟随参照输入框
• 背景——取第一个不透明的祖先背景，贴合所在卡片/面板，深色页面自动适配
• 边框色与圆角——向同一 <form> 内的第一个文本输入框对齐；不在表单里时就近取周围的表单控件，再退就近按钮（只取圆角，封顶 24px）；复选框圆角按比例缩放
• 强调色——表单设置了 accent-color 则优先使用，否则回落正文色（用于加载环、焦点框与疑难链接）

自动主题只补齐你没有显式设置的变量：CSS 里声明过的 --cap-* 变量始终优先，因此 auto 可与下方手动覆盖组合使用。系统深浅色切换时会自动重新采样；如果你的应用在运行时切主题（如切换 class），切换后重新设置一次属性（el.setAttribute("data-cap-theme", "auto")）即可重新采样。

CSS 变量

在 cap-widget 元素上设置以下任意变量（示例值即默认值）：

cap-widget {
  --cap-background: #fdfdfd;
  --cap-border-color: #dddddd8f;
  --cap-border-radius: 14px;
  --cap-widget-width: 260px;
  --cap-widget-height: 58px;
  --cap-widget-padding: 14px;
  --cap-gap: 15px;
  --cap-color: #212121;
  --cap-font: system-ui, sans-serif;
  --cap-font-size: 15px;
  --cap-checkbox-size: 25px;
  --cap-checkbox-border: 1px solid #aaaaaad1;
  --cap-checkbox-border-radius: 6px;
  --cap-checkbox-background: #fafafa91;
  --cap-spinner-color: #000;
  --cap-spinner-background-color: #eee;
  --cap-focus-ring: #0066cc;
}

常用配方——让组件和其他表单字段一样占满容器宽度：

cap-widget {
  display: block;
  --cap-widget-width: 100%;
}

隐藏角标（付费套餐）

data-cap-branding="hidden" 可去掉组件角落的 Capcat 角标。这是付费套餐权益：先在控制台为站点开启隐藏组件 Capcat 角标——免费站点上服务端会让角标重新出现。

React / Vue / Svelte 等框架接入示例，参见上游文档 Widget 章节。