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`	剪裁此范围列表中的每个单元格中的空白字符（例如空格、制表符或换行符）。
`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()`

将范围列表内包含的所有水平或垂直合并的单元格再次拆分为单个单元格。

对范围列表调用此函数相当于选择一组范围，然后选择 Format > Merge > Unmerge（格式 > 合并 > 取消合并）Google 表格菜单项。

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 设置字体系列。字体系列由字符串标识符（例如 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()`

剪裁此范围列表中的每个单元格中的空白字符（例如空格、制表符或换行符）。移除每个单元格文本开头和结尾的所有空格，并将剩余的任何后续空格字符减少为单个空格。

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

Class RangeList 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

方法

详细文档

activate()

返回

授权

breakApart()

返回

授权

check()

返回

授权

clear()

返回

授权

clear(options)

参数

高级参数

返回

授权

clearContent()

返回

授权

clearDataValidations()

返回

授权

clearFormat()

返回

授权

clearNote()

返回

授权

getRanges()

返回

授权

insertCheckboxes()

返回

授权

insertCheckboxes(checkedValue)

参数

返回

授权

insertCheckboxes(checkedValue, uncheckedValue)

参数

返回

授权

removeCheckboxes()

返回

授权

setBackground(color)

参数

返回

授权

setBackgroundRGB(red, green, blue)

参数

返回

授权

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

参数

返回

授权

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

参数

返回

授权

setFontColor(color)

参数

返回

授权

setFontFamily(fontFamily)

参数

返回

授权

setFontLine(fontLine)

参数

返回

授权

setFontSize(size)

参数

返回

Class RangeList

`activate()`

`breakApart()`

`check()`

`clear()`

`clear(options)`

`clearContent()`

`clearDataValidations()`

`clearFormat()`

`clearNote()`

`getRanges()`

`insertCheckboxes()`

`insertCheckboxes(checkedValue)`

`insertCheckboxes(checkedValue, uncheckedValue)`

`removeCheckboxes()`

`setBackground(color)`

`setBackgroundRGB(red, green, blue)`

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

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

`setFontColor(color)`

`setFontFamily(fontFamily)`

`setFontLine(fontLine)`

`setFontSize(size)`

`setFontStyle(fontStyle)`

`setFontWeight(fontWeight)`

`setFormula(formula)`

`setFormulaR1C1(formula)`

`setHorizontalAlignment(alignment)`

`setNote(note)`

`setNumberFormat(numberFormat)`

`setShowHyperlink(showHyperlink)`

`setTextDirection(direction)`

`setTextRotation(degrees)`

`setValue(value)`

`setVerticalAlignment(alignment)`

`setVerticalText(isVertical)`

`setWrap(isWrapEnabled)`

`setWrapStrategy(strategy)`

`trimWhitespace()`

`uncheck()`