此页面由 Cloud Translation API 翻译。

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

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

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 个并发调用。如果您进行第 11 次调用，而 10 次调用仍在运行时，则服务器函数直到 10 个位置中的其中一个释放出来。在实际操作中考虑到这一限制，特别是考虑到大多数浏览器已经向同一服务器发出的并发请求数小于 10 例如，在 Firefox 中，上限为 6。大多数浏览器同样会延迟服务器请求，直到某个现有请求完成为止。

参数和返回值

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

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

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

成功处理程序

因为客户端代码会继续执行下一行，而不必等待服务器调用完成 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) 可让您使用 Error 对象（如果有）作为参数传递。

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

失败处理程序的语法与成功处理程序几乎完全相同，因为示例。

Code.gs

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

function getUnreadEmails() {
  // 'got' instead of 'get' will throw 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 类 - 可让您响应客户端与服务器联系的上下文。由于用户对象不是发送到服务器，它们几乎可以是任何内容，包括函数、DOM 元素等等，而无需限制参数和返回值。但是，用户对象不能是使用 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 元素作为参数来调用服务器函数，则表单会变为单个对象，并以字段名称作为键，以字段值作为值。通过值均转换为字符串，但 file-input 的内容除外字段，这些字段将变为 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 视为“脚本运行程序”的构建器。如果您向脚本运行程序添加成功处理程序、失败处理程序或用户对象，不会更改现有运行程序；而是会返回一个新的脚本运行程序新行为。

您可以使用 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 文档、表格或 Google 文档中的自定义对话框通过调用 google.script.host 方法 setWidth(width) 或 setHeight(height) 英寸客户端代码中。（如需设置对话框的初始大小，请使用 HtmlOutput 种方式 setWidth(width) 和 setHeight(height)。）请注意，对话框在调整尺寸后不会将父窗口重新居中，无法调整边栏的大小。

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

如果您使用 HTML 服务显示对话框或边栏创建 Google 文档、表格或表单，您无法通过调用 window.close() 关闭接口。相反，必须调用 google.script.host.close()。有关示例，请参见提供 HTML 作为 Google Workspace 界面。

将浏览器焦点移到 Google Workspace

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