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

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

方法

方法傳回類型簡短說明
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>

參數

名稱類型說明
...大多數類型為合法，但並非 Date、Function、 form 以外的 DOM 元素；查看說明法律參數為 JavaScript 基本功能，例如 Number、Boolean、String 或 null 以及由基元組成的 JavaScript 物件和陣列 物件和陣列網頁中的 form 元素同樣可做為參數，但 該參數必須為函式的唯一參數。如果您嘗試 Date、Function、DOM 元素以外的 form 或其他元素 禁止的類型，包括物件或陣列中禁止的類型。建立循環的物件 參照也會失敗，陣列中的未定義欄位會變成 null。請注意， 傳遞至伺服器的物件成為原始項目的副本，如果伺服器函式 物件並變更其屬性，則不會影響用戶端的屬性。

回攻員

void：這是非同步的方法，不會直接傳回；不過， 伺服器端函式可以將值傳回至用戶端，做為傳遞至 成功處理常式；傳回類型也必須符合 限制與參數類型相同，但 form 元素並非法律 傳回類型

withFailureHandler(function)

設定在伺服器端函式擲回例外狀況時要執行的回呼函式。 Error 物件會做為第一個引數傳遞至函式，而 user 物件 (如有) 做為第二個引數傳遞。不含 失敗的處理常式、失敗時都會記錄在 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 物件會做為第一個引數傳遞至函式，而 user 物件 (如有) 做為第二個引數傳遞

回攻員

google.script.run — 這段「指令碼執行器」鏈結

withSuccessHandler(function)

設定伺服器端函式成功傳回時要執行的回呼函式。伺服器的 傳回值會做為第一個引數傳遞至函式，而 user 物件 (如有) 做為第二個引數傳遞。

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 類別 — 允許回呼 函式會回應用戶端與伺服器連線的內容。由於使用者物件 不會傳送至伺服器，它們也不受參數限制，且會傳回 伺服器呼叫的值。然而，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要做為第二個參數傳遞的物件 新增至成功和失敗處理常式因為系統不會將使用者物件傳送至伺服器 須遵守參數， 伺服器呼叫。然而，User 物件不能是建構物件 使用 new 運算子

回攻員

google.script.run — 這段「指令碼執行器」鏈結