reCAPTCHA 的 JavaScript API 参考文档

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

reCAPTCHA JavaScript API 方法

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

grecaptcha.enterprise.render

将容器呈现为 reCAPTCHA 微件，并返回新创建的微件的 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() 返回的微件 ID。如果不是 则默认为创建的第一个微件的 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() 返回的微件 ID。 如果未指定，则默认为创建的第一个微件的 ID。 注意：适用于复选框网站密钥。
sitekey	指定要保护的 reCAPTCHA 网站密钥。 注意：适用于基于得分的网站密钥。
action	具有单个键值对的对象，其中 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() 返回的微件 ID。如果未指定，则默认为创建的第一个微件的 ID。

返回值

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

配置

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

JavaScript 资源 (enterprise.js) 参数

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

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

参数	值	说明
onload	callback	可选。要执行的回调函数 依赖项加载完毕
render	onload	可选，默认值。在找到的第一个 g-recaptcha 标签中呈现微件。 注意：适用于复选框网站密钥。
	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 遇到错误（通常是网络连接问题），并且在恢复连接之前无法继续时执行的回调函数名称。回调不会收到任何包含错误详细信息的参数。如果您在此处指定了函数 应负责通知用户应重试。