google.script.run (用戶端 API)

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

google.script.run 是 HTML 服務頁面中的非同步用戶端 JavaScript API，可呼叫伺服器端 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!');
}

索引.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、DOM 元素到 form 或其他禁止的類型 (包括物件或陣列中不允許的類型)，則要求會失敗。建立循環參照的物件也會失敗，陣列中的未定義欄位會變成 null。請注意，傳遞到伺服器的物件會成為原始的副本。如果伺服器函式收到物件並變更其屬性，用戶端上的屬性不會受到影響。

Return 鍵

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();
}

索引.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 物件會做為第一個引數傳遞至函式，並將使用者物件 (如果有的話) 做為第二個引數傳遞

Return 鍵

google.script.run：這個「指令碼執行器」，適用於鏈結

withSuccessHandler(function)

設定在伺服器端函式成功傳回時執行的回呼函式。伺服器的傳回值會傳遞至函式做為第一個引數，使用者物件 (如果有的話) 則做為第二個引數傳遞。

Code.gs

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

function getUnreadEmails() {
  return GmailApp.getInboxUnreadCount();
}

索引.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如果伺服器端函式成功傳回，則要執行的用戶端回呼函式；伺服器的傳回值將做為第一個引數傳遞至函式，並將使用者物件 (如果有的話) 做為第二個引數傳遞

Return 鍵

google.script.run：這個「指令碼執行器」，適用於鏈結

withUserObject(object)

設定要做為成功和失敗處理常式的第二個參數。這個「使用者物件」不會和 User 類別混淆，回呼函式可讓回應回應用戶端與伺服器通訊的情況。由於使用者物件不會傳送至伺服器，因此不受參數限制並傳回伺服器呼叫的值。不過，使用者物件不能是透過 new 運算子建構的物件。

Code.gs

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

function getEmail() {
  return Session.getActiveUser().getEmail();
}

索引.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 運算子建構的物件

Return 鍵

google.script.run：這個「指令碼執行器」，適用於鏈結