reCAPTCHA v2

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

要显示微件,您可以使用以下任一操作:

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

请参阅验证用户的响应,确认用户是否成功完成了人机识别系统验证。

自动呈现 reCAPTCHA widget

如需在网页上呈现 reCAPTCHA widget,最简单的方法是添加必要的 JavaScript 资源和 g-recaptcha 标记。g-recaptcha 标记是一个 DIV 元素,其类名称为 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 (可选)加载所有依赖项后要执行的回调函数的名称。
呈现 明确的
onload
(可选)是否显式呈现微件。默认为 onload,它将在找到的第一个 g-recaptcha 标签中呈现微件。
hl 参阅语言代码 (可选)强制微件以特定语言呈现。如果未指定语言,则会自动检测用户的语言。

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

g-recaptcha 标签特性 grecaptcha.render 参数 默认 说明
data-sitekey sitekey 您的网站密钥。
data-theme 主题背景 深色 浅色 (可选)微件的颜色主题背景。
data-size 大小 正常紧凑 正常 (可选)微件的大小。
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>