(GAS)getRange與getDataRange差異

本文記錄一下在取得google spreadsheet 的資料時，經常會使用到兩個函式，getRange 與 getDataRange，下面來說明這兩個函式的差別。

getRange：傳回指定座標資料範圍

getRange(row, column)

僅傳遞兩個參數會傳回單一儲存格的「範圍」。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange(1, 1); // 第一列第一欄資料

// 列印單一儲存格的值
var values = range.getValues();
Logger.log(values[0][0]);

參數

名稱	類型	說明
row	Integer	列索引；列索引會從 1 開始。
column	Integer	欄索引；欄索引會從 1 開始。

getRange(row, column, numRows)

當使用numRows參數時，僅傳回指定行數的單欄資料範圍。
當使用numRows參數時，傳回從指定列(row)、欄(column)的儲存格開始，往下取得指定行數(numRows)的資料範圍。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange(1, 1, 3); // 從第一列第一欄的儲存格開始，往下取3列
var values = range.getValues();

// 從第一列開始，列印第一欄的 3 個值。
for (var row in values) {
  for (var col in values[row]) {
    Logger.log(values[row][col]);
  }
}

參數

名稱	類型	說明
row	Integer	範圍的起始列索引；列索引會從 1 開始。
column	Integer	範圍的欄索引；欄索引會從 1 開始。
numRows	Integer	要傳回的列數。

getRange(row, column, numRows, numColumns)

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange(1, 1, 3, 3); // 從第一列第一欄的儲存格開始，往下取3列，往右取3欄
var values = range.getValues();

// 列印取得3x3範圍內的值。
for (var row in values) {
  for (var col in values[row]) {
    Logger.log(values[row][col]);
  }
}

參數

名稱	類型	說明
row	Integer	範圍的起始列索引；列索引會從 1 開始。
column	Integer	範圍的欄索引；欄索引會從 1 開始。
numRows	Integer	要傳回的列數。
numColumns	Integer	要傳回的欄數。

getRange(a1Notation)

傳回A1標記或R1C1標記法中指定的範圍

// 在名為"Invoices"的sheet取得範圍A1:D4
var ss = SpreadsheetApp.getActiveSpreadsheet();
var range = ss.getRange("Invoices!A1:D4");

// 取得第一個sheet的A1儲存格
var sheet = ss.getSheets()[0];
var cell = sheet.getRange("A1");

參數

名稱	類型	說明
aiNotation	String	要傳回的範圍，如 A1 標記法或 R1C1 標記法中的指定。

getDataRange：傳回與顯示資料的維度相對應的範圍

在不知道分頁的列數及欄數，但想抓出整個分頁的資料，可用此函數。

getDataRange會回傳此 sheet 所有有資料的範圍(A1到此sheet最後一列最後一欄)，等同於getRange(1, 1, sheet.getLastRow(), sheet.getLastColumn())

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

// 取得所有資料
var range = sheet.getDataRange();
var values = range.getValues();

// 將資料以CSV格式記錄，以逗號為分隔
for (var i = 0; i < values.length; i++) {
  var row = "";
  for (var j = 0; j < values[i].length; j++) {
    if (values[i][j]) {
      row = row + values[i][j];
    }
    row = row + ",";
  }
  Logger.log(row);
}