Turnstile API 参考

# API 参考 ## 客户端 JavaScript API 加载脚本后，Turnstile JavaScript API 可通过 `window.turnstile` 访问。 ### `turnstile.render(container, options)` 将 Turnstile 小部件渲染到容器元素中。 **参数：** - `container` (string | HTMLElement): CSS 选择器或 DOM 元素 - `options` (TurnstileOptions): 配置对象 (参考 [configuration.md](configuration.md)) **返回值：** `string` - 用于其他 API 方法的小部件 ID **示例：** javascript const widgetId = window.turnstile.render('#my-container', { sitekey: 'YOUR_SITE_KEY', callback: (token) => console.log('Success:', token), 'error-callback': (code) => console.error('Error:', code) }); ### `turnstile.reset(widgetId)` 重置小部件（清除令牌，重置挑战状态）。在表单验证失败时非常有用。 **参数：** - `widgetId` (string): 来自 `render()` 的小部件 ID，或容器元素 **返回值：** `void` **示例：** javascript // 表单错误时重置 if (!validateForm()) { window.turnstile.reset(widgetId); } ### `turnstile.remove(widgetId)` 从 DOM 中完全移除小部件。 **参数：** - `widgetId` (string): 来自 `render()` 的小部件 ID **返回值：** `void` **示例：** javascript // 导航时清理 window.turnstile.remove(widgetId); ### `turnstile.getResponse(widgetId)` 获取小部件的当前令牌（如果挑战已完成）。 **参数：** - `widgetId` (string): 来自 `render()` 的小部件 ID，或容器元素 **返回值：** `string | undefined` - 令牌字符串，如果未就绪则返回 undefined **示例：** javascript const token = window.turnstile.getResponse(widgetId); if (token) { submitForm(token); } ### `turnstile.isExpired(widgetId)` 检查小部件的令牌是否已过期（超过 5 分钟）。 **参数：** - `widgetId` (string): 来自 `render()` 的小部件 ID **返回值：** `boolean` - 如果过期则为 true **示例：** javascript if (window.turnstile.isExpired(widgetId)) { window.turnstile.reset(widgetId); } ## 回调签名 typescript type TurnstileCallback = (token: string) => void; type ErrorCallback = (errorCode: string) => void; type TimeoutCallback = () => void; type ExpiredCallback = () => void; type BeforeInteractiveCallback = () => void; type AfterInteractiveCallback = () => void; type UnsupportedCallback = () => void; ## Siteverify API (服务端) **端点：** `https://challenges.cloudflare.com/turnstile/v0/siteverify` ### 请求 **方法：**