google.script.run(客户端 API)类

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

google.script.run 是一个异步客户端 JavaScript API,可在 HTML 服务页面中使用,该 API 可调用服务器端 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>

参数

名称类型说明
...大多数类型都是合法的,但 DateFunctionform 之外的 DOM 元素除外;请参阅说明合法参数是 NumberBooleanStringnull 等 JavaScript 原语,以及由基元、对象和数组组成的 JavaScript 对象和数组。网页中的 form 元素作为参数也是合法的,但必须是函数的唯一参数。如果您尝试传递 DateFunctionform 之外的 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 - 此“脚本运行程序”,用于串联