SpreadsheetApp 與 Range
Spreadsheet 服務有四層：SpreadsheetApp（入口）→ Spreadsheet（一整本活頁簿）→ Sheet（一張工作表）→ Range（一格或一塊區域）。日常讀寫幾乎都落在 Range 的 getValues / setValues。
拿到工作表
繫結腳本：
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheetByName("資料") || ss.getActiveSheet();
獨立腳本改用 SpreadsheetApp.openById(id)。工作表名稱寫錯會得到 null，後面呼叫 getRange 就會失敗，先檢查名稱。
讀與寫
| 方法 | 回傳／參數 | 何時用 |
|---|---|---|
getValue() / setValue() |
單一值 | 只動一格 |
getValues() / setValues() |
二維陣列 | 批次讀寫（預設選這個） |
getDisplayValues() |
字串二維陣列 | 要畫面上看到的格式（日期、千分位） |
appendRow(array) |
一維陣列 | 在資料區下方追加一列 |
function copyNames() {
const sheet = SpreadsheetApp.getActiveSheet();
const lastRow = sheet.getLastRow();
if (lastRow < 2) return;
const names = sheet.getRange(2, 1, lastRow - 1, 1).getValues();
const stamped = names.map(([name]) => [name, new Date()]);
sheet.getRange(2, 2, stamped.length, 2).setValues(stamped);
}
getRange(列, 欄, 列數, 欄數) 的列、欄都從 1 開始，不是 0。setValues 的陣列尺寸必須剛好等於 Range，否則執行期錯誤。
效能
迴圈裡對每一格呼叫 getValue / setValue 很容易碰到 6 分鐘上限。先 getValues() 到記憶體、處理完、再一次 setValues()。
常用定位
getDataRange()：從 A1 到有資料的最右下角。getLastRow()/getLastColumn()：最後有值的列／欄。getRange("A2:C")：A1 記法；開到欄底時注意空白列也會被讀進來，要自己過濾。getRangeByName("訂單")：活頁簿裡的命名範圍。
空儲存格讀出來是空字串 ""，不是 null。數字是 number，核取方塊是 boolean，日期是 Date。
完整類別說明見官方 Spreadsheet 服務。畫面示範可看 YouTube 優質教學 的 Get / Set Values 片段。