google.script.run 是非同步的用戶端 JavaScript API，可讓 HTML 服務頁面呼叫伺服器端的 Apps Script 函式。以下範例顯示 google.script.run 最基本的功能，也就是透過用戶端 JavaScript 呼叫伺服器上的函式。
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>
</html>
如果您將此指令碼部署為網頁應用程式並造訪其網址，您不會看到任何內容，但查看記錄時，就會看到已呼叫伺服器函式 doSomething()。
用戶端對伺服器端函式的呼叫並非同步：在瀏覽器要求伺服器執行 doSomething() 函式後，瀏覽器會立即繼續前往下一行程式碼，不必等待回應。這表示伺服器函式呼叫可能無法按照預期順序執行。如果您同時發出兩個函式呼叫，系統無法得知將先執行哪個函式；結果可能會在每次載入網頁時產生不同結果。在這種情況下，成功處理常式和失敗處理常式可協助控製程式碼流程。
google.script.run API 允許對伺服器函式並行 10 次呼叫。如果您在 10 目前仍在執行時進行第 11 次呼叫，則伺服器函式會延遲，直到 10 個位置中的其中一個釋放為止。實際上，您應該很少需要考量這項限制，特別是因為多數瀏覽器已限制對相同伺服器進行的並行要求數量限制低於 10。例如，Firefox 的上限是 6。多數瀏覽器同樣會延遲額外的伺服器要求，直到其中一個現有的要求完成為止。
參數和傳回值
您可以透過用戶端使用參數呼叫伺服器函式。同樣地，伺服器函式可將值傳回至用戶端，做為參數傳遞至成功處理常式。
法律參數和傳回值是指 JavaScript 基本項目，例如 Number、Boolean、String 或 null，以及由基元、物件和陣列組成的 JavaScript 物件和陣列。頁面中的 form 元素也適用於參數，但必須是函式的唯一參數，且不合法做為傳回值。如果您嘗試傳遞 Date、Function、除了 form 以外的 DOM 元素或其他禁止的類型 (包括物件或陣列中禁止的類型)，要求就會失敗。建立循環參照的物件也會失敗，而陣列中的未定義欄位會變成 null。
請注意，傳遞至伺服器的物件會成為原始物件的副本。如果某個伺服器函式收到物件並變更其屬性，則用戶端上的屬性不會受到影響。
成功處理常式
由於用戶端程式碼會持續進行下一行，不必等待伺服器呼叫完成，因此 withSuccessHandler(function) 可讓您指定伺服器回應時要執行的用戶端回呼函式。如果伺服器函式傳回值，API 會將該值以參數的形式傳遞至新函式。
以下範例顯示伺服器回應時的瀏覽器快訊。請注意，這個程式碼範例需要授權，因為伺服器端函式會存取您的 Gmail 帳戶。授權指令碼最簡單的方式，就是在載入網頁前，從指令碼編輯器手動執行 getUnreadEmails() 函式一次。或者，在部署網頁應用程式時，您可以選擇以「存取網頁應用程式的使用者」的身分執行應用程式。在這種情況下，系統會在您載入應用程式時提示您授權。
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>
失敗處理常式
如果伺服器無法回應或擲回錯誤，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>
User 物件
您可以呼叫 withUserObject(object) 指定要傳送至處理常式的物件做為第二個參數，藉此重複使用相同的成功或失敗處理常式進行多個呼叫。這個「使用者物件」與 User 類別並不相同，可讓您回應用戶端與伺服器連線的情境。由於使用者物件不會傳送至伺服器，因此幾乎可以是任何任何內容，包括函式、DOM 元素等，不受參數和伺服器呼叫傳回值的限制。但是，使用者物件不能是以 new 運算子建構的物件。
在此範例中，點選兩個按鈕都會將按鈕更新為來自伺服器的值，另一個按鈕則維持不變，即使這些按鈕共用一個成功處理常式也一樣。在 onclick 處理常式中，關鍵字 this 是指 button 本身。
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>
表單
如果您使用 form 元素做為參數來呼叫伺服器函式，表單會視為單一物件，並以欄位名稱做為索引鍵和欄位值。這些值都會轉換為字串，但檔案輸入欄位的內容除外，後者會成為 Blob 物件。
這個範例會處理包含檔案輸入欄位的表單，但不會重新載入頁面；該檔案會將檔案上傳至 Google 雲端硬碟，然後在用戶端頁面輸出檔案的網址。在 onsubmit 處理常式中，關鍵字 this 是指表單本身。請注意，在頁面中載入所有表單時，preventFormSubmit 會停用預設的提交動作。這可防止在發生例外狀況時，將頁面重新導向至不正確的網址。
Code.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function processForm(formObject) {
var formBlob = formObject.myFile;
var driveFile = DriveApp.createFile(formBlob);
return driveFile.getUrl();
}
Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
// Prevent forms from submitting.
function preventFormSubmit() {
var forms = document.querySelectorAll('form');
for (var i = 0; i < forms.length; i++) {
forms[i].addEventListener('submit', function(event) {
event.preventDefault();
});
}
}
window.addEventListener('load', preventFormSubmit);
function handleFormSubmit(formObject) {
google.script.run.withSuccessHandler(updateUrl).processForm(formObject);
}
function updateUrl(url) {
var div = document.getElementById('output');
div.innerHTML = '<a href="' + url + '">Got it!</a>';
}
</script>
</head>
<body>
<form id="myForm" onsubmit="handleFormSubmit(this)">
<input name="myFile" type="file" />
<input type="submit" value="Submit" />
</form>
<div id="output"></div>
</body>
</html>
指令碼執行器
您可以將 google.script.run 視為「指令碼執行器」的建構工具。如果您在指令碼執行器中加入成功處理常式、失敗處理常式或使用者物件，並不會變更現有的執行器，而是會取回包含新行為的新指令碼執行器。
您可以使用 withSuccessHandler()、withFailureHandler() 和 withUserObject() 的任何任意組合。您也可以在已設定值的指令碼執行器上呼叫任何修改函式。新值只會覆寫先前的值。
這個範例會為全部三種伺服器呼叫設定共同失敗處理常式，但有兩個不同的成功處理常式：
var myRunner = google.script.run.withFailureHandler(onFailure);
var myRunner1 = myRunner.withSuccessHandler(onSuccess);
var myRunner2 = myRunner.withSuccessHandler(onDifferentSuccess);
myRunner1.doSomething();
myRunner1.doSomethingElse();
myRunner2.doSomething();
私人函式
系統會將名稱結尾為底線的伺服器函式視為私人函式。google.script 無法呼叫這些函式，且其名稱絕不會傳送至用戶端。因此，您可以利用這些註解隱藏需要在伺服器中保持密鑰的實作詳細資料。google.script 也無法查看程式庫中的函式，以及未在指令碼頂層宣告的函式。
在本例中，用戶端程式碼提供 getBankBalance() 函式；即使您並未呼叫原始碼，檢查原始碼的使用者仍可找到其名稱。不過，用戶端完全看不到 deepSecret_() 和 obj.objectMethod() 函式。
Code.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function getBankBalance() {
var email = Session.getActiveUser().getEmail()
return deepSecret_(email);
}
function deepSecret_(email) {
// Do some secret calculations
return email + ' has $1,000,000 in the bank.';
}
var obj = {
objectMethod: function() {
// More secret calculations
}
};
Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
function onSuccess(balance) {
var div = document.getElementById('output');
div.innerHTML = balance;
}
google.script.run.withSuccessHandler(onSuccess)
.getBankBalance();
</script>
</head>
<body>
<div id="output">No result yet...</div>
</body>
</html>
調整 Google Workspace 應用程式中的對話方塊大小
Google 文件、試算表或表單中的自訂對話方塊，可在用戶端程式碼中呼叫 google.script.host 方法 setWidth(width) 或 setHeight(height)，藉此調整大小。(如要設定對話方塊的初始大小，請使用 HtmlOutput 方法 setWidth(width) 和 setHeight(height))。請注意，對話方塊調整大小後，對話方塊不會重新置中在父項視窗中，而且您無法調整側欄大小。
正在關閉「 Google Workspace」中的對話方塊和側欄
如果您使用 HTML 服務在 Google 文件、試算表或簡報中顯示對話方塊或側欄，則無法呼叫 window.close() 來關閉介面。而是必須呼叫 google.script.host.close()。如需範例，請參閱「以 Google Workspace 使用者介面提供 HTML」一節。
正在將瀏覽器焦點移至 Google Workspace
如要將使用者瀏覽器的焦點從對話方塊或側欄切換回 Google 文件、試算表或表單編輯器，只要呼叫 google.script.host.editor.focus() 方法即可。此方法特別適合與文件服務方法 Document.setCursor(position) 和 Document.setSelection(range) 搭配使用。