reCAPTCHA 的 JavaScript API 参考文档

reCAPTCHA JavaScript API 提供的方法和配置参数可让您使用网站密钥在网页上呈现和管理 reCAPTCHA 微件。

reCAPTCHA JavaScript API 方法

本部分介绍了 reCAPTCHA 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"}。 如需详细了解每个可配置参数，请参阅属性和参数。

返回值

返回新创建的小部件的 ID。

grecaptcha.enterprise.reset

重置 reCAPTCHA 微件。

语法

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

参数

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

返回值

不返回值。

grecaptcha.enterprise.execute

以编程方式调用 reCAPTCHA 验证。

语法

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

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

参数

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

返回值

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

grecaptcha.enterprise.ready

在 reCAPTCHA 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() 返回的 widget ID。如果未指定，则默认为创建的第一个 widget 的 ID。

返回值

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

配置

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

JavaScript 资源 (enterprise.js) 参数

下表列出了您在使用 reCAPTCHA 时必须添加的 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 遇到错误（通常是网络连接问题），并且在恢复连接之前无法继续时执行的回调函数名称。回调不会收到任何包含错误详情的参数。如果您在此处指定了函数，则需要负责通知用户重试。