google.script.run 類別 (用戶端 API)

google.script.run 是非同步的用戶端 JavaScript API，可在 HTML 服務網頁中呼叫伺服器端 Apps Script 函式。如要透過用戶端程式碼與 Google 文件、試算表或表單中的對話方塊或側欄互動，請使用 google.script.host。詳情請參閱 HTML 服務中與伺服器函式通訊的指南。

方法

方法傳回類型簡短說明
myFunction(...) (任何伺服器端函式) void 以對應的名稱執行伺服器端 Apps Script 函式。
withFailureHandler(function) google.script.run 設定在伺服器端函式擲回例外狀況時執行的回呼函式。
withSuccessHandler(function) google.script.run 設定當伺服器端函式成功傳回時，要執行的回呼函式。
withUserObject(object) google.script.run 設定物件，做為成功和失敗處理常式的第二個參數。

內容詳盡的說明文件

myFunction(...) (任何伺服器端函式)

以對應的名稱執行伺服器端 Apps Script 函式。

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 元素均不合法；請參閱說明法律參數是指 JavaScript 基本項目，例如 Number、Boolean、String 或 null，以及由原始參數、物件和陣列組成的 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 — 此為「指令碼執行器」，用於鏈結