此页面由 Cloud Translation API 翻译。

Class Range

访问和修改电子表格范围。范围可以是工作表中的单个单元格，也可以是工作表中的一组相邻单元格。

方法

方法	返回类型	简介
`activate()`	`Range`	将指定范围设置为 `active range`，并将该范围内的左上角单元格设置为 `current cell`。
`activateAsCurrentCell()`	`Range`	将指定单元格设置为 `current cell`。
`addDeveloperMetadata(key)`	`Range`	向范围添加具有指定键的开发者元数据。
`addDeveloperMetadata(key, visibility)`	`Range`	向范围添加具有指定键和可见性的开发者元数据。
`addDeveloperMetadata(key, value)`	`Range`	向范围添加具有指定键和值的开发者元数据。
`addDeveloperMetadata(key, value, visibility)`	`Range`	向范围添加具有指定键、值和公开范围的开发者元数据。
`applyColumnBanding()`	`Banding`	将默认的列条纹主题应用于范围。
`applyColumnBanding(bandingTheme)`	`Banding`	将指定的列条带主题应用于范围。
`applyColumnBanding(bandingTheme, showHeader, showFooter)`	`Banding`	将指定的列条带主题应用于具有指定页眉和页脚设置的范围。
`applyRowBanding()`	`Banding`	将默认的行条纹主题应用于范围。
`applyRowBanding(bandingTheme)`	`Banding`	将指定的行条带主题应用于范围。
`applyRowBanding(bandingTheme, showHeader, showFooter)`	`Banding`	将指定的行条带主题应用于具有指定页眉和页脚设置的范围。
`autoFill(destination, series)`	`void`	根据此范围内的数据填充 `destinationRange`。
`autoFillToNeighbor(series)`	`void`	根据相邻单元格计算要填充新数据的范围，并根据该范围内的数据自动填充新值。
`breakApart()`	`Range`	将范围内的所有多列单元格再次拆分为单个单元格。
`canEdit()`	`Boolean`	确定用户是否有权修改范围内的每个单元格。
`check()`	`Range`	将范围内的复选框的状态更改为“已选中”。
`clear()`	`Range`	清除指定范围内的内容和格式。
`clear(options)`	`Range`	根据指定的高级选项清除相应范围的内容、格式、数据验证规则和/或注释。
`clearContent()`	`Range`	清除范围的内容，但保留格式。
`clearDataValidations()`	`Range`	清除相应范围内的数据验证规则。
`clearFormat()`	`Range`	清除相应范围的格式。
`clearNote()`	`Range`	清除指定单元格中的注释。
`collapseGroups()`	`Range`	收起完全包含在范围内的所有群组。
`copyFormatToRange(gridId, column, columnEnd, row, rowEnd)`	`void`	将范围的格式复制到指定位置。
`copyFormatToRange(sheet, column, columnEnd, row, rowEnd)`	`void`	将范围的格式复制到指定位置。
`copyTo(destination)`	`void`	将某个单元格范围内的数据复制到另一个单元格范围。
`copyTo(destination, copyPasteType, transposed)`	`void`	将某个单元格范围内的数据复制到另一个单元格范围。
`copyTo(destination, options)`	`void`	将某个单元格范围内的数据复制到另一个单元格范围。
`copyValuesToRange(gridId, column, columnEnd, row, rowEnd)`	`void`	将范围的内容复制到指定位置。
`copyValuesToRange(sheet, column, columnEnd, row, rowEnd)`	`void`	将范围的内容复制到指定位置。
`createDataSourcePivotTable(dataSource)`	`DataSourcePivotTable`	根据数据源创建一个空的数据源透视表，并以相应范围内的第一个单元格为锚点。
`createDataSourceTable(dataSource)`	`DataSourceTable`	根据数据源创建一个空数据源表，该表锚定在相应范围内的第一个单元格。
`createDeveloperMetadataFinder()`	`DeveloperMetadataFinder`	返回一个 DeveloperMetadataFinderApi，用于查找此范围内的开发者元数据。
`createFilter()`	`Filter`	创建过滤器并将其应用于工作表中的指定范围。
`createPivotTable(sourceData)`	`PivotTable`	根据指定的 `sourceData` 创建一个空数据透视表，该表锚定在此范围内的第一个单元格。
`createTextFinder(findText)`	`TextFinder`	为指定范围创建文本查找器，该查找器可查找和替换此范围内的文本。
`deleteCells(shiftDimension)`	`void`	删除相应范围的单元格。
`expandGroups()`	`Range`	展开范围或控制切换开关与此范围相交的已收起组。
`getA1Notation()`	`String`	以 A1 符号表示法返回范围的字符串说明。
`getBackground()`	`String`	返回范围（例如 `'#ffffff'`）中左上角单元格的背景颜色。
`getBackgroundObject()`	`Color`	返回范围中左上角单元格的背景颜色。
`getBackgroundObjects()`	`Color[][]`	返回指定范围内单元格的背景颜色。
`getBackgrounds()`	`String[][]`	返回指定范围内单元格的背景颜色（例如 `'#ffffff'`）。
`getBandings()`	`Banding[]`	返回应用于相应范围内任何单元格的所有条带。
`getCell(row, column)`	`Range`	返回指定范围内的指定单元格。
`getColumn()`	`Integer`	返回相应范围的起始列位置。
`getDataRegion()`	`Range`	返回在四个基本方向上扩展的范围的副本，以覆盖所有包含数据的相邻单元格。`Direction`
`getDataRegion(dimension)`	`Range`	如果指定维度为 `Dimension.ROWS`，则返回扩展后的范围（`Direction.UP` 和 `Direction.DOWN`）；如果维度为 `Dimension.COLUMNS`，则返回扩展后的范围（`Direction.NEXT` 和 `Direction.PREVIOUS`）。
`getDataSourceFormula()`	`DataSourceFormula`	返回范围中第一个单元格的 `DataSourceFormula`，如果该单元格不包含数据源公式，则返回 `null`。
`getDataSourceFormulas()`	`DataSourceFormula[]`	返回相应范围内单元格的 `DataSourceFormula`。
`getDataSourcePivotTables()`	`DataSourcePivotTable[]`	获取与指定范围相交的所有数据源透视表。
`getDataSourceTables()`	`DataSourceTable[]`	获取与范围相交的所有数据源表。
`getDataSourceUrl()`	`String`	返回相应范围内数据的网址，该网址可用于创建图表和查询。
`getDataTable()`	`DataTable`	以 DataTable 形式返回此对象内的数据。
`getDataTable(firstRowIsHeader)`	`DataTable`	以 DataTable 形式返回此范围内的相应数据。
`getDataValidation()`	`DataValidation`	返回范围左上角单元格的数据验证规则。
`getDataValidations()`	`DataValidation[][]`	返回指定范围内所有单元格的数据验证规则。
`getDeveloperMetadata()`	`DeveloperMetadata[]`	获取与相应范围关联的开发者元数据。
`getDisplayValue()`	`String`	返回范围中左上角单元格的显示值。
`getDisplayValues()`	`String[][]`	返回相应范围的值的矩形网格。
`getFilter()`	`Filter`	返回相应范围所属工作表的过滤器；如果工作表上没有过滤器，则返回 `null`。
`getFontColorObject()`	`Color`	返回范围左上角单元格的字体颜色。
`getFontColorObjects()`	`Color[][]`	返回指定范围内单元格的字体颜色。
`getFontFamilies()`	`String[][]`	返回相应范围内单元格的字体系列。
`getFontFamily()`	`String`	返回范围左上角单元格的字体系列。
`getFontLine()`	`String`	获取范围左上角单元格的线条样式（`'underline'`、`'line-through'` 或 `'none'`）。
`getFontLines()`	`String[][]`	获取相应范围内单元格的线条样式（`'underline'`、`'line-through'` 或 `'none'`）。
`getFontSize()`	`Integer`	返回范围左上角单元格的字体大小（以磅为单位）。
`getFontSizes()`	`Integer[][]`	返回指定范围内单元格的字号。
`getFontStyle()`	`String`	返回范围左上角单元格的字体样式（`'italic'` 或 `'normal'`）。
`getFontStyles()`	`String[][]`	返回指定范围内单元格的字体样式。
`getFontWeight()`	`String`	返回范围左上角单元格的字重（正常/粗体）。
`getFontWeights()`	`String[][]`	返回相应范围内单元格的字重。
`getFormula()`	`String`	返回范围左上角单元格的公式（A1 符号），如果单元格为空或不包含公式，则返回空字符串。
`getFormulaR1C1()`	`String`	返回指定单元格的公式（R1C1 表示法），如果没有公式，则返回 `null`。
`getFormulas()`	`String[][]`	返回相应范围内单元格的公式（A1 符号）。
`getFormulasR1C1()`	`String[][]`	返回相应范围内单元格的公式（R1C1 表示法）。
`getGridId()`	`Integer`	返回相应范围的父工作表的网格 ID。
`getHeight()`	`Integer`	返回范围的高度。
`getHorizontalAlignment()`	`String`	返回范围左上角单元格中文字的水平对齐方式（左对齐/居中对齐/右对齐）。
`getHorizontalAlignments()`	`String[][]`	返回指定范围内单元格的水平对齐方式。
`getLastColumn()`	`Integer`	返回结束列位置。
`getLastRow()`	`Integer`	返回结束行位置。
`getMergedRanges()`	`Range[]`	返回一个 `Range` 对象数组，表示完全位于当前范围内的合并单元格，或包含当前范围内的至少一个单元格的合并单元格。
`getNextDataCell(direction)`	`Range`	从范围的第一列和第一行中的单元格开始，返回指定方向上的下一个单元格，该单元格是包含数据的连续单元格范围的边缘，或者是该方向上工作表的边缘单元格。
`getNote()`	`String`	返回与指定范围关联的注释。
`getNotes()`	`String[][]`	返回与指定范围内的单元格关联的备注。
`getNumColumns()`	`Integer`	返回相应范围内的列数。
`getNumRows()`	`Integer`	返回相应范围内的行数。
`getNumberFormat()`	`String`	获取指定范围左上角单元格的数字或日期格式。
`getNumberFormats()`	`String[][]`	返回指定范围内单元格的数字或日期格式。
`getRichTextValue()`	`RichTextValue`	返回范围左上角单元格的富文本值，如果单元格值不是文本，则返回 `null`。
`getRichTextValues()`	`RichTextValue[][]`	返回指定范围内单元格的富文本值。
`getRow()`	`Integer`	返回相应范围的行位置。
`getRowIndex()`	`Integer`	返回相应范围的行位置。
`getSheet()`	`Sheet`	返回相应范围所属的工作表。
`getTextDirection()`	`TextDirection`	返回范围左上角单元格的文字方向。
`getTextDirections()`	`TextDirection[][]`	返回指定范围内单元格的文字方向。
`getTextRotation()`	`TextRotation`	返回指定范围左上角单元格的文字旋转设置。
`getTextRotations()`	`TextRotation[][]`	返回指定范围内单元格的文字旋转设置。
`getTextStyle()`	`TextStyle`	返回范围左上角单元格的文本样式。
`getTextStyles()`	`TextStyle[][]`	返回指定范围内单元格的文本样式。
`getValue()`	`Object`	返回范围中左上角单元格的值。
`getValues()`	`Object[][]`	返回相应范围的值的矩形网格。
`getVerticalAlignment()`	`String`	返回范围左上角单元格的垂直对齐方式（顶部/中间/底部）。
`getVerticalAlignments()`	`String[][]`	返回指定范围内单元格的垂直对齐方式。
`getWidth()`	`Integer`	返回范围的宽度（以列为单位）。
`getWrap()`	`Boolean`	返回单元格中的文本是否换行。
`getWrapStrategies()`	`WrapStrategy[][]`	返回指定范围内单元格的文字换行策略。
`getWrapStrategy()`	`WrapStrategy`	返回范围左上角单元格的文字换行策略。
`getWraps()`	`Boolean[][]`	返回单元格中的文本是否换行。
`insertCells(shiftDimension)`	`Range`	在此范围内插入空单元格。
`insertCheckboxes()`	`Range`	在范围内的每个单元格中插入复选框，并配置勾选和未勾选状态分别对应的 `true` 和 `false`。
`insertCheckboxes(checkedValue)`	`Range`	在范围内的每个单元格中插入复选框，并为勾选状态配置自定义值，为未勾选状态配置空字符串。
`insertCheckboxes(checkedValue, uncheckedValue)`	`Range`	在范围内的每个单元格中插入复选框，并为勾选和未勾选状态配置自定义值。
`isBlank()`	`Boolean`	如果范围完全空白，则返回 `true`。
`isChecked()`	`Boolean`	返回指定范围内的所有单元格的复选框状态是否均为“已选中”。
`isEndColumnBounded()`	`Boolean`	确定范围的末尾是否绑定到特定列。
`isEndRowBounded()`	`Boolean`	确定范围的末尾是否绑定到特定行。
`isPartOfMerge()`	`Boolean`	如果当前范围内的单元格与任何合并的单元格重叠，则返回 `true`。
`isStartColumnBounded()`	`Boolean`	确定范围的开头是否绑定到特定列。
`isStartRowBounded()`	`Boolean`	确定范围的开头是否绑定到特定行。
`merge()`	`Range`	将范围内的单元格合并为一个块。
`mergeAcross()`	`Range`	合并范围中各列的单元格。
`mergeVertically()`	`Range`	合并指定范围内的单元格。
`moveTo(target)`	`void`	将此范围内的内容（包括格式和值）剪切并粘贴到目标范围。
`offset(rowOffset, columnOffset)`	`Range`	返回一个新范围，该范围相对于当前范围偏移了指定的行数和列数（可以是负数）。
`offset(rowOffset, columnOffset, numRows)`	`Range`	返回一个相对于当前范围的新范围，该范围的左上角点相对于当前范围偏移了指定的行数和列数，并且具有指定的单元格高度。
`offset(rowOffset, columnOffset, numRows, numColumns)`	`Range`	返回一个相对于当前范围的新范围，其左上角点相对于当前范围偏移了给定的行数和列数，并且具有给定的高度和宽度（以单元格为单位）。
`protect()`	`Protection`	创建一个对象，该对象可以保护范围免遭编辑，但具有相应权限的用户除外。
`randomize()`	`Range`	随机化指定范围内的行顺序。
`removeCheckboxes()`	`Range`	移除范围内的所有复选框。
`removeDuplicates()`	`Range`	移除此范围内的行，这些行包含的值与任何前一行中的值重复。
`removeDuplicates(columnsToCompare)`	`Range`	移除此范围内的行，这些行在指定列中包含与任何前一行中的值重复的值。
`setBackground(color)`	`Range`	以 CSS 表示法（例如 `'#ffffff'` 或 `'white'`）设置指定范围内所有单元格的背景颜色。
`setBackgroundObject(color)`	`Range`	设置指定范围内所有单元格的背景颜色。
`setBackgroundObjects(color)`	`Range`	设置背景色的矩形网格（必须与相应范围的尺寸一致）。
`setBackgroundRGB(red, green, blue)`	`Range`	使用 RGB 值（介于 0 到 255 之间的整数，包括 0 和 255）将背景设置为指定颜色。
`setBackgrounds(color)`	`Range`	设置背景色的矩形网格（必须与相应范围的尺寸一致）。
`setBorder(top, left, bottom, right, vertical, horizontal)`	`Range`	设置边框属性。
`setBorder(top, left, bottom, right, vertical, horizontal, color, style)`	`Range`	设置具有颜色和/或样式的边框属性。
`setDataValidation(rule)`	`Range`	为指定范围内的所有单元格设置一个数据验证规则。
`setDataValidations(rules)`	`Range`	为范围内的所有单元格设置数据验证规则。
`setFontColor(color)`	`Range`	以 CSS 表示法（例如 `'#ffffff'` 或 `'white'`）设置字体颜色。
`setFontColorObject(color)`	`Range`	设置指定范围的字体颜色。
`setFontColorObjects(colors)`	`Range`	设置字体颜色的矩形网格（必须与相应范围的尺寸一致）。
`setFontColors(colors)`	`Range`	设置字体颜色的矩形网格（必须与相应范围的尺寸一致）。
`setFontFamilies(fontFamilies)`	`Range`	设置字体系列的矩形网格（必须与此范围的尺寸一致）。
`setFontFamily(fontFamily)`	`Range`	设置字体系列，例如“Arial”或“Helvetica”。
`setFontLine(fontLine)`	`Range`	设置指定范围（`'underline'`、`'line-through'` 或 `'none'`）的字体线样式。
`setFontLines(fontLines)`	`Range`	设置线样式的矩形网格（必须与此范围的维度一致）。
`setFontSize(size)`	`Range`	设置字体大小，其中 size 是要使用的点大小。
`setFontSizes(sizes)`	`Range`	设置字体大小的矩形网格（必须与此范围的维度一致）。
`setFontStyle(fontStyle)`	`Range`	为指定范围设置字体样式（`'italic'` 或 `'normal'`）。
`setFontStyles(fontStyles)`	`Range`	设置字体样式的矩形网格（必须与此范围的维度一致）。
`setFontWeight(fontWeight)`	`Range`	为指定范围设置字重（常规/粗体）。
`setFontWeights(fontWeights)`	`Range`	设置字体粗细的矩形网格（必须与此范围的维度一致）。
`setFormula(formula)`	`Range`	更新相应范围的公式。
`setFormulaR1C1(formula)`	`Range`	更新相应范围的公式。
`setFormulas(formulas)`	`Range`	设置公式的矩形网格（必须与此范围的维度一致）。
`setFormulasR1C1(formulas)`	`Range`	设置公式的矩形网格（必须与此范围的维度一致）。
`setHorizontalAlignment(alignment)`	`Range`	为指定范围设置水平（从左到右）对齐方式（左对齐/居中/右对齐）。
`setHorizontalAlignments(alignments)`	`Range`	设置水平对齐方式的矩形网格。
`setNote(note)`	`Range`	将备注设置为指定值。
`setNotes(notes)`	`Range`	设置一个矩形网格的音符（必须与此范围的维度一致）。
`setNumberFormat(numberFormat)`	`Range`	将数字或日期格式设置为给定的格式字符串。
`setNumberFormats(numberFormats)`	`Range`	设置数字或日期格式的矩形网格（必须与相应范围的维度一致）。
`setRichTextValue(value)`	`Range`	为指定范围内的单元格设置富文本值。
`setRichTextValues(values)`	`Range`	设置富文本值的矩形网格。
`setShowHyperlink(showHyperlink)`	`Range`	设置范围是否应显示超链接。
`setTextDirection(direction)`	`Range`	设置指定范围内单元格的文字方向。
`setTextDirections(directions)`	`Range`	设置文本方向的矩形网格。
`setTextRotation(degrees)`	`Range`	为范围内的单元格设置文字旋转设置。
`setTextRotation(rotation)`	`Range`	为范围内的单元格设置文字旋转设置。
`setTextRotations(rotations)`	`Range`	设置文本旋转的矩形网格。
`setTextStyle(style)`	`Range`	为范围内的单元格设置文本样式。
`setTextStyles(styles)`	`Range`	设置文本样式的矩形网格。
`setValue(value)`	`Range`	设置范围的值。
`setValues(values)`	`Range`	设置一个矩形值网格（必须与相应范围的维度相匹配）。
`setVerticalAlignment(alignment)`	`Range`	设置指定范围（顶部/中间/底部）的垂直（从上到下）对齐方式。
`setVerticalAlignments(alignments)`	`Range`	设置垂直对齐方式的矩形网格（必须与相应范围的维度一致）。
`setVerticalText(isVertical)`	`Range`	设置是否堆叠指定范围内单元格的文本。
`setWrap(isWrapEnabled)`	`Range`	设置指定范围的单元格换行。
`setWrapStrategies(strategies)`	`Range`	设置环绕策略的矩形网格。
`setWrapStrategy(strategy)`	`Range`	为范围内的单元格设置文字换行策略。
`setWraps(isWrapEnabled)`	`Range`	设置一个字词换行政策的矩形网格（必须与此范围的维度一致）。
`shiftColumnGroupDepth(delta)`	`Range`	按指定量更改范围的列分组深度。
`shiftRowGroupDepth(delta)`	`Range`	按指定量更改范围的行分组深度。
`sort(sortSpecObj)`	`Range`	按指定的列和顺序对给定范围内的单元格进行排序。
`splitTextToColumns()`	`void`	根据自动检测到的分隔符，将文本列拆分为多个列。
`splitTextToColumns(delimiter)`	`void`	使用指定字符串作为自定义分隔符，将文本列拆分为多个列。
`splitTextToColumns(delimiter)`	`void`	根据指定的分隔符将文本列拆分为多列。
`trimWhitespace()`	`Range`	剪裁相应范围内每个单元格中的空白字符（例如空格、制表符或换行符）。
`uncheck()`	`Range`	将范围内的复选框的状态更改为“未选中”。

已弃用的方法

方法	返回类型	简介
`getFontColor()`	`String`	以 CSS 表示法（例如 `'#ffffff'` 或 `'white'`）返回范围左上角单元格的字体颜色。
`getFontColors()`	`String[][]`	以 CSS 表示法（例如 `'#ffffff'` 或 `'white'`）返回指定范围内单元格的字体颜色。

详细文档

`activate()`

将指定范围设置为 active range，并将该范围内的左上角单元格设置为 current cell。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getRange('A1:D10');
range.activate();

const selection = sheet.getSelection();
// Current cell: A1
const currentCell = selection.getCurrentCell();
// Active Range: A1:D10
const activeRange = selection.getActiveRange();

Range - 此范围，用于链式调用。

`activateAsCurrentCell()`

将指定单元格设置为 current cell。

如果指定单元格位于现有范围内，则该范围会成为活动范围，并且该单元格会成为当前单元格。

如果指定单元格不在任何现有范围内，则系统会移除现有选择，并将该单元格设为当前单元格和有效范围。

注意：指定的 Range 必须仅包含一个单元格，否则会抛出异常。

// Gets the first sheet of the spreadsheet.
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// Gets the cell B5 and sets it as the active cell.
const range = sheet.getRange('B5');
const currentCell = range.activateAsCurrentCell();

// Logs the activated cell.
console.log(currentCell.getA1Notation());

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`addDeveloperMetadata(key)`

向范围添加具有指定键的开发者元数据。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');

// Adds the key 'NAME' to the developer metadata for row 2.
range.addDeveloperMetadata('NAME');

// Gets the metadata and logs it to the console.
const developerMetaData = range.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());

参数

名称	类型	说明
`key`	`String`	新开发者元数据的键。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`addDeveloperMetadata(key, visibility)`

向范围添加具有指定键和可见性的开发者元数据。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on Sheet1.
const range = sheet.getRange('2:2');

// Adds the key 'NAME' and sets the developer metadata visibility to 'DOCUMENT'
// for row 2 on Sheet1.
range.addDeveloperMetadata(
    'NAME',
    SpreadsheetApp.DeveloperMetadataVisibility.DOCUMENT,
);

// Gets the updated metadata info and logs it to the console.
const developerMetaData = range.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getVisibility().toString());

参数

名称	类型	说明
`key`	`String`	新开发者元数据的键。
`visibility`	`DeveloperMetadataVisibility`	新开发者元数据的公开范围。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`addDeveloperMetadata(key, value)`

向范围添加具有指定键和值的开发者元数据。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 of Sheet1.
const range = sheet.getRange('2:2');

// Adds the key 'NAME' and sets the value to 'GOOGLE' for the metadata of row 2.
range.addDeveloperMetadata('NAME', 'GOOGLE');

// Gets the metadata and logs it to the console.
const developerMetaData = range.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getValue());

参数

名称	类型	说明
`key`	`String`	新开发者元数据的键。
`value`	`String`	新开发者元数据的值。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`addDeveloperMetadata(key, value, visibility)`

向范围添加具有指定键、值和公开范围的开发者元数据。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');

// Adds the key 'NAME', sets the value to 'GOOGLE', and sets the visibility
// to PROJECT for row 2 on the sheet.
range.addDeveloperMetadata(
    'NAME',
    'GOOGLE',
    SpreadsheetApp.DeveloperMetadataVisibility.PROJECT,
);

// Gets the updated metadata info and logs it to the console.
const developerMetaData = range.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getValue());
console.log(developerMetaData.getVisibility().toString());

参数

名称	类型	说明
`key`	`String`	新开发者元数据的键。
`value`	`String`	新开发者元数据的值。
`visibility`	`DeveloperMetadataVisibility`	新开发者元数据的公开范围。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`applyColumnBanding()`

将默认的列条纹主题应用于相应范围。默认情况下，条带具有标题颜色，但没有页脚颜色。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');

// Applies column banding to row 2.
const colBanding = range.applyColumnBanding();

// Gets the first banding on the sheet and logs the color of the header column.
console.log(
    sheet.getBandings()[0]
        .getHeaderColumnColorObject()
        .asRgbColor()
        .asHexString(),
);

// Gets the first banding on the sheet and logs the color of the second column.
console.log(
    sheet.getBandings()[0]
        .getSecondColumnColorObject()
        .asRgbColor()
        .asHexString(),
);

Banding - 新的条带化。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`applyColumnBanding(bandingTheme)`

将指定的列条带主题应用于范围。默认情况下，条带具有标题颜色，但没有页脚颜色。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');

// Applies the INDIGO color banding theme to the columns in row 2.
const colBanding = range.applyColumnBanding(SpreadsheetApp.BandingTheme.INDIGO);

// Gets the first banding on the sheet and logs the color of the second column.
console.log(
    sheet.getBandings()[0]
        .getSecondColumnColorObject()
        .asRgbColor()
        .asHexString(),
);

参数

名称	类型	说明
`bandingTheme`	`BandingTheme`	要应用于相应范围内的列的颜色主题。

Banding - 新的条带化。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`applyColumnBanding(bandingTheme, showHeader, showFooter)`

将指定的列条带主题应用于具有指定页眉和页脚设置的范围。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets rows 12-22 on the sheet.
const range = sheet.getRange('12:22');

// Applies the BLUE color banding theme to rows 12-22.
// Sets the header visibility to false and the footer visibility to true.
const colBanding = range.applyColumnBanding(
    SpreadsheetApp.BandingTheme.BLUE,
    false,
    true,
);

// Gets the banding color and logs it to the console.
console.log(
    sheet.getBandings()[0]
        .getSecondColumnColorObject()
        .asRgbColor()
        .asHexString(),
);

// Gets the header color object and logs it to the console. Returns null because
// the header visibility is set to false.
console.log(sheet.getBandings()[0].getHeaderColumnColorObject());

// Gets the footer color and logs it to the console.
console.log(
    sheet.getBandings()[0]
        .getFooterColumnColorObject()
        .asRgbColor()
        .asHexString(),
);

参数

名称	类型	说明
`bandingTheme`	`BandingTheme`	要应用于相应范围内的列的颜色主题。
`showHeader`	`Boolean`	如果值为 `true`，则将条带主题标题颜色应用于第一列。
`showFooter`	`Boolean`	如果值为 `true`，则将条带主题页脚颜色应用于最后一列。

Banding - 新的条带化。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`applyRowBanding()`

向范围应用默认的行条纹主题。默认情况下，条带具有标题颜色，但没有页脚颜色。

// Opens the spreadsheet by its URL. If you created your script from within a
// Google Sheets spreadsheet, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets rows 1-30 on Sheet1.
const range = sheet.getRange('1:30');

// Applies row banding to rows 1-30.
range.applyRowBanding();

// Gets the hex color of the second banded row.
const secondRowColor =
    range.getBandings()[0].getSecondRowColorObject().asRgbColor().asHexString();

// Logs the hex color to console.
console.log(secondRowColor);

Banding - 色带。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`applyRowBanding(bandingTheme)`

将指定行条纹主题应用于范围。默认情况下，条带具有标题颜色，但没有页脚颜色。

// Opens the spreadsheet by its URL. If you created your script from within a
// Google Sheets spreadsheet, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets rows 1-30 on Sheet1.
const range = sheet.getRange('1:30');

// Applies the INDIGO row banding theme to rows 1-30.
range.applyRowBanding(SpreadsheetApp.BandingTheme.INDIGO);

// Gets the hex color of the second banded row.
const secondRowColor =
    range.getBandings()[0].getSecondRowColorObject().asRgbColor().asHexString();

// Logs the hex color to console.
console.log(secondRowColor);

参数

名称	类型	说明
`bandingTheme`	`BandingTheme`	要应用于相应范围内的行的颜色主题。

Banding - 新的条带化。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`applyRowBanding(bandingTheme, showHeader, showFooter)`

将指定的行条带主题应用于具有指定页眉和页脚设置的范围。

// Opens the spreadsheet by its URL. If you created your script from within a
// Google Sheets spreadsheet, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets rows 1-30 on Sheet1.
const range = sheet.getRange('1:30');

// Applies the INDIGO row banding to rows 1-30 and
// specifies to hide the header and show the footer.
range.applyRowBanding(SpreadsheetApp.BandingTheme.INDIGO, false, true);

参数

名称	类型	说明
`bandingTheme`	`BandingTheme`	要应用于相应范围内的行的颜色主题。
`showHeader`	`Boolean`	如果值为 `true`，则将条带主题标题颜色应用于第一行。
`showFooter`	`Boolean`	如果值为 `true`，则将条带主题页脚颜色应用于最后一行。

Banding - 新的条带化。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`autoFill(destination, series)`

根据此范围内的数据填充 destinationRange。新值也由指定的 series 类型确定。目标范围必须包含此范围，并且只能向一个方向扩展。例如，以下代码会根据 A1:A4 中的当前值，使用一系列递增的数字填充 A1:A20：

const sheet = SpreadsheetApp.getActiveSheet();

// Has values [1, 2, 3, 4].
const sourceRange = sheet.getRange('A1:A4');
// The range to fill with values.
const destination = sheet.getRange('A1:A20');

// Inserts new values in A5:A20, continuing the pattern expressed in A1:A4
sourceRange.autoFill(destination, SpreadsheetApp.AutoFillSeries.DEFAULT_SERIES);

参数

名称	类型	说明
`destination`	`Range`	要自动填充值的范围。目标范围应包含此范围，并且只能向一个方向（向上、向下、向左或向右）扩展。
`series`	`AutoFillSeries`	应使用哪种自动填充序列来计算新值。此序列的效果因源数据的类型和数量而异。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`autoFillToNeighbor(series)`

根据相邻单元格计算要填充新数据的范围，并根据该范围内的数据自动填充新值。这些新值也由指定的 series 类型确定。

计算出的目标范围会考虑周围的数据，以确定应在何处插入新值：如果正在自动填充的列的紧邻左侧或右侧有数据，则新值只会扩展到此相邻数据的位置。

例如，如果 A1:A20 中填充了一系列递增的数字，并且此方法是在包含一系列日期的范围 B1:B4 上调用的，则仅将新值插入到 B5:B20 中。这样一来，这些新值就会“粘附”到包含 A 列中值的单元格。

const sheet = SpreadsheetApp.getActiveSheet();

// A1:A20 has values [1, 2, 3, ... 20].
// B1:B4 has values [1/1/2017, 1/2/2017, ...]
const sourceRange = sheet.getRange('B1:B4');

// Results in B5:B20 having values [1/5/2017, ... 1/20/2017]
sourceRange.autoFillToNeighbor(SpreadsheetApp.AutoFillSeries.DEFAULT_SERIES);

参数

名称	类型	说明
`series`	`AutoFillSeries`	应使用哪种自动填充序列来计算新值。此序列的效果因源数据的类型和数量而异。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`breakApart()`

将范围内的所有多列单元格再次拆分为单个单元格。

对某个范围调用此函数相当于选择该范围，然后依次点击格式 > 合并单元格 > 取消合并。

// Opens the spreadsheet by its URL. If you created your script from within a
// Google Sheets spreadsheet, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:C6 on Sheet1.
const range = sheet.getRange('A1:C6');

// Unmerges the range A1:C6 into individual cells.
range.breakApart();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`canEdit()`

确定用户是否有权修改范围内的每个单元格。电子表格所有者始终可以修改受保护的范围和工作表。

// Opens the spreadsheet by its URL. If you created your script from within a
// Google Sheets spreadsheet, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:C6 on Sheet1.
const range = sheet.getRange('A1:C6');

// Logs whether the user has permission to edit every cell in the range.
console.log(range.canEdit());

Boolean - 如果用户有权修改相应范围内的每个单元格，则为 true；否则为 false。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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 range A1:B10 to 'checked'.
const range = SpreadsheetApp.getActive().getRange('A1:B10');
range.check();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`clear()`

清除指定范围内的内容和格式。

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

const range = sheet.getRange('A1:D10');
range.clear();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`clear(options)`

根据指定的高级选项，清除相应范围的内容、格式、数据验证规则和/或注释。默认情况下，系统会清除所有数据。

// The code below clears range C2:G7 in the active sheet, but preserves the
// format, data validation rules, and comments.
SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 5).clear({
  contentsOnly: true
});

参数

名称	类型	说明
`options`	`Object`	一个 JavaScript 对象，用于指定高级参数，如下所列。

高级参数

名称	类型	说明
`commentsOnly`	`Boolean`	是否仅清除注释。
`contentsOnly`	`Boolean`	是否仅清除内容。
`formatOnly`	`Boolean`	是否仅清除格式；请注意，清除格式也会清除数据验证规则。
`validationsOnly`	`Boolean`	是否仅清除数据验证规则。
`skipFilteredRows`	`Boolean`	是否避免清除过滤后的行。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`clearContent()`

清除范围的内容，但保留格式。

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

const range = sheet.getRange('A1:D10');
range.clearContent();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`clearDataValidations()`

清除相应范围内的数据验证规则。

// Clear the data validation rules for cells A1:B5.
const range = SpreadsheetApp.getActive().getRange('A1:B5');
range.clearDataValidations();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`clearFormat()`

清除相应范围的格式。

此方法会清除指定范围内一个或多个单元格的文本格式，但不会重置任何数字格式设置规则。

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

const range = sheet.getRange('A1:D10');
range.clearFormat();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`clearNote()`

清除指定单元格中的注释。

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

const range = sheet.getRange('A1:D10');
range.clearNote();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`collapseGroups()`

收起完全包含在范围内的所有群组。如果没有群组完全位于该范围内，则会收起部分位于该范围内的最深展开群组。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getActiveRange();

// All row and column groups within the range are collapsed.
range.collapseGroups();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`copyFormatToRange(gridId, column, columnEnd, row, rowEnd)`

将范围的格式复制到指定位置。如果目标范围大于或小于源范围，则相应地重复或截断源。请注意，此方法仅复制格式。

如需详细了解 gridId 参数，请参阅 getGridId()。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const source = ss.getSheets()[0];

const range = source.getRange('B2:D4');

// This copies the formatting in B2:D4 in the source sheet to
// D4:F6 in the sheet with gridId 1555299895. Note that you can get the gridId
// of a sheet by calling sheet.getSheetId() or range.getGridId().
range.copyFormatToRange(1555299895, 4, 6, 4, 6);

参数

名称	类型	说明
`gridId`	`Integer`	电子表格中工作表的唯一 ID，与位置无关。
`column`	`Integer`	目标范围的第一列。
`columnEnd`	`Integer`	目标范围的结束列。
`row`	`Integer`	目标范围的起始行。
`rowEnd`	`Integer`	目标范围的结束行。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

另请参阅

getGridId()

`copyFormatToRange(sheet, column, columnEnd, row, rowEnd)`

将范围的格式复制到指定位置。如果目标范围大于或小于源范围，则相应地重复或截断源。请注意，此方法仅复制格式。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const source = ss.getSheets()[0];
const destination = ss.getSheets()[1];

const range = source.getRange('B2:D4');

// This copies the formatting in B2:D4 in the source sheet to
// D4:F6 in the second sheet
range.copyFormatToRange(destination, 4, 6, 4, 6);

参数

名称	类型	说明
`sheet`	`Sheet`	目标工作表。
`column`	`Integer`	目标范围的第一列。
`columnEnd`	`Integer`	目标范围的结束列。
`row`	`Integer`	目标范围的起始行。
`rowEnd`	`Integer`	目标范围的结束行。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`copyTo(destination)`

将某个单元格范围内的数据复制到另一个单元格范围。系统会同时复制值和格式。

// The code below copies the first 5 columns over to the 6th column.
const sheet = SpreadsheetApp.getActiveSheet();
const rangeToCopy = sheet.getRange(1, 1, sheet.getMaxRows(), 5);
rangeToCopy.copyTo(sheet.getRange(1, 6));

参数

名称	类型	说明
`destination`	`Range`	要复制到的目标范围；只有左上角的单元格位置相关。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`copyTo(destination, copyPasteType, transposed)`

将某个单元格范围内的数据复制到另一个单元格范围。

// The code below copies only the values of the first 5 columns over to the 6th
// column.
const sheet = SpreadsheetApp.getActiveSheet();
sheet.getRange('A:E').copyTo(
    sheet.getRange('F1'),
    SpreadsheetApp.CopyPasteType.PASTE_VALUES,
    false,
);

参数

名称	类型	说明
`destination`	`Range`	要复制到的目标范围；只有左上角的单元格位置相关。
`copyPasteType`	`CopyPasteType`	一种类型，用于指定如何将范围内容粘贴到目标位置。
`transposed`	`Boolean`	是否应以转置方向粘贴范围。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`copyTo(destination, options)`

将某个单元格范围内的数据复制到另一个单元格范围。默认情况下，系统会同时复制值和格式，但您可以使用高级实参替换此行为。

// The code below copies only the values of the first 5 columns over to the 6th
// column.
const sheet = SpreadsheetApp.getActiveSheet();
sheet.getRange('A:E').copyTo(sheet.getRange('F1'), {contentsOnly: true});

参数

名称	类型	说明
`destination`	`Range`	要复制到的目标范围；只有左上角的单元格位置相关。
`options`	`Object`	一个 JavaScript 对象，用于指定高级参数，如下所列。

高级参数

名称	类型	说明
`formatOnly`	`Boolean`	表示仅应复制格式
`contentsOnly`	`Boolean`	表示仅应复制内容

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`copyValuesToRange(gridId, column, columnEnd, row, rowEnd)`

将范围的内容复制到指定位置。如果目标范围大于或小于源范围，则相应地重复或截断源。

如需详细了解 gridId 参数，请参阅 getGridId()。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const source = ss.getSheets()[0];

const range = source.getRange('B2:D4');

// This copies the data in B2:D4 in the source sheet to
// D4:F6 in the sheet with gridId 0
range.copyValuesToRange(0, 4, 6, 4, 6);

参数

名称	类型	说明
`gridId`	`Integer`	电子表格中工作表的唯一 ID，与位置无关。
`column`	`Integer`	目标范围的第一列。
`columnEnd`	`Integer`	目标范围的结束列。
`row`	`Integer`	目标范围的起始行。
`rowEnd`	`Integer`	目标范围的结束行。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

另请参阅

getGridId()

`copyValuesToRange(sheet, column, columnEnd, row, rowEnd)`

将范围的内容复制到指定位置。如果目标范围大于或小于源范围，则相应地重复或截断源。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const source = ss.getSheets()[0];
const destination = ss.getSheets()[1];

const range = source.getRange('B2:D4');

// This copies the data in B2:D4 in the source sheet to
// D4:F6 in the second sheet
range.copyValuesToRange(destination, 4, 6, 4, 6);

参数

名称	类型	说明
`sheet`	`Sheet`	目标工作表。
`column`	`Integer`	目标范围的第一列。
`columnEnd`	`Integer`	目标范围的结束列。
`row`	`Integer`	目标范围的起始行。
`rowEnd`	`Integer`	目标范围的结束行。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`createDataSourcePivotTable(dataSource)`

根据数据源创建一个空的数据源透视表，该透视表锚定在此范围内的第一个单元格中。

此示例展示了如何创建和配置新的数据源数据透视表。

const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
const anchorCell = spreadsheet.getSheets()[0].getRange('A1');
const dataSource = spreadsheet.getDataSources()[0];

const pivotTable = anchorCell.createDataSourcePivotTable(dataSource);
pivotTable.addRowGroup('dataColumnA');
pivotTable.addColumnGroup('dataColumnB');
pivotTable.addPivotValue(
    'dataColumnC',
    SpreadsheetApp.PivotTableSummarizeFunction.SUM,
);
pivotTable.addFilter(
    'dataColumnA',
    SpreadsheetApp.newFilterCriteria().whenTextStartsWith('A').build(),
);

参数

名称	类型	说明
`dataSource`	`DataSource`	用于创建数据透视表的数据源。

DataSourcePivotTable - 新创建的数据源数据透视表。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`createDataSourceTable(dataSource)`

根据数据源创建一个空的数据源表，该表锚定在相应范围内的第一个单元格中。

此示例展示了如何创建和配置新的数据源表。

const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
const anchorCell = spreadsheet.getSheets()[0].getRange('A1');
const dataSource = spreadsheet.getDataSources()[0];

const dataSourceTable =
    anchorCell.createDataSourceTable(dataSource)
        .addColumns('dataColumnA', 'dataColumnB', 'dataColumnC')
        .addSortSpec('dataColumnA', true)    // ascending=true
        .addSortSpec('dataColumnB', false);  // ascending=false

参数

名称	类型	说明
`dataSource`	`DataSource`	用于创建数据透视表的数据源。

DataSourceTable - 新创建的数据源表。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`createDeveloperMetadataFinder()`

返回一个 DeveloperMetadataFinderApi，用于查找此范围内的开发者元数据。只有当元数据完全包含在相应范围内时，才属于该范围。例如，与行“3:3”关联的元数据不在范围“A1:D5”的范围内，但位于范围“1:5”的范围内。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:C6.
const range = sheet.getRange('A1:C6');

// Creates a developer metadata finder to search for metadata in the scope of
// this range.
const developerMetaDataFinder = range.createDeveloperMetadataFinder();

// Logs information about the developer metadata finder to the console.
const developerMetaData = developerMetaDataFinder.find()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getValue());
console.log(developerMetaData.getVisibility().toString());

DeveloperMetadataFinder - 用于在此范围的范围内搜索元数据的开发者元数据查找器。

`createFilter()`

创建过滤器并将其应用于工作表中的指定范围。您无法在工作表中创建多个过滤条件。如需在创建过滤条件后访问和修改该过滤条件，请使用 getFilter() 或 Sheet.getFilter()。

const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');

// Creates a new filter and applies it to the range A1:C20 on the active sheet.
function createFilter() {
  range.createFilter();
}
// Gets the filter and applies criteria that only shows cells that aren't empty.
function getFilterAddCriteria() {
  const filter = range.getFilter();
  const criteria =
      SpreadsheetApp.newFilterCriteria().whenCellNotEmpty().build();
  filter.setColumnFilterCriteria(2, criteria);
}

使用此方法可为 Grid 工作表（默认工作表类型）创建过滤条件。网格工作表是指未连接到数据库的工作表。如需创建其他类型的过滤条件，请参阅以下内容：

使用 PivotTable.addFilter(sourceDataColumn, filterCriteria) 创建数据透视表过滤条件
为与数据库关联的工作表创建过滤条件，其中包含 DataSourceSheet.addFilter(columnName, filterCriteria)
为连接到 DataSourcePivotTable.addFilter(columnName, filterCriteria) 的数据库的数据透视表创建过滤条件

Filter - 新过滤条件。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`createPivotTable(sourceData)`

根据指定的 sourceData 创建一个空数据透视表，该数据透视表锚定在此范围内的第一个单元格中。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets cell A1 as a range in order to place the pivot table.
const range = sheet.getRange('A1');

// Gets the range of the source data for the pivot table.
const dataRange = sheet.getRange('E12:G20');

// Creates an empty pivot table from the specified source data.
const pivotTable = range.createPivotTable(dataRange);

// Logs the values from the pivot table's source data to the console.
console.log(pivotTable.getSourceDataRange().getValues());

参数

名称	类型	说明
`sourceData`	`Range`	用于创建数据透视表的数据。

PivotTable - 新创建的 PivotTable。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`createTextFinder(findText)`

为指定范围创建文本查找器，该查找器可查找和替换此范围内的文本。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getActiveRange();

// Creates  a text finder for the range.
const textFinder = range.createTextFinder('dog');

// Returns the first occurrence of 'dog'.
const firstOccurrence = textFinder.findNext();

// Replaces the last found occurrence of 'dog' with 'cat' and returns the number
// of occurrences replaced.
const numOccurrencesReplaced = textFinder.replaceWith('cat');

参数

名称	类型	说明
`findText`	`String`	要搜索的文本。

TextFinder - 相应范围的 TextFinder

`deleteCells(shiftDimension)`

删除相应范围的单元格。工作表中沿所提供维度的现有数据会向已删除的范围移动。

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

const range = sheet.getRange('A1:D10');
range.deleteCells(SpreadsheetApp.Dimension.COLUMNS);

参数

名称	类型	说明
`shiftDimension`	`Dimension`	用于平移现有数据的维度。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`expandGroups()`

展开范围或控制切换开关与此范围相交的已收起组。控制切换开关位置是指显示控制切换开关的索引，具体是在群组之前还是之后显示取决于设置。如果同一位置有多个群组，则展开最浅的群组。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getActiveRange();

// All row and column groups within the range are expanded.
range.expandGroups();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getA1Notation()`

以 A1 符号表示法返回范围的字符串说明。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange(1, 1, 2, 5);

// Logs "A1:E2"
Logger.log(range.getA1Notation());

String - 以 A1 表示法表示的范围的字符串说明。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getBackground()`

返回范围（例如 '#ffffff'）中左上角单元格的背景颜色。

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

const cell = sheet.getRange('B5');
Logger.log(cell.getBackground());

String - 背景的颜色代码。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getBackgroundObject()`

返回指定范围内左上角单元格的背景颜色。

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

const cell = sheet.getRange('B5');
Logger.log(cell.getBackgroundObject().asRgbColor().asHexString());

Color - 范围左上角单元格的背景颜色。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getBackgroundObjects()`

返回指定范围内单元格的背景颜色。

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

const range = sheet.getRange('B5:C6');
const bgColors = range.getBackgroundObjects();
for (const i in bgColors) {
  for (const j in bgColors[i]) {
    Logger.log(bgColors[i][j].asRgbColor().asHexString());
  }
}

Color[][] - 一个二维背景颜色数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getBackgrounds()`

返回指定范围内单元格的背景颜色（例如 '#ffffff'）。

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

const range = sheet.getRange('B5:C6');
const bgColors = range.getBackgrounds();
for (const i in bgColors) {
  for (const j in bgColors[i]) {
    Logger.log(bgColors[i][j]);
  }
}

String[][] - 背景颜色代码的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getBandings()`

返回应用于相应范围内任何单元格的所有条带。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Sets a range.
const range = sheet.getRange('A1:K50');

// Gets the banding info for the range.
const bandings = range.getBandings();

// Logs the second row color for each banding to the console.
for (const banding of bandings) {
  console.log(banding.getSecondRowColor());
}

Banding[] - 应用于此范围内任何单元格的所有条带。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getCell(row, column)`

返回指定范围内的指定单元格。

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

const range = sheet.getRange('B2:D4');

// The row and column here are relative to the range
// getCell(1,1) in this code returns the cell at B2
const cell = range.getCell(1, 1);
Logger.log(cell.getValue());

参数

名称	类型	说明
`row`	`Integer`	单元格相对于范围的行。
`column`	`Integer`	单元格相对于范围的列。

Range - 包含指定坐标处单个单元格的范围。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getColumn()`

返回相应范围的起始列位置。

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

const range = sheet.getRange('B2:D4');
// Logs "2.0"
Logger.log(range.getColumn());

Integer - 电子表格中范围的起始列位置。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDataRegion()`

返回在四个基本方向上扩展的范围的副本，以覆盖所有包含数据的相邻单元格。Direction如果该范围被空单元格包围（不包括对角线上的空单元格），则返回该范围本身。这类似于在编辑器中选择范围并输入 Ctrl+A。

// Assume the active spreadsheet is blank.
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
sheet.getRange('C2').setValue(100);
sheet.getRange('B3').setValue(100);
sheet.getRange('D3').setValue(100);
sheet.getRange('C4').setValue(100);
// Logs "B2:D4"
Logger.log(sheet.getRange('C3').getDataRegion().getA1Notation());

Range - 范围的数据区域或整个电子表格的范围。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDataRegion(dimension)`

如果指定维度为 Dimension.ROWS，则返回扩展后的范围（Direction.UP 和 Direction.DOWN）；如果维度为 Dimension.COLUMNS，则返回扩展后的范围（Direction.NEXT 和 Direction.PREVIOUS）。范围的扩展基于对范围旁边以表格形式整理的数据的检测。扩展范围涵盖指定维度上所有包含数据的相邻单元格，包括表格边界。如果原始范围沿指定维度被空单元格包围，则返回该范围本身。此方法类似于在编辑器中选择范围并为列输入 Ctrl+Space 或为行输入 Shift+Space。

// Assume the active spreadsheet is blank.
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
sheet.getRange('C2').setValue(100);
sheet.getRange('B3').setValue(100);
sheet.getRange('D3').setValue(100);
sheet.getRange('C4').setValue(100);
// Logs "C2:C4"
Logger.log(
    sheet.getRange('C3')
        .getDataRegion(SpreadsheetApp.Dimension.ROWS)
        .getA1Notation(),
);
// Logs "B3:D3"
Logger.log(
    sheet.getRange('C3')
        .getDataRegion(SpreadsheetApp.Dimension.COLUMNS)
        .getA1Notation(),
);

参数

名称	类型	说明
`dimension`	`Dimension`	要沿哪个维度扩展范围。

Range - 范围的数据区域，或涵盖原始范围所跨越的每个列或每个行的范围。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDataSourceFormula()`

返回范围中第一个单元格的 DataSourceFormula，如果该单元格不包含数据源公式，则返回 null。

// Opens the spreadsheet file by its ID. If you created your script from a
// Google Sheets file, use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1 on Sheet1.
const range = sheet.getRange('A1');

// Gets the data source formula from cell A1.
const dataSourceFormula = range.getDataSourceFormula();

// Gets the formula.
const formula = dataSourceFormula.getFormula();

// Logs the formula.
console.log(formula);

DataSourceFormula - 相应单元格的 DataSourceFormula。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDataSourceFormulas()`

返回相应范围内单元格的 DataSourceFormula。

// Opens the spreadsheet file by its ID. If you created your script from a
// Google Sheets file, use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:B5 on Sheet1.
const range = sheet.getRange('A1:B5');

// Gets an array of the data source formulas in the range A1:B5.
const dataSourceFormulas = range.getDataSourceFormulas();

// Logs the first formula in the array.
console.log(dataSourceFormulas[0].getFormula());

DataSourceFormula[] - DataSourceFormula 的数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDataSourcePivotTables()`

获取与指定范围相交的所有数据源数据透视表。

// Opens the spreadsheet file by its ID. If you created your script from a
// Google Sheets file, use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:G50 on Sheet1.
const range = sheet.getRange('A1:G50');

// Gets an array of the data source pivot tables in the range A1:G50.
const dataSourcePivotTables = range.getDataSourcePivotTables();

// Logs the last time that the first pivot table in the array was refreshed.
console.log(dataSourcePivotTables[0].getStatus().getLastRefreshedTime());

DataSourcePivotTable[] - 数据源数据透视表的列表。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDataSourceTables()`

获取与指定范围相交的所有数据源表。

// Opens the spreadsheet file by its ID. If you created your script from a
// Google Sheets file, use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:G50 on Sheet1.
const range = sheet.getRange('A1:G50');

// Gets the first data source table in the range A1:G50.
const dataSourceTable = range.getDataSourceTables()[0];

// Logs the time of the last completed data execution on the data source table.
console.log(dataSourceTable.getStatus().getLastExecutionTime());

DataSourceTable[] - 数据源表的列表。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDataSourceUrl()`

返回相应范围内数据的网址，该网址可用于创建图表和查询。

Code.gs

function doGet() {
  const ss = SpreadsheetApp.openById(
      '1khO6hBWTNNyvyyxvob7aoZTI9ZvlqqASNeq0e29Tw2c',
  );
  const sheet = ss.getSheetByName('ContinentData');
  const range = sheet.getRange('A1:B8');

  const template = HtmlService.createTemplateFromFile('piechart');
  template.dataSourceUrl = range.getDataSourceUrl();
  return template.evaluate();
}

piechart.html

<!DOCTYPE html>
<html>
  <head>
    <!--Load the AJAX API-->
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript">
      // Load the Visualization API and the corechart package.
      google.charts.load('current', {'packages': ['corechart']});

      // Set a callback to run when the Google Visualization API is loaded.
      google.charts.setOnLoadCallback(queryData);

      function queryData() {
        var query = new google.visualization.Query('<?= dataSourceUrl ?>');
        query.send(drawChart);
      }

      // Callback that creates and populates a data table,
      // instantiates the pie chart, passes in the data and
      // draws it.
      function drawChart(response) {
        if (response.isError()) {
          alert('Error: ' + response.getMessage() + ' ' + response.getDetailedMessage());
          return;
        }
        var data = response.getDataTable();

        // Set chart options.
        var options = {
          title: 'Population by Continent',
          width: 400,
          height: 300
        };

        // Instantiate and draw the chart, passing in some options.
        var chart = new google.visualization.PieChart(document.getElementById('chart_div'));
        chart.draw(data, options);
      }
    </script>
  </head>
  <body>
    <!-- Div that holds the pie chart. -->
    <div id="chart_div"></div>
  </body>
</html>

String - 此范围的网址，可作为数据源传递给其他 API（例如图表）。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDataTable()`

以 DataTable 形式返回此对象内的数据。

// Opens the spreadsheet file by its ID. If you created your script from a
// Google Sheets file, use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:B7 on Sheet1.
const range = sheet.getRange('A1:B7');

// Gets the range A1:B7 as a data table. The values in each column must be of
// the same type.
const datatable = range.getDataTable();

// Uses the Charts service to build a bar chart from the data table.
// This doesn't build an embedded chart. To do that, use
// sheet.newChart().addRange() instead.
const chart = Charts.newBarChart()
                  .setDataTable(datatable)
                  .setOption('title', 'Your Chart Title Here')
                  .build();

DataTable - 以数据表形式呈现的数据。

`getDataTable(firstRowIsHeader)`

返回此范围内的相应数据，以 DataTable 形式呈现。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:B7');

// Calling this method with "true" sets the first line to be the title of the
// axes
const datatable = range.getDataTable(true);

// Note that this doesn't build an EmbeddedChart, so you can't just use
// Sheet#insertChart(). To do that, use sheet.newChart().addRange() instead.
const chart = Charts.newBarChart()
                  .setDataTable(datatable)
                  .setOption('title', 'Your Title Here')
                  .build();

参数

名称	类型	说明
`firstRowIsHeader`	`Boolean`	是否将第一行视为标题。

DataTable - 以数据表形式呈现的数据。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDataValidation()`

返回范围左上角单元格的数据验证规则。如果未对单元格设置数据验证，此方法会返回 null。

// Log information about the data validation rule for cell A1.
const cell = SpreadsheetApp.getActive().getRange('A1');
const rule = cell.getDataValidation();
if (rule != null) {
  const criteria = rule.getCriteriaType();
  const args = rule.getCriteriaValues();
  Logger.log('The data validation rule is %s %s', criteria, args);
} else {
  Logger.log('The cell does not have a data validation rule.');
}

DataValidation - 范围中左上角单元格的数据验证规则。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDataValidations()`

返回指定范围内所有单元格的数据验证规则。如果未对指定单元格设置数据验证，此方法会针对该单元格在数组中的位置返回 null。

// Change existing data validation rules that require a date in 2013 to require
// a date in 2014.
const oldDates = [new Date('1/1/2013'), new Date('12/31/2013')];
const newDates = [new Date('1/1/2014'), new Date('12/31/2014')];
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange(1, 1, sheet.getMaxRows(), sheet.getMaxColumns());
const rules = range.getDataValidations();

for (let i = 0; i < rules.length; i++) {
  for (let j = 0; j < rules[i].length; j++) {
    const rule = rules[i][j];

    if (rule != null) {
      const criteria = rule.getCriteriaType();
      const args = rule.getCriteriaValues();

      if (criteria === SpreadsheetApp.DataValidationCriteria.DATE_BETWEEN &&
          args[0].getTime() === oldDates[0].getTime() &&
          args[1].getTime() === oldDates[1].getTime()) {
        // Create a builder from the existing rule, then change the dates.
        rules[i][j] = rule.copy().withCriteria(criteria, newDates).build();
      }
    }
  }
}
range.setDataValidations(rules);

DataValidation[][] - 与范围内的单元格关联的数据验证规则的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDeveloperMetadata()`

获取与此范围关联的开发者元数据。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on Sheet1.
const range = sheet.getRange('2:2');

// Adds metadata to row 2.
range.addDeveloperMetadata('NAME', 'GOOGLE');

// Logs the metadata to console.
for (const metadata of range.getDeveloperMetadata()) {
  console.log(`${metadata.getKey()}: ${metadata.getValue()}`);
}

DeveloperMetadata[] - 与此范围关联的开发者元数据。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDisplayValue()`

返回范围中左上角单元格的显示值。该值为 String。显示的值会考虑日期、时间和币种格式，包括电子表格的语言区域设置自动应用的格式。空单元格会返回空字符串。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets cell A30 and sets its value to 'Test code.'
const cell = sheet.getRange('A30');
cell.setValue('Test code');

// Gets the value and logs it to the console.
console.log(cell.getDisplayValue());

String - 此单元格中显示的值。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getDisplayValues()`

返回相应范围的值的矩形网格。

返回一个显示值的二维数组，按行和列进行索引。这些值是 String 对象。显示的值会考虑日期、时间和币种格式，包括电子表格的语言区域设置自动应用的格式。空单元格在数组中以空字符串表示。请注意，虽然范围索引从 1, 1 开始，但 JavaScript 数组的索引从 [0][0] 开始。

// The code below gets the displayed values for the range C2:G8
// in the active spreadsheet.  Note that this is a JavaScript array.
const values =
    SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getDisplayValues();
Logger.log(values[0][0]);

String[][] - 值的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFilter()`

返回相应范围所属工作表的过滤器；如果工作表上没有过滤器，则返回 null。

const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
// Gets the existing filter on the sheet that the given range belongs to.
const filter = range.getFilter();

Filter - 过滤条件。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontColorObject()`

返回范围左上角单元格的字体颜色。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.getFontColorObject().asRgbColor().asHexString());

Color - 范围左上角单元格的字体颜色。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontColorObjects()`

返回指定范围内单元格的字体颜色。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

const results = range.getFontColorObjects();

for (const i in results) {
  for (const j in results[i]) {
    Logger.log(results[i][j].asRgbColor().asHexString());
  }
}

Color[][] - 与指定范围内的单元格关联的字体颜色二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontFamilies()`

返回指定范围内单元格的字体系列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

const results = range.getFontFamilies();

for (const i in results) {
  for (const j in results[i]) {
    Logger.log(results[i][j]);
  }
}

String[][] - 与指定范围内的单元格关联的字体系列的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontFamily()`

返回指定范围左上角单元格的字体系列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.getFontFamily());

String - 相应单元格的字体系列。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontLine()`

获取范围左上角单元格的线条样式（'underline'、'line-through' 或 'none'）。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.getFontLine());

String - 字体行。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontLines()`

获取相应范围内单元格的线条样式（'underline'、'line-through' 或 'none'）。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

const results = range.getFontLines();

for (const i in results) {
  for (const j in results[i]) {
    Logger.log(results[i][j]);
  }
}

String[][] - 与范围内的单元格关联的字体线条的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontSize()`

返回范围左上角单元格的字体大小（以磅为单位）。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.getFontSize());

Integer - 字号（以磅为单位）。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontSizes()`

返回指定范围内单元格的字号。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

const results = range.getFontSizes();

for (const i in results) {
  for (const j in results[i]) {
    Logger.log(results[i][j]);
  }
}

Integer[][] - 与范围内的单元格关联的文本的字体大小的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontStyle()`

返回范围左上角单元格的字体样式（'italic' 或 'normal'）。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.getFontStyle());

String - 单元格中文字的字体样式。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontStyles()`

返回指定范围内单元格的字体样式。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

const results = range.getFontStyles();

for (const i in results) {
  for (const j in results[i]) {
    Logger.log(results[i][j]);
  }
}

String[][] - 与指定范围内的单元格关联的文本的字体样式的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontWeight()`

返回范围左上角单元格的字重（正常/粗体）。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.getFontWeight());

String - 单元格中文字的字体粗细。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontWeights()`

返回指定范围内单元格的字重。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

const results = range.getFontWeights();

for (const i in results) {
  for (const j in results[i]) {
    Logger.log(results[i][j]);
  }
}

String[][] - 与指定范围内的单元格关联的文本的字体粗细二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFormula()`

返回范围左上角单元格的公式（A1 符号），如果单元格为空或不包含公式，则返回空字符串。

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

// This assumes you have a function in B5 that sums up
// B2:B4
const range = sheet.getRange('B5');

// Logs the calculated value and the formula
Logger.log(
    'Calculated value: %s Formula: %s',
    range.getValue(),
    range.getFormula(),
);

String - 相应单元格的公式。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFormulaR1C1()`

返回指定单元格的公式（R1C1 表示法），如果没有公式，则返回 null。

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

const range = sheet.getRange('B5');
const formula = range.getFormulaR1C1();
Logger.log(formula);

String - R1C1 表示法中的公式。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFormulas()`

返回相应范围内单元格的公式（A1 符号）。对于不含公式的单元格，二维数组中的条目为空字符串。

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

const range = sheet.getRange('B5:C6');
const formulas = range.getFormulas();
for (const i in formulas) {
  for (const j in formulas[i]) {
    Logger.log(formulas[i][j]);
  }
}

String[][] - 字符串格式的公式二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFormulasR1C1()`

返回相应范围内单元格的公式（R1C1 表示法）。二维数组中的条目对于不含公式的单元格为 null。

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

const range = sheet.getRange('B5:C6');
const formulas = range.getFormulasR1C1();
for (const i in formulas) {
  for (const j in formulas[i]) {
    Logger.log(formulas[i][j]);
  }
}

String[][] - 采用 R1C1 表示法的公式二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getGridId()`

返回相应范围的父工作表的网格 ID。ID 是随机非负整数值。

// Log the grid ID of the first sheet (by tab position) in the spreadsheet.
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.getGridId());

Integer - 父工作表的网格 ID。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getHeight()`

返回范围的高度。

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

const range = sheet.getRange('B2:D4');
// logs 3.0
Logger.log(range.getHeight());

Integer - 范围的高度。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getHorizontalAlignment()`

返回范围左上角单元格中文字的水平对齐方式（左对齐/居中/右对齐）。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.getHorizontalAlignment());

String - 单元格中文字的水平对齐方式。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getHorizontalAlignments()`

返回指定范围内单元格的水平对齐方式。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

const results = range.getHorizontalAlignments();

for (const i in results) {
  for (const j in results[i]) {
    Logger.log(results[i][j]);
  }
}

String[][] - 与范围内的单元格关联的文本的水平对齐方式的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getLastColumn()`

返回结束列位置。

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

const range = sheet.getRange('B2:D4');
// Logs "4.0"
Logger.log(range.getLastColumn());

Integer - 电子表格中范围的结束列位置。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getLastRow()`

返回结束行位置。

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

const range = sheet.getRange('B2:D4');
// Logs "4.0"
Logger.log(range.getLastRow());

Integer - 电子表格中范围的结束行位置。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getMergedRanges()`

返回一个 Range 对象数组，表示完全位于当前范围内的合并单元格，或包含当前范围内的至少一个单元格。

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

const range = sheet.getRange('A1:B3');

const mergedRanges = range.getMergedRanges();
for (let i = 0; i < mergedRanges.length; i++) {
  Logger.log(mergedRanges[i].getA1Notation());
  Logger.log(mergedRanges[i].getDisplayValue());
}

Range[] - 一个 Range 对象数组，表示与相应范围重叠的合并单元格。

`getNextDataCell(direction)`

从范围的第一列和第一行中的单元格开始，返回指定方向上的下一个单元格，该单元格是包含数据的连续单元格范围的边缘，或者是该方向上工作表的边缘单元格。这相当于在编辑器中输入 Ctrl+[arrow key]。

// Assume the active spreadsheet is blank.
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

const range = sheet.getRange('C3:E5');
// Logs "C1"
Logger.log(range.getNextDataCell(SpreadsheetApp.Direction.UP).getA1Notation());

参数

名称	类型	说明
`direction`	`Direction`	查找下一个数据区域边缘单元格的方向。

Range - 数据区域边缘的单元格或电子表格边缘的单元格。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getNote()`

返回与指定范围关联的注释。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.getNote());

String - 与指定单元格关联的注释。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getNotes()`

返回与指定范围内的单元格关联的备注。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

const results = range.getNotes();

for (const i in results) {
  for (const j in results[i]) {
    Logger.log(results[i][j]);
  }
}

String[][] - 与范围内的单元格关联的注释的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getNumColumns()`

返回相应范围内的列数。

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

const range = sheet.getRange('B2:D5');
Logger.log(range.getNumColumns());

Integer - 此范围内的列数。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getNumRows()`

返回相应范围内的行数。

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

const range = sheet.getRange('B2:D5');
Logger.log(range.getNumRows());

Integer - 此范围内的行数。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getNumberFormat()`

获取指定范围左上角单元格的数字或日期格式。返回的格式模式在 Sheets API 文档中进行了说明。

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

const cell = sheet.getRange('C4');
Logger.log(cell.getNumberFormat());

String - 范围左上角单元格的数字格式。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getNumberFormats()`

返回指定范围内单元格的数字或日期格式。Google 表格 API 文档中介绍了返回的格式模式。

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

const range = sheet.getRange('B5:C6');
const formats = range.getNumberFormats();
for (const i in formats) {
  for (const j in formats[i]) {
    Logger.log(formats[i][j]);
  }
}

String[][] - 数字格式的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getRichTextValue()`

返回范围左上角单元格的富文本值，如果单元格值不是文本，则返回 null。

// Gets the Rich Text value of cell D4.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('D4:F6');
const richText = range.getRichTextValue();
console.log(richText.getText());

RichTextValue - 相应范围内左上角单元格的富文本值；如果单元格值不是文本，则为 null。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getRichTextValues()`

返回指定范围内单元格的富文本值。

// Gets the Rich Text values for all cells in range B5:C6
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B5:C6');
const values = range.getRichTextValues();

for (let i = 0; i < values.length; i++) {
  for (let j = 0; j < values[i].length; j++) {
    console.log(values[i][j].getText());
  }
}

RichTextValue[][] - 富文本值的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getRow()`

返回相应范围的行位置。与 getRowIndex() 相同。

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

const range = sheet.getRange('B2');
Logger.log(range.getRow());

Integer - 范围的行位置。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getRowIndex()`

返回相应范围的行位置。与 getRow() 相同。

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

const range = sheet.getRange('B2');
Logger.log(range.getRowIndex());

Integer - 范围的行位置。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

另请参阅

getRow()

`getSheet()`

返回相应范围所属的工作表。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Gets the sheet that the range belongs to.
const rangeSheet = range.getSheet();

// Gets the sheet name and logs it to the console.
console.log(rangeSheet.getName());

Sheet - 相应范围所属的工作表。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getTextDirection()`

返回范围左上角单元格的文字方向。如果通过自动检测确定了单元格文本方向，则返回 null。

// Get the text direction of cell B1.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B1:D4');
Logger.log(range.getTextDirection());

TextDirection - 范围中左上角单元格的文字方向。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getTextDirections()`

返回指定范围内单元格的文字方向。二维数组中的条目对于使用自动检测的单元格为 null。

// Get the text directions for all cells in range B5:C6
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B5:C6');
const directions = range.getTextDirections();

for (let i = 0; i < directions.length; i++) {
  for (let j = 0; j < directions[i].length; j++) {
    Logger.log(directions[i][j]);
  }
}

TextDirection[][] - 文本方向的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getTextRotation()`

返回指定范围左上角单元格的文字旋转设置。

// Log the text rotation settings for a cell.
const sheet = SpreadsheetApp.getActiveSheet();

const cell = sheet.getRange('A1');
Logger.log(cell.getTextRotation());

TextRotation - 文字旋转设置。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getTextRotations()`

返回指定范围内单元格的文字旋转设置。

const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B2:D4');

const results = range.getTextRotations();

for (const i in results) {
  for (const j in results[i]) {
    const rotation = results[i][j];
    Logger.log('Cell [%s, %s] has text rotation: %v', i, j, rotation);
  }
}

TextRotation[][] - 与范围内的单元格关联的文本旋转角度的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getTextStyle()`

返回范围左上角单元格的文本样式。

// Get the text style of cell D4.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('D4:F6');
const style = range.getTextStyle();
Logger.log(style);

TextStyle - 范围中左上角单元格的文字样式。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getTextStyles()`

返回指定范围内单元格的文本样式。

// Get the text styles for all cells in range B5:C6
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B5:C6');
const styles = range.getTextStyles();

for (let i = 0; i < styles.length; i++) {
  for (let j = 0; j < styles[i].length; j++) {
    Logger.log(styles[i][j]);
  }
}

TextStyle[][] - 文本样式的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getValue()`

返回范围中左上角单元格的值。该值可以是 Number、Boolean、Date 或 String 类型，具体取决于单元格的值。空单元格会返回空字符串。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Gets the value of the top-left cell in the range and logs it to the console.
console.log(range.getValue());

Object - 相应单元格中的值。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getValues()`

返回相应范围的值的矩形网格。

返回一个二维值数组，按行和列进行索引。这些值可以是 Number、Boolean、Date 或 String 类型，具体取决于单元格的值。空单元格在数组中以空字符串表示。请注意，虽然范围索引从 1, 1 开始，但 JavaScript 数组的索引从 [0][0] 开始。

// The code below gets the values for the range C2:G8
// in the active spreadsheet.  Note that this is a JavaScript array.
const values = SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getValues();
Logger.log(values[0][0]);

在 Web 应用中，Date 值不是合法的参数。如果范围包含具有 Date 值的单元格，则 getValues() 无法向 Web 应用返回数据。而是将从工作表中检索到的所有值转换为受支持的 JavaScript 原语，例如 Number、Boolean 或 String。

Object[][] - 值的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getVerticalAlignment()`

返回范围左上角单元格的垂直对齐方式（顶部/中间/底部）。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.getVerticalAlignment());

String - 单元格中文字的垂直对齐方式。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getVerticalAlignments()`

返回指定范围内单元格的垂直对齐方式。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

const results = range.getVerticalAlignments();

for (const i in results) {
  for (const j in results[i]) {
    Logger.log(results[i][j]);
  }
}

String[][] - 与范围中单元格关联的文本的垂直对齐方式的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getWidth()`

返回范围的宽度（以列为单位）。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Gets the width of the range in number of columns and logs it to the console.
console.log(range.getWidth());

Integer - 范围内的列数。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getWrap()`

返回单元格中的文本是否换行。如需获得更精细的封装策略，请使用 getWrapStrategy()。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.getWrap());

Boolean - 此单元格中的文本是否换行。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getWrapStrategies()`

返回指定范围内单元格的文字换行策略。

// Get the text wrapping strategies for all cells in range B5:C6
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B5:C6');
const strategies = range.getWrapStrategies();

for (let i = 0; i < strategies.length; i++) {
  for (let j = 0; j < strategies[i].length; j++) {
    Logger.log(strategies[i][j]);
  }
}

WrapStrategy[][] - 文本换行策略的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getWrapStrategy()`

返回范围左上角单元格的文字换行策略。

// Get the text wrapping strategy of cell B1.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B1:D4');
Logger.log(range.getWrapStrategy());

WrapStrategy - 范围中左上角单元格的文字换行策略。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getWraps()`

返回单元格中的文本是否换行。如需获得更精细的封装策略，请使用 getWrapStrategies()。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

const results = range.getVerticalAlignments();

for (const i in results) {
  for (const j in results[i]) {
    const isWrapped = results[i][j];
    if (isWrapped) {
      Logger.log('Cell [%s, %s] has wrapped text', i, j);
    }
  }
}

Boolean[][] - 与范围中单元格关联的文本的垂直对齐方式的二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`insertCells(shiftDimension)`

在此范围内插入空单元格。新单元格会保留之前占据此范围的单元格中的所有格式。工作表中沿所提供维度的现有数据会从插入的范围移开。

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

const range = sheet.getRange('A1:D10');
range.insertCells(SpreadsheetApp.Dimension.COLUMNS);

参数

名称	类型	说明
`shiftDimension`	`Dimension`	用于平移现有数据的维度。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`insertCheckboxes()`

在范围内的每个单元格中插入复选框，并配置勾选和未勾选状态分别对应的 true 和 false。将相应范围内所有单元格的值设置为 false。

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

// Inserts checkboxes into each cell in the range A1:B10 configured with 'true'
// for checked and 'false' for unchecked. Also, sets the value of each cell in
// the range A1:B10 to 'false'.
range.insertCheckboxes();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`insertCheckboxes(checkedValue)`

在范围内的每个单元格中插入复选框，并为勾选状态配置自定义值，为未勾选状态配置空字符串。将范围中每个单元格的值设置为空字符串。

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

// Inserts checkboxes into each cell in the range A1:B10 configured with 'yes'
// for checked and the empty string for unchecked. Also, sets the value of each
// cell in the range A1:B10 to
//  the empty string.
range.insertCheckboxes('yes');

参数

名称	类型	说明
`checkedValue`	`Object`	复选框数据验证的选中值。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`insertCheckboxes(checkedValue, uncheckedValue)`

在范围内的每个单元格中插入复选框，并为勾选和未勾选状态配置自定义值。将范围中每个单元格的值设置为自定义未选中值。

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

// Inserts checkboxes into each cell in the range A1:B10 configured with 'yes'
// for checked and 'no' for unchecked. Also, sets the value of each cell in the
// range A1:B10 to 'no'.
range.insertCheckboxes('yes', 'no');

参数

名称	类型	说明
`checkedValue`	`Object`	复选框数据验证的选中值。
`uncheckedValue`	`Object`	复选框数据验证的未选中值。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`isBlank()`

如果范围完全空白，则返回 true。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.isBlank());

Boolean - 如果范围为空，则为 true；否则为 false。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`isChecked()`

返回范围内的所有单元格的复选框状态是否均为“已选中”。如果部分单元格处于选中状态，其余单元格处于未选中状态，或者部分单元格没有复选框数据验证，则返回 null。

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

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

const range1 = SpreadsheetApp.getActive().getRange('A1');
range1.setValue('yes');
// Sets the value of isRange1Checked as true as it contains the checked value.
const isRange1Checked = range1.isChecked();

const range2 = SpreadsheetApp.getActive().getRange('A2');
range2.setValue('no');
// Sets the value of isRange2Checked as false as it contains the unchecked
// value.
const isRange2Checked = range2.isChecked();

const range3 = SpreadsheetApp.getActive().getRange('A3');
range3.setValue('random');
// Sets the value of isRange3Checked as null, as it contains an invalid checkbox
// value.
const isRange3Checked = range3.isChecked();

Boolean - true，如果范围内的所有单元格都已选中，则为 false；如果范围内的所有单元格都未选中，则为 null；如果有任何单元格未选中或没有复选框数据验证，则为 null。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`isEndColumnBounded()`

确定范围的末尾是否绑定到特定列。例如，对于绑定到范围末尾列的范围 A1:B10 或 B:B，此方法会返回 true；对于仅绑定到范围末尾特定行的范围 3:7 或 A1:5，此方法会返回 false。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Determines if the end of the range is bound to a particular column and logs
// it to the console.
console.log(range.isEndColumnBounded());

Boolean - 如果范围的末尾绑定到特定列，则为 true；否则为 false。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`isEndRowBounded()`

确定范围的末尾是否绑定到特定行。例如，对于绑定到范围末尾的行的范围 A1:B10 或 3:7，此方法返回 true；对于仅绑定到范围末尾的特定列的范围 B:B 或 A1:C，此方法返回 false。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Determines if the end of the range is bound to a particular row and logs it
// to the console.
console.log(range.isEndRowBounded());

Boolean - 如果范围的末尾绑定到特定行；否则为 true。false

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`isPartOfMerge()`

如果当前范围内的单元格与任何合并的单元格重叠，则返回 true。

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

const range = sheet.getRange('A1:B3');

// True if any of the cells in A1:B3 is included in a merge.
const isPartOfMerge = range.isPartOfMerge();

Boolean - 如果范围与任何合并的单元格重叠，则为 true，否则为 false。

`isStartColumnBounded()`

确定范围的开头是否绑定到特定列。例如，对于绑定到范围开头列的范围 A1:B10 或 B:B，此方法会返回 true；对于仅绑定到范围开头行的范围 3:7，此方法会返回 false。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Determines if the start of the range is bound to a particular column and logs
// it to the console.
console.log(range.isStartColumnBounded());

Boolean - 如果范围的开头绑定到特定列；否则为 true。false

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`isStartRowBounded()`

确定范围的开头是否绑定到特定行。例如，对于绑定到范围开头的行的范围 A1:B10 或 3:7，此方法会返回 true；对于仅绑定到范围开头特定列的范围 B:B，此方法会返回 false。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');

// Determines if the start of the range is bound to a particular row and logs it
// to the console.
console.log(range.isStartRowBounded());

Boolean - 如果范围的开头绑定到特定行，则为 true；否则为 false。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`merge()`

将范围内的单元格合并为一个块。

const sheet = SpreadsheetApp.getActiveSheet();

// The code below 2-dimensionally merges the cells in A1 to B3
sheet.getRange('A1:B3').merge();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`mergeAcross()`

合并范围内的单元格（跨范围内的列）。

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

// The code below merges cells C5:E5 into one cell
const range1 = sheet.getRange('C5:E5');
range1.mergeAcross();

// The code below creates 2 horizontal cells, F5:H5 and F6:H6
const range2 = sheet.getRange('F5:H6');
range2.mergeAcross();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`mergeVertically()`

合并指定范围内的单元格。

const sheet = SpreadsheetApp.getActiveSheet();

// The code below vertically merges the cells in A1 to A10
sheet.getRange('A1:A10').mergeVertically();

// The code below creates 3 merged columns: B1 to B10, C1 to C10, and D1 to D10
sheet.getRange('B1:D10').mergeVertically();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`moveTo(target)`

将此范围内的内容（包括格式和值）剪切并粘贴到目标范围内。

// The code below moves the first 5 columns over to the 6th column
const sheet = SpreadsheetApp.getActiveSheet();
sheet.getRange('A1:E').moveTo(sheet.getRange('F1'));

参数

名称	类型	说明
`target`	`Range`	要将相应范围复制到的目标范围；只有左上角的单元格位置相关。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`offset(rowOffset, columnOffset)`

返回一个新范围，该范围相对于当前范围偏移了指定的行数和列数（可以是负数）。新范围的大小与原始范围的大小相同。

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

const cell = sheet.getRange('A1');

// newCell references B2
const newCell = cell.offset(1, 1);

参数

名称	类型	说明
`rowOffset`	`Integer`	从范围的左上角单元格向下数的行数；负值表示从范围的左上角单元格向上数的行数。
`columnOffset`	`Integer`	范围左上角单元格右侧的列数；负值表示范围左上角单元格左侧的列数。

Range - 此范围，用于链式调用。

`offset(rowOffset, columnOffset, numRows)`

返回一个相对于当前范围的新范围，该范围的左上角点相对于当前范围偏移了给定的行数和列数，并且具有给定的单元格高度。

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

const cell = sheet.getRange('A1');

// newCell references B2:B3
const newRange = cell.offset(1, 1, 2);

参数

名称	类型	说明
`rowOffset`	`Integer`	从范围的左上角单元格向下数的行数；负值表示从范围的左上角单元格向上数的行数。
`columnOffset`	`Integer`	范围左上角单元格右侧的列数；负值表示范围左上角单元格左侧的列数。
`numRows`	`Integer`	新范围的高度（以行数表示）。

Range - 此范围，用于链式调用。

`offset(rowOffset, columnOffset, numRows, numColumns)`

返回一个相对于当前范围的新范围，其左上角点相对于当前范围偏移了指定的行数和列数，并且具有指定的单元格高度和宽度。

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

const cell = sheet.getRange('A1');

// newCell references B2:C3
const newRange = cell.offset(1, 1, 2, 2);

参数

名称	类型	说明
`rowOffset`	`Integer`	从范围的左上角单元格向下数的行数；负值表示从范围的左上角单元格向上数的行数。
`columnOffset`	`Integer`	范围左上角单元格右侧的列数；负值表示范围左上角单元格左侧的列数。
`numRows`	`Integer`	新范围的高度（以行数表示）。
`numColumns`	`Integer`	新范围的列宽度。

Range - 此范围，用于链式调用。

`protect()`

创建一个对象，该对象可以保护范围免遭编辑，但具有权限的用户除外。在脚本实际更改相应范围的编辑者列表之前（通过调用 Protection.removeEditor(emailAddress)、Protection.removeEditor(user)、Protection.removeEditors(emailAddresses)、Protection.addEditor(emailAddress)、Protection.addEditor(user)、Protection.addEditors(emailAddresses) 或为 Protection.setDomainEdit(editable) 设置新值），相应权限与电子表格本身的权限相同，这实际上意味着相应范围仍处于未受保护的状态。如果该范围已受保护，此方法会创建一个与现有受保护范围重叠的新受保护范围。如果某个单元格受多个受保护范围保护，并且其中任何一个受保护范围阻止特定用户修改该单元格，则该用户不得修改该单元格。

// Protect range A1:B10, then remove all other users from the list of editors.
const ss = SpreadsheetApp.getActive();
const range = ss.getRange('A1:B10');
const protection = range.protect().setDescription('Sample protected range');

// Ensure the current user is an editor before removing others. Otherwise, if
// the user's edit permission comes from a group, the script throws an exception
// upon removing the group.
const me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

Protection - 表示保护设置的对象。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`randomize()`

随机化指定范围内的行顺序。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:C7');

// Randomizes the range
range.randomize();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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 range1 = SpreadsheetApp.getActive().getRange('A1');
range1.setValue('yes');
// Removes the checkbox data validation in cell A1 and clears its value.
range1.removeCheckboxes();

const range2 = SpreadsheetApp.getActive().getRange('A2');
range2.setValue('random');
// Removes the checkbox data validation in cell A2 but does not clear its value.
range2.removeCheckboxes();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`removeDuplicates()`

移除此范围内的行，这些行包含的值与任何前一行中的值重复。即使行内的值字母大小写、格式设置、所用公式不一样，但是值相同，则均会被视为重复内容。此方法还会移除视图中隐藏的重复行（例如，因过滤条件而隐藏的行）。此范围之外的内容不会被移除。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B1:D7');

// Remove duplicate rows in the range.
range.removeDuplicates();

Range - 移除重复项后的结果范围。每移除一行，范围的大小就会减少一行。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`removeDuplicates(columnsToCompare)`

移除此范围内的行，这些行在指定列中包含的值与任何前一行中的值重复。即使行内的值字母大小写、格式设置、所用公式不一样，但是值相同，则均会被视为重复内容。此方法还会移除视图中隐藏的重复行（例如，因过滤条件而隐藏的行）。此范围之外的内容不会被移除。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B1:D7');

// Remove rows which have duplicate values in column B.
range.removeDuplicates([2]);

// Remove rows which have duplicate values in both columns B and D.
range.removeDuplicates([2, 4]);

参数

名称	类型	说明
`columnsToCompare`	`Integer[]`	要分析是否存在重复值的列。如果未提供任何列，则系统会分析所有列中是否存在重复项。

Range - 移除重复项后的结果范围。每移除一行，范围的大小就会减少一行。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setBackground(color)`

以 CSS 表示法（例如 '#ffffff' 或 'white'）设置指定范围内所有单元格的背景颜色。

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

const range = sheet.getRange('B2:D5');
range.setBackground('red');

参数

名称	类型	说明
`color`	`String`	采用 CSS 表示法的颜色代码（例如 `'#ffffff'` 或 `'white'`）；`null` 值可重置颜色。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setBackgroundObject(color)`

设置指定范围内所有单元格的背景颜色。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const bgColor = SpreadsheetApp.newColor()
                    .setThemeColor(SpreadsheetApp.ThemeColorType.BACKGROUND)
                    .build();

const range = sheet.getRange('B2:D5');
range.setBackgroundObject(bgColor);

参数

名称	类型	说明
`color`	`Color`	要设置的背景颜色；`null` 值会重置背景颜色。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setBackgroundObjects(color)`

设置背景颜色矩形网格（必须与相应范围的尺寸一致）。

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

const colorAccent1 = SpreadsheetApp.newColor()
                         .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
                         .build();
const colorAccent2 = SpreadsheetApp.newColor()
                         .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
                         .build();
const colorAccent3 = SpreadsheetApp.newColor()
                         .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
                         .build();
const colorAccent4 = SpreadsheetApp.newColor()
                         .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4)
                         .build();

const colors = [
  [colorAccent1, colorAccent2],
  [colorAccent3, colorAccent4],
];

const cell = sheet.getRange('B5:C6');
cell.setBackgroundObjects(colors);

参数

名称	类型	说明
`color`	`Color[][]`	一个二维颜色数组；`null` 值会重置颜色。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setBackgroundRGB(red, green, blue)`

使用 RGB 值（介于 0 到 255 之间的整数，含 0 和 255）将背景设置为指定颜色。

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

const cell = sheet.getRange('B2');

// Sets the background to white
cell.setBackgroundRGB(255, 255, 255);

// Sets the background to red
cell.setBackgroundRGB(255, 0, 0);

参数

名称	类型	说明
`red`	`Integer`	采用 RGB 表示法的红色值。
`green`	`Integer`	采用 RGB 表示法的绿色值。
`blue`	`Integer`	采用 RGB 表示法的蓝色值。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setBackgrounds(color)`

设置矩形网格的背景颜色（必须与相应范围的尺寸一致）。颜色采用 CSS 表示法（例如 '#ffffff' 或 'white'）。

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

const colors = [
  ['red', 'white', 'blue'],
  ['#FF0000', '#FFFFFF', '#0000FF'],  // These are the hex equivalents
];

const cell = sheet.getRange('B5:D6');
cell.setBackgrounds(colors);

参数

名称	类型	说明
`color`	`String[][]`	采用 CSS 表示法的颜色二维数组（例如 `'#ffffff'` 或 `'white'`）；`null` 值会重置颜色。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

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

设置边框属性。有效值为 true（开启）、false（关闭）和 null（无变化）。

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

const cell = sheet.getRange('B2');
// Sets borders on the top and bottom, but leaves the left and right unchanged
cell.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` 表示无变化。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

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

设置具有颜色和/或样式的边框属性。有效值为 true（开启）、false（关闭）和 null（无变化）。对于颜色，请使用 CSS 表示法中的颜色（例如 '#ffffff' 或 'white'）。

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

const cell = sheet.getRange('B2');
// Sets borders on the top and bottom, but leaves the left and right unchanged
// Also sets the color to "red", and the border to "DASHED".
cell.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` 表示默认样式（实线）。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setDataValidation(rule)`

为指定范围内的所有单元格设置一个数据验证规则。

// Set the data validation rule for cell A1 to require a value from B1:B10.
const cell = SpreadsheetApp.getActive().getRange('A1');
const range = SpreadsheetApp.getActive().getRange('B1:B10');
const rule =
    SpreadsheetApp.newDataValidation().requireValueInRange(range).build();
cell.setDataValidation(rule);

参数

名称	类型	说明
`rule`	`DataValidation`	要设置的数据验证规则，或 `null`（用于移除数据验证）。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setDataValidations(rules)`

为范围内的所有单元格设置数据验证规则。此方法采用一个二维数据验证数组，该数组按行和列进行索引。数组维度必须与范围维度相对应。

// Set the data validation rules for Sheet1!A1:B5 to require a value from
// Sheet2!A1:A10.
const destinationRange =
    SpreadsheetApp.getActive().getSheetByName('Sheet1').getRange('A1:B5');
const sourceRange =
    SpreadsheetApp.getActive().getSheetByName('Sheet2').getRange('A1:A10');
const rule =
    SpreadsheetApp.newDataValidation().requireValueInRange(sourceRange).build();
const rules = destinationRange.getDataValidations();
for (let i = 0; i < rules.length; i++) {
  for (let j = 0; j < rules[i].length; j++) {
    rules[i][j] = rule;
  }
}
destinationRange.setDataValidations(rules);

参数

名称	类型	说明
`rules`	`DataValidation[][]`	要设置的数据验证规则的二维数组；值为 `null` 时会移除数据验证。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontColor(color)`

以 CSS 表示法（例如 '#ffffff' 或 'white'）设置字体颜色。

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

const cell = sheet.getRange('B2');
cell.setFontColor('red');

参数

名称	类型	说明
`color`	`String`	采用 CSS 表示法的字体颜色（例如 `'#ffffff'` 或 `'white'`）；`null` 值可重置颜色。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontColorObject(color)`

设置指定范围的字体颜色。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const color = SpreadsheetApp.newColor()
                  .setThemeColor(SpreadsheetApp.ThemeColorType.TEXT)
                  .build();

const cell = sheet.getRange('B2');
cell.setFontColor(color);

参数

名称	类型	说明
`color`	`Color`	要设置的字体颜色；`null` 值会重置颜色。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontColorObjects(colors)`

设置字体颜色的矩形网格（必须与此范围的维度一致）。

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

const colorAccent1 = SpreadsheetApp.newColor()
                         .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
                         .build();
const colorAccent2 = SpreadsheetApp.newColor()
                         .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
                         .build();
const colorAccent3 = SpreadsheetApp.newColor()
                         .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
                         .build();
const colorAccent4 = SpreadsheetApp.newColor()
                         .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4)
                         .build();

const colors = [
  [colorAccent1, colorAccent2],
  [colorAccent3, colorAccent4],
];

const cell = sheet.getRange('B5:C6');
cell.setFontColorObjects(colors);

参数

名称	类型	说明
`colors`	`Color[][]`	一个二维颜色数组；`null` 值会重置字体颜色。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontColors(colors)`

设置字体颜色的矩形网格（必须与此范围的维度一致）。颜色采用 CSS 表示法（例如 '#ffffff' 或 'white'）。

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

const colors = [
  ['red', 'white', 'blue'],
  ['#FF0000', '#FFFFFF', '#0000FF'],  // These are the hex equivalents
];

const cell = sheet.getRange('B5:D6');
cell.setFontColors(colors);

参数

名称	类型	说明
`colors`	`Object[][]`	采用 CSS 表示法的颜色二维数组（例如 `'#ffffff'` 或 `'white'`）；`null` 值会重置颜色。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontFamilies(fontFamilies)`

设置字体系列的矩形网格（必须与此范围的尺寸一致）。字体系列的示例包括“Arial”或“Helvetica”。

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

const fonts = [
  ['Arial', 'Helvetica', 'Verdana'],
  ['Courier New', 'Arial', 'Helvetica'],
];

const cell = sheet.getRange('B2:D3');
cell.setFontFamilies(fonts);

参数

名称	类型	说明
`fontFamilies`	`Object[][]`	字体系列的二维数组；`null` 值会重置字体系列。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontFamily(fontFamily)`

设置字体系列，例如“Arial”或“Helvetica”。

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

const cell = sheet.getRange('B2');
cell.setFontFamily('Helvetica');

参数

名称	类型	说明
`fontFamily`	`String`	要设置的字体系列；值为 `null` 时会重置字体系列。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontLine(fontLine)`

设置指定范围（'underline'、'line-through' 或 'none'）的字体线条样式。

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

const cell = sheet.getRange('B2');
cell.setFontLine('line-through');

参数

名称	类型	说明
`fontLine`	`String`	字体线条样式，可以是 `'underline'`、`'line-through'` 或 `'none'`；值为 `null` 时会重置字体线条样式。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontLines(fontLines)`

设置线样式的矩形网格（必须与相应范围的维度一致）。

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

// The size of the two-dimensional array must match the size of the range.
const fontLines = [['underline', 'line-through', 'none']];

const range = sheet.getRange('B2:D2');
range.setFontLines(fontLines);

参数

名称	类型	说明
`fontLines`	`Object[][]`	字体线条样式的二维数组（`'underline'`、`'line-through'` 或 `'none'`）；`null` 值会重置字体线条样式。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontSize(size)`

设置字体大小，其中大小是要使用的点大小。

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

const cell = sheet.getRange('B2');
cell.setFontSize(20);

参数

名称	类型	说明
`size`	`Integer`	以磅为单位的字号。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontSizes(sizes)`

设置字体大小的矩形网格（必须与此范围的维度一致）。尺寸以磅为单位。

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

// The size of the two-dimensional array must match the size of the range.
const fontSizes = [[16, 20, 24]];

const range = sheet.getRange('B2:D2');
range.setFontSizes(fontSizes);

参数

名称	类型	说明
`sizes`	`Object[][]`	一个二维尺寸数组。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontStyle(fontStyle)`

为指定范围设置字体样式（'italic' 或 'normal'）。

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

const cell = sheet.getRange('B2');
cell.setFontStyle('italic');

参数

名称	类型	说明
`fontStyle`	`String`	字体样式，可以是 `'italic'` 或 `'normal'`；`null` 值会重置字体样式。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontStyles(fontStyles)`

设置字体样式的矩形网格（必须与此范围的维度一致）。

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

// The size of the two-dimensional array must match the size of the range.
const fontStyles = [['italic', 'normal']];

const range = sheet.getRange('B2:C2');
range.setFontStyles(fontStyles);

参数

名称	类型	说明
`fontStyles`	`Object[][]`	字体样式的二维数组，可以是 `'italic'` 或 `'normal'`；`null` 值会重置字体样式。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontWeight(fontWeight)`

为指定范围设置字重（正常/粗体）。

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

const cell = sheet.getRange('B2');
cell.setFontWeight('bold');

参数

名称	类型	说明
`fontWeight`	`String`	字体粗细，可以是 `'bold'` 或 `'normal'`；值为 `null` 时会重置字体粗细。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFontWeights(fontWeights)`

设置字体粗细的矩形网格（必须与此范围的维度一致）。字体粗细的一个示例是“粗体”。

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

// The size of the two-dimensional array must match the size of the range.
const fontStyles = [['bold', 'bold', 'normal']];

const range = sheet.getRange('B2:D2');
range.setFontWeights(fontStyles);

参数

名称	类型	说明
`fontWeights`	`Object[][]`	字体粗细的二维数组，可以是 `'bold'` 或 `'normal'`；`null` 值会重置字体粗细。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFormula(formula)`

更新相应范围的公式。指定的公式必须采用 A1 符号。

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

const cell = sheet.getRange('B5');
cell.setFormula('=SUM(B3:B4)');

参数

名称	类型	说明
`formula`	`String`	表示要为单元格设置的公式的字符串。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFormulaR1C1(formula)`

更新相应范围的公式。给定的公式必须采用 R1C1 标记法。

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

const cell = sheet.getRange('B5');
// This sets the formula to be the sum of the 3 rows above B5
cell.setFormulaR1C1('=SUM(R[-3]C[0]:R[-1]C[0])');

参数

名称	类型	说明
`formula`	`String`	字符串公式。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFormulas(formulas)`

设置公式的矩形网格（必须与此范围的维度一致）。给定的公式必须采用 A1 表示法。此方法接受一个二维公式数组，该数组先按行编制索引，然后再按列编制索引。数组维度必须与范围维度相对应。

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

// This sets the formulas to be a row of sums, followed by a row of averages
// right below. The size of the two-dimensional array must match the size of the
// range.
const formulas = [
  ['=SUM(B2:B4)', '=SUM(C2:C4)', '=SUM(D2:D4)'],
  ['=AVERAGE(B2:B4)', '=AVERAGE(C2:C4)', '=AVERAGE(D2:D4)'],
];

const cell = sheet.getRange('B5:D6');
cell.setFormulas(formulas);

参数

名称	类型	说明
`formulas`	`String[][]`	公式的二维字符串数组。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setFormulasR1C1(formulas)`

设置公式的矩形网格（必须与此范围的维度一致）。给定的公式必须采用 R1C1 标记法。

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

// This creates formulas for a row of sums, followed by a row of averages.
const sumOfRowsAbove = '=SUM(R[-3]C[0]:R[-1]C[0])';
const averageOfRowsAbove = '=AVERAGE(R[-4]C[0]:R[-2]C[0])';

// The size of the two-dimensional array must match the size of the range.
const formulas = [
  [sumOfRowsAbove, sumOfRowsAbove, sumOfRowsAbove],
  [averageOfRowsAbove, averageOfRowsAbove, averageOfRowsAbove],
];

const cell = sheet.getRange('B5:D6');
// This sets the formula to be the sum of the 3 rows above B5.
cell.setFormulasR1C1(formulas);

参数

名称	类型	说明
`formulas`	`String[][]`	采用 R1C1 格式的公式二维数组。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setHorizontalAlignment(alignment)`

为指定范围设置水平（从左到右）对齐方式（左对齐/居中对齐/右对齐）。

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

const cell = sheet.getRange('B2');
cell.setHorizontalAlignment('center');

参数

名称	类型	说明
`alignment`	`String`	对齐方式，可以是 `'left'`、`'center'` 或 `'normal'`；`null` 值会重置对齐方式。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setHorizontalAlignments(alignments)`

设置水平对齐方式的矩形网格。请参阅 setHorizontalAlignment(alignment)

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

// The size of the two-dimensional array must match the size of the range.
const horizontalAlignments = [['left', 'right', 'center']];

const range = sheet.getRange('B2:D2');
range.setHorizontalAlignments(horizontalAlignments);

参数

名称	类型	说明
`alignments`	`Object[][]`	一个二维对齐数组，可以是 `'left'`、`'center'` 或 `'normal'`；`null` 值会重置对齐方式。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

另请参阅

setHorizontalAlignment(alignment)

`setNote(note)`

将备注设置为指定值。

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

const cell = sheet.getRange('B2');
cell.setNote('This is a note');

参数

名称	类型	说明
`note`	`String`	要为范围设置的注释值；值为 `null` 时会移除注释。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setNotes(notes)`

设置一个矩形网格的音符（必须与此范围的维度一致）。

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

// The size of the two-dimensional array must match the size of the range.
const notes = [
  ['it goes', 'like this', 'the fourth, the fifth'],
  ['the minor fall', 'and the', 'major lift'],
];

const cell = sheet.getRange('B2:D3');
cell.setNotes(notes);

参数

名称	类型	说明
`notes`	`Object[][]`	一个二维音符数组；`null` 值表示移除相应音符。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

另请参阅

setNote(note)

`setNumberFormat(numberFormat)`

将数字或日期格式设置为给定的格式字符串。Google Sheets API 文档中介绍了接受的格式模式。

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

const cell = sheet.getRange('B2');
// Always show 3 decimal points
cell.setNumberFormat('0.000');

参数

名称	类型	说明
`numberFormat`	`String`	数字格式字符串。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setNumberFormats(numberFormats)`

设置数字或日期格式的矩形网格（必须与相应范围的维度一致）。这些值是格式模式字符串，如 Sheets API 文档中所述。

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

// The size of the two-dimensional array must match the size of the range.
const formats = [['0.000', '0,000,000', '$0.00']];

const range = sheet.getRange('B2:D2');
range.setNumberFormats(formats);

参数

名称	类型	说明
`numberFormats`	`Object[][]`	数字格式的二维数组。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setRichTextValue(value)`

为指定范围内的单元格设置富文本值。

// Sets all cells in range B2:D4 to have the text "Hello world", with "Hello"
// bolded.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B2:D4');
const bold = SpreadsheetApp.newTextStyle().setBold(true).build();
const richText = SpreadsheetApp.newRichTextValue()
                     .setText('Hello world')
                     .setTextStyle(0, 5, bold)
                     .build();
range.setRichTextValue(richText);

参数

名称	类型	说明
`value`	`RichTextValue`	所需的富文本值。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setRichTextValues(values)`

设置富文本值的矩形网格。

// Sets the cells in range A1:A2 to have Rich Text values.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('A1:A2');
const bold = SpreadsheetApp.newTextStyle().setBold(true).build();
const italic = SpreadsheetApp.newTextStyle().setItalic(true).build();
const richTextA1 = SpreadsheetApp.newRichTextValue()
                       .setText('This cell is bold')
                       .setTextStyle(bold)
                       .build();
const richTextA2 = SpreadsheetApp.newRichTextValue()
                       .setText('bold words, italic words')
                       .setTextStyle(0, 11, bold)
                       .setTextStyle(12, 24, italic)
                       .build();
range.setRichTextValues([[richTextA1], [richTextA2]]);

参数

名称	类型	说明
`values`	`RichTextValue[][]`	所需的富文本值。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setShowHyperlink(showHyperlink)`

设置范围是否应显示超链接。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can useSpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets cell A30 and sets its hyperlink value.
const range = sheet.getRange('A30');
range.setValue('https://www.example.com');

// Sets cell A30 to show hyperlinks.
range.setShowHyperlink(true);

参数

名称	类型	说明
`showHyperlink`	`Boolean`	是否显示超链接。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setTextDirection(direction)`

设置指定范围内单元格的文字方向。如果指定的方向为 null，则系统会推断并设置方向。

// Sets right-to-left text direction for the range.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B5:C6');
range.setTextDirection(SpreadsheetApp.TextDirection.RIGHT_TO_LEFT);

参数

名称	类型	说明
`direction`	`TextDirection`	所需的文字方向；如果值为 `null`，则在设置之前推断方向。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setTextDirections(directions)`

设置文本方向的矩形网格。如果指定的方向为 null，则系统会推断方向，然后进行设置。

// Copies all of the text directions from range A1:B2 over to range C5:D6.
const sheet = SpreadsheetApp.getActiveSheet();
const range1 = sheet.getRange('A1:B2');
const range2 = sheet.getRange('C5:D6');

range2.setTextRotations(range1.getTextDirections());

参数

名称	类型	说明
`directions`	`TextDirection[][]`	所需的文字方向；如果指定的方向为 `null`，则会在设置之前进行推断。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setTextRotation(degrees)`

为范围内的单元格设置文字旋转设置。输入内容对应于标准文字方向与所需方向之间的角度。输入值为零表示文本设置为标准方向。

对于从左到右的文本方向，正角度为逆时针方向，而对于从右到左的文本方向，正角度为顺时针方向。

// Sets all cell's in range B2:D4 to have text rotated up 45 degrees.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B2:D4');

range.setTextRotation(45);

参数

名称	类型	说明
`degrees`	`Integer`	标准方向与所需方向之间的所需角度。对于从左到右的文字，正角度为逆时针方向。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setTextRotation(rotation)`

为范围内的单元格设置文字旋转设置。

// Sets all cell's in range B2:D4 to have the same text rotation settings as
// cell A1.
const sheet = SpreadsheetApp.getActiveSheet();

const rotation = sheet.getRange('A1').getTextRotation();

sheet.getRange('B2:D4').setTextRotation(rotation);

参数

名称	类型	说明
`rotation`	`TextRotation`	所需的文字旋转设置。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setTextRotations(rotations)`

设置文本旋转的矩形网格。

// Copies all of the text rotations from range A1:B2 over to range C5:D6.
const sheet = SpreadsheetApp.getActiveSheet();
const range1 = sheet.getRange('A1:B2');
const range2 = sheet.getRange('C5:D6');

range2.setTextRotations(range1.getTextRotations());

参数

名称	类型	说明
`rotations`	`TextRotation[][]`	所需的文字旋转设置。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setTextStyle(style)`

为范围内的单元格设置文本样式。

// Sets the cells in range C5:D6 to have underlined size 15 font.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('C5:D6');
const style =
    SpreadsheetApp.newTextStyle().setFontSize(15).setUnderline(true).build();
range.setTextStyle(style);

参数

名称	类型	说明
`style`	`TextStyle`	所需的文字样式。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setTextStyles(styles)`

设置文本样式的矩形网格。

// Sets text styles for cells in range A1:B2
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('A1:B2');
const bold = SpreadsheetApp.newTextStyle().setBold(true).build();
const otherStyle = SpreadsheetApp.newTextStyle()
                       .setBold(true)
                       .setUnderline(true)
                       .setItalic(true)
                       .setForegroundColor('#335522')
                       .setFontSize(44)
                       .build();
range.setTextStyles([
  [bold, otherStyle],
  [otherStyle, bold],
]);

参数

名称	类型	说明
`styles`	`TextStyle[][]`	所需的文字样式。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setValue(value)`

设置范围的值。该值可以是数值、字符串、布尔值或日期。如果以 '=' 开头，则会被解读为公式。

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

const cell = sheet.getRange('B2');
cell.setValue(100);

参数

名称	类型	说明
`value`	`Object`	范围的值。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setValues(values)`

设置一个矩形值网格（必须与相应范围的维度相匹配）。如果值以 = 开头，则会被解读为公式。

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

// The size of the two-dimensional array must match the size of the range.
const values = [['2.000', '1,000,000', '$2.99']];

const range = sheet.getRange('B2:D2');
range.setValues(values);

参数

名称	类型	说明
`values`	`Object[][]`	一个二维值数组。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setVerticalAlignment(alignment)`

设置指定范围（顶部/中间/底部）的垂直（从上到下）对齐方式。

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

const cell = sheet.getRange('B2');
cell.setVerticalAlignment('middle');

参数

名称	类型	说明
`alignment`	`String`	对齐方式，可以是 `'top'`、`'middle'` 或 `'bottom'`；`null` 值会重置对齐方式。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setVerticalAlignments(alignments)`

设置垂直对齐方式的矩形网格（必须与此范围的维度一致）。

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

// The size of the two-dimensional array must match the size of the range.
const alignments = [['top', 'middle', 'bottom']];

const range = sheet.getRange('B2:D2');
range.setVerticalAlignments(alignments);

参数

名称	类型	说明
`alignments`	`Object[][]`	一个二维对齐数组，可以是 `'top'`、`'middle'` 或 `'bottom'`；`null` 值会重置对齐。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

另请参阅

setVerticalAlignment(alignment)

`setVerticalText(isVertical)`

设置是否堆叠指定范围内单元格的文本。如果文字是垂直堆叠的，系统会忽略度数文字旋转设置。

// Sets all cell's in range B2:D4 to have vertically stacked text.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B2:D4');

range.setVerticalText(true);

参数

名称	类型	说明
`isVertical`	`Boolean`	是否堆叠文本。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setWrap(isWrapEnabled)`

设置指定范围的单元格换行。

启用自动换行的单元格（默认设置）会调整大小以显示完整内容。如果单元格的自动换行功能处于停用状态，系统会在单元格中尽可能多地显示内容，而不会调整大小或换行。

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

const cell = sheet.getRange('B2');
cell.setWrap(true);

参数

名称	类型	说明
`isWrapEnabled`	`Boolean`	是否换行。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setWrapStrategies(strategies)`

设置环绕策略的矩形网格。

// Copies all of the wrap strategies from range A1:B2 over to range C5:D6.
const sheet = SpreadsheetApp.getActiveSheet();
const range1 = sheet.getRange('A1:B2');
const range2 = sheet.getRange('C5:D6');

range2.setWrapStrategies(range1.getWrapStrategies());

参数

名称	类型	说明
`strategies`	`WrapStrategy[][]`	所需的换行策略。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setWrapStrategy(strategy)`

为范围内的单元格设置文字换行策略。

// Sets all cells in range B2:D4 to use the clip wrap strategy.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B2:D4');

range.setWrapStrategy(SpreadsheetApp.WrapStrategy.CLIP);

参数

名称	类型	说明
`strategy`	`WrapStrategy`	所需的封装策略。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`setWraps(isWrapEnabled)`

设置一个换行政策的矩形网格（必须与此范围的维度一致）。启用自动换行（默认）的单元格会调整大小以显示完整内容。如果单元格未启用自动换行，则会在单元格中尽可能多地显示内容，而不会调整大小或换行。

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

// The size of the two-dimensional array must match the size of the range.
const wraps = [[true, true, false]];

const range = sheet.getRange('B2:D2');
range.setWraps(wraps);

参数

名称	类型	说明
`isWrapEnabled`	`Object[][]`	一个二维数组，包含用于确定是否在单元格中换行的包装变量。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

另请参阅

setWrap(isWrapEnabled)

`shiftColumnGroupDepth(delta)`

按指定量更改范围的列分组深度。

这会创建、修改或删除与该范围相交的群组。对于正增量，系统会创建和/或修改群组；对于负增量，系统会销毁和/或修改群组。

当组深度减小到低于 0 或高于 8 时，此参数无效。

如果 column group control position 为 BEFORE，则在尝试移动第一行的深度时会抛出错误。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getActiveRange();

// The column grouping depth is increased by 1.
range.shiftColumnGroupDepth(1);

// The column grouping depth is decreased by 1.
range.shiftColumnGroupDepth(-1);

参数

名称	类型	说明
`delta`	`Integer`	相应范围的列组列数变化量。

Range - 此范围，用于链式调用。

抛出

Error - 当尝试在控制位置为 GroupControlTogglePosition.BEFORE 时移动第一列的深度时

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`shiftRowGroupDepth(delta)`

按指定量更改范围的行分组深度。

这会创建、修改或删除与该范围相交的群组。对于正增量，系统会创建和/或修改群组；对于负增量，系统会销毁和/或修改群组。

当组深度减小到低于 0 或高于 8 时，此参数无效。

如果 row group control position 为 BEFORE，则在尝试移动第一行的深度时会抛出错误。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getActiveRange();

// The row grouping depth is increased by 1.
range.shiftRowGroupDepth(1);

// The row grouping depth is decreased by 1.
range.shiftRowGroupDepth(-1);

参数

名称	类型	说明
`delta`	`Integer`	相应范围的行组深度变化量。

Range - 此范围，用于链式调用。

抛出

Error - 当尝试在控制位置为 GroupControlTogglePosition.BEFORE 时移动第一行的深度时

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`sort(sortSpecObj)`

按指定的列和顺序对给定范围内的单元格进行排序。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:C7');

// Sorts by the values in the first column (A)
range.sort(1);

// Sorts by the values in the second column (B)
range.sort(2);

// Sorts descending by column B
range.sort({column: 2, ascending: false});

// Sorts descending by column B, then ascending by column A
// Note the use of an array
range.sort([
  {column: 2, ascending: false},
  {column: 1, ascending: true},
]);

// For rows that are sorted in ascending order, the "ascending" parameter is
// optional, and just an integer with the column can be used instead. Note that
// in general, keeping the sort specification consistent results in more
// readable code. You can express the earlier sort as:
range.sort([{column: 2, ascending: false}, 1]);

// Alternatively, if you want all columns to be in ascending order, you can use
// the following (this makes column 2 ascending)
range.sort([2, 1]);
// ... which is equivalent to
range.sort([
  {column: 2, ascending: true},
  {column: 1, ascending: true},
]);

参数

名称	类型	说明
`sortSpecObj`	`Object`	要排序的列。

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`splitTextToColumns()`

根据自动检测到的分隔符，将文本列拆分为多个列。

// A1:A3 has the following values:
//           A                  B                 C
// 1 |one,one,one      |                 |                 |
// 2 |two,two,two      |                 |                 |
// 3 |three,three,three|                 |                 |

const range = SpreadsheetApp.getActiveSheet().getRange('A1:A3');
range.splitTextToColumns();

// Result after splitting the text to columns:
//           A                  B                 C
// 1 |one              |one              |one              |
// 2 |two              |two              |two              |
// 3 |three            |three            |three            |

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`splitTextToColumns(delimiter)`

使用指定字符串作为自定义分隔符，将文本列拆分为多个列。

// A1:A3 has the following values:
//           A                  B                 C
// 1 |one#one#one      |                 |                 |
// 2 |two#two#two      |                 |                 |
// 3 |three#three#three|                 |                 |

const range = SpreadsheetApp.getActiveSheet().getRange('A1:A3');
range.splitTextToColumns('#');

// Result after splitting the text to columns:
//           A                  B                 C
// 1 |one              |one              |one              |
// 2 |two              |two              |two              |
// 3 |three            |three            |three            |

参数

名称	类型	说明
`delimiter`	`String`	用于拆分的自定义分隔符。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`splitTextToColumns(delimiter)`

根据指定的分隔符将文本列拆分为多个列。

// A1:A3 has the following values:
//           A                  B                 C
// 1 |one;one;one      |                 |                 |
// 2 |two;two;two      |                 |                 |
// 3 |three;three;three|                 |                 |

const range = SpreadsheetApp.getActiveSheet().getRange('A1:A3');
range.splitTextToColumns(SpreadsheetApp.TextToColumnsDelimiter.SEMICOLON);

// Result after splitting the text to columns:
//           A                  B                 C
// 1 |one              |one              |one              |
// 2 |two              |two              |two              |
// 3 |three            |three            |three            |

参数

名称	类型	说明
`delimiter`	`TextToColumnsDelimiter`	用于拆分的预设分隔符。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

range.trimWhitespace();

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

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`uncheck()`

将指定范围内复选框的状态更改为“未选中”。忽略指定范围内当前未包含已配置的选中或未选中值的单元格。

// Changes the state of cells which currently contain either the checked or
// unchecked value configured in the range A1:B10 to 'unchecked'.
const range = SpreadsheetApp.getActive().getRange('A1:B10');
range.uncheck();

Range - 此范围，用于链式调用。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

已弃用的方法

`getFontColor()`

已弃用。已替换为 getFontColorObject()

以 CSS 表示法（例如 '#ffffff' 或 'white'）返回范围左上角单元格的字体颜色。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

Logger.log(range.getFontColor());

String - CSS 表示法中的字体颜色（例如 '#ffffff' 或 'white'）。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

`getFontColors()`

已弃用。已替换为 getFontColorObjects()

以 CSS 表示法（例如 '#ffffff' 或 'white'）返回指定范围内单元格的字体颜色。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');

const results = range.getFontColors();

for (const i in results) {
  for (const j in results[i]) {
    Logger.log(results[i][j]);
  }
}

String[][] - 与指定范围内的单元格关联的字体颜色二维数组。

授权

使用此方法的脚本需要获得以下一项或多项范围的授权：

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

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

方法

已弃用的方法

详细文档

activate()

返回

activateAsCurrentCell()

返回

授权

addDeveloperMetadata(key)

参数

返回

授权

addDeveloperMetadata(key, visibility)

参数

返回

授权

addDeveloperMetadata(key, value)

参数

返回

授权

addDeveloperMetadata(key, value, visibility)

参数

返回

授权

applyColumnBanding()

返回

授权

applyColumnBanding(bandingTheme)

参数

返回

授权

applyColumnBanding(bandingTheme, showHeader, showFooter)

参数

返回

授权

applyRowBanding()

返回

授权

applyRowBanding(bandingTheme)

参数

返回

授权

applyRowBanding(bandingTheme, showHeader, showFooter)

参数

返回

授权

autoFill(destination, series)

参数

授权

autoFillToNeighbor(series)

参数

授权

breakApart()

返回

授权

canEdit()

返回

授权

check()

返回

授权

clear()

返回

授权

clear(options)

参数

高级参数

返回

授权

clearContent()

返回

授权

clearDataValidations()

返回

授权

clearFormat()

返回

授权

clearNote()

Class Range

`activate()`

`activateAsCurrentCell()`

`addDeveloperMetadata(key)`

`addDeveloperMetadata(key, visibility)`

`addDeveloperMetadata(key, value)`

`addDeveloperMetadata(key, value, visibility)`

`applyColumnBanding()`

`applyColumnBanding(bandingTheme)`

`applyColumnBanding(bandingTheme, showHeader, showFooter)`

`applyRowBanding()`

`applyRowBanding(bandingTheme)`

`applyRowBanding(bandingTheme, showHeader, showFooter)`

`autoFill(destination, series)`

`autoFillToNeighbor(series)`

`breakApart()`

`canEdit()`

`check()`

`clear()`

`clear(options)`

`clearContent()`

`clearDataValidations()`

`clearFormat()`

`clearNote()`

`collapseGroups()`

`copyFormatToRange(gridId, column, columnEnd, row, rowEnd)`

`copyFormatToRange(sheet, column, columnEnd, row, rowEnd)`

`copyTo(destination)`

`copyTo(destination, copyPasteType, transposed)`

`copyTo(destination, options)`

`copyValuesToRange(gridId, column, columnEnd, row, rowEnd)`

`copyValuesToRange(sheet, column, columnEnd, row, rowEnd)`

`createDataSourcePivotTable(dataSource)`

`createDataSourceTable(dataSource)`

`createDeveloperMetadataFinder()`

`createFilter()`

`createPivotTable(sourceData)`

`createTextFinder(findText)`

`deleteCells(shiftDimension)`

`expandGroups()`

`getA1Notation()`

`getBackground()`

`getBackgroundObject()`

`getBackgroundObjects()`

`getBackgrounds()`