本页面介绍了 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 |
以键值对形式包含参数的对象,例如 如需详细了解每个可配置参数,请参阅特性和参数。 |
返回值
返回新创建的 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 键的值指定与受保护元素关联的操作名称。
例如: |
返回值
如果成功,则返回包含令牌的 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 |
可选,默认值。在找到的第一个 |
explicit
|
可选。不自动呈现 widget。您需要调用 |
|
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 |
可选。微件的颜色主题背景。 |
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 遇到错误(通常是网络连接问题),并且在恢复连接之前无法继续时执行的回调函数名称。如果在此处指定功能,您需负责通知用户进行重试。 |