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

google.script.run 是一种异步客户端 JavaScript API，适用于 HTML 服务页面，可调用服务器端 Apps 脚本函数。如需通过客户端代码与 Google 文档、表格或表单中的对话框或边栏进行交互，请使用 google.script.host。如需了解详情，请参阅 HTML 服务中与服务器功能通信的指南。

方法

方法返回类型简介
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>

参数

名称类型说明
...大多数类型都合法，但除了 form 之外，Date、Function 或 DOM 元素都无效；请参阅说明法律参数是指 Number、Boolean、String 或 null 等 JavaScript 原语，以及由基元、对象和数组组成的 JavaScript 对象和数组。页面中的 form 元素也可以作为参数合法，但它必须是函数的唯一参数。如果您尝试传递 Date、Function、除 form 之外的 DOM 元素或其他被禁止的类型（包括对象或数组内禁止的类型），请求将会失败。创建循环引用的对象也会失败，并且数组中未定义的字段会变为 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)

设置一个对象，将其作为第二个参数传递给成功和失败处理程序。这个“用户对象”（不要与 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 - 此“脚本运行程序”，用于链接