此页面由 Cloud Translation API 翻译。

隐形 reCAPTCHA

本页介绍了如何在您的网页上启用和自定义不可见的 reCAPTCHA。

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

自动将挑战绑定到按钮或
以编程方式将质询绑定到按钮或
以程序化方式调用验证问题

请参阅配置，了解如何自定义隐形 reCAPTCHA。例如，您可能需要指定语言或标志位置。

请参阅验证用户的回复，检查用户是否成功通过人机识别系统测试。

自动将挑战绑定到按钮

若要在网页上使用不可见的 reCAPTCHA 微件，最简单的方法就是添加必要的 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 中呈现质询，然后以编程方式调用 execute。

使用 data-size="invisible" 创建一个 div。

<div class="g-recaptcha"
      data-sitekey="_your_site_key_"
      data-callback="onSubmit"
      data-size="invisible">
</div>

通过 JavaScript 方法调用 grecaptcha.execute。
```
grecaptcha.execute();
```
执行回调时，您可以从 JavaScript API 调用 grecaptcha.render 方法。
<ph type="x-smartling-placeholder">
</ph> 必须在 reCAPTCHA API 加载之前定义 onload 回调函数。为确保不存在竞态条件，请执行以下操作： <ph type="x-smartling-placeholder">
- 先使用回调对脚本进行排序，然后再使用 reCAPTCHA
- 在 `script` 标记中使用 `async` 和 `defer` 参数

配置

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 元素本身。参数包含键值对的对象，例如 {"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>