如何有效利用 onEdit 函數？Google Apps Script 新手完全指南

更新日期： 2023 年 7 月 31 日

Google Apps Script 的 onEdit 函數，是一種特殊的「觸發器」函數。

當試算表（Google Sheets） 中的儲存格被編輯時，會自動啟動該函數。

本文將介紹 onEdit 函數的基礎知識，包括它是什麼、如何使用，以及一些實際的例子。

此外，我們也會討論一些使用 onEdit 函數時，可能會遇到的常見問題。

現在，讓我們開始深入了解 onEdit 函數吧！

什麼是 onEdit 函數？

在 Google Apps Script 中，onEdit 是一種特殊的觸發器函數。

當使用者更改任何試算表中儲存格的值時，試算表會自動觸發 onEdit 函數，並執行包含在該函數內程式碼。

以下是一個簡單的 onEdit 函數範例：

function onEdit(e) {
  let range = e.range;
  range.setNote('最後修改時間: ' + new Date());
}

在此範例中，每當儲存格被編輯，都會在該單元格添加一個註釋，註釋內容是該單元格最後被修改的日期和時間。

請注意，onEdit 函數接受一個參數「 e 」。這個參數是一個物件，它包含關於編輯事件的相關訊息。

在這個範例中，我們使用了 e.range 來獲取被編輯的儲存格位置。

使用 onEdit 函數，我們可以根據單元格內容的變化來自動執行許多操作，這提供了大量的彈性和可能性。

onEdit 函數的實例解析

在這部分，我們會透過兩個實例來更深入地理解 onEdit 函數的用法。

自動追蹤更改日期和時間

以下代碼，用來表示每當任何儲存格的內容被編輯，我們會在同一行的最後一個單元格中，記錄當前的日期和時間。

此功能對於追蹤數據的時間變化非常有用。

// 定義 onEdit 的函數，該函數會在 Google Sheets 中的任何單元格被編輯時自動執行。
// 這裡的 e 是一個事件物件，包含了關於這次編輯事件的資訊。
function onEdit(e) { 

    // 從事件物件 e 中取出了被編輯的單元格範圍（Range），並將它存放在變數 range 中
    let range = e.range; 

    // 使用 getSheet 方法，取得了被編輯的單元格所在的工作表（Sheet），並將它存放在變數 sheet 中。
    let sheet = range.getSheet(); 

    // 使用 getLastColumn 方法，找出了該工作表中，最後一列有內容的「列數」（垂直），並將它存放在變數 lastColumn 中。
    let lastColumn = sheet.getLastColumn(); 

    // 使用 getRow 方法，取得了被編輯的單元格的「行數」（水平），並將它存放在變數 row 中。
    let row = range.getRow(); 

    // 創建了一個新的 Date 物件，表示現在的日期和時間，並將它存放在變數 currentDate 中。
    let currentDate = new Date(); 

    // 將當前的日期和時間，設置為被編輯的「單元格所在行」的「最後一列」的值。
    sheet.getRange(row, lastColumn).setValue(currentDate); 
} 

基於單元格更改的條件格式

以下代碼，用來表示當單元格的值變成「完成」時，該單元格的背景色變為綠色。

// 同樣定義了一個名為 onEdit 的函數，該函數會在 Google Sheets 中的任何單元格被編輯時自動執行。
// e 依然是一個事件物件。
function onEdit(e) { 

    // 取出了被編輯的單元格範圍。
    let range = e.range; 

    // 使用 getValue 方法，取得了被編輯的單元格的內容，並將它存放在變數 value 中。
    let value = range.getValue(); 

    // 檢查是否等於 '完成'。
    if (value == '完成') { 

        // 如果條件成立（也就是單元格的內容等於 '完成'），那麼就將該單元格的背景顏色設置為綠色。
        range.setBackground('green'); 

    } 
    
    // 如果條件不成立（也就是單元格的內容不等於 '完成'）
    else { 
        // 那麼就將該單元格的背景顏色設置為白色。
        range.setBackground('white'); 
    } 
}

當單元格的值變為「完成」時，這個程式碼會將該單元格的背景色變為綠色。否則，背景色會被設定為白色。

以上僅簡單示範基本的功能，你可以根據自己的需求，進行自動化的功能增添。

onEdit 函數的常見問題

onEdit 函數的執行限制

在 Google Apps Script 中，onEdit 函數和其他觸發器函數都有執行時間的限制。

在大部分情況下，每個觸發器函數的執行時間不能超過 30 秒。

如果你的 onEdit 函數，需要執行大量的操作或進行網路請求，就可能會超過時間限制。

編輯操作的範圍

onEdit 函數的參數 e 包含了一個 range 屬性，表示被編輯的儲存格範圍。

然而，請注意這個範圍可能不止包含一個單元格。

例如，如果用戶選擇了多個儲存格並一次性修改了它們的內容，那麼這個 range 就會包含所有被編輯的單元格。

onEdit 函數不會對非手動編輯操作觸發

onEdit 函數只會在儲存格的內容，被「手動編輯」時被觸發。

如果一個單元格的內容變化，是由於其他單元格的公式計算結果改變，或是由 Apps Script 程式碼的執行，那麼 onEdit 函數並不會被觸發。

結語

---

藉由本文，我們了解了 Google Apps Script 中 onEdit 函數的基礎知識、實際應用。

同時釐清了一些常見的問題與疑惑。

希望這些內容，能對你在實際操作中提供有力的參考和幫助。

參考資源

以下是一些有關 Google Apps Script 和 onEdit 函數的參考資源：

以上就是一些學習 Google Apps Script 和 onEdit 函數的參考資源。

希望這些資源可以幫助你在學習的道路上一路前行。