reCAPTCHA Enterprise 的 JavaScript API 参考文档

本页面介绍了 reCAPTCHA Enterprise JavaScript API 的方法及其配置参数，可用于通过 reCAPTCHA 密钥（网站密钥）呈现网页。

reCAPTCHA Enterprise JavaScript API 方法

本部分介绍了 reCAPTCHA Enterprise JavaScript API 方法的语法和参数。

grecaptcha.enterprise.render

将容器渲染为 reCAPTCHA widget，并返回新创建的 widget 的 ID。

语法

grecaptcha.enterprise.render(container: string | HTMLelement, parameters: Object): number

方法参数

参数	说明
container	用于呈现 reCAPTCHA 微件的 HTML 元素。指定容器（字符串）的 ID 或 DOM 元素本身。
parameters	以键值对形式包含参数的对象，例如 {"sitekey": "your_site_key", "action": "login", "theme": "dark"}。 如需详细了解每个可配置参数，请参阅特性和参数。

返回值

返回新创建的 widget 的 ID。

grecaptcha.enterprise.reset

重置 reCAPTCHA 微件。

语法

grecaptcha.enterprise.reset(widget_id: number): void

参数

参数	说明
widget_id	可选。从 grecaptcha.enterprise.render() 返回的微件 ID。如果未指定，则默认为创建的第一个 widget 的 ID。

返回值

不返回任何值。

grecaptcha.enterprise.execute

以编程方式调用 reCAPTCHA Enterprise 验证。

语法

grecaptcha.enterprise.execute(widget_id: number): Promise<string>

grecaptcha.enterprise.execute(sitekey: string, action: Object): Promise<string>

参数

参数	说明
widget_id	可选。从 grecaptcha.enterprise.render() 返回的微件 ID。 如果未指定，则默认为创建的第一个 widget 的 ID。 注意：与复选框网站键搭配使用。
sitekey	指定要保护的 reCAPTCHA 网站密钥。 注意：适用于基于得分的网站键。
action	具有一个键值对的对象，其中 action 键的值指定与受保护元素关联的操作名称。 注意：适用于基于得分的网站键。 例如：{"action": "action_name"}

返回值

如果成功，则返回包含令牌的 Promise 对象。

grecaptcha.enterprise.ready

在 reCAPTCHA Enterprise JavaScript 库加载时运行您的函数。

语法

grecaptcha.enterprise.ready(callback: function): void

参数

参数	说明
callback	reCAPTCHA 库完成加载时要调用的函数。

返回值

不返回任何值。

grecaptcha.enterprise.getResponse

获取 reCAPTCHA 微件的响应。

语法

grecaptcha.enterprise.getResponse(widget_id: number): string

参数

参数	说明
widget_id	可选。从 grecaptcha.enterprise.render() 返回的微件 ID。如果未指定，则默认为创建的第一个 widget 的 ID。

返回值

获取 reCAPTCHA widget 的响应。它可以是包含由 grecaptcha.enterprise.execute() 创建的令牌的字符串；如果令牌尚未创建，则可以为空字符串。

配置

本部分介绍了 grecaptcha.enterprise.render() 使用的 JavaScript 资源参数和参数以及 g-recaptcha widget 的属性。

JavaScript 资源 (enterprise.js) 参数

下表列出了使用 reCAPTCHA Enterprise 时必须包含的 JavaScript 资源 (enterprise.js) 的参数。

如需详细了解如何使用这些参数，请参阅 在前端呈现 reCAPTCHA widget 中的示例。

参数	值	说明
onload	callback	可选。要在所有依赖项加载完成后执行的回调函数的名称。
render	onload	可选，默认值。在找到的第一个 g-recaptcha 标记中渲染此 widget。 注意：与复选框网站密钥搭配使用。
	explicit	可选。不自动呈现 widget。您需要调用 grecaptcha.enterprise.render() 以程序化方式呈现。 注意：与复选框网站密钥搭配使用。
	siteKey	与基于得分的网站键一起使用时，此参数不是可选参数。值 siteKey 指定关联的基于得分的网站密钥。 注意：仅适用于基于得分的网站键；如果与复选框网站键搭配使用，脚本将无法加载。
hl	参阅语言代码	可选。强制微件以特定语言呈现。 如果未指定语言，则会自动检测用户的语言。

g-recaptcha 代码属性和 grecaptcha.enterprise.render() 参数

下表列出了 g-recaptcha 标记属性和相应的 grecaptcha.enterprise.render() 参数。

g-recaptcha 标记属性	grecaptcha.enterprise.render() 参数	允许使用的值	默认	说明
data-sitekey	sitekey			reCAPTCHA 密钥
data-badge	badge	bottomright、bottomleft、inline	bottomright	可选。调整 reCAPTCHA 徽章的位置。inline 可让您使用 CSS 确定位置。
data-action	action			可选。描述当前操作的字符串。
data-theme	theme	dark, light	light	可选。微件的颜色主题背景。
data-size	size	compact，normal	normal	可选。微件的大小。
data-tabindex	tabindex	整数	0	可选。微件和挑战的 tabindex。如果页面中的其他元素使用 tabindex，则应对其进行设置使其可更为轻松地使用户导航。
data-callback	callback	字符串	不适用	可选。当用户提交成功的响应时执行的回调函数的名称。g-recaptcha-response 令牌将传递给您的回调。
data-expired-callback	expired-callback	字符串	不适用	可选。在 reCAPTCHA 响应到期且用户需要重新验证时执行的回调函数的名称，。
data-error-callback	error-callback	字符串	不适用	可选。在 reCAPTCHA 遇到错误（通常是网络连接问题），并且在恢复连接之前无法继续时执行的回调函数名称。如果在此处指定功能，您需负责通知用户进行重试。