此页面由 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`	返回展开的范围 `Direction.UP` 和 `Direction.DOWN` 的副本，前提是如果维度为 `Dimension.COLUMNS`，则为 `Dimension.ROWS` 或 `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`	设置字体大小，大小为要使用的点大小。
`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`	为范围内的单元格设置 RTF 值。
`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。

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

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

Range - 此范围，用于链接。

`activateAsCurrentCell()`

将指定单元格设为 current cell。

如果指定的单元格存在于现有范围中，则该范围会变为有效范围该单元格作为当前单元格。

如果指定的单元格不存在于任何现有范围中，则现有选择会应用于移除后，该单元格会成为当前单元格和活动范围。

注意：指定的 Range 必须由一个单元格组成，否则会抛出异常。

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

// Gets the cell B5 and sets it as the active cell.
var range = sheet.getRange('B5');
var 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:A20 以 A1:A4 中的当前值为基础，添加一系列递增数字：

var sheet = SpreadsheetApp.getActiveSheet();

// Has values [1, 2, 3, 4].
var sourceRange = sheet.getRange("A1:A4");
// The range to fill with values.
var 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 列中的值。

var sheet = SpreadsheetApp.getActiveSheet();

// A1:A20 has values [1, 2, 3, ... 20].
// B1:B4 has values [1/1/2017, 1/2/2017, ...]
var 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'.
var range = SpreadsheetApp.getActive().getRange('A1:B10');
range.check();

Range - 此范围，用于链接。

授权

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

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

`clear()`

清除内容和格式的范围。

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

var 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()`

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

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

var 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.
var range = SpreadsheetApp.getActive().getRange('A1:B5');
range.clearDataValidations();

Range - 此范围，用于链接。

授权

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

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

`clearFormat()`

清除此范围的格式。

此操作将清除范围中一个或多个单元格的文本格式，但不会重置任何单元格数字格式规则。

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

var range = sheet.getRange("A1:D10");
range.clearFormat();

Range - 此范围，用于链接。

授权

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

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

`clearNote()`

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

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

var range = sheet.getRange("A1:D10");
range.clearNote();

Range - 此范围，用于链接。

授权

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

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

`collapseGroups()`

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

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var 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()。

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

var 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)`

将该范围的格式复制到指定位置。目的地较大或较小超出来源范围，则系统会相应地重复或截断该来源。请注意，方法仅复制格式。

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

var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var 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.
var 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.
var 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()。

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

var 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)`

将该范围的内容复制到指定位置。目的地较大或较小超出来源范围，则系统会相应地重复或截断该来源。

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

var 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)`

根据数据源创建一个空的数据源数据透视表，并将其锚定在。

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

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

var 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)`

根据数据源创建一个空数据源表格，并锚定在此范围。

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

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

var dataSourceTable = anchorCell.createDataSourceTable(dataSource);
    .addColumns('dataColumnA', 'dataColumnB', 'dataColumnC')
    .addSortSpec('dataColumnA', /* ascending= *\/ true)
    .addSortSpec('dataColumnB', /* 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()。

let ss = SpreadsheetApp.getActiveSheet();
let 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() {
  let filter = range.getFilter();
  let criteria = SpreadsheetApp.newFilterCriteria()
    .whenCellNotEmpty()
    .build();
  filter.setColumnFilterCriteria(2, criteria);
}

您可以使用此方法为 Grid 个工作表（默认的工作表类型）创建过滤条件。网格工作表是指未与数据库关联的工作表。要创建其他类型的过滤条件，请执行以下操作：请参阅以下内容： <ph type="x-smartling-placeholder">

使用 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)`

为范围创建文本查找器，用于查找和替换此范围内的文本。

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

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

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

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

参数

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

TextFinder - 范围的 TextFinder

`deleteCells(shiftDimension)`

删除此单元格范围。工作表中的现有数据沿所提供的维度发生偏移删除范围内的数据

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

var 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()`

如果范围或控制切换开关与此范围相交，则展开收起的组。通过控件切换位置是指控件切换显示位置的索引，它直接位于或具体取决于设置如果同一地点有多个群组，将最浅的组展开。

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var 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 表示法）。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var 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'）。

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

var cell = sheet.getRange("B5");
Logger.log(cell.getBackground());

String - 背景的颜色代码。

授权

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

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

`getBackgroundObject()`

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

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

var 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()`

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

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

var range = sheet.getRange("B5:C6");
var bgColors = range.getBackgroundObjects();
for (var i in bgColors) {
  for (var 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'）。

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

var range = sheet.getRange("B5:C6");
var bgColors = range.getBackgrounds();
for (var i in bgColors) {
  for (var 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 (let banding of bandings) {
  console.log(banding.getSecondRowColor());
}

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

授权

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

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

`getCell(row, column)`

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

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

var 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
var 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()`

返回此范围的起始列位置。

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

var 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.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var 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)`

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

// Assume the active spreadsheet is blank.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var 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() {
  var ss = SpreadsheetApp.openById('1khO6hBWTNNyvyyxvob7aoZTI9ZvlqqASNeq0e29Tw2c');
  var sheet = ss.getSheetByName('ContinentData');
  var range = sheet.getRange('A1:B8');

  var 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 的形式返回此范围中的数据。

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

// Calling this method with "true" sets the first line to be the title of the axes
var 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.
var 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.
var cell = SpreadsheetApp.getActive().getRange('A1');
var rule = cell.getDataValidation();
if (rule != null) {
  var criteria = rule.getCriteriaType();
  var 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.
var oldDates = [new Date('1/1/2013'), new Date('12/31/2013')];
var newDates = [new Date('1/1/2014'), new Date('12/31/2014')];
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange(1, 1, sheet.getMaxRows(), sheet.getMaxColumns());
var rules = range.getDataValidations();

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

    if (rule != null) {
      var criteria = rule.getCriteriaType();
      var 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.
var 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 。

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

Filter - 过滤条件。

授权

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

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

`getFontColorObject()`

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

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var 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()`

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

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

var results = range.getFontColorObjects();

for (var i in results) {
  for (var 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()`

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

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

var results = range.getFontFamilies();

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

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

授权

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

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

`getFontFamily()`

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

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var 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'）。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var 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'）。

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

var results = range.getFontLines();

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

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

授权

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

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

`getFontSize()`

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

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

Logger.log(range.getFontSize());

Integer - 字体大小（以点大小为单位）。

授权

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

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

`getFontSizes()`

返回范围内单元格的字体大小。

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

var results = range.getFontSizes();

for (var i in results) {
  for (var 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'）范围角。

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

Logger.log(range.getFontStyle());

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

授权

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

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

`getFontStyles()`

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

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

var results = range.getFontStyles();

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

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

授权

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

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

`getFontWeight()`

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

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

Logger.log(range.getFontWeight());

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

授权

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

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

`getFontWeights()`

返回范围内单元格的字体粗细。

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

var results = range.getFontWeights();

for (var i in results) {
  for (var 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 表示法），如果将单元格为空或不包含公式。

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

// This assumes you have a function in B5 that sums up
// B2:B4
var 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。

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

var range = sheet.getRange("B5");
var formula = range.getFormulaR1C1();
Logger.log(formula);

String - 采用 R1C1 表示法的公式。

授权

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

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

`getFormulas()`

返回范围中单元格的公式（A1 表示法）。二维数组中的条目为不含公式的单元格的空白字符串。

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

var range = sheet.getRange("B5:C6");
var formulas = range.getFormulas();
for (var i in formulas) {
  for (var 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 表示不含公式的单元格。

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

var range = sheet.getRange("B5:C6");
var formulas = range.getFormulasR1C1();
for (var i in formulas) {
  for (var 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.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var 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()`

返回范围的高度。

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

var 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()`

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

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

Logger.log(range.getHorizontalAlignment());

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

授权

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

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

`getHorizontalAlignments()`

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

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

var results = range.getHorizontalAlignments();

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

String[][] - 与范围。

授权

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

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

`getLastColumn()`

返回结束列位置。

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

var 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()`

返回结束行位置。

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

var 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 对象数组，这些对象代表已完全合并的单元格或至少包含当前范围内的一个单元格。

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

var range = sheet.getRange("A1:B3");

var mergedRanges = range.getMergedRanges();
for (var 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.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var 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()`

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

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

Logger.log(range.getNote());

String - 与给定单元格关联的备注。

授权

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

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

`getNotes()`

返回与范围内的单元格相关联的注释。

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

var results = range.getNotes();

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

String[][] - 与范围内的单元格相关联的二维笔记数组。

授权

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

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

`getNumColumns()`

返回此范围内的列数。

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

var range = sheet.getRange("B2:D5");
Logger.log(range.getNumColumns());

Integer - 此范围内的列数。

授权

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

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

`getNumRows()`

返回此范围内的行数。

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

var 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 文档。

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

var cell = sheet.getRange("C4");
Logger.log(cell.getNumberFormat());

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

授权

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

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

`getNumberFormats()`

返回范围内单元格的数字或日期格式。返回的格式模式 Sheets API 文档中所述。

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

var range = sheet.getRange("B5:C6");
var formats = range.getNumberFormats();
for (var i in formats) {
  for (var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("D4:F6");
var 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
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
var values = range.getRichTextValues();

for (var i = 0; i < values.length; i++) {
  for (var 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() 相同。

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

var range = sheet.getRange("B2");
Logger.log(range.getRow());

Integer - 范围的行位置。

授权

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

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

`getRowIndex()`

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

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

var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var 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
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
var directions = range.getTextDirections();

for (var i = 0; i < directions.length; i++) {
  for (var 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.
var sheet = SpreadsheetApp.getActiveSheet();

var cell = sheet.getRange("A1");
Logger.log(cell.getTextRotation());

TextRotation - 文本旋转设置。

授权

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

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

`getTextRotations()`

返回范围内单元格的文本旋转设置。

var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B2:D4");

var results = range.getTextRotations();

for (var i in results) {
  for (var j in results[i]) {
    var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("D4:F6");
var 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
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
var styles = range.getTextStyles();

for (var i = 0; i < styles.length; i++) {
  for (var 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.
var values = SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getValues();
Logger.log(values[0][0]);

在 Web 应用中，Date 值不是合法参数。getValues() 无法返回将数据发送到 Web 应用。Date而是将从工作表中检索到的所有值传递给受支持的 JavaScript 基元（例如 Number、Boolean 或 String）。

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

授权

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

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

`getVerticalAlignment()`

返回单元格在范围。

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

Logger.log(range.getVerticalAlignment());

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

授权

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

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

`getVerticalAlignments()`

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

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

var results = range.getVerticalAlignments();

for (var i in results) {
  for (var 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()。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var 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
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
var strategies = range.getWrapStrategies();

for (var i = 0; i < strategies.length; i++) {
  for (var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var 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()。

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

var results = range.getVerticalAlignments();

for (var i in results) {
  for (var j in results[i]) {
    var 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)`

在此范围内插入空单元格。新单元格会保留单元格中存在的所有格式之前会处于此范围之内工作表中的现有数据以及所提供的维度为从插入的范围移走了

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

var 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。

var 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)`

在范围中的每个单元格中插入复选框，并配置已选中和空字符串表示未选中。将范围内每个单元格的值设置为空字符串。

var 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)`

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

var 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。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var 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 数据验证。

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

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

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

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

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

Boolean - true（如果检查范围中的所有单元格），false（如果范围中的所有单元格）范围或 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。

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

var range = sheet.getRange("A1:B3");

// True if any of the cells in A1:B3 is included in a merge.
var 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()`

将范围内的单元格合并为一个块。

var 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()`

将范围中的单元格与范围列合并。

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

// The code below merges cells C5:E5 into one cell
var range1 = sheet.getRange("C5:E5");
range1.mergeAcross();

// The code below creates 2 horizontal cells, F5:H5 and F6:H6
var range2 = sheet.getRange("F5:H6");
range2.mergeAcross();

Range - 此范围，用于链接。

授权

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

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

`mergeVertically()`

将范围内的单元格合并在一起。

var 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
var 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)`

返回从该范围偏移了指定的行数和列数的新范围（可为负数）。新范围的大小与原始范围相同。

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

var cell = sheet.getRange("A1");

// newCell references B2
var newCell = cell.offset(1, 1);

参数

名称	类型	说明
`rowOffset`	`Integer`	从范围左上角单元格向下的行数；负值表示从范围的左上角单元格向上的行。
`columnOffset`	`Integer`	范围左上角单元格右侧的列数；负值表示距范围的左上角单元格左侧的列。

Range - 此范围，用于链接。

`offset(rowOffset, columnOffset, numRows)`

返回相对于当前范围的新范围，其左上方点是偏移量按给定的行和列从当前范围中选取，并在单元格中指定高度。

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

var cell = sheet.getRange("A1");

// newCell references B2:B3
var newRange = cell.offset(1, 1, 2);

参数

名称	类型	说明
`rowOffset`	`Integer`	从范围左上角单元格向下的行数；负值表示从范围的左上角单元格向上的行。
`columnOffset`	`Integer`	范围左上角单元格右侧的列数；负值表示距范围的左上角单元格左侧的列。
`numRows`	`Integer`	新范围的高度（以行为单位）。

Range - 此范围，用于链接。

`offset(rowOffset, columnOffset, numRows, numColumns)`

返回相对于当前范围的新范围，其左上方点是偏移量从当前范围中按指定的行和列进行计算，并通过单元格。

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

var cell = sheet.getRange("A1");

// newCell references B2:C3
var 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.
var ss = SpreadsheetApp.getActive();
var range = ss.getRange('A1:B10');
var 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.
var 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()`

对给定范围内行的顺序进行随机。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var 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()`

删除范围中的所有复选框。清除每个单元格的数据验证，以及如果单元格包含选中或未选中值，则还会清除相应的值。

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

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

var range1 = SpreadsheetApp.getActive().getRange('A1');
range1.setValue('yes');
// Removes the checkbox data validation in cell A1 and clears its value.
range1.removeCheckboxes();

var 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()`

如果此范围内包含的值与任何字段中的值重复，则移除此范围内的行上一行。行包含相同的值，但字母大小写、格式或公式不同被视为重复内容。此方法还会从视图中移除隐藏的重复行（对于（例如使用过滤条件）。系统不会移除此范围之外的内容。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var 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)`

移除此范围内包含指定列中重复值的行任何前一行的值。具有相同值但字母大小写、格式、或公式被视为重复。此方法还会移除隐藏的重复行（例如，由于过滤器所致）。系统不会移除此范围之外的内容。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var 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'）。

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

var 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)`

设置范围内所有单元格的背景颜色。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var bgColor = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.BACKGROUND)
    .build();

var 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)`

用于设置背景颜色的矩形网格（必须匹配此范围的尺寸）。

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

var colorAccent1 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
    .build();
var colorAccent2 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
    .build();
var colorAccent3 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
    .build();
var colorAccent4 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4)
    .build();

var colors = [
  [colorAccent1, colorAccent2],
  [colorAccent3, colorAccent4]
];

var 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）将背景设置为指定颜色。

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

var 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'）。

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

var colors = [
  ["red", "white", "blue"],
  ["#FF0000", "#FFFFFF", "#0000FF"] // These are the hex equivalents
];

var 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（无变化）。

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

var 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'）。

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

var 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.
var cell = SpreadsheetApp.getActive().getRange('A1');
var range = SpreadsheetApp.getActive().getRange('B1:B10');
var 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.
var destinationRange = SpreadsheetApp.getActive().getSheetByName('Sheet1').getRange('A1:B5');
var sourceRange = SpreadsheetApp.getActive().getSheetByName('Sheet2').getRange('A1:A10');
var rule = SpreadsheetApp.newDataValidation().requireValueInRange(sourceRange).build();
var rules = destinationRange.getDataValidations();
for (var i = 0; i < rules.length; i++) {
  for (var 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'）。

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

var 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)`

设置给定范围的字体颜色。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var color = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.TEXT)
    .build();

var 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)`

用于设置字体颜色的矩形网格（必须匹配此范围的尺寸）。

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

var colorAccent1 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
    .build();
var colorAccent2 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
    .build();
var colorAccent3 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
    .build();
var colorAccent4 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4)
    .build();

var colors = [
  [colorAccent1, colorAccent2],
  [colorAccent3, colorAccent4]
];

var 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'）。

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

var colors = [
  ["red", "white", "blue"],
  ["#FF0000", "#FFFFFF", "#0000FF"] // These are the hex equivalents
];

var 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”。

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

var fonts = [
  ["Arial", "Helvetica", "Verdana"],
  ["Courier New", "Arial", "Helvetica]
];

var 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”。

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

var 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'）。

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

var 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)`

用于设置线条样式的矩形网格（必须匹配此范围的尺寸）。

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

// The size of the two-dimensional array must match the size of the range.
var fontLines = [
  ["underline", "line-through", "none"]
];

var 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)`

设置字体大小，大小为要使用的点大小。

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

var 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)`

用于设置字体大小的矩形网格（必须匹配此范围的尺寸）。尺寸为积分。

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

// The size of the two-dimensional array must match the size of the range.
var fontSizes = [
  [16, 20, 24]
];

var 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'）的字体样式。

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

var 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)`

用于设置字体样式的矩形网格（必须匹配此范围的尺寸）。

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

// The size of the two-dimensional array must match the size of the range.
var fontStyles = [
  ["italic", "normal"]
];

var 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)`

设置给定范围（正常/粗体）的字体粗细。

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

var 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)`

用于设置字体粗细的矩形网格（必须匹配此范围的尺寸）。示例字体粗细为“bold”。

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

// The size of the two-dimensional array must match the size of the range.
var fontStyles = [
  [ "bold", "bold", "normal" ]
];

var 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 表示法。

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

var 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 表示法。

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

var 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 表示法。此方法采用二维公式数组，按行编入索引，然后按列。数组维度必须与范围维度相对应。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var 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.
var formulas = [
  ["=SUM(B2:B4)", "=SUM(C2:C4)", "=SUM(D2:D4)"],
  ["=AVERAGE(B2:B4)", "=AVERAGE(C2:C4)", "=AVERAGE(D2:D4)"]
];

var 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 表示法。

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

// This creates formulas for a row of sums, followed by a row of averages.
var sumOfRowsAbove = "=SUM(R[-3]C[0]:R[-1]C[0])";
var averageOfRowsAbove = "=AVERAGE(R[-4]C[0]:R[-2]C[0])";

// The size of the two-dimensional array must match the size of the range.
var formulas = [
  [sumOfRowsAbove, sumOfRowsAbove, sumOfRowsAbove],
  [averageOfRowsAbove, averageOfRowsAbove, averageOfRowsAbove]
];

var 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)`

为给定范围（左/中/右）设置水平（从左到右）对齐方式。

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

var 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)

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

// The size of the two-dimensional array must match the size of the range.
var horizontalAlignments = [
  [ "left", "right", "center" ]
];

var 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)`

将备注设为指定值。

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

var 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)`

设置一个矩形备注网格（必须匹配此范围的尺寸）。

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

// The size of the two-dimensional array must match the size of the range.
var notes = [
  ["it goes", "like this", "the fourth, the fifth"],
  ["the minor fall", "and the", "major lift"]
];

var 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)`

将数字或日期格式设置为给定的格式字符串。可接受的格式模式包括 Sheets API 文档中所述。

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

var 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 文档。

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

// The size of the two-dimensional array must match the size of the range.
var formats = [
  [ "0.000", "0,000,000", "$0.00" ]
];

var 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)`

为范围内的单元格设置 RTF 值。

// Sets all cells in range B2:D4 to have the text "Hello world", with "Hello" bolded.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B2:D4");
var bold = SpreadsheetApp.newTextStyle()
    .setBold(true)
    .build();
var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("A1:A2");
var bold = SpreadsheetApp.newTextStyle()
    .setBold(true)
    .build();
var italic = SpreadsheetApp.newTextStyle()
    .setItalic(true)
    .build();
var richTextA1 = SpreadsheetApp.newRichTextValue()
    .setText("This cell is bold")
    .setTextStyle(bold)
    .build();
var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var range1 = sheet.getRange("A1:B2");
var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var 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.
var sheet = SpreadsheetApp.getActiveSheet();

var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var range1 = sheet.getRange("A1:B2");
var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("C5:D6");
var 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
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("A1:B2");
var bold = SpreadsheetApp.newTextStyle()
    .setBold(true)
    .build();
var 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)`

设置范围的值。该值可以是数字、字符串、布尔值或日期。如果开始时间若使用 '='，则会被解释为公式。

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

var 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)`

用于设置一个矩形的值网格（必须匹配此范围的尺寸）。如果某个值以 =，系统会将其解释为公式。

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

// The size of the two-dimensional array must match the size of the range.
var values = [
  [ "2.000", "1,000,000", "$2.99" ]
];

var 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)`

为指定范围（顶部/中间/底部）设置垂直（从上到下）对齐方式。

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

var 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)`

用于设置垂直对齐的矩形网格（必须匹配此范围的尺寸）。

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

// The size of the two-dimensional array must match the size of the range.
var alignments = [
  [ "top", "middle", "bottom" ]
];

var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var 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)`

设置给定范围的单元格换行。

启用了换行（默认）的单元格会调整大小，以显示其完整内容。已自动换行的单元格在单元格中尽可能多地显示，而无需调整大小或运行多行。

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

var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var range1 = sheet.getRange("A1:B2");
var 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.
var sheet = SpreadsheetApp.getActiveSheet();
var 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)`

用于设置自动换行政策的矩形网格（必须匹配此范围的尺寸）。包含启用封装功能（默认）调整大小以显示其完整内容。已停用换行的单元格在单元格中显示尽可能多的内容，而无需调整大小或显示多行内容。

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

// The size of the two-dimensional array must match the size of the range.
var wraps = [
  [ true, true, false ]
];

var 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，则在尝试偏移时抛出错误第一行的深度。

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var 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，则在尝试将第一行的深度。

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var 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)`

按列和指定顺序对给定范围内的单元格进行排序。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var 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|                 |                 |

var range = SpreadsheetApp.getActiveSheet().getRange("A1:A3");
range.splitTextToColumns();

// Result after spliting 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|                 |                 |

var range = SpreadsheetApp.getActiveSheet().getRange("A1:A3");
range.splitTextToColumns('#');

// Result after spliting 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|                 |                 |

var range = SpreadsheetApp.getActiveSheet().getRange("A1:A3");
range.splitTextToColumns(SpreadsheetApp.TextToColumnsDelimiter.SEMICOLON);

// Result after spliting 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()`

修剪此范围中每个单元格的空格（例如空格、制表符或换行符）。移除每个单元格文本开头和末尾的所有空格，并减少保留一个空格。

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

range.trimWhitespace();

var 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'.
var 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'）。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var 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'）。

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

var results = range.getFontColors();

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

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

授权

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

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