HTML 服务：与服务器功能通信

google.script.run 是一个异步客户端 JavaScript API，允许 HTML 服务页面调用服务器端 Apps 脚本函数。以下示例展示了最基本功能 google.script.run，即从客户端 JavaScript 调用服务器上的函数。

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function doSomething() {
  Logger.log('I was called!');
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      google.script.run.doSomething();
    </script>
  </head>
</html>

如果您将此脚本部署为 Web 应用并访问其网址，则不会看到任何内容，但如果您查看日志，则会看到服务器函数 doSomething 已被调用。

对服务器端函数的客户端调用是异步的：在浏览器请求服务器运行函数 doSomething 后，浏览器会立即继续执行下一行代码，而无需等待响应。这意味着服务器函数调用可能不会按您预期的顺序执行。如果您同时进行两个函数调用，则无法知道哪个函数先运行；每次加载页面时，结果可能会有所不同。在这种情况下，成功处理程序和失败处理程序有助于控制代码的流程。

google.script.run API 允许对服务器函数进行 10 个并发调用。如果您在 10 个调用仍在运行时进行第 11 个调用，则服务器函数会延迟执行，直到其中一个位置空闲为止。实际上，您很少需要考虑此限制，尤其是在大多数浏览器已经将对同一服务器的并发请求数限制为低于 10 的情况下。例如，在 Firefox 中，此限制为 6。大多数浏览器同样会延迟多余的服务器请求，直到其中一个现有请求完成为止。

参数和返回值

使用客户端的参数调用服务器函数。同样，服务器函数可以将值作为传递给成功处理程序的参数返回给客户端。

合法参数和返回值采用 Number、Boolean、String 或 null 等 JavaScript 原语，以及由原语、对象和数组组成的 JavaScript 对象和数组。页面中的 form 元素也可以作为参数，但它必须是函数的唯一参数，并且不能作为返回值。如果您尝试传递 Date、Function、form 以外的 DOM 元素或其他禁止的类型（包括对象或数组中的禁止类型），请求将会失败。创建循环引用的对象也会失败，并且数组中未定义的字段会变为 null。

请注意，传递给服务器的对象会成为原始对象的副本。如果服务器函数接收到对象并更改其属性，则客户端上的属性不会受到影响。

成功处理程序

由于 google.script.run 调用是异步的，因此客户端代码会继续执行下一行，而无需等待响应。如需指定在服务器响应时运行的回调函数，请使用 withSuccessHandler(function)。如果服务器函数返回值，API 会将该值作为参数传递给回调函数。

以下示例会在服务器响应时显示浏览器提醒。此代码示例需要授权，因为服务器端函数会访问您的 Gmail 账号。如需授权脚本，请在加载页面之前，从脚本编辑器手动运行一次 getUnreadEmails 函数。或者，当您部署 Web 应用以作为“访问 Web 应用的用户”执行时，系统会在加载应用时提示您进行授权。

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getUnreadEmails() {
  return GmailApp.getInboxUnreadCount();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function onSuccess(numUnread) {
        var div = document.getElementById('output');
        div.innerHTML = 'You have ' + numUnread
            + ' unread messages in your Gmail inbox.';
      }

      google.script.run.withSuccessHandler(onSuccess)
          .getUnreadEmails();
    </script>
  </head>
  <body>
    <div id="output"></div>
  </body>
</html>

失败处理程序

如果服务器未能响应或抛出错误， withFailureHandler(function) 您可以使用指定一个失败处理程序来代替成功处理程序运行。如果发生错误，API 会将 Error 对象作为实参传递给失败处理程序。

默认情况下，如果您未指定失败处理程序，系统会将失败记录到 JavaScript 控制台中。如需替换此行为，请调用 withFailureHandler(null) 或提供一个不执行任何操作的失败处理程序。

失败处理程序的语法与成功处理程序的语法几乎相同，如以下示例所示。

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getUnreadEmails() {
  // 'got' instead of 'get' throws an error.
  return GmailApp.gotInboxUnreadCount();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function onFailure(error) {
        var div = document.getElementById('output');
        div.innerHTML = "ERROR: " + error.message;
      }

      google.script.run.withFailureHandler(onFailure)
          .getUnreadEmails();
    </script>
  </head>
  <body>
    <div id="output"></div>
  </body>
</html>

User 对象

如需对服务器的多个调用重复使用相同的成功或失败处理程序，请调用 withUserObject(object) 以指定作为第二个参数传递给处理程序的对象。此“User 对象”（不要与 User类混淆）可让您响应客户端与服务器联系时所处的上下文。由于 User 对象不会发送到服务器，因此它们可以是大多数内容，包括函数和 DOM 元素，而无需受服务器调用参数和返回值的限制。User 对象不能是使用 new 运算符构造的对象。

在此示例中，点击两个按钮中的任意一个都会使用服务器中的值更新该按钮，而另一个按钮保持不变，即使它们共享一个成功处理程序也是如此。在 onclick 处理程序中，关键字 this 指的是 button 本身。

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getEmail() {
  return Session.getActiveUser().getEmail();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function updateButton(email, button) {
        button.value = 'Clicked by ' + email;
      }
    </script>
  </head>
  <body>
    <input type="button" value="Not Clicked"
      onclick="google.script.run
          .withSuccessHandler(updateButton)
          .withUserObject(this)
          .getEmail()" />
    <input type="button" value="Not Clicked"
      onclick="google.script.run
          .withSuccessHandler(updateButton)
          .withUserObject(this)
          .getEmail()" />
  </body>
</html>

表单

如果您使用 form 元素作为参数调用服务器函数，则该表单会成为一个对象，其中字段名称作为键，字段值作为值。这些值都会转换为字符串，但文件输入字段的内容除外，这些内容会变为 Blob 对象。

此示例处理表单（包括文件输入字段），而无需重新加载页面；它会将文件上传到 Google 云端硬盘，然后在客户端页面中输出文件的网址。在 onsubmit 处理程序中，关键字 this 指的是表单本身。请注意，加载后，页面中的所有表单都会通过 preventFormSubmit 停用默认提交操作。这样可以防止页面在发生异常时重定向到不准确的网址。

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function processForm(formObject) {
  var formBlob = formObject.myFile;
  var driveFile = DriveApp.createFile(formBlob);
  return driveFile.getUrl();
}

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      // Prevent forms from submitting.
      function preventFormSubmit() {
        var forms = document.querySelectorAll('form');
        for (var i = 0; i < forms.length; i++) {
          forms[i].addEventListener('submit', function(event) {
            event.preventDefault();
          });
        }
      }
      window.addEventListener('load', preventFormSubmit);

      function handleFormSubmit(formObject) {
        google.script.run.withSuccessHandler(updateUrl).processForm(formObject);
      }
      function updateUrl(url) {
        var div = document.getElementById('output');
        div.innerHTML = '<a href="' + url + '">Got it!</a>';
      }
    </script>
  </head>
  <body>
    <form id="myForm" onsubmit="handleFormSubmit(this)">
      <input name="myFile" type="file" />
      <input type="submit" value="Submit" />
    </form>
    <div id="output"></div>
 </body>
</html>

脚本运行程序

您可以将 google.script.run 视为“脚本运行程序”的构建器。如果您向脚本运行程序添加成功处理程序、失败处理程序或 User 对象，则不会更改现有运行程序；相反，您会获得一个具有新行为的新脚本运行程序。

使用 withSuccessHandler、withFailureHandler 和 withUserObject 的任意组合和任意顺序。此外，还可以对已设置值的脚本运行程序调用任何修改函数。新值会覆盖先前的值。

此示例为所有三个服务器调用设置了一个通用失败处理程序，但设置了两个单独的成功处理程序：

var myRunner = google.script.run.withFailureHandler(onFailure);
var myRunner1 = myRunner.withSuccessHandler(onSuccess);
var myRunner2 = myRunner.withSuccessHandler(onDifferentSuccess);

myRunner1.doSomething();
myRunner1.doSomethingElse();
myRunner2.doSomething();

私有函数

名称以英文下划线结尾的服务器函数被视为私有函数。 google.script 无法调用这些函数，并且其名称永远不会发送给客户端。您可以使用它们来隐藏需要在服务器上保密的实现详细信息。google.script 也无法查看库中的函数或未在脚本顶层声明的函数。

在此示例中，函数 getBankBalance 在客户端代码中可用；即使您不调用它，检查源代码的用户也可以发现其名称。但是，函数 deepSecret_ 和 obj.objectMethod 对客户端完全不可见。

Code.gs

function doGet() {
  return HtmlService.createHtmlOutputFromFile('Index');
}

function getBankBalance() {
  var email = Session.getActiveUser().getEmail()
  return deepSecret_(email);
}

function deepSecret_(email) {
 // Do some secret calculations
 return email + ' has $1,000,000 in the bank.';
}

var obj = {
  objectMethod: function() {
    // More secret calculations
  }
};

Index.html

<!DOCTYPE html>
<html>
  <head>
    <base target="_top">
    <script>
      function onSuccess(balance) {
        var div = document.getElementById('output');
        div.innerHTML = balance;
      }

      google.script.run.withSuccessHandler(onSuccess)
          .getBankBalance();
    </script>
  </head>
  <body>
    <div id="output">No result yet...</div>
  </body>
</html>

调整 Google Workspace 应用中的对话框大小

您可以通过在客户端代码中调用 google.script.host方法 setWidth(width)或 setHeight(height)来调整 Google 文档、 Google 表格或表单中的自定义对话框的大小。（如需设置对话框的初始大小，请使用 HtmlOutput 方法 setWidth(width) 和 setHeight(height)。）请注意，对话框在调整大小后不会在父窗口中重新居中，并且无法调整边栏的大小。

关闭 Google Workspace 中的对话框和边栏

如果您使用 HTML 服务在 Google 文档、表格或表单中显示对话框或边栏，则无法通过调用 window.close来关闭界面。您必须改为调用 google.script.host.close。如需查看示例，请参阅以 Google Workspace 用户界面的形式提供 HTML 的部分。

在 Google Workspace 中移动浏览器焦点

如需将用户浏览器中的焦点从对话框或边栏切换回 Google 文档、表格或表单编辑器，请调用方法 google.script.host.editor.focus。此方法与文档服务方法 Document.setCursor(position) 和 Document.setSelection(range)结合使用时特别有用。

HTML 服务：与服务器功能通信 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Code.gs

Index.html

参数和返回值

成功处理程序

Code.gs

Index.html

失败处理程序

Code.gs

Index.html

User 对象

Code.gs

Index.html

表单

Code.gs

Index.html

脚本运行程序

私有函数

Code.gs

Index.html

调整 Google Workspace 应用中的对话框大小

关闭 Google Workspace 中的对话框和边栏

在 Google Workspace 中移动浏览器焦点

HTML 服务：与服务器功能通信