reCAPTCHA v2

本页介绍了如何在网页上显示和自定义 reCAPTCHA v2 微件。

要显示微件，您可以使用以下任一操作：

请参阅配置，了解如何自定义 widget。例如，您可能要指定微件的语言或主题背景。

请参阅验证用户的响应，检查用户是否成功解开了 CAPTCHA。

自动呈现 reCAPTCHA 微件

在页面上呈现 reCAPTCHA 微件的最简单方法是包括必要的 JavaScript 资源和 g-recaptcha 标签。g-recaptcha 标记 是类名称为 g-recaptcha 且您的网站密钥位于 data-sitekey 属性：


  
    reCAPTCHA demo: Simple page

该脚本必须使用 HTTPS 协议加载，并且可以从页面的任意位置无限制地添加。

显式呈现 reCAPTCHA widget

通过指定 onload 回调函数并向 JavaScript 资源添加参数，可以延迟呈现。

  1. 指定您的 onload 回调函数。在调用此函数时， 所有依赖项都已加载完毕

  2. 插入 JavaScript 资源，将 onload 参数设置为 onload 回调函数的名称，并将 render 参数设置为 explicit。

    执行回调后，您可以从 JavaScript API 调用 grecaptcha.render 方法。

配置

JavaScript 资源 (api.js) 参数

参数 值 说明
onload 可选。加载所有依赖项后要执行的回调函数的名称。
render 明确的
onload		 可选。是否显式呈现微件。默认为 onload，它将在找到的第一个 g-recaptcha 标签中呈现微件。
hl 参阅语言代码 可选。强制微件以特定语言呈现。如果未指定语言，则会自动检测用户的语言。

g-recaptcha 标签特性和 grecaptcha.render 参数

g-recaptcha 标签特性 grecaptcha.render 参数 值 默认 说明
data-sitekey sitekey 您的网站密钥。
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 遇到错误（通常是网络连接问题），并且在恢复连接之前无法继续时执行的回调函数名称。如果在此处指定功能，您需负责通知用户进行重试。

JavaScript API

方法 说明
grecaptcha.render(
容器
参数
) 		将容器呈现为 reCAPTCHA 微件，并返回新创建的微件的 ID。
容器
  用于呈现 reCAPTCHA 微件的 HTML 元素。 指定容器的 ID（字符串）或 DOM 元素本身。
参数
包含键值对的对象，例如 {"sitekey": "your_site_key", "theme": "light"}。请参阅 grecaptcha.render 参数。
grecaptcha.reset(
opt_widget_id
) 		重置 reCAPTCHA 微件。
opt_widget_id
  可选的微件 ID，如果未指定，则默认为创建的第一个微件。
grecaptcha.getResponse(
opt_widget_id
) 		获取 reCAPTCHA 微件的响应。
opt_widget_id
  可选的微件 ID，如果未指定，则默认为创建的第一个微件。

示例

在 onload 回调之后进行显式呈现


  
    reCAPTCHA demo: Explicit render after an onload callback

显式呈现多个微件


  
    reCAPTCHA demo: Explicit render for multiple widgets