小组件配置

配置小组件外观、语言和回调函数。

您可以使用 data 属性或 JavaScript 渲染参数来配置 Turnstile 小组件的外观、行为和功能。

渲染方法

可以通过隐式或显式渲染来实施 Turnstile 小组件。

隐式渲染 (Implicit rendering) 会在页面加载时自动扫描 HTML 以查找带有 cf-turnstile 类的元素，并渲染该小组件。它最适合简单的实现、静态网站，或者当您希望小组件在页面加载时立即出现的情况。

工作原理

将 Turnstile 脚本添加到页面中。
包含 <div class="cf-turnstile" data-sitekey="您的 sitekey"></div> 元素。
小组件会在页面加载时自动渲染。
使用 HTML 元素上的 data-* 属性配置小组件。

示例html

	<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-theme="light"></div>

显式渲染 (Explicit rendering) 允许您使用 JavaScript 函数对何时以及如何创建小组件进行编程控制。它最适合动态网站和单页应用 (SPA)、需要控制小组件创建的时机、根据访问者交互进行条件渲染，或者需要具有不同配置的多个小组件的情况。

工作原理

添加带有 ?render=explicit 参数的 Turnstile 脚本。
创建容器元素（不要包含 cf-turnstile 类）。
当您想要创建小组件时，调用 turnstile.render() 函数。
使用 JavaScript 对象参数配置小组件。

示例html

	<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit" defer></script>
	<div id="my-widget"></div>
	
	<script>
	window.onload = function() {
		turnstile.render('#my-widget', {
			sitekey: '<YOUR-SITE-KEY>',
			theme: 'light',
			callback: function(token) {
				console.log('成功：', token);
			}
		});
	};
	</script>

在使用托管 (Managed) 或非交互式 (Non-Interactive) 模式时，Turnstile 小组件可以具有两种不同的固定尺寸或自适应宽度尺寸。

尺寸	宽度	高度	用例
Normal (正常)	300px	65px	标准实现
Flexible (自适应)	100% (最小: 300px)	65px	响应式设计
Compact (紧凑)	150px	140px	空间受限的布局

normal：默认尺寸，适用于大多数桌面和移动端布局。如果您的网站或表单上有足够的水平空间，请使用此尺寸。
flexible：自动适应容器宽度，同时保持最低可用性。适用于需要跨所有屏幕尺寸工作的响应式设计。
compact：非常适合移动端界面、侧边栏或任何水平空间受限的空间。紧凑型小组件比普通型更高，以适应较小的宽度。

普通尺寸（默认）html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

自适应尺寸html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="flexible"></div>

紧凑尺寸html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="compact"></div>

普通尺寸（默认）js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

自适应尺寸js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		size: 'flexible'
	});

紧凑尺寸js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		size: 'compact'
	});

主题选项

自定义小组件的外观，以匹配您网站的设计。

auto（默认）：自动匹配访问者的系统主题偏好。建议在大多数实现中使用 auto，因为它尊重访问者的偏好并提供最佳的无障碍体验。
light：带有明亮色彩和清晰对比度的浅色主题。浅色主题在明亮的背景上效果最好，并提供高对比度以利于阅读。
dark：针对深色界面优化的深色主题。深色主题非常适合深色界面、游戏网站或使用深色配色方案的应用程序。

自动主题（默认）html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

浅色主题html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-theme="light"></div>

深色主题html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-theme="dark"></div>

自动主题（默认）js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

浅色主题js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		theme: 'light'
	});

深色主题js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		theme: 'dark'
	});

外观模式 (Appearance modes)

使用外观模式控制小组件何时对访问者可见。

always（默认）：小组件从页面加载起始终可见。对于希望访问者立即看到小组件的大多数实现来说，这是最佳选择，因为它提供了安全验证正在实施的清晰视觉反馈。
execute：小组件仅在质询开始后才变得可见。这对于您需要控制小组件出现时机的情况很有用，例如仅在访问者开始填写表单或选择提交按钮时才显示它。
interaction-only：小组件仅在需要访问者交互时才变得可见，从而提供最整洁的访问者体验。大多数访问者永远不会看到该小组件，但疑似 bot 将会遇到交互式质询。

始终可见（默认）html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

仅在质询开始后可见html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-appearance="execute"></div>

仅在需要交互时可见html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-appearance="interaction-only"></div>

始终可见（默认）js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

仅在质询开始后可见js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		appearance: 'execute'
	});

仅在需要交互时可见js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		appearance: 'interaction-only'
	});

执行模式 (Execution modes)

控制质询何时运行并生成令牌。

render（默认）：在调用 render() 函数后自动运行质询，并在小组件加载时立即提供保护。质询在页面加载时在后台运行，确保令牌在访问者提交数据时准备就绪。
execute：在单独调用 turnstile.execute() 函数后运行质询，让您精确控制何时进行验证。此选项对于多步骤表单、条件验证，或者当您希望将质询推迟到访问者实际尝试提交数据时很有用。这可以通过仅在需要时运行验证来提高页面加载性能和访问者体验。

常见场景
- 多步骤表单：仅在最后一步运行验证。
- 条件保护：仅验证符合特定条件的访问者。
- 性能优化：推迟验证以减少初始页面加载时间。
- 用户触发的验证：让访问者手动启动验证过程。

自动执行（默认）html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

手动执行html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-execution="execute"></div>

自动执行（默认）js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

手动执行js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		execution: 'execute'
	});

稍后执行质询js

	turnstile.execute('#widget-container');

语言配置

设置小组件界面的语言。

auto（默认）：使用访问者的浏览器语言首选项。
特定语言代码：ISO 639-1 双字母代码，例如 es、fr、de。
语言和地区：用于地区变体的组合代码，例如 en-US、es-MX、pt-BR。

自动语言（默认）html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

特定语言html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-language="es"></div>

语言和国家html

	<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-language="en-US"></div>

自动语言（默认）js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>'
	});

特定语言js

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		language: 'es'
	});

回调配置

使用回调处理小组件事件。

callback：质询成功完成时触发。
error-callback：质询期间发生错误时触发。
expired-callback：令牌过期（超时前）时触发。
timeout-callback：交互式质询超时时触发。

成功回调会接收一个令牌，该令牌必须在您的服务器上使用 Siteverify API 进行验证。令牌为一次性使用，并在 300 秒（五分钟）后过期。

	<div class="cf-turnstile"
		data-sitekey="<YOUR-SITE-KEY>"
		data-callback="onSuccess"
		data-error-callback="onError"
		data-expired-callback="onExpired"
		data-timeout-callback="onTimeout"></div>
	<script>
	function onSuccess(token) {
	console.log('质询成功：', token);
	}
	function onError(errorCode) {
	console.log('质询错误：', errorCode);
	}
	function onExpired() {
	console.log('令牌已过期');
	}
	function onTimeout() {
	console.log('质询已超时');
	}
	</script>

	turnstile.render('#widget-container', {
		sitekey: '<YOUR-SITE-KEY>',
		callback: function(token) {
			console.log('质询成功：', token);
		},
		'error-callback': function(errorCode) {
			console.log('质询错误：', errorCode);
		},
		'expired-callback': function() {
			console.log('令牌已过期');
		},
		'timeout-callback': function() {
			console.log('质询已超时');
		}
	});

最佳实践

始终实现成功回调以处理令牌并继续表单提交或下一步骤。
使用错误回调进行妥善的错误处理和访问者反馈。
监控过期的令牌，以便在它们失效之前刷新质询。
处理超时以引导访问者解决质询。

高级配置选项

重试行为

控制 Turnstile 如何处理失败的质询。

auto（默认）：自动重试失败的质询。自动重试通过自动从临时网络问题或处理错误中恢复，提供更好的访问者体验。
never：禁用自动重试。这需要手动干预，并能让您在需要自定义重试逻辑的应用程序中完全控制错误处理。
retry-interval：控制重试尝试之间的时间（默认值：8000ms），让您在快速恢复与服务器负载之间取得平衡。

自动重试（默认）html

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

禁用重试html

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-retry="never"></div>

自定义重试间隔（默认 8000ms）html

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-retry-interval="8000"></div>

刷新行为

控制 Turnstile 如何处理令牌过期和交互式超时。

refresh-expired：控制令牌过期时的行为（auto、manual、never）。
refresh-timeout：控制交互式质询超时时的行为（auto、manual、never）。

优势

auto 刷新提供无缝的访问者体验，但会使用更多资源。
manual 刷新为访问者提供控制，但需要他们采取行动。
never 刷新要求您的应用程序处理所有刷新逻辑。

可以根据您的访问者体验需求，对令牌过期与交互式超时采用不同的策略。

自动刷新过期令牌（默认）html

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>"></div>

手动刷新html

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-refresh-expired="manual"></div>

自动刷新超时（托管模式的默认设置）html

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-refresh-timeout="auto"></div>

自定义数据

在您的质询中添加自定义标识符和数据。

action：用于分析和区分的自定义标识符（最多 32 个字符）。
cData：在验证期间返回的自定义负载数据（最多 255 个字符）。

用例

操作跟踪：在您的分析中区分登录、注册、联系表单等。
访问者上下文：传递访问者 ID、会话信息或其他上下文数据。
A/B 测试：跟踪不同的小组件配置或页面变体。
欺诈检测：包含用于风险评估的额外上下文。

添加自定义操作标识符html

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-action="login"></div>

添加自定义数据负载html

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-cdata="user-cdata"></div>

表单集成

配置 Turnstile 如何与 HTML 表单集成。

启用后，Turnstile 会自动创建一个带有验证令牌的隐藏 <input> 元素。这会与您的其他表单数据一起提交，使服务器端验证变得简单明了。

response-field：确定是否使用令牌创建隐藏的表单字段（默认值：true）
response-field-name：隐藏表单字段的自定义名称（默认值：cf-turnstile-response）

优势

自动表单集成意味着在提交表单时包含令牌，无需额外的 JavaScript。
自定义字段名称有助于避免与现有表单字段冲突。
禁用的响应字段使您能够在复杂的表单场景中完全控制令牌处理。

自定义响应字段名称html

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-response-field-name="turnstile-token"></div>

禁用响应字段html

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-response-field="false"></div>

完整配置参考

JavaScript 渲染参数	Data 属性	描述
`sitekey`	`data-sitekey`	每个小组件都有一个 sitekey。该 sitekey 与相应的小组件配置相关联，并在创建小组件时创建。
`action`	`data-action`	自定义值，可用于在分析中区分同一 sitekey 下的小组件，并在验证时返回。这只能包含最多 32 个字母数字字符，包括 `_` 和 `-`。
`cData`	`data-cdata`	自定义负载，可用于在整个质询签发过程中将客户数据附加到质询，并在验证时返回。这只能包含最多 255 个字母数字字符，包括 `_` 和 `-`。
`callback`	`data-callback`	质询成功时调用的 JavaScript 回调函数。该回调会传递一个可以验证的令牌。
`error-callback`	`data-error-callback`	发生错误时调用的 JavaScript 回调函数（例如网络错误或质询失败）。请参阅客户端错误。
`execution`	`data-execution`	执行控制何时获取小组件的令牌，可以是 `render`（默认）或 `execute`。有关更多信息，请参阅执行模式。
`expired-callback`	`data-expired-callback`	令牌过期且未重置小组件时调用的 JavaScript 回调函数。
`before-interactive-callback`	`data-before-interactive-callback`	在质询进入交互模式之前调用的 JavaScript 回调函数。
`after-interactive-callback`	`data-after-interactive-callback`	质询离开交互模式时调用的 JavaScript 回调函数。
`unsupported-callback`	`data-unsupported-callback`	当 Turnstile 不支持给定的客户端/浏览器时调用的 JavaScript 回调函数。
`theme`	`data-theme`	小组件主题。可以采用以下值：`light`、`dark`、`auto`。默认值为 `auto`，它尊重访问者的偏好。这可以通过相应设置主题来强制设为浅色或深色。
`language`	`data-language`	要显示的语言，必须是：`auto`（默认）以使用访问者选择的语言，或者是 ISO 639-1 双字母语言代码（如 `en`）或语言和国家/地区代码（如 `en-US`）。有关更多信息，请参阅受支持语言列表。
`tabindex`	`data-tabindex`	出于无障碍目的的 Turnstile iframe 的 tabindex。默认值为 `0`。
`timeout-callback`	`data-timeout-callback`	当质询呈现交互式质询但在给定时间内未解决时调用的 JavaScript 回调函数。回调将重置小组件以允许访问者再次解决质询。
`response-field`	`data-response-field`	控制是否创建带有响应令牌的 input 元素的布尔值，默认为 `true`。
`response-field-name`	`data-response-field-name`	input 元素的名称，默认为 `cf-turnstile-response`。
`size`	`data-size`	小组件尺寸。可以采用以下值：`normal`、`flexible`、`compact`。
`retry`	`data-retry`	控制小组件在未成功获取令牌时是否应自动重试。默认值为 `auto`，它将自动重试。可以将其设置为 `never` 以禁用失败时的重试。
`retry-interval`	`data-retry-interval`	当 `retry` 设置为 `auto` 时，`retry-interval` 控制重试尝试之间的间隔时间（以毫秒为单位）。值必须是小于 `900000` 的正整数，默认为 `8000`。
`refresh-expired`	`data-refresh-expired`	在令牌过期时自动刷新令牌。可采用 `auto`、`manual` 或 `never`，默认为 `auto`。
`refresh-timeout`	`data-refresh-timeout`	控制小组件在进入交互式质询并观察到超时时是否应自动刷新。可采用 `auto`（在遇到交互式超时时自动刷新）、`manual`（提示访问者手动刷新）或 `never`（将显示超时），默认为 `auto`。仅适用于托管模式的小组件。
`appearance`	`data-appearance`	外观控制小组件何时可见。它可以是 `always`（默认）、`execute` 或 `interaction-only`。有关更多信息，请参阅外观模式。
`feedback-enabled`	`data-feedback-enabled`	允许 Cloudflare 在小组件失败时收集访问者反馈。可以是 `true`（默认）或 `false`。
`offlabel-show-privacy`	`data-offlabel-show-privacy`	为无品牌 Turnstile 小组件显示隐私政策链接。可以是 `true`（默认）或 `false`。
`offlabel-show-help`	`data-offlabel-show-help`	为无品牌 Turnstile 小组件显示帮助链接。可以是 `true`（默认）或 `false`。

示例

响应式设计小组件html

<div style="max-width: 500px;">
  <div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="flexible" data-theme="auto"></div>
</div>

移动端优化的紧凑尺寸小组件html

<div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-size="compact" data-theme="light" data-language="en">
</div>