隐形 reCAPTCHA

本页介绍了如何在网页上启用和自定义隐形 reCAPTCHA。

如需调用隐形 reCAPTCHA,您可以执行以下任一操作:

如需了解如何自定义隐形 reCAPTCHA,请参阅配置。例如,您可以指定语言或徽章位置。

请参阅验证用户的响应,检查用户是否已成功通过人机识别系统验证。

自动将质询绑定到按钮

在网页上使用不可见的 reCAPTCHA widget 的最简单方法是添加必要的 JavaScript 资源,并向 HTML 按钮添加一些属性。必需的属性包括类名称“g-recaptcha”、data-sitekey 属性中的网站键,以及处理 data-callback 属性中人机识别系统完成情况的 JavaScript 回调的名称。

<html>
  <head>
    <title>reCAPTCHA demo: Simple page</title>
     <script src="https://www.google.com/recaptcha/api.js" async defer></script>
     <script>
       function onSubmit(token) {
         document.getElementById("demo-form").submit();
       }
     </script>
  </head>
  <body>
    <form id="demo-form" action="?" method="POST">
      <button class="g-recaptcha" data-sitekey="your_site_key" data-callback="onSubmit">Submit</button>
      <br/>
    </form>
  </body>
</html>

该脚本必须使用 HTTPS 协议加载,并且可以从网页上的任何位置不受限制。

以程序化方式将质询绑定到按钮或调用质询。

通过指定 onload 回调函数并向 JavaScript 资源添加参数,可以实现延迟绑定。这与常规的 reCAPTCHA 验证相同。

以编程方式调用质询。

您可以通过以下方法以程序化方式调用 reCAPTCHA 验证:在具有属性 data-size="invisible" 的 div 中呈现质询,然后以编程方式调用 perform。

  1. 使用 data-size="invisible" 创建 div。

    <div class="g-recaptcha"
          data-sitekey="_your_site_key_"
          data-callback="onSubmit"
          data-size="invisible">
    </div>
    
  2. 通过 JavaScript 方法调用 grecaptcha.execute 方法。

    grecaptcha.execute();
    

    执行回调时,您可以通过 JavaScript API 调用 grecaptcha.render 方法。

配置

JavaScript 资源 (api.js) 参数

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

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

g-recaptcha 标签特性 grecaptcha.render 参数 默认 说明
data-sitekey sitekey 您的网站密钥。
数据标记 徽章 右下角(内嵌) 右下角 可选。调整 reCAPTCHA 徽章的位置。“inline”可让您使用 CSS 确定其位置
data-size 大小 invisible 可选。用于创建绑定到 div 并以编程方式执行的不可见 widget。
data-tabindex tabindex 0 可选。挑战的 tabindex。如果页面中的其他元素使用 tabindex,则应对其进行设置使其可更为轻松地使用户导航。
data-callback callback 可选。当用户提交成功的响应时执行的回调函数的名称。g-recaptcha-response 令牌将传递给您的回调。
data-expired-callback expired-callback 可选。在 reCAPTCHA 响应到期且用户需要重新验证时执行的回调函数的名称,。
data-error-callback error-callback 可选。在 reCAPTCHA 遇到错误(通常是网络连接问题),并且在恢复连接之前无法继续时执行的回调函数名称。如果在此处指定功能,您需负责通知用户进行重试。
隔离 false 可选。让插件所有者能够干扰网页上现有的 reCAPTCHA 安装。如果为 true,此 reCAPTCHA 实例将属于单独的 ID 空间。

JavaScript API

方法 说明
grecaptcha.render(
容器
参数,
继承
将容器呈现为 reCAPTCHA 微件,并返回新创建的微件的 ID。
容器
  用于呈现 reCAPTCHA 微件的 HTML 元素。 指定容器的 ID(字符串)或 DOM 元素本身。
parameters
以键值对形式包含参数的对象,例如 {"sitekey": "your_site_key", "theme": "light"}。请参阅 grecaptcha.render 参数
继承
如果未指定相应参数,请在元素上使用现有的 data-* 属性。参数的优先级高于属性。
grecaptcha.execute(
)
opt_widget_id
以编程方式调用 reCAPTCHA 检查。如果隐形 reCAPTCHA 位于 div(而非按钮)上,使用此属性。
opt_widget_id
  可选的微件 ID,如果未指定,则默认为创建的第一个微件。
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>
        var onSubmit = function(token) {
          console.log('success!');
        };

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

在客户端验证后调用隐形 reCAPTCHA 验证。

<html>
  <head>
  <script>
    function onSubmit(token) {
      alert('thanks ' + document.getElementById('field').value);
    }

    function validate(event) {
      event.preventDefault();
      if (!document.getElementById('field').value) {
        alert("You must add text to the required field");
      } else {
        grecaptcha.execute();
      }
    }

    function onload() {
      var element = document.getElementById('submit');
      element.onclick = validate;
    }
  </script>
  <script src="https://www.google.com/recaptcha/api.js" async defer></script>
  </head>
  <body>
    <form>
      Name: (required) <input id="field" name="field">
      <div id="recaptcha" class="g-recaptcha"
          data-sitekey="_your_site_key_"
          data-callback="onSubmit"
          data-size="invisible"></div>
      <button id="submit">submit</button>
    </form>
    <script>onload();</script>
  </body>
</html>