google.script.run 类（客户端 API）

google.script.run 是一个异步客户端 JavaScript API，可通过 可调用服务器端 Apps 脚本的 HTML 服务网页 函数。从客户端与 Google 文档、表格或表单中的对话框或边栏互动 代码，请使用 google.script.host。有关详情，请参阅 与服务器功能通信指南 。

方法

方法返回类型简介
myFunction(...)（任何服务器端函数） void 使用相应名称执行服务器端 Apps 脚本函数。
withFailureHandler(function) google.script.run 设置在服务器端函数引发异常时要运行的回调函数。
withSuccessHandler(function) google.script.run 设置在服务器端函数成功返回时运行的回调函数。
withUserObject(object) google.script.run 设置一个对象，作为第二个参数传递给成功和失败处理程序。

详细文档

myFunction(...)（任何服务器端函数）

使用相应名称执行服务器端 Apps 脚本函数。

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>
  <body>
  </body>
</html>

参数

名称类型说明
...大多数类型都是合法的，但 Date、Function、 或 form 之外的 DOM 元素；查看说明法律参数是 JavaScript Number、Boolean、String 或 null 以及由基元组成的 JavaScript 对象和数组， 对象和数组。网页中的 form 元素也可作为参数，但 它必须是函数的唯一参数。如果您尝试传递 Date、Function、DOM 元素（form 或其他元素） 禁止的类型，包括对象或数组内禁止的类型。可创造圆形物体的物体 引用也将失败，且数组中未定义的字段变为 null。请注意， 传递给服务器的对象将成为原始对象的副本。如果服务器函数收到一个 对象并更改其属性时，客户端上的属性不会受到影响。

返回

void - 此方法是异步的，不直接返回；不过， 服务器端函数可以将值作为传递给 成功处理程序；此外，返回类型还受 与参数类型具有相同的限制，但 form 元素不合法 返回值类型

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>

参数

名称类型说明
functionFunction客户端回调函数 在服务器端函数抛出异常时运行；该 Error 对象会作为第一个参数传递给函数，而 用户对象（如果有）作为第二个参数传递

返回

google.script.run - 此“脚本运行程序”用于串联

withSuccessHandler(function)

设置在服务器端函数成功返回时运行的回调函数。服务器的 返回值将作为第一个参数传递给函数，而 用户对象（如果有）作为第二个参数进行传递。

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>

参数

名称类型说明
functionFunction客户端回调函数 如果服务器端函数成功返回结果，则运行 系统会将服务器的返回值 函数作为第一个参数，用户对象（如果有） 作为第二个参数传递

返回

google.script.run - 此“脚本运行程序”用于串联

withUserObject(object)

设置一个对象，作为第二个参数传递给成功和失败处理程序。此“用户 object&quot;，不要与 User 类 - 允许回调 函数会响应客户端与服务器联系的上下文。因为用户对象 不会发送到服务器，它们既不受参数限制，也不会返回 服务器调用的值。但是，用户对象不能是对象 使用 new 运算符构造而成。

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>

参数

名称类型说明
objectObject要作为第二个参数传递的对象 成功和失败处理程序因为用户对象不会发送到服务器 所遵循的参数和返回值的限制 服务器调用。但是，用户对象不能是构造的对象 使用 new 运算符

返回

google.script.run - 此“脚本运行程序”用于串联