Class RangeList

範圍清單

同一個工作表中一或多個 Range 例項的集合。您可以使用這個類別，在非相鄰範圍或儲存格集合上套用運算。

方法

方法	傳回類型	簡短說明
activate()	RangeList	選取 Range 例項清單。
breakApart()	RangeList	將範圍清單中所有水平或垂直合併的儲存格再次分割為個別儲存格。
check()	RangeList	將範圍內的核取方塊狀態變更為「已勾選」。
clear()	RangeList	清除範圍清單中每個 Range 的內容範圍、格式和資料驗證規則。
clear(options)	RangeList	清除指定選項指定的內容範圍、格式、資料驗證規則和註解。
clearContent()	RangeList	清除範圍清單中每個 Range 的內容，但格式保持不變。
clearDataValidations()	RangeList	清除指定範圍清單中每個 Range 的資料驗證規則。
clearFormat()	RangeList	清除指定範圍清單中每個 Range 的文字格式。
clearNote()	RangeList	清除範圍清單中每個 Range 的附註。
getRanges()	Range[]	傳回同一個工作表中一或多個 Range 例項的清單。
insertCheckboxes()	RangeList	在範圍內的每個儲存格中插入核取方塊，並以 true 代表已勾選，以 false 代表未勾選。
insertCheckboxes(checkedValue)	RangeList	在指定範圍內的每個儲存格中插入核取方塊，並設定勾選狀態為已勾選的自訂值，未勾選狀態為空字串。
insertCheckboxes(checkedValue, uncheckedValue)	RangeList	在範圍內的每個儲存格中插入核取方塊，並為已勾選和未勾選狀態設定自訂值。
removeCheckboxes()	RangeList	從指定範圍移除所有核取方塊。
setBackground(color)	RangeList	設定範圍清單中每個 Range 的背景顏色。
setBackgroundRGB(red, green, blue)	RangeList	將背景設為指定的 RGB 顏色。
setBorder(top, left, bottom, right, vertical, horizontal)	RangeList	為範圍清單中的每個 Range 設定邊框屬性。
setBorder(top, left, bottom, right, vertical, horizontal, color, style)	RangeList	為範圍清單中的每個 Range 設定邊框屬性，包括顏色和/或樣式。
setFontColor(color)	RangeList	設定範圍清單中每個 Range 的字型顏色。
setFontFamily(fontFamily)	RangeList	設定範圍清單中每個 Range 的字型系列。
setFontLine(fontLine)	RangeList	設定範圍清單中每個 Range 的字型線條樣式。
setFontSize(size)	RangeList	設定範圍清單中每個 Range 的字型大小 (以點為單位)。
setFontStyle(fontStyle)	RangeList	設定範圍清單中每個 Range 的字型樣式。
setFontWeight(fontWeight)	RangeList	為範圍清單中的每個 Range 設定字型粗細。
setFormula(formula)	RangeList	更新範圍清單中每個 Range 的公式。
setFormulaR1C1(formula)	RangeList	更新範圍清單中每個 Range 的公式。
setHorizontalAlignment(alignment)	RangeList	設定範圍清單中每個 Range 的水平對齊方式。
setNote(note)	RangeList	設定範圍清單中每個 Range 的註解文字。
setNumberFormat(numberFormat)	RangeList	為範圍清單中的每個 Range 設定數字或日期格式。
setShowHyperlink(showHyperlink)	RangeList	設定範圍清單中的每個 Range 是否應顯示超連結。
setTextDirection(direction)	RangeList	設定範圍清單中每個 Range 中儲存格文字的方向。
setTextRotation(degrees)	RangeList	為範圍清單中每個 Range 中的儲存格設定文字旋轉設定。
setValue(value)	RangeList	設定範圍清單中每個 Range 的值。
setVerticalAlignment(alignment)	RangeList	設定範圍清單中每個 Range 的垂直對齊方式。
setVerticalText(isVertical)	RangeList	設定是否要為範圍清單中的每個 Range 的儲存格堆疊文字。
setWrap(isWrapEnabled)	RangeList	為範圍清單中的每個 Range 設定文字斷行。
setWrapStrategy(strategy)	RangeList	為範圍清單中的每個 Range 設定文字斷行策略。
trimWhitespace()	RangeList	這個範圍清單中的每個儲存格都會去除空白字元 (例如空格、tab 或換行符號)。
uncheck()	RangeList	將指定範圍內的核取方塊狀態變更為「未勾選」。

內容詳盡的說明文件

activate()

選取 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

---

breakApart()

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

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

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

---

check()

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

// 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

---

clear()

清除範圍清單中每個 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

---

clear(options)

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

// 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});

參數

名稱	類型	說明
options	Object	指定進階參數的 JavaScript 物件，如下所列。

進階參數

名稱	類型	說明
commentsOnly	Boolean	是否只清除留言。
contentsOnly	Boolean	是否只清除內容。
formatOnly	Boolean	是否只清除格式；請注意，清除格式也會清除資料驗證規則。
validationsOnly	Boolean	是否只清除資料驗證規則。
skipFilteredRows	Boolean	是否要避免清除篩選出的資料列。

回攻員

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

授權

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

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

---

clearContent()

清除範圍清單中每個 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

---

clearDataValidations()

清除指定範圍清單中每個 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

---

clearFormat()

清除指定範圍清單中每個 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

---

clearNote()

清除範圍清單中每個 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

---

getRanges()

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

回攻員

Range[]：範圍清單。

授權

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

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

---

insertCheckboxes()

在範圍內的每個儲存格中插入核取方塊，並以 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

---

insertCheckboxes(checkedValue)

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

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');

參數

名稱	類型	說明
checkedValue	Object	核取方塊資料驗證的勾選值。

回攻員

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

授權

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

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

---

insertCheckboxes(checkedValue, uncheckedValue)

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

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');

參數

名稱	類型	說明
checkedValue	Object	核取方塊資料驗證的勾選值。
uncheckedValue	Object	核取方塊資料驗證的未勾選值。

回攻員

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

授權

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

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

---

removeCheckboxes()

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

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

---

setBackground(color)

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

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

參數

名稱	類型	說明
color	String	CSS 符號中的背景顏色代碼，例如 '#ffffff' 或 'white'；null 值會重設顏色。

回攻員

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

授權

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

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

---

setBackgroundRGB(red, green, blue)

將背景設為指定的 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);

參數

名稱	類型	說明
red	Integer	RGB 標記法中的紅色值。
green	Integer	RGB 符號中的綠色值。
blue	Integer	RGB 符號中的藍色值。

回攻員

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

授權

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

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

---

setBorder(top, left, bottom, right, vertical, horizontal)

為範圍清單中的每個 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);

參數

名稱	類型	說明
top	Boolean	true 代表邊框，false 代表無邊框，null 代表不變更。
left	Boolean	true 代表邊框，false 代表無邊框，null 代表不變更。
bottom	Boolean	true 代表邊框，false 代表無邊框，null 代表不變更。
right	Boolean	true 代表邊框，false 代表無邊框，null 代表不變更。
vertical	Boolean	true 代表內部垂直邊框，false 代表無邊框，null 代表不變。
horizontal	Boolean	true 代表內部水平邊框，false 代表無邊框，null 代表不變。

回攻員

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

授權

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

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

---

setBorder(top, left, bottom, right, vertical, horizontal, color, style)

為範圍清單中的每個 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,
);

參數

名稱	類型	說明
top	Boolean	true 代表邊框，false 代表無邊框，null 代表不變更。
left	Boolean	true 代表邊框，false 代表無邊框，null 代表不變更。
bottom	Boolean	true 代表邊框，false 代表無邊框，null 代表不變更。
right	Boolean	true 代表邊框，false 代表無邊框，null 代表不變更。
vertical	Boolean	true 代表內部垂直邊框，false 代表無邊框，null 代表不變。
horizontal	Boolean	true 代表內部水平邊框，false 代表無邊框，null 代表不變。
color	String	CSS 符號中的邊框顏色，例如 '#ffffff' 或 'white'，null 為預設顏色 (黑色)。
style	BorderStyle	框線的樣式，null 為預設樣式 (實線)。

回攻員

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

授權

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

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

---

setFontColor(color)

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

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

參數

名稱	類型	說明
color	String	CSS 符號中的字型顏色，例如 '#ffffff' 或 'white'；null 值會重設顏色。

回攻員

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

授權

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

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

---

setFontFamily(fontFamily)

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

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

參數

名稱	類型	說明
fontFamily	String	要設定的字型系列；null 值會重設字型系列。

回攻員

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

授權

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

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

---

setFontLine(fontLine)

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

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

參數

名稱	類型	說明
fontLine	String	字型線條樣式，可選 'underline'、'line-through' 或 'none'；null 值會重設字型線條樣式。

回攻員

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

授權

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

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

---

setFontSize(size)

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

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

參數

名稱	類型	說明
size	Integer	字型點大小。

回攻員

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

授權

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

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

---

setFontStyle(fontStyle)

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

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

參數

名稱	類型	說明
fontStyle	String	字型樣式，為 'italic' 或 'normal'；null 值會重設字型樣式。

回攻員

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

授權

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

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

---

setFontWeight(fontWeight)

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

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

參數

名稱	類型	說明
fontWeight	String	字型粗細，可為 'bold' 或 'normal'；null 值會重設字型粗細。

回攻員

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

授權

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

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

---

setFormula(formula)

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

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

參數

名稱	類型	說明
formula	String	代表要設定的公式的字串。

回攻員

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

授權

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

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

---

setFormulaR1C1(formula)

更新範圍清單中每個 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])');

參數

名稱	類型	說明
formula	String	字串公式。

回攻員

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

授權

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

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

---

setHorizontalAlignment(alignment)

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

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

參數

名稱	類型	說明
alignment	String	對齊方式 ('left'、'center' 或 'normal')；null 值會重設對齊方式。

回攻員

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

授權

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

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

---

setNote(note)

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

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

參數

名稱	類型	說明
note	String	要設定的附註文字；null 值會移除附註。

回攻員

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

授權

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

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

---

setNumberFormat(numberFormat)

為範圍清單中的每個 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');

參數

名稱	類型	說明
numberFormat	String	數字格式字串。

回攻員

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

授權

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

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

---

setShowHyperlink(showHyperlink)

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

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

參數

名稱	類型	說明
showHyperlink	Boolean	是否顯示超連結。

回攻員

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

授權

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

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

---

setTextDirection(direction)

設定範圍清單中每個 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);

參數

名稱	類型	說明
direction	TextDirection	所需的文字方向；如果為 null，系統會在設定前推斷方向。

回攻員

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

授權

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

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

---

setTextRotation(degrees)

為範圍清單中每個 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);

參數

名稱	類型	說明
degrees	Integer	標準方向和所需方向之間的角度。對於從左到右的文字，正角度為逆時針方向。

回攻員

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

授權

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

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

---

setValue(value)

設定範圍清單中每個 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);

參數

名稱	類型	說明
value	Object	範圍的值。

回攻員

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

授權

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

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

---

setVerticalAlignment(alignment)

為範圍清單中的每個 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');

參數

名稱	類型	說明
alignment	String	對齊方式 ('top'、'middle' 或 'bottom')；null 值會重設對齊方式。

回攻員

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

授權

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

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

---

setVerticalText(isVertical)

設定是否要為範圍清單中的每個 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);

參數

名稱	類型	說明
isVertical	Boolean	是否要堆疊文字。

回攻員

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

授權

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

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

---

setWrap(isWrapEnabled)

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

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

參數

名稱	類型	說明
isWrapEnabled	Boolean	是否要換行文字。

回攻員

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

授權

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

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

---

setWrapStrategy(strategy)

為範圍清單中的每個 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);

參數

名稱	類型	說明
strategy	WrapStrategy	所需的換行策略。

回攻員

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

授權

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

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

---

trimWhitespace()

會修剪這個範圍清單中每個儲存格中的空白字元 (例如空格、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()

---

uncheck()

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

// 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