reCAPTCHA v2

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

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

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

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

自动呈现 reCAPTCHA 微件

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

<html>
  <head>
    <title>reCAPTCHA demo: Simple page</title>
    <script src="https://www.google.com/recaptcha/api.js" async defer></script>
  </head>
  <body>
    <form action="?" method="POST">
      <div class="g-recaptcha" data-sitekey="your_site_key"></div>
      <br/>
      <input type="submit" value="Submit">
    </form>
  </body>
</html>

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

显式呈现 reCAPTCHA widget

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

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

    <script type="text/javascript">
  var onloadCallback = function() {
    alert("grecaptcha is ready!");
  };
</script>

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

    <script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit"
    async defer>
</script>

    执行回调后，您可以从 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 回调之后进行显式呈现

<html>
  <head>
    <title>reCAPTCHA demo: Explicit render after an onload callback</title>
    <script type="text/javascript">
      var onloadCallback = function() {
        grecaptcha.render('html_element', {
          'sitekey' : 'your_site_key'
        });
      };
    </script>
  </head>
  <body>
    <form action="?" method="POST">
      <div id="html_element"></div>
      <br>
      <input type="submit" value="Submit">
    </form>
    <script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>

显式呈现多个微件

<html>
  <head>
    <title>reCAPTCHA demo: Explicit render for multiple widgets</title>
    <script type="text/javascript">
      var verifyCallback = function(response) {
        alert(response);
      };
      var widgetId1;
      var widgetId2;
      var onloadCallback = function() {
        // Renders the HTML element with id 'example1' as a reCAPTCHA widget.
        // The id of the reCAPTCHA widget is assigned to 'widgetId1'.
        widgetId1 = grecaptcha.render('example1', {
          'sitekey' : 'your_site_key',
          'theme' : 'light'
        });
        widgetId2 = grecaptcha.render(document.getElementById('example2'), {
          'sitekey' : 'your_site_key'
        });
        grecaptcha.render('example3', {
          'sitekey' : 'your_site_key',
          'callback' : verifyCallback,
          'theme' : 'dark'
        });
      };
    </script>
  </head>
  <body>
    <!-- The g-recaptcha-response string displays in an alert message upon submit. -->
    <form action="javascript:alert(grecaptcha.getResponse(widgetId1));">
      <div id="example1"></div>
      <br>
      <input type="submit" value="getResponse">
    </form>
    <br>
    <!-- Resets reCAPTCHA widgetId2 upon submit. -->
    <form action="javascript:grecaptcha.reset(widgetId2);">
      <div id="example2"></div>
      <br>
      <input type="submit" value="reset">
    </form>
    <br>
    <!-- POSTs back to the page's URL upon submit with a g-recaptcha-response POST parameter. -->
    <form action="?" method="POST">
      <div id="example3"></div>
      <br>
      <input type="submit" value="Submit">
    </form>
    <script src="https://www.google.com/recaptcha/api.js?onload=onloadCallback&render=explicit"
        async defer>
    </script>
  </body>
</html>