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 bottomrightbottomleftinline bottomright 可选。调整 reCAPTCHA 徽章的位置。inline 可让您使用 CSS 对其进行定位。
data-action action 可选。描述当前操作的字符串。
data-theme theme darklight light 可选。微件的颜色主题背景。
data-size size compactnormal 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 遇到错误(通常是网络连接问题),并且在恢复连接之前无法继续时执行的回调函数名称。回调不会收到任何包含错误详细信息的参数。如果您在此处指定了函数 应负责通知用户应重试。