您可以通过隐式或显式渲染在您的网页上初始化和自定义 Turnstile 小部件。
警告
api.js 必须从下面所述的确切 URL 获取。代理或缓存此文件将在未来更新发布时导致 Turnstile 失败。
注意
HTML 会扫描具有 cf-turnstile 类名的元素:
data-sitekey="你的站点密钥" data-callback="javascriptCallback"
一旦挑战被解决，令牌将传递给成功回调。此令牌必须通过我们的网站验证端点进行验证。令牌只能验证一次，不能被重复使用。
警告
使用 siteverify API 强制执行 Turnstile 令牌至关重要。Turnstile 令牌可能无效、过期或已被兑换。不验证令牌将使您的实现存在重大漏洞。
注意
一旦令牌被发出，它可以在接下来的300秒内进行验证。300秒后，令牌将不再有效，需要解决另一个挑战。
要配置挑战，请参阅 配置，其中包含数据属性和渲染参数。
Turnstile 通常用于保护网站上的表单，例如登录表单、联系表单等。在插入 JavaScript 脚本标签后，您可以将 <div class="cf-turnstile"></div> 嵌入到您的网站中以保护您的表单。
<form action="/login" method="POST"> <input type="text" placeholder="用户名" /> <input type="password" placeholder="密码" /> <div class="cf-turnstile" data-sitekey="<YOUR_SITE_KEY>"></div> <button type="submit" value="Submit">登录</button>
添加了一个名为 cf-turnstile-response 的隐形输入，并将与其他字段一起发送到服务器。
注意
表单并不因为渲染了一个小部件而受到保护。渲染小部件所产生的相应令牌也需要使用 siteverify API 进行验证。
您可以通过替换以下脚本来禁用隐式渲染:
https://challenges.cloudflare.com/turnstile/v0/api.js
收件人：
https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit
使用 render=explicit 时，带有 cf-turnstile 类的 HTML 元素将不会显示挑战。必须按照以下步骤调用 turnstile.render 函数。要结合这两个选项，请传递查询字符串 ?render=explicit&onload=onloadTurnstileCallback：
https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit&onload=onloadTurnstileCallback
注意
- 插入下面的 JavaScript 标签和相关代码。确保您已将
.cf-turnstile的类名重命名为#example-container（如果您没有设置如上所示的render=explicit查询字符串选项，它仍然会以其他方式呈现）。一旦脚本嵌入，您将可以访问一个具有多个可自定义回调选项的全局函数。为了使以下函数正常工作，页面必须包含一个 ID 为example-container的 HTML 元素。
src="https://challenges.cloudflare.com/turnstile/v0/api.js?onload=onloadTurnstileCallback"
window.onloadTurnstileCallback = function () { turnstile.render("#example-container", { sitekey: "<YOUR_SITE_KEY>", callback: function (token) { console.log(`挑战成功 ${token}`);
或:
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"></script>
// 如果使用同步加载，将在 DOM 准备好后调用turnstile.ready(function () { turnstile.render("#example-container", { sitekey: "<YOUR_SITE_KEY>", callback: function (token) { console.log(`挑战成功 ${token}`);
旋转门可以通过在全局 window 对象中调用 turnstile.render() 函数进行程序化加载。
turnstile.render: function (container: string | HTMLElement, params: RenderParameters) 渲染函数接受一个 HTML 小部件的参数。
如果调用成功，函数返回一个 widgetId (字符串)。如果调用不成功，函数返回 undefined。
除了 render() 函数，Turnstile 还支持通过 turnstile.getResponse(widgetId: string) 函数从 widgetId 获取小部件的响应。如果省略 widgetId，turnstile.getResponse() 将返回最后创建的小部件的响应。
经过一段时间，部件可能会过期，需要刷新（通过调用 turnstile.reset(widgetId: string)）。如果部件已过期，turnstile.getResponse() 仍然会返回最后的响应，但该响应将不再有效，因为它已过期。
您可以通过订阅 expired-callback 或使用 turnstile.isExpired(widgetId: string) 函数来检查小部件是否已过期，如果小部件已过期，则返回 true。如果您省略 widgetId，turnstile.isExpired() 将返回最后创建的小部件是否已过期。
如果某个小部件超时、过期或需要重新加载，您可以使用 turnstile.reset(widgetId: string) 函数来重置该小部件。
一旦不再需要小部件，可以使用 turnstile.remove(widgetId: string) 从页面中移除它。这不会调用任何回调，并将移除所有相关的 DOM 元素。
要卸载 Turnstile，turnstile.render() 将返回一个 ID，您可以将其传递给 turnstile.remove()。
在令牌过期前几秒，expired-callback 被调用。
refresh-expired 或 data-refresh-expired 参数定义了当 Turnstile 小部件的令牌过期时的行为。
默认情况下，参数设置为 auto，这将自动指示 Turnstile 通过重新运行挑战来获取新令牌。在挑战再次解决后，如果指定了 callback，则会使用新令牌调用该回调。
访客还可以通过将 refresh-expired 参数设置为 manual 来手动获取新令牌。
此外，指定 never 将不会导致令牌的重新生成，使用 Turnstile 的应用程序将负责获取新的 Turnstile 令牌。
当选择管理模式时，Turnstile 可能会在某些时候向访客呈现一个互动挑战。如果这个互动挑战被呈现但在给定的时间内没有解决，它将超时，Turnstile 的挑战过程将需要重新启动。
refresh-timeout 或 data-refresh-timeout 参数定义了当交互式挑战遇到超时时的行为。默认情况下，组件会自动刷新（auto）。然而，组件也可以配置为访客需要手动刷新超时的组件（manual），或者组件只能由应用程序外部刷新（refresh-timeout="never"），例如通过调用 Turnstile 的 reset() 函数。
当一个小部件遇到交互超时时，timeout-callback 被调用。
默认情况下，Turnstile 令牌在小部件渲染时为访客获取（即使在隐形模式下）。然而，在某些情况下，应用程序可能希望嵌入 Turnstile，但推迟在某个时间点运行挑战。这时可以使用执行模式来控制挑战何时运行以及令牌何时生成。
有两个选项：
- 挑战在调用
render()函数后自动运行。
- 挑战在调用了
render()函数后运行，通过单独调用turnstile.execute(container: string | HTMLElement, jsParams?: RenderParameters)函数。
这将小部件的外观和渲染与其执行分离。
如果一个小部件是可见的，它的外观可以通过 appearance 参数进行控制。
默认情况下，appearance 对于可见的控件类型设置为 always。然而，如果 appearance 设置为 execute，控件将在挑战开始后才会变得可见。这在 execute() 在 render() 之后被调用的情况下是有帮助的。如果 appearance 设置为 interaction-only，控件仅在需要交互的情况下才会变得可见。
请参阅 小部件类型 以按类型和状态查看小部件。
转闸小部件可以在使用管理模式或非交互模式时具有两种不同的固定大小或灵活的宽度大小：
大小
宽度
高度
正常
300像素
65像素
灵活的
100%（最小：300px）
65像素
紧凑
150像素
140像素
<div style="display: block; flex-flow: row;"> data-sitekey="1x00000000000000000000AA"
<div style="display: block; flex-flow: row;"> data-sitekey="1x00000000000000000000AA"
JavaScript 渲染参数
数据属性
描述
站点密钥
数据站点密钥
每个小部件都有一个站点密钥。此站点密钥与相应的小部件配置相关联，并在小部件创建时生成。
动作
数据操作
一个可以用于在分析中区分同一 sitekey 下小部件的客户值，并在验证后返回。此值只能包含最多 32 个字母数字字符，包括 _ 和 -。
cData
data-cdata
一个客户有效载荷，可用于在整个挑战发放过程中附加客户数据，并在验证后返回。此有效载荷最多只能包含 255 个字母数字字符，包括 _ 和 -。
回调
data-callback
在挑战成功时调用的 JavaScript 回调。回调会传递一个可以验证的令牌。
错误回调
数据错误回调
当发生错误时（例如网络错误或挑战失败）调用的 JavaScript 回调。请参阅 客户端错误。
执行
数据执行
执行控制何时获取小部件的令牌，可以在 render（默认）或 execute 上进行。有关更多信息，请参阅 执行模式。
过期回调
数据过期回调
当令牌过期且不重置小部件时调用的 JavaScript 回调。
交互前回调
数据前交互回调
在挑战进入交互模式之前调用的 JavaScript 回调。
交互式回调后
数据后交互回调
当挑战离开交互模式时调用的 JavaScript 回调。
不支持的回调
data-unsupported-callback
当给定的客户端/浏览器不被 Turnstile 支持时调用的 JavaScript 回调。
主题
数据主题
小部件主题。可以取以下值：light，dark，auto。
默认值为 auto，它尊重用户的偏好。可以通过相应地设置主题强制为浅色或深色。
语言
数据语言
显示语言，必须是：auto（默认）以使用访问者选择的语言，或一个 ISO 639-1 两字母语言代码（例如 en）或语言和国家代码（例如 en-US）。有关更多信息，请参阅 支持的语言列表。
tabindex
data-tabindex
Turnstile 的 iframe 的 tabindex 以便于无障碍访问。默认值为 0。
超时回调
数据超时回调
当挑战呈现一个互动挑战但在给定时间内未解决时调用的 JavaScript 回调。回调将重置小部件，以允许访客再次解决挑战。
响应字段
数据响应字段
一个布尔值，用于控制是否创建带有响应令牌的输入元素，默认为 true。
响应字段名称
数据响应字段名称
输入元素的名称，默认为 cf-turnstile-response。
大小
数据大小
小部件大小。可以取以下值：normal，flexible，compact。
重试
data-retry
控制小部件是否应在未成功时自动重试获取令牌。默认值为 auto，将自动重试。可以设置为 never 以禁用失败时的重试。
重试间隔
data-retry-interval
当 retry 设置为 auto 时，retry-interval 控制重试尝试之间的时间（以毫秒为单位）。值必须是一个小于 900000 的正整数，默认为 8000。
刷新过期
data-refresh-expired
当令牌过期时自动刷新。可以选择 auto、manual 或 never，默认为 auto。
刷新超时
数据刷新超时
控制小部件在进入交互挑战并观察到超时时是否应自动刷新。可以取 auto（在遇到交互超时时自动刷新）、manual（提示访客手动刷新）或 never（将显示超时），默认为 auto。仅适用于受管理模式的小部件。
外观
数据外观
外观控制小部件何时可见。它可以是 always（默认），execute 或 interaction-only。有关更多信息，请参阅 外观模式。
反馈启用
数据反馈启用
允许 Cloudflare 在小部件失败时收集访客反馈。它可以是 true（默认）或 false。