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>
參數
名稱 | 類型 | 說明 |
---|---|---|
function | Function | 當伺服器端函式擲回例外狀況時要執行的用戶端回呼函式;系統會將 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>
參數
名稱 | 類型 | 說明 |
---|---|---|
function | Function | 成功傳回伺服器端函式時要執行的用戶端回呼函式;伺服器回傳值會以第一個引數傳遞至函式,並將「使用者物件」 (如果有的話) 做為第二個引數傳遞 |
回攻員
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>
參數
名稱 | 類型 | 說明 |
---|---|---|
object | Object | 傳送物件為成功和失敗處理常式的第二個參數;使用者物件不會傳送至伺服器,因此不受參數和伺服器呼叫傳回值的限制。但是,使用者物件無法以透過 new 運算子建構的物件 |
回攻員
google.script.run
— 此為「指令碼執行器」,用於鏈結