此页面由 Cloud Translation API 翻译。

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 元素本身。

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

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 微件的响应。它可以是包含 grecaptcha.enterprise.execute() 创建的令牌的字符串，也可以是空字符串（如果尚未创建令牌）。

配置

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

JavaScript 资源 (enterprise.js) 参数

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

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

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