您可以通过隐式或显式渲染在您的网页上初始化和自定义 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像素