Turnstile 小组件

Turnstile 小组件定义了 Turnstile 在您网页上的行为方式。每个小组件都有一个模式 (mode)、一个标签 (label)、一个 sitekey 和一个密匙 (secret key)。您可以创建多个具有不同配置的小组件。

Turnstile 托管在 challenges.cloudflare.com 下。您的应用程序将连接到此源。如果您的站点使用内容安全策略 (Content Security Policy)，您必须允许连接到此域。

每个小组件都有自己唯一的 sitekey 和 secret key 对，以及配置选项。

组件	描述
Sitekey	用于在您的网站上调用 Turnstile 小组件的公钥。
Secret key	用于服务器端令牌验证的私钥。
配置	模式、主机名、外观设置和其他选项。

Turnstile 小组件的可用模式为 Managed（托管）、Non-Interactive（非交互式） 和 Invisible（不可见）。

小组件模式	描述	用例
Managed（托管）（推荐）	根据访问者风险级别，在非交互式质询或复选框质询之间自动进行选择。无需辨认图像或文字。	具有自适应安全性的简单设置。平衡安全防护和用户体验。
Non-Interactive（非交互式）	显示带有加载环的可见小组件。运行质询而不需要访问者进行交互。	在展示正在进行验证的同时，最大限度减少摩擦。
Invisible（不可见）	完全在后台运行质询，没有可见的小组件或加载指示器。	通过零可见的验证元素，最大化视觉体验。

托管模式 (Managed mode)（推荐）

托管模式完全由 Cloudflare 托管。它会根据客户端信号和风险级别自动选择适当的操作。Cloudflare 使用来自访问者的信息来决定是否应使用交互式质询。

只有在需要进一步检查以验证访问者是人类时，Turnstile 才会要求交互。需要交互时，访问者将被提示勾选一个方框。无需辨认图像或文字。

托管模式非常适合想要简单配置而无需微调小组件行为的用户。

非交互式模式 (Non-Interactive mode)

在浏览器中运行质询时，访问者将看到一个带有加载环的小组件。与托管模式不同，访问者永远不会被要求或被提示与小组件进行交互。

非交互式模式非常适合想要优先考虑访问者体验且不想通过 Turnstile 交互在网站上增加任何摩擦的用户。

不可见模式 (Invisible mode)

不可见模式类似于非交互式模式，访问者永远不需要与 Turnstile 小组件进行交互。访问者也不会看到小组件，或者看到正在进行不可见浏览器质询的任何指示。

不可见模式非常适合想要在网站上优先考虑访问者体验和视觉体验的用户。

尺寸

小组件可以以 normal（正常）、flexible（自适应）或 compact（紧凑）尺寸进行实施。

有关详细的配置选项和代码示例，请参阅小组件配置。

外观与主题

Turnstile 小组件支持多种外观模式和主题，以匹配您网站的设计。

有关实施细节，请参阅小组件配置。

flowchart LR
accTitle: 小组件正常运行状态
accDescr: 此图说明 Turnstile 小组件的正常运行状态。
    A[<b>Loading (加载中)</b><br /><small>小组件正在处理质询。</small> ] --> B[<b>Interaction (交互)*</b><br /><small>访问者需要勾选复选框。<br />*仅限托管模式。</small>]
    B --> C[<b>Success (成功)</b><br /><small>质询已成功完成。</small>]

错误状态

类型	描述
未知错误 (Unknown error)	当质询期间发生未知错误时，访问者将遇到此小组件状态。访问者可以按照小组件的故障排除指南进行操作，或刷新页面以重试质询。
交互超时 (Interaction timed out)	当向访问者呈现复选框但其在较长时间内未与其进行交互时。必须通过重新加载页面或小组件来重新发出质询。
质询超时 (Challenge timed out)	当验证已完成但未采取进一步行动时，质询结果将不再有效。例如，如果 Turnstile 小组件在登录页面上且 Turnstile 成功运行，但访问者在较长时间内未登录，则必须通过重新加载页面或小组件来重新发出质询。
浏览器版本过旧或不受支持 (Outdated or unsupported browser)	使用过旧浏览器或不受支持浏览器的访问者将遇到此小组件状态。有关受支持浏览器的更多信息，请参阅受支持的浏览器。

Turnstile 小组件

小组件组成部分

小组件模式