Google Apps Script: 從零開始掌握 google.script.run 函數 – 完整教學與實用範例

更新日期： 2023 年 9 月 6 日

google.script.run 函數，允許我們在客戶端腳本（例如 HTML 中的 JavaScript）調用伺服器端的 Apps Script 函數。

這為前、後端之間的互動和數據交流，提供了強大的支援。

無論是建立一個動態的網頁，還是處理後端的數據分析，這個函數都發揮著關鍵作用。

本文會向初學者介紹 google.script.run 函數的基本概念、使用方法、實際應用，以及常見問題的解答。

無論你是剛接觸 Google Apps Script 的新手，還是有一些基本經驗，並希望深入了解的開發者，本文都會為你提供有用的指引。

那麼，讓我們不要再等待，馬上開始這個學習之旅吧！

什麼是 google.script.run？

google.script.run 是 Google Apps Script 中的一個特殊函數，它允許客戶端的 JavaScript 代碼，調用伺服器端的 Apps Script 函數。

這功能提供了一個橋樑，連接了前端（如網頁上的按鈕、輸入框等）與後端（如資料庫操作、API 請求等）的功能。

基本概念

使用場景

google.script.run 常用於以下幾種場景：

google.script.run 是 Google Apps Script 的核心特性之一，為前端和後端的互動提供了簡單且強大的解決方案。

通過理解和掌握這一函數，你可以為你的 Apps Script 項目開闢更多的可能性，讓它們變得更為動態和互動。

如何使用 google.script.run？

以下是如何使用它的步驟和範例：

1. 定義伺服器端的函數

首先，你需要在 Apps Script 中，定義一個或多個你想要在客戶端調用的函數。

// 伺服器端代碼
function myServerFunction(name) {
  return `Hello, ${name}!`;
}

2. 在客戶端調用伺服器端函數

接下來，你可以使用 google.script.run 在客戶端的 JavaScript 中調用上述函數。

<!-- 客戶端代碼 -->
<button onclick="callServerFunction()">Say Hello</button>

<script>
function callServerFunction() {
  google.script.run.withSuccessHandler(onSuccess).myServerFunction('Alice');
}

function onSuccess(response) {
  alert(response); // 彈出 "Hello, Alice!"
}
</script>

在這個例子中，執行順序是為：

1. google.script.run 開始配置一個請求，以便從客戶端（也就是瀏覽器）調用伺服器端（Google Apps Script）的函數。
2. .withSuccessHandler(onSuccess) 指定了一個成功處理程序，即當伺服器端函數成功執行並返回結果時，應該調用哪個函數。在這個例子中，它是 onSuccess 函數。
3. .myServerFunction(‘Alice’) 最終指定了哪個伺服器端函數需要被調用，以及需要傳遞哪些參數。

總體來說，當這一行碼執行時，會先發出一個請求到伺服器端，調用 myServerFunction 並傳入 ‘Alice’ 作為參數。

伺服器端函數執行完畢後，其返回值（在這個例子中是 “Hello, Alice!”）會作為參數傳遞給 onSuccess 函數。

這個順序是由 google.script.run 的設計確定的。

這是一種非同步操作，你不能預先確定伺服器端函數何時完成執行。

但一旦它完成，成功處理程序（在這個例子中是 onSuccess）就會被調用。

這種模式是非常典型的在 JavaScript 和其他非同步編碼環境中。

3. 處理錯誤

你還可以使用 withFailureHandler() 定義一個當伺服器端函數執行失敗時，會被調用的回調函數。

function callServerFunction() {
  google.script.run
    .withSuccessHandler(onSuccess)
    .withFailureHandler(onFailure)
    .myServerFunction('Alice');
}

function onFailure(error) {
  alert('Something went wrong: ' + error.message);
}

在上面的代碼中，google.script.run 的執行順序如下：

1. 初始化：google.script.run 開始設置一個從客戶端到伺服器端的請求。
2. 設置成功處理程序：.withSuccessHandler(onSuccess) 指定了，如果伺服器端函數成功執行，那麼應該調用哪個函數（在這個例子中是 onSuccess）。
3. 設置失敗處理程序：.withFailureHandler(onFailure) 指定了，如果伺服器端函數執行時發生了錯誤或異常，那麼應該調用哪個函數（在這個例子中是 onFailure）。
4. 調用伺服器端函數：.myServerFunction(‘Alice’) 這是實際的伺服器端函數調用。這個函數會被傳入一個參數 ‘Alice’ 並在伺服器端執行。

這裡要注意的是：withSuccessHandler 和 withFailureHandler 只是設置了回調函數，這些回調函數在 myServerFunction 完成後才會被調用。

如果 myServerFunction 成功執行，則調用 onSuccess；如果出錯，則調用 onFailure。

這意味著當 callServerFunction 被調用時，真正首先執行的是 myServerFunction(‘Alice’)，然後根據伺服器端函數的結果，會觸發 onSuccess 或 onFailure。

google.script.run 的實際應用實例。

實例 1：表單提交和數據驗證

假設你有一個表單，用戶可以填寫一些資料並提交。

使用 google.script.run，你可以將數據傳送到伺服器進行處理和驗證。

<!-- 客戶端代碼 -->
<form id="myForm">
    <!-- 用戶名輸入欄位 -->
    <input type="text" name="username" required>
    <!-- 提交按鈕 -->
    <button type="button" onclick="submitForm()">Submit</button>
</form>

<script>
    // 提交表單函數
    function submitForm() {
        // 取得表單元素
        let form = document.getElementById('myForm');
        // 呼叫 `google.script.run()` 函數來處理表單
        google.script.run.withSuccessHandler(onSuccess).processForm(form);
    }

    // 成功處理函數
    function onSuccess(response) {
        // 顯示回應訊息
        alert(response.message);
    }
</script>

// 伺服器端代碼
function processForm(form) {
  // 檢查是否有用戶名
  if (form.username) {
    // 驗證和處理數據
    // 返回成功訊息
    return { message: 'Success!' };
  } else {
    // 返回錯誤訊息
    return { message: 'Please enter a username.' };
  }
}

實例 2：動態更新網頁內容

你可以使用 google.script.run 來動態更新網頁內容，根據伺服器端的數據或邏輯。

基本的代碼邏輯如下：

// 伺服器端代碼
function fetchContent() {
  // 從數據庫或其他來源獲取內容
  return 'Updated content goes here!';
}

<!-- 客戶端代碼 -->
<button onclick="updateContent()">Update Content</button>
<div id="content"></div>

<script>
    function updateContent() {
        google.script.run.withSuccessHandler(showContent).fetchContent();
    }

    function showContent(newContent) {
        document.getElementById('content').innerHTML = newContent;
    }
</script>

你可以使用 google.script.run 從客戶端網頁與 Google 試算表互動，例如讀取數據或插入新行。

我們以試算表（Google Spread Sheet）作為資料庫，實際的例子如下：

// 伺服器端代碼
function getSheetData() {
  // 取得當前活動的試算表和工作表
  let sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();

  // 取得指定範圍的值
  return sheet.getRange('A1:B10').getValues();
}

<!-- 客戶端代碼 -->
<!-- 建立了一個按鈕。當這個按鈕被點擊時，會執行loadData這個JavaScript函數。-->
<button onclick="loadData()">Load Data</button>

<!-- 建立了一個div元素，它的ID為"data"。此div將用於顯示從伺服器端獲取的資料。 -->
<div id="data"></div>

<script>
    // 載入數據按鈕
    function loadData() {
        // 呼叫 `google.script.run()` 函數來取得試算表數據
        google.script.run.withSuccessHandler(displayData).getSheetData();
    }

    // 顯示數據函數
    function displayData(data) {
        // 選擇了之前在 HTML 中定義的 div 元素。
        let div = document.getElementById('data');

        // 這行代碼處理從伺服器端獲取的資料，並將其格式化為字符串，然後將其插入到div中。
        // 具體來說，它先將每一行資料用逗號連接起來，然後用<br>將每一行分隔開。
        div.innerHTML = data.map(row => row.join(', ')).join('<br>');
    }
</script>

與 google.script.run 相關的進階技巧

一旦掌握了 google.script.run 的基本用法，你可能會想要瞭解一些更進階的技巧，以更靈活和有效地使用這個功能。以下是一些進階技巧的詳細解釋：

1. 設定超時

在某些情況下，你可能想要設定一個超時，以便在指定的時間內完成伺服器端的操作。你可以使用客戶端的 setTimeout 函數來達到這個目的。

<script>
    // 客戶端代碼

    // 設定一個超時計時器，它將在5秒後觸發。這時，計時器開始計時。
    let timeoutID = setTimeout(function () {
        // 如果 serverFunction 超過5秒還沒有回應，那麼由於計時器已達到，所以將彈出 Request timed out! 的提示框：
        alert('Request timed out!');
    }, 5000);

    // 調用 Google Apps Script 的 serverFunction。
    // 如果 serverFunction 在5秒內成功完成，那麼成功處理器將被觸發：
    google.script.run
        .withSuccessHandler(function () {
            // 此行會取消之前設定的5秒計時器，阻止彈出提示框
            clearTimeout(timeoutID);
            // 調用 onSuccess 函數，注意這部分代碼片段中沒有提供此函數的具體實現
            onSuccess();
        })
        .serverFunction();
</script>

// 設定一個將在5秒後執行的定時器
let timerId = setTimeout(function() {
    console.log("This message will be delayed by 5 seconds.");
}, 5000);

console.log("Timer ID:", timerId); // 你會看到一個數字，例如：1、2、3等，這取決於之前已經設定了多少定時器

// 如果你在定時器執行之前決定取消它：
clearTimeout(timerId);

2. 同時處理多個請求

你可以同時發送多個 google.script.run 請求，並通過各自的成功和失敗處理器來處理每個請求。

<script>
    // 客戶端代碼
    google.script.run.withSuccessHandler(onSuccess1).function1();
    google.script.run.withSuccessHandler(onSuccess2).function2();
</script>

3. 在服務器端使用 Session 信息

有時你可能需要根據用戶的 Session 信息來進行操作。

你可以在伺服器端使用 Session.getActiveUser() 函數，它允許你獲取當前的使用者（通常是 Google 帳戶的電子郵件地址）。

// 伺服器端代碼
function getUserInfo() {
  var user = Session.getActiveUser();
  return user.getEmail();
}

在你的客戶端 HTML/JavaScript 中：

google.script.run.withSuccessHandler(function(email) {
  console.log("The active user is: " + email);
}).getActiveUserEmail();

這樣，當使用者與你的應用互動時，你就可以知道誰是當前的使用者，並可能根據他們的身份進行一些特定的操作或調整。

結語

掌握了這些進階技巧，你將能夠更加靈活和有效地使用 google.script.run，解決更複雜的問題。

從錯誤處理到設定超時，這些技巧提供了更深入的控制和自定義能力，有助於提升你的開發效率和代碼品質。