Class RangeList

選取 Range 例項清單。清單中的最後一個範圍會設為 active range。

注意：這可讓您一次選取多個範圍。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['D4', 'B2:C4']);
rangeList.activate();

const selection = sheet.getSelection();
// Current cell: B2
const currentCell = selection.getCurrentCell();
// Active range: B2:C4
const activeRange = selection.getActiveRange();
// Active range list: [D4, B2:C4]
const activeRangeList = selection.getActiveRangeList();

回攻員

RangeList：有效範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

將範圍清單中所有水平或垂直合併的儲存格，再次分割為個別儲存格。

在範圍清單上呼叫這個函式，等同於選取一組範圍，然後選取「格式」>「合併」>「取消合併」的試算表選單項目。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.breakApart();

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

將範圍內的核取方塊狀態變更為「已勾選」。忽略目前不含已勾選或未勾選值的範圍內儲存格。

// Changes the state of cells which currently contain either the checked or
// unchecked value configured in the ranges D4 and E6 to 'checked'.
const rangeList = SpreadsheetApp.getActive().getRangeList(['D4', 'E6']);
rangeList.check();

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

清除範圍清單中每個 Range 的內容範圍、格式和資料驗證規則。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.clear();

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

清除指定選項指定的內容範圍、格式、資料驗證規則和註解。根據預設，系統會清除所有資料。

// The code below clears the contents of the following ranges A:A and C:C in the
// active sheet, but preserves the format, data validation rules, and comments.
const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.clear({contentsOnly: true});

參數

進階參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

清除範圍清單中每個 Range 的內容，但格式保持不變。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.clearContent();

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

清除指定範圍清單中每個 Range 的資料驗證規則。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.clearDataValidations();

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

清除指定範圍清單中每個 Range 的文字格式。

這會清除每個範圍的文字格式，但不會重設任何數字格式規則。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.clearFormat();

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

清除範圍清單中每個 Range 的附註。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.clearNote();

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

傳回同一個工作表中一或多個 Range 例項的清單。

回攻員

Range[]：範圍清單。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

在範圍內的每個儲存格中插入核取方塊，並以 true 代表已勾選，以 false 代表未勾選。將範圍內所有儲存格中的值都設為 false。

const rangeList = SpreadsheetApp.getActive().getRangeList(['D4', 'E6']);

// Inserts checkboxes into each cell in the ranges D4 and E6 configured with
// 'true' for checked and 'false' for unchecked. Also, sets the value of each
// cell in the ranges D4 and E6 to 'false'.
rangeList.insertCheckboxes();

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

在範圍內的每個儲存格中插入核取方塊，並設定勾選狀態的值和空白字串。將範圍中每個儲存格的值設為空字串。

const rangeList = SpreadsheetApp.getActive().getRangeList(['D4', 'E6']);

// Inserts checkboxes into each cell in the ranges D4 and E6 configured with
// 'yes' for checked and the empty string for unchecked. Also, sets the value of
// each cell in the ranges D4 and E6 to the empty string.
rangeList.insertCheckboxes('yes');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

在範圍內的每個儲存格中插入核取方塊，並為已勾選和未勾選狀態設定自訂值。將範圍中每個儲存格中的值設為自訂未勾選值。

const rangeList = SpreadsheetApp.getActive().getRangeList(['D4', 'E6']);

// Inserts checkboxes into each cell in the ranges D4 and E6 configured with
// 'yes' for checked and 'no' for unchecked. Also, sets the value of each cell
// in the ranges D4 and E6 to 'no'.
rangeList.insertCheckboxes('yes', 'no');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

從指定範圍移除所有核取方塊。清除每個儲存格的資料驗證，如果儲存格含有勾選或未勾選的值，則一併清除其值。

const range = SpreadsheetApp.getActive().getRange('A1:B10');

// Inserts checkboxes and sets each cell value to 'no' in the range A1:B10.
range.insertCheckboxes('yes', 'no');

const rangeList1 = SpreadsheetApp.getActive().getRangeList(['A1', 'A3']);
rangeList1.setValue('yes');
// Removes the checkbox data validation in cells A1 and A3 and clears their
// value.
rangeList1.removeCheckboxes();

const rangeList2 = SpreadsheetApp.getActive().getRangeList(['A5', 'A7']);
rangeList2.setValue('random');
// Removes the checkbox data validation in cells A5 and A7 but does not clear
// their value.
rangeList2.removeCheckboxes();

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

設定範圍清單中每個 Range 的背景顏色。顏色會以 CSS 符號表示，例如 '#ffffff' 或 'white'。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.setBackground('red');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

將背景設為指定的 RGB 顏色。這是 setBackground(color) 呼叫的便利包裝函式。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
// Sets the background to red for each range in the range list.
rangeList.setBackgroundRGB(255, 0, 0);

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

為範圍清單中的每個 Range 設定邊框屬性。有效值為 true (開啟)、false (關閉) 和 null (不變)。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A2:B4', 'C1:D4']);
// Sets borders on the top and bottom of the ranges A2:B4 and C1:D4, but leaves
// the left and right unchanged.
rangeList.setBorder(true, null, true, null, false, false);

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

為範圍清單中的每個 Range 設定邊框屬性，包括顏色和/或樣式。有效值為 true (開啟)、false (關閉) 和 null (不變)。顏色會以 CSS 符號表示，例如 '#ffffff' 或 'white'。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A2:B4', 'C1:D4']);
// Sets borders on the top and bottom, but leaves the left and right unchanged
// of the ranges A2:B4 and C1:D4. Also sets the color to 'red', and the border
// to 'DASHED'.
rangeList.setBorder(
    true,
    null,
    true,
    null,
    false,
    false,
    'red',
    SpreadsheetApp.BorderStyle.DASHED,
);

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

設定範圍清單中每個 Range 的字型顏色。顏色會以 CSS 符號表示，例如 '#ffffff' 或 'white'。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.setFontColor('red');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

為範圍清單中的每個 Range 設定字型系列。字型系列會以字串 ID 描述，例如 Arial 或 Roboto。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.setFontFamily('Roboto');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

設定範圍清單中每個 Range 的字型線條樣式。線條樣式選項為 'underline'、'line-through' 或 'none'。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.setFontLine('line-through');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

設定範圍清單中每個 Range 的字型大小 (以點為單位)。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.setFontSize(20);

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

設定範圍清單中每個 Range 的字型樣式。字型樣式選項為 'italic' 或 'normal'。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.setFontStyle('italic');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

為範圍清單中的每個 Range 設定字型粗細。字型粗細選項為 'normal' 或 'bold'。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.setFontWeight('bold');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

更新範圍清單中每個 Range 的公式。給定的公式必須採用 A1 標記法。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A11', 'C11']);
rangeList.setFormula('=SUM(B1:B10)');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

更新範圍清單中每個 Range 的公式。給定的公式必須採用 R1C1 符號。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A11', 'C11']);
// This sets the formula to be the sum of the 3 rows above B5
rangeList.setFormulaR1C1('=SUM(R[-3]C[0]:R[-1]C[0])');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

為範圍清單中的每個 Range 設定水平對齊方式。對齊選項為 'left'、'center' 或 'right'。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.setHorizontalAlignment('center');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

設定範圍清單中每個 Range 的註解文字。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.setNote('This is a note');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

為範圍清單中的每個 Range 設定數字或日期格式。

如要瞭解系統接受的格式模式，請參閱 Sheets API 日期和數字格式指南。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A1:A10', 'C1:C10']);
// Always show 3 decimal points for the specified ranges.
rangeList.setNumberFormat('0.000');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

設定範圍清單中的每個 Range 是否應顯示超連結。

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A1:A10', 'C1:C10']);
// Show hyperlinks for all the ranges.
rangeList.setShowHyperlink(true);

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

設定範圍清單中每個 Range 中儲存格文字的方向。如果指定的方向為 null，系統會推斷方向，然後進行設定。

// Sets right-to-left text direction each range in the range list.
const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A1:A10', 'C1:C10']);
rangeList.setTextDirection(SpreadsheetApp.TextDirection.RIGHT_TO_LEFT);

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

為範圍清單中每個 Range 的儲存格設定文字旋轉設定。輸入值對應於標準文字方向與所需方向之間的角度。輸入零表示文字已設為標準方向。

如果文字方向是從左到右，正角度會以逆時針方向計算，如果文字方向是從右到左，則會以順時針方向計算。

// Sets the cells in the ranges A1:A10 and C1:C10 to have text rotated up 45
// degrees.
const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['A1:A10', 'C1:C10']);
rangeList.setTextRotation(45);

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

設定範圍清單中每個 Range 的值。值可以是數字、字串、布林值或日期。如果開頭為「=」，則會解讀為公式。

const sheet = SpreadsheetApp.getActiveSheet();
// Set value of 100 to each range in the range list.
const rangeList = sheet.getRangeList(['A:A', 'C:C']);
rangeList.setValue(100);

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

為範圍清單中的每個 Range 設定垂直對齊方式。對齊選項包括 'top'、'middle' 或 'bottom'。

// Sets the vertical alignment to middle for the list of ranges.
const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['D4', 'B2:C4']);
rangeList.setVerticalAlignment('middle');

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

設定是否要為範圍清單中的每個 Range 的儲存格堆疊文字。如果文字是垂直堆疊，系統會忽略文字旋轉角度設定。

// Sets all cell's in ranges D4 and B2:D4 to have vertically stacked text.
const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['D4', 'B2:C4']);
rangeList.setVerticalText(true);

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

為範圍清單中的每個 Range 設定文字斷行。啟用換行的儲存格會調整大小，以便顯示完整內容。停用折行功能的儲存格會盡可能在儲存格中顯示，而不會調整大小或顯示在多行中。

// Enable text wrap for the list of ranges.
const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['D4', 'B2:C4']);
rangeList.setWrap(true);

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

為範圍清單中的每個 Range 設定文字斷行策略。

// Sets the list of ranges to use the clip wrap strategy.
const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['D4', 'B2:C4']);
rangeList.setWrapStrategy(SpreadsheetApp.WrapStrategy.CLIP);

參數

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

會修剪這個範圍清單中每個儲存格中的空白字元 (例如空格、tab 或換行符號)。移除每個儲存格文字開頭和結尾的所有空白字元，並將剩餘空白字元的子序列縮減為單一空格。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getRange('A1:A4');
range.activate();
range.setValues([
  ' preceding space',
  'following space ',
  'two  middle  spaces',
  '   =SUM(1,2)',
]);

const rangeList = sheet.getRangeList(['A1', 'A2', 'A3', 'A4']);
rangeList.trimWhitespace();

const values = range.getValues();
// Values are ['preceding space', 'following space', 'two middle spaces',
// '=SUM(1,2)']

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets

另請參閱

• Range.trimWhitespace()

將範圍內的核取方塊狀態變更為「未勾選」。忽略目前不含已勾選或未勾選值的範圍內儲存格。

// Changes the state of cells which currently contain either the checked or
// unchecked value configured in the ranges D4 and E6 to 'unchecked'.
const rangeList = SpreadsheetApp.getActive().getRangeList(['D4', 'E6']);
rangeList.uncheck();

回攻員

RangeList：這個範圍清單，用於鏈結。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

• https://www.googleapis.com/auth/spreadsheets.currentonly
• https://www.googleapis.com/auth/spreadsheets