此页面由 Cloud Translation API 翻译。

Class Sheet

访问和修改电子表格工作表。常见操作包括重命名工作表和从工作表中访问范围对象。

方法

方法	返回类型	简介
`activate()`	`Sheet`	激活此工作表。
`addDeveloperMetadata(key)`	`Sheet`	向工作表添加具有指定键的开发者元数据。
`addDeveloperMetadata(key, visibility)`	`Sheet`	向工作表添加具有指定键和可见性的开发者元数据。
`addDeveloperMetadata(key, value)`	`Sheet`	将具有指定键和值的开发者元数据添加到工作表中。
`addDeveloperMetadata(key, value, visibility)`	`Sheet`	向工作表添加具有指定键、值和公开范围的开发者元数据。
`appendRow(rowContents)`	`Sheet`	将一行附加到工作表中当前数据区域的底部。
`asDataSourceSheet()`	`DataSourceSheet`	如果工作表的类型为 `SheetType.DATASOURCE`，则以 `DataSourceSheet` 的形式返回工作表；否则，返回 `null`。
`autoResizeColumn(columnPosition)`	`Sheet`	将给定列的宽度设置为适合其内容。
`autoResizeColumns(startColumn, numColumns)`	`Sheet`	设置从给定列位置开始的所有列的宽度，以适应其内容。
`autoResizeRows(startRow, numRows)`	`Sheet`	设置从给定行位置开始的所有行的高度，以适应其内容。
`clear()`	`Sheet`	清除工作表中的内容和格式信息。
`clear(options)`	`Sheet`	清除表格的内容和/或格式（如通过给定高级选项指定）。
`clearConditionalFormatRules()`	`void`	从工作表中移除所有条件格式规则。
`clearContents()`	`Sheet`	清除目录工作表，同时保留格式信息。
`clearFormats()`	`Sheet`	清除工作表格式，同时保留内容。
`clearNotes()`	`Sheet`	清除工作表中的所有备注。
`collapseAllColumnGroups()`	`Sheet`	收起工作表中的所有列组。
`collapseAllRowGroups()`	`Sheet`	收起工作表上的所有行组。
`copyTo(spreadsheet)`	`Sheet`	将工作表复制到给定电子表格（可以与来源相同）。
`createDeveloperMetadataFinder()`	`DeveloperMetadataFinder`	返回 `DeveloperMetadataFinder`，用于在此工作表范围内查找开发者元数据。
`createTextFinder(findText)`	`TextFinder`	为工作表创建文本查找器，该查找器可查找和替换工作表中的文本。
`deleteColumn(columnPosition)`	`Sheet`	删除指定列位置的列。
`deleteColumns(columnPosition, howMany)`	`void`	从指定列位置开始删除多列。
`deleteRow(rowPosition)`	`Sheet`	删除指定行位置的行。
`deleteRows(rowPosition, howMany)`	`void`	从指定行位置开始删除多行。
`expandAllColumnGroups()`	`Sheet`	展开工作表中的所有列组。
`expandAllRowGroups()`	`Sheet`	展开工作表中的所有行组。
`expandColumnGroupsUpToDepth(groupDepth)`	`Sheet`	展开深度不超过给定深度的所有列组，并收起所有其他列组。
`expandRowGroupsUpToDepth(groupDepth)`	`Sheet`	展开深度不超过给定深度的所有行组，并收起所有其他行组。
`getActiveCell()`	`Range`	返回此工作表中的活动单元格。
`getActiveRange()`	`Range`	返回活动工作表中的选定范围，如果没有活动范围，则返回 `null`。
`getActiveRangeList()`	`RangeList`	返回活动工作表中的有效范围列表，如果没有有效范围，则返回 `null`。
`getBandings()`	`Banding[]`	返回此工作表中的所有条带。
`getCharts()`	`EmbeddedChart[]`	返回此工作表中的图表数组。
`getColumnGroup(columnIndex, groupDepth)`	`Group`	返回指定索引和组深度的列组。
`getColumnGroupControlPosition()`	`GroupControlTogglePosition`	返回工作表中所有列组的 `GroupControlTogglePosition`。
`getColumnGroupDepth(columnIndex)`	`Integer`	返回指定索引处列的组深度。
`getColumnWidth(columnPosition)`	`Integer`	获取给定列的宽度（以像素为单位）。
`getConditionalFormatRules()`	`ConditionalFormatRule[]`	获取此工作表中的所有条件格式规则。
`getCurrentCell()`	`Range`	返回活动工作表中的当前单元格；如果没有当前单元格，则返回 `null`。
`getDataRange()`	`Range`	返回与数据所在的维度对应的 `Range`。
`getDataSourceFormulas()`	`DataSourceFormula[]`	获取所有数据源公式。
`getDataSourcePivotTables()`	`DataSourcePivotTable[]`	获取所有数据源数据透视表。
`getDataSourceTables()`	`DataSourceTable[]`	获取所有数据源表。
`getDeveloperMetadata()`	`DeveloperMetadata[]`	获取与此工作表关联的所有开发者元数据。
`getDrawings()`	`Drawing[]`	返回工作表上的绘图数组。
`getFilter()`	`Filter`	返回此工作表中的过滤条件；如果没有过滤条件，则返回 `null`。
`getFormUrl()`	`String`	返回将其回复发送到此工作表的表单的网址；如果此工作表没有关联的表单，则返回 `null`。
`getFrozenColumns()`	`Integer`	返回冻结列的数量。
`getFrozenRows()`	`Integer`	返回冻结的行数。
`getImages()`	`OverGridImage[]`	返回工作表中的所有网格外图片。
`getIndex()`	`Integer`	获取工作表在其父级电子表格中的位置。
`getLastColumn()`	`Integer`	返回包含内容的最后一列的位置。
`getLastRow()`	`Integer`	返回包含内容的最后一行的索引。
`getMaxColumns()`	`Integer`	返回工作表中的当前列数（不考虑内容）。
`getMaxRows()`	`Integer`	返回工作表中的当前行数（不考虑内容）。
`getName()`	`String`	返回工作表的名称。
`getNamedRanges()`	`NamedRange[]`	获取此工作表中的所有命名范围。
`getParent()`	`Spreadsheet`	返回包含此工作表的 `Spreadsheet`。
`getPivotTables()`	`PivotTable[]`	返回此工作表中的所有数据透视表。
`getProtections(type)`	`Protection[]`	获取一个对象数组，表示工作表中的所有受保护范围，或一个表示工作表本身保护状态的单元素数组。
`getRange(row, column)`	`Range`	返回左上角单元格位于给定坐标的范围。
`getRange(row, column, numRows)`	`Range`	返回左上角单元格位于给定坐标且行数为给定值的范围。
`getRange(row, column, numRows, numColumns)`	`Range`	返回左上角单元格位于给定坐标且行数和列数为给定值的范围。
`getRange(a1Notation)`	`Range`	返回 A1 表示法或 R1C1 表示法中指定的范围。
`getRangeList(a1Notations)`	`RangeList`	返回一个 `RangeList` 集合，表示由 A1 表示法或 R1C1 表示法组成的非空列表指定的同一工作表中的范围。
`getRowGroup(rowIndex, groupDepth)`	`Group`	返回指定索引和分组深度处的行组。
`getRowGroupControlPosition()`	`GroupControlTogglePosition`	返回工作表中所有行组的 `GroupControlTogglePosition`。
`getRowGroupDepth(rowIndex)`	`Integer`	返回指定索引处的行组深度。
`getRowHeight(rowPosition)`	`Integer`	获取给定行的高度（以像素为单位）。
`getSelection()`	`Selection`	返回电子表格中的当前 `Selection`。
`getSheetId()`	`Integer`	返回此对象所代表的工作表的 ID。
`getSheetName()`	`String`	返回工作表名称。
`getSheetValues(startRow, startColumn, numRows, numColumns)`	`Object[][]`	返回从给定坐标开始的此范围的值矩形网格。
`getSlicers()`	`Slicer[]`	返回工作表上的切片器数组。
`getTabColorObject()`	`Color`	获取工作表标签页的颜色；如果工作表标签页没有颜色，则返回 `null`。
`getType()`	`SheetType`	返回工作表的类型。
`hasHiddenGridlines()`	`Boolean`	如果工作表的网格线处于隐藏状态，则返回 `true`；否则返回 `false`。
`hideColumn(column)`	`void`	隐藏指定范围中的列。
`hideColumns(columnIndex)`	`void`	隐藏给定索引处的单个列。
`hideColumns(columnIndex, numColumns)`	`void`	隐藏从给定索引开始的连续一列或多列。
`hideRow(row)`	`void`	隐藏给定范围中的行。
`hideRows(rowIndex)`	`void`	隐藏指定索引处的行。
`hideRows(rowIndex, numRows)`	`void`	隐藏从给定索引开始的一条或多条连续行。
`hideSheet()`	`Sheet`	隐藏此工作表。
`insertChart(chart)`	`void`	向此工作表添加新图表。
`insertColumnAfter(afterPosition)`	`Sheet`	在指定列位置后插入一列。
`insertColumnBefore(beforePosition)`	`Sheet`	在指定列位置之前插入一列。
`insertColumns(columnIndex)`	`void`	在工作表的指定位置插入空白列。
`insertColumns(columnIndex, numColumns)`	`void`	在工作表中从指定位置开始插入一个或多个连续的空白列。
`insertColumnsAfter(afterPosition, howMany)`	`Sheet`	在指定列位置后插入指定数量的列。
`insertColumnsBefore(beforePosition, howMany)`	`Sheet`	在指定列位置之前插入多列。
`insertImage(blobSource, column, row)`	`OverGridImage`	将 `BlobSource` 作为图片插入文档中的指定行和列。
`insertImage(blobSource, column, row, offsetX, offsetY)`	`OverGridImage`	将 `BlobSource` 作为图片插入文档中的给定行和列，并带有像素偏移。
`insertImage(url, column, row)`	`OverGridImage`	在文档中指定行和列插入图片。
`insertImage(url, column, row, offsetX, offsetY)`	`OverGridImage`	在文档中指定行和列（并带有像素偏移量）插入图片。
`insertRowAfter(afterPosition)`	`Sheet`	在指定的行位置后插入一行。
`insertRowBefore(beforePosition)`	`Sheet`	在指定的行位置之前插入一行。
`insertRows(rowIndex)`	`void`	在工作表的指定位置插入空白行。
`insertRows(rowIndex, numRows)`	`void`	在工作表中从指定位置开始插入一个或多个连续的空白行。
`insertRowsAfter(afterPosition, howMany)`	`Sheet`	在指定的行位置后插入多行。
`insertRowsBefore(beforePosition, howMany)`	`Sheet`	在指定的行位置之前插入多行。
`insertSlicer(range, anchorRowPos, anchorColPos)`	`Slicer`	向此工作表添加新的切片器。
`insertSlicer(range, anchorRowPos, anchorColPos, offsetX, offsetY)`	`Slicer`	向此工作表添加新的切片器。
`isColumnHiddenByUser(columnPosition)`	`Boolean`	返回指定列是否已被用户隐藏。
`isRightToLeft()`	`Boolean`	如果此工作表布局为从右到左，则返回 `true`。
`isRowHiddenByFilter(rowPosition)`	`Boolean`	返回给定行是否被过滤器（而非过滤器视图）隐藏。
`isRowHiddenByUser(rowPosition)`	`Boolean`	返回指定行是否已被用户隐藏。
`isSheetHidden()`	`Boolean`	如果工作表当前处于隐藏状态，则返回 `true`。
`moveColumns(columnSpec, destinationIndex)`	`void`	将通过给定范围选择的列移至 `destinationIndex` 指示的位置。
`moveRows(rowSpec, destinationIndex)`	`void`	将通过给定范围选择的行移至 `destinationIndex` 指示的位置。
`newChart()`	`EmbeddedChartBuilder`	返回一个构建器，用于为此工作表创建新图表。
`protect()`	`Protection`	创建一个对象，可保护工作表免遭修改，除非用户拥有相应权限。
`removeChart(chart)`	`void`	从父工作表中移除图表。
`setActiveRange(range)`	`Range`	将指定范围设置为活动工作表中的 `active range`，并将该范围的左上角单元格设置为 `current cell`。
`setActiveRangeList(rangeList)`	`RangeList`	将指定的范围列表设置为活动工作表中的 `active ranges`。
`setActiveSelection(range)`	`Range`	设置此工作表的有效选择区域。
`setActiveSelection(a1Notation)`	`Range`	设置 A1 或 R1C1 表示法中指定的有效选择。
`setColumnGroupControlPosition(position)`	`Sheet`	设置列组控件切换开关在工作表中的位置。
`setColumnWidth(columnPosition, width)`	`Sheet`	设置给定列的宽度（以像素为单位）。
`setColumnWidths(startColumn, numColumns, width)`	`Sheet`	设置给定列的宽度（以像素为单位）。
`setConditionalFormatRules(rules)`	`void`	将工作表中当前存在的所有条件格式规则替换为输入规则。
`setCurrentCell(cell)`	`Range`	将指定单元格设置为 `current cell`。
`setFrozenColumns(columns)`	`void`	冻结指定数量的列。
`setFrozenRows(rows)`	`void`	冻结指定的行数。
`setHiddenGridlines(hideGridlines)`	`Sheet`	隐藏或显示工作表网格线。
`setName(name)`	`Sheet`	设置工作表名称。
`setRightToLeft(rightToLeft)`	`Sheet`	将工作表布局设置为从右到左或取消设置。
`setRowGroupControlPosition(position)`	`Sheet`	设置行组控件切换开关在工作表中的位置。
`setRowHeight(rowPosition, height)`	`Sheet`	以像素为单位设置给定行的行高。
`setRowHeights(startRow, numRows, height)`	`Sheet`	以像素为单位设置指定行的高度。
`setRowHeightsForced(startRow, numRows, height)`	`Sheet`	以像素为单位设置指定行的高度。
`setTabColor(color)`	`Sheet`	设置工作表标签页颜色。
`setTabColorObject(color)`	`Sheet`	设置工作表标签页颜色。
`showColumns(columnIndex)`	`void`	取消隐藏指定索引处的列。
`showColumns(columnIndex, numColumns)`	`void`	取消隐藏从给定编号开始的连续一列或多列。
`showRows(rowIndex)`	`void`	取消隐藏指定索引处的行。
`showRows(rowIndex, numRows)`	`void`	取消隐藏从给定索引开始的一个或多个连续行。
`showSheet()`	`Sheet`	使工作表可见。
`sort(columnPosition)`	`Sheet`	按列（升序）对工作表进行排序。
`sort(columnPosition, ascending)`	`Sheet`	按列对工作表进行排序。
`unhideColumn(column)`	`void`	取消隐藏给定范围内的列。
`unhideRow(row)`	`void`	取消隐藏给定范围中的行。
`updateChart(chart)`	`void`	更新此工作表中的图表。

已弃用的方法

方法	返回类型	简介
`getSheetProtection()`	`PageProtection`	返回一个 `PageProtection` 实例，用于描述当前工作表的权限。
`getTabColor()`	`String`	获取工作表标签页的颜色；如果工作表标签页没有颜色，则返回 `null`。
`setSheetProtection(permissions)`	`void`	设置当前工作表的权限。

详细文档

`activate()`

激活此工作表。不会更改工作表本身，只会更改父级对活动工作表的概念。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.activate();

Sheet - 新激活的工作表。

`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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Adds the key 'NAME' to the developer metadata for the sheet.
sheet.addDeveloperMetadata('NAME');

// Gets the updated metadata info and logs it to the console.
console.log(sheet.getDeveloperMetadata()[0].getKey());

参数

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

Sheet - 此工作表，用于链式调用。

授权

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

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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Adds the key 'NAME' and sets the developer metadata visibility to PROJECT
// for the sheet.
sheet.addDeveloperMetadata(
    'NAME',
    SpreadsheetApp.DeveloperMetadataVisibility.PROJECT,
);

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

参数

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

Sheet - 此工作表，用于链式调用。

授权

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

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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Adds the key 'COMPANY' with the value 'TECH' to the developer metadata for
// the sheet.
sheet.addDeveloperMetadata('COMPANY', 'TECH');

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

参数

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

Sheet - 此工作表，用于链式调用。

授权

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

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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Adds the key 'COMPANY' with the value 'TECH' to the developer metadata and
// sets the visibility to DOCUMENT for the sheet.
sheet.addDeveloperMetadata(
    'COMPANY',
    'TECH',
    SpreadsheetApp.DeveloperMetadataVisibility.DOCUMENT,
);

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

参数

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

Sheet - 此工作表，用于链式调用。

授权

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

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

`appendRow(rowContents)`

将一行附加到工作表中当前数据区域的底部。如果单元格的内容以 = 开头，则会被解读为公式。

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

// Appends a new row with 3 columns to the bottom of the current
// data region in the sheet containing the values in the array.
sheet.appendRow(['a man', 'a plan', 'panama']);

参数

名称	类型	说明
`rowContents`	`Object[]`	要插入到工作表中最后一行的后面的值数组。

Sheet - 工作表，适用于方法链接。

授权

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

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

`asDataSourceSheet()`

如果工作表的类型为 SheetType.DATASOURCE，则以 DataSourceSheet 的形式返回工作表；否则，返回 null。

// 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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the data source sheet value if the sheet is of type
// SpreadsheetApp.SheetType.DATASOURCE, otherwise this returns a null value.
const dataSourceSheet = sheet.asDataSourceSheet();

// Gets the data source sheet value and logs it to the console.
console.log(dataSourceSheet);
console.log(sheet.getType().toString());

DataSourceSheet - 数据源工作表。

授权

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

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

`autoResizeColumn(columnPosition)`

将给定列的宽度设置为适合其内容。

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

sheet.getRange('a1').setValue(
    'Whenever it is a damp, drizzly November in my soul...');

// Sets the first column to a width which fits the text
sheet.autoResizeColumn(1);

参数

名称	类型	说明
`columnPosition`	`Integer`	要调整大小的给定列的位置。

Sheet - 工作表，适用于方法链接

授权

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

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

`autoResizeColumns(startColumn, numColumns)`

设置从给定列位置开始的所有列的宽度，以适应其内容。

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

// Sets the first 15 columns to a width that fits their text.
sheet.autoResizeColumns(1, 15);

参数

名称	类型	说明
`startColumn`	`Integer`	要自动调整列宽的起始列。
`numColumns`	`Integer`	要自动调整列宽的列数。

Sheet - 此工作表，用于链式调用。

授权

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

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

`autoResizeRows(startRow, numRows)`

设置从给定行位置开始的所有行的高度，以适应其内容。

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

// Sets the first 15 rows to a height that fits their text.
sheet.autoResizeRows(1, 15);

参数

名称	类型	说明
`startRow`	`Integer`	要自动调整大小的起始行。
`numRows`	`Integer`	要自动调整大小的行数。

Sheet - 此工作表，用于链式调用。

授权

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

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

`clear()`

清除工作表中的内容和格式信息。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.clear();

Sheet - 已清除的电子表格。

授权

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

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

`clear(options)`

清除表格的内容和/或格式（如通过给定高级选项指定）。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
sheet.clear({formatOnly: true, contentsOnly: true});

参数

名称	类型	说明
`options`	`Object`	包含以下高级选项的 JavaScript 地图。

高级参数

名称	类型	说明
`contentsOnly`	`Boolean`	是否清除内容。
`formatOnly`	`Boolean`	是否清除格式。

Sheet - 此工作表，用于链式调用。

授权

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

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

`clearConditionalFormatRules()`

从工作表中移除所有条件格式规则。等同于使用空数组作为输入调用 setConditionalFormatRules(rules)。

const sheet = SpreadsheetApp.getActiveSheet();
sheet.clearConditionalFormatRules();

授权

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

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

`clearContents()`

清除内容工作表，同时保留格式信息。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.clearContents();

Sheet - 此工作表，用于链式调用。

授权

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

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

`clearFormats()`

清除工作表的格式，同时保留内容。

格式是指“格式”菜单下允许的选项（例如粗体、斜体、条件格式）对数据的格式设置，而不是单元格的宽度或高度。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.clearFormats();

Sheet - 此工作表，用于链式调用。

授权

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

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

`clearNotes()`

清除工作表中的所有记事。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.clearNotes();

Sheet - 此工作表，用于链式调用。

授权

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

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

`collapseAllColumnGroups()`

收起工作表中的所有列组。

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

// All column groups on the sheet are collapsed.
sheet.collapseAllColumnGroups();

Sheet - 此工作表，用于链式调用。

授权

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

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

`collapseAllRowGroups()`

收起工作表上的所有行组。

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

// All row groups on the sheet are collapsed.
sheet.collapseAllRowGroups();

Sheet - 此工作表，用于链式调用。

授权

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

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

`copyTo(spreadsheet)`

将工作表复制到给定电子表格（可以与来源相同）。复制的工作表将命名为“[原始名称]的副本”。

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

const destination = SpreadsheetApp.openById('ID_GOES HERE');
sheet.copyTo(destination);

参数

名称	类型	说明
`spreadsheet`	`Spreadsheet`	要将此工作表复制到的电子表格，可以与来源相同。

Sheet - 用于串联的新工作表。

授权

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

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

`createDeveloperMetadataFinder()`

返回 DeveloperMetadataFinder，用于在此工作表范围内查找开发者元数据。如果元数据与工作表本身相关联，或者与该工作表中的行、列或范围相关联，则属于该工作表的范围。

// 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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Adds developer metadata for testing.
sheet.addDeveloperMetadata('CITY', 'PARIS');

// Creates the developer metadata finder.
const metadatafinder = sheet.createDeveloperMetadataFinder();

// Finds the metadata with value 'PARIS' and displays its key in the console.
console.log(metadatafinder.withValue('PARIS').find()[0].getKey());

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

`createTextFinder(findText)`

为工作表创建文本查找器，该查找器可查找和替换工作表中的文本。

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

// Creates  a text finder.
const textFinder = sheet.createTextFinder('dog');

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

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

参数

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

TextFinder - 工作表的 TextFinder。

`deleteColumn(columnPosition)`

删除给定列位置的列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Columns start at "1" - this deletes the first column
sheet.deleteColumn(1);

参数

名称	类型	说明
`columnPosition`	`Integer`	列的位置，第一个列从 1 开始。

Sheet - 工作表，适用于方法链接

授权

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

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

`deleteColumns(columnPosition, howMany)`

从指定列位置开始删除多列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Columns start at "1" - this deletes the first two columns
sheet.deleteColumns(1, 2);

参数

名称	类型	说明
`columnPosition`	`Integer`	要删除的第一列的位置。
`howMany`	`Integer`	要删除的列数。

授权

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

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

`deleteRow(rowPosition)`

删除指定行位置的行。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Rows start at "1" - this deletes the first row
sheet.deleteRow(1);

参数

名称	类型	说明
`rowPosition`	`Integer`	行的编号，从第一行开始为 1。

Sheet - 工作表，适用于方法链接

授权

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

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

`deleteRows(rowPosition, howMany)`

从指定行位置开始删除多行。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Rows start at "1" - this deletes the first two rows
sheet.deleteRows(1, 2);

参数

名称	类型	说明
`rowPosition`	`Integer`	要删除的第一行的行号。
`howMany`	`Integer`	要删除的行数。

授权

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

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

`expandAllColumnGroups()`

展开工作表中的所有列组。此方法至少需要一个列组。

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

// All column groups on the sheet are expanded.
sheet.expandAllColumnGroups();

Sheet - 此工作表，用于链式调用。

授权

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

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

`expandAllRowGroups()`

展开工作表中的所有行组。此方法至少需要一个行组。

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

// All row groups on the sheet are expanded.
sheet.expandAllRowGroups();

Sheet - 此工作表，用于链式调用。

授权

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

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

`expandColumnGroupsUpToDepth(groupDepth)`

展开深度不超过给定深度的所有列组，并收起所有其他列组。

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

// All column groups of depth 2 and lower are expanded, and groups with depth
// 3 and higher are collapsed.
sheet.expandColumnGroupsUpToDepth(2);

参数

名称	类型	说明
`groupDepth`	`Integer`	列组的展开深度上限。

Sheet - 此工作表，用于链式调用。

授权

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

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

`expandRowGroupsUpToDepth(groupDepth)`

展开深度不超过给定深度的所有行组，并收起所有其他行组。

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

// All row groups of depth 2 and lower are expanded, and groups with depth
// 3 and higher are collapsed.
sheet.expandRowGroupsUpToDepth(2);

参数

名称	类型	说明
`groupDepth`	`Integer`	行组的最大展开深度。

Sheet - 此工作表，用于链式调用。

授权

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

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

`getActiveCell()`

返回此工作表中的活动单元格。

注意：最好使用 getCurrentCell()，它会返回当前突出显示的单元格。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Returns the active cell
const cell = sheet.getActiveCell();

Range - 当前的活动单元格

授权

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

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

`getActiveRange()`

返回活动工作表中的选定范围，如果没有活动范围，则返回 null。如果选择了多个范围，此方法只会返回最后一个所选范围。

“有效范围”一词是指用户在活动表格中选择的范围，但在自定义函数中，它是指正在积极重新计算的单元格。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
const activeRange = sheet.getActiveRange();

Range - 有效范围

授权

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

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

另请参阅

setActiveRange(range)

`getActiveRangeList()`

返回活动工作表中的有效范围列表，如果没有有效范围，则返回 null。

如果只选择了一个范围，则此操作的行为类似于 getActiveRange() 调用。

const sheet = SpreadsheetApp.getActiveSheet();
// Returns the list of active ranges.
const activeRangeList = sheet.getActiveRangeList();

RangeList - 有效范围的列表

授权

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

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

另请参阅

setActiveRangeList(rangeList)

`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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

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

// Gets info on the bandings' second row color and logs it to the console.
for (const banding of bandings) {
  console.log(banding.getSecondRowColor());
}

Banding[] - 此工作表中的所有分组。

授权

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

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

`getCharts()`

返回此工作表中的图表数组。

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

for (const i in charts) {
  const chart = charts[i];
  // Do something with the chart
}

EmbeddedChart[] - 图表数组。

授权

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

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

`getColumnGroup(columnIndex, groupDepth)`

返回指定索引和组深度的列组。

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

// Returns the group whose control index is at column 2 and has a depth of 1, or
// null if the group doesn’t exist.
const columnGroup = sheet.getColumnGroup(2, 1);

参数

名称	类型	说明
`columnIndex`	`Integer`	组控件切换开关的列编号或组内的编号。
`groupDepth`	`Integer`	群组的深度。

Group - 控制索引和深度处的列组，如果该组不存在，则抛出异常。

授权

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

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

`getColumnGroupControlPosition()`

返回工作表中所有列组的 GroupControlTogglePosition。

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

// GroupControlTogglePosition.AFTER if the column grouping control toggle is
// shown after the group.
const columnGroupControlPosition = sheet.getColumnGroupControlPosition();

GroupControlTogglePosition - 如果此工作表上的组后面显示列分组控件切换开关，则为 true；否则为 false。

授权

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

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

`getColumnGroupDepth(columnIndex)`

返回指定索引处列的组深度。

组深度表示与该列重叠的组数量。此值的范围介于 0 到 8 之间。

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

// 1 if there is a group over columns 1 through 3
const groupDepth = sheet.getColumnGroupDepth(1);

参数

名称	类型	说明
`columnIndex`	`Integer`	列的索引。

Integer - 给定索引处列的组深度。

授权

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

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

`getColumnWidth(columnPosition)`

获取给定列的宽度（以像素为单位）。

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

// Columns start at 1
Logger.log(sheet.getColumnWidth(1));

参数

名称	类型	说明
`columnPosition`	`Integer`	要检查的列的位置。

Integer - 列宽度（以像素为单位）

授权

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

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

`getConditionalFormatRules()`

获取此工作表中的所有条件格式规则。

// Logs the conditional format rules in a sheet.
const rules = SpreadsheetApp.getActiveSheet().getConditionalFormatRules();
for (let i = 0; i < rules.length; i++) {
  const rule = rules[i];
  Logger.log(rule);
}

ConditionalFormatRule[] - 工作表中所有规则的数组。

授权

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

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

`getCurrentCell()`

返回活动工作表中的当前单元格；如果没有当前单元格，则返回 null。当前单元格是 Google 表格界面中具有焦点的单元格，并带有深色边框。当前单元格永远不会超过一个。当用户选择一个或多个单元格范围时，所选范围中的某个单元格就是当前单元格。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
// Returns the current highlighted cell in the one of the active ranges.
const currentCell = sheet.getCurrentCell();

Range - 当前单元格

授权

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

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

`getDataRange()`

返回与数据所在的维度对应的 Range。

这在功能上等同于创建一个由 A1 和 (Sheet.getLastColumn(), Sheet.getLastRow()) 限定的 Range。

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

// This represents ALL the data
const range = sheet.getDataRange();
const values = range.getValues();

// This logs the spreadsheet in CSV format with a trailing comma
for (let i = 0; i < values.length; i++) {
  let row = '';
  for (let j = 0; j < values[i].length; j++) {
    if (values[i][j]) {
      row = row + values[i][j];
    }
    row = `${row},`;
  }
  Logger.log(row);
}

Range - 包含电子表格中所有数据的范围

授权

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

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

`getDataSourceFormulas()`

获取所有数据源公式。

// Opens the spreadsheet by its ID. If you created your script from within 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 an array of the data source formulas on Sheet1.
// To get an array of data source formulas for the entire spreadsheet,
// replace 'sheet' with 'ss'.
const dataSourceFormulas = sheet.getDataSourceFormulas();

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

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 an array of the data source pivot tables on Sheet1.
// To get an array of data source pivot tables for the entire
// spreadsheet, replace 'sheet' with 'ss'.
const dataSourcePivotTables = sheet.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 an array of data source tables on Sheet1.
// To get an array of data source tables for the entire spreadsheet,
// replace 'sheet' with 'ss'.
const dataSourceTables = sheet.getDataSourceTables();

// Logs the last completed data execution time on the first data source table.
console.log(dataSourceTables[0].getStatus().getLastExecutionTime());

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

授权

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

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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Adds developer metadata for testing.
sheet.addDeveloperMetadata('CITY', 'PARIS');

// Gets all the developer metadata for the sheet.
const developerMetaDataList = sheet.getDeveloperMetadata();

// Logs the developer metadata to the console.
for (const developerMetaData of developerMetaDataList) {
  console.log(developerMetaData.getKey());
}

DeveloperMetadata[] - 与此工作表关联的开发者元数据。

授权

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

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

`getDrawings()`

返回工作表上的绘图数组。

// 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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets all the drawings from the sheet.
const allDrawings = sheet.getDrawings();

// Logs the number of drawings present on the sheet.
console.log(allDrawings.length);

Drawing[] - 此工作表上的绘图列表。

授权

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

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

`getFilter()`

返回此工作表中的过滤条件；如果没有过滤条件，则返回 null。

// Gets the filter on the active sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();

Filter - 过滤器。

授权

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

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

`getFormUrl()`

返回将其回复发送到此工作表的表单的网址；如果此工作表没有关联的表单，则返回 null。如果用户无权修改电子表格，则会抛出异常。

const sheet = SpreadsheetApp.getActiveSheet();
const url = sheet.getFormUrl();

String - 将回复放置在此工作表中的表单的网址；如果此工作表没有关联的表单，则为 null。

授权

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

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

`getFrozenColumns()`

返回冻结列的数量。

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

Logger.log('Number of frozen columns: %s', sheet.getFrozenColumns());

Integer - 冻结列的数量

授权

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

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

`getFrozenRows()`

返回冻结的行数。

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

Logger.log('Number of frozen rows: %s', sheet.getFrozenRows());

Integer - 冻结行的数量

授权

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

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

`getImages()`

返回工作表中的所有网格外图片。

// Opens the spreadsheet file 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 over-the-grid images from Sheet1.
// To get the over-the-grid images from the entire spreadsheet, use
// ss.getImages() instead.
const images = sheet.getImages();

// For each image, logs the anchor cell in A1 notation.
for (const image of images) {
  console.log(image.getAnchorCell().getA1Notation());
}

OverGridImage[] - 一个网格上方图片数组。

授权

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

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

`getIndex()`

获取工作表在其父级电子表格中的位置。从 1 开始。

const ss = SpreadsheetApp.getActiveSpreadsheet();
// Note that the JavaScript index is 0, but this logs 1
const sheet = ss.getSheets()[0];
// ... because spreadsheets are 1-indexed
Logger.log(sheet.getIndex());

Integer - 工作表在其父级电子表格中的位置。

授权

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

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

`getLastColumn()`

返回包含内容的最后一列的位置。

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

// This logs the value in the very last cell of this sheet
const lastRow = sheet.getLastRow();
const lastColumn = sheet.getLastColumn();
const lastCell = sheet.getRange(lastRow, lastColumn);
Logger.log(lastCell.getValue());

Integer - 工作表中包含内容的最后一列

授权

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

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

`getLastRow()`

返回包含内容的最后一行的索引。

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

// This logs the value in the very last cell of this sheet
const lastRow = sheet.getLastRow();
const lastColumn = sheet.getLastColumn();
const lastCell = sheet.getRange(lastRow, lastColumn);
Logger.log(lastCell.getValue());

Integer - 包含内容的表格的最后一行

授权

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

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

`getMaxColumns()`

返回工作表中的当前列数（不考虑内容）。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
Logger.log(first.getMaxColumns());

Integer - 工作表的最大宽度。

授权

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

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

`getMaxRows()`

返回工作表中的当前行数（不考虑内容）。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
Logger.log(first.getMaxRows());

Integer - 工作表的最大高度。

授权

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

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

`getName()`

返回工作表的名称。

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

String - 工作表的名称。

授权

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

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

`getNamedRanges()`

获取此工作表中的所有命名范围。

// The code below logs the name of the first named range.
const namedRanges = SpreadsheetApp.getActiveSheet().getNamedRanges();
if (namedRanges.length > 1) {
  Logger.log(namedRanges[0].getName());
}

NamedRange[] - 工作表中所有命名范围的数组。

授权

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

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

`getParent()`

返回包含此工作表的 Spreadsheet。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// parent is identical to ss
const parent = sheet.getParent();

Spreadsheet - 父级电子表格。

授权

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

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

`getPivotTables()`

返回此工作表中的所有数据透视表。

// 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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets all the pivot table info for the sheet.
const pivotTables = sheet.getPivotTables();

// Logs the pivot tables to the console.
for (const pivotTable of pivotTables) {
  console.log(pivotTable.getSourceDataRange().getValues());
}

PivotTable[] - 此工作表中的数据透视表。

授权

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

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

`getProtections(type)`

获取一个对象数组，表示工作表中的所有受保护范围，或一个表示工作表本身保护状态的单元素数组。

// Remove all range protections in the spreadsheet that the user has permission
// to edit.
const sheet = SpreadsheetApp.getActiveSheet();
const protections = sheet.getProtections(SpreadsheetApp.ProtectionType.RANGE);
for (let i = 0; i < protections.length; i++) {
  const protection = protections[i];
  if (protection.canEdit()) {
    protection.remove();
  }
}

// Remove sheet protection from the active sheet, if the user has permission to
// edit it.
const sheet = SpreadsheetApp.getActiveSheet();
const protection = sheet.getProtections(SpreadsheetApp.ProtectionType.SHEET)[0];
if (protection?.canEdit()) {
  protection.remove();
}

参数

名称	类型	说明
`type`	`ProtectionType`	受保护区域的类型，`SpreadsheetApp.ProtectionType.RANGE` 或 `SpreadsheetApp.ProtectionType.SHEET`。

Protection[] - 一个对象数组，表示工作表中的所有受保护范围，或一个单元素数组，表示工作表本身的保护。

授权

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

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

`getRange(row, column)`

返回左上角单元格位于给定坐标的范围。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Passing only two arguments returns a "range" with a single cell.
const range = sheet.getRange(1, 1);
const values = range.getValues();
Logger.log(values[0][0]);

参数

名称	类型	说明
`row`	`Integer`	要返回的单元格的行索引；行索引从 1 开始。
`column`	`Integer`	要返回的单元格的列编号；列编号从 1 开始。

Range - 仅包含此单元格的范围。

授权

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

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

`getRange(row, column, numRows)`

返回左上角单元格位于给定坐标且行数为给定值的范围。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// When the "numRows" argument is used, only a single column of data is
// returned.
const range = sheet.getRange(1, 1, 3);
const values = range.getValues();

// Prints 3 values from the first column, starting from row 1.
for (const row in values) {
  for (const col in values[row]) {
    Logger.log(values[row][col]);
  }
}

参数

名称	类型	说明
`row`	`Integer`	范围的起始行索引；行索引从 1 开始。
`column`	`Integer`	范围的列索引；列索引从 1 开始。
`numRows`	`Integer`	要返回的行数。

Range - 包含指定行数的单列数据的范围。

授权

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

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

`getRange(row, column, numRows, numColumns)`

返回左上角单元格位于给定坐标且行数和列数为给定值的范围。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange(1, 1, 3, 3);
const values = range.getValues();

// Print values from a 3x3 box.
for (const row in values) {
  for (const col in values[row]) {
    Logger.log(values[row][col]);
  }
}

参数

名称	类型	说明
`row`	`Integer`	范围的起始行索引；行索引从 1 开始。
`column`	`Integer`	范围的起始列索引；列索引从 1 开始。
`numRows`	`Integer`	要返回的行数。
`numColumns`	`Integer`	要返回的列数。

Range - 与指定区域对应的范围。

授权

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

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

`getRange(a1Notation)`

返回 A1 表示法或 R1C1 表示法中指定的范围。

// Get a range A1:D4 on sheet titled "Invoices"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const range = ss.getRange('Invoices!A1:D4');

// Get cell A1 on the first sheet
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('A1');

参数

名称	类型	说明
`a1Notation`	`String`	要返回的范围，以 A1 表示法或 R1C1 表示法指定。

Range - 指定地点的范围

授权

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

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

`getRangeList(a1Notations)`

返回一个 RangeList 集合，表示由 A1 表示法或 R1C1 表示法组成的非空列表指定的同一工作表中的范围。

// Get a list of ranges A1:D4, F1:H4.
const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
const rangeList = sheet.getRangeList(['A1:D4', 'F1:H4']);

参数

名称	类型	说明
`a1Notations`	`String[]`	要返回的范围的列表，以 A1 表示法或 R1C1 表示法指定。

RangeList - 指定位置的范围列表

授权

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

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

`getRowGroup(rowIndex, groupDepth)`

返回指定索引和分组深度处的行组。

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

// Returns the group whose control index is at row 2 and has a depth of 1, or
// null if the group doesn’t exist.
const rowGroup = sheet.getRowGroup(2, 1);

参数

名称	类型	说明
`rowIndex`	`Integer`	组控件切换开关的行编号或组内的编号。
`groupDepth`	`Integer`	群组的深度。

Group - 控制索引和深度处的行组，如果该组不存在，则抛出异常。

授权

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

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

`getRowGroupControlPosition()`

返回工作表中所有行组的 GroupControlTogglePosition。

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

// GroupControlTogglePosition.AFTER if the row grouping control toggle is shown
// after the group.
const rowGroupControlPosition = sheet.getRowGroupControlPosition();

GroupControlTogglePosition - 如果此工作表中的分组后面显示行分组控件切换开关，则为 true；否则为 false。

授权

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

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

`getRowGroupDepth(rowIndex)`

返回指定索引处的行组深度。

组深度表示与该行重叠的组数量。此值的范围介于 0 到 8 之间。

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

// 1 if there is a group over rows 1 through 3
const groupDepth = sheet.getRowGroupDepth(1);

参数

名称	类型	说明
`rowIndex`	`Integer`	行的索引。

Integer - 给定索引处的行组深度。

授权

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

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

`getRowHeight(rowPosition)`

获取给定行的高度（以像素为单位）。

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

// Rows start at 1
Logger.log(sheet.getRowHeight(1));

参数

名称	类型	说明
`rowPosition`	`Integer`	要检查的行的位置。

Integer - 行高（以像素为单位）

授权

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

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

`getSelection()`

返回电子表格中的当前 Selection。

const selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
const currentCell = selection.getCurrentCell();

Selection - 当前选择

授权

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

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

`getSheetId()`

返回此对象所代表的工作表的 ID。

这是电子表格中唯一的电子表格 ID。该 ID 是在创建工作表时分配的单调递增整数，与工作表位置无关。这对于与 Range.copyFormatToRange(gridId, column, columnEnd, row, rowEnd) 等接受 gridId 参数（而非 Sheet 实例）的方法搭配使用非常有用。

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

Logger.log(sheet.getSheetId());

Integer - 电子表格中唯一的电子表格 ID

授权

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

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

`getSheetName()`

返回工作表名称。

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

Logger.log(sheet.getSheetName());

String - 工作表的名称

授权

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

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

`getSheetValues(startRow, startColumn, numRows, numColumns)`

返回从给定坐标开始的此范围的值矩形网格。将 -1 值作为行或列位置提供，相当于获取工作表中包含数据的最后一行或最后一列。

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

// The two samples below produce the same output
let values = sheet.getSheetValues(1, 1, 3, 3);
Logger.log(values);

const range = sheet.getRange(1, 1, 3, 3);
values = range.getValues();
Logger.log(values);

参数

名称	类型	说明
`startRow`	`Integer`	起始行的编号。
`startColumn`	`Integer`	起始列的位置。
`numRows`	`Integer`	要返回值的行数。
`numColumns`	`Integer`	要返回值的列数。

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

授权

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

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

`getSlicers()`

返回工作表上的切片器数组。

// 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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets all slicers in the spreadsheet.
const slicers = sheet.getSlicers();

// Logs the slicer titles to the console.
for (const slicer of slicers) {
  console.log(slicer.getTitle());
}

Slicer[] - 此工作表中的切片器列表。

授权

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

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

`getTabColorObject()`

获取工作表标签页的颜色；如果工作表标签页没有颜色，则返回 null。

// This example assumes there is a sheet named "Sheet1"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('Sheet1');
const color = first.getTabColorObject();

Color - 工作表标签页的颜色，如果工作表标签页没有颜色，则为 null。

授权

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

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

`getType()`

返回工作表的类型。

工作表的默认类型为 SheetType.GRID。包含单个嵌入对象（例如 EmbeddedChart）的工作表是 SheetType.OBJECT 工作表。

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

SheetType - 工作表的类型。

授权

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

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

`hasHiddenGridlines()`

如果工作表的网格线处于隐藏状态，则返回 true；否则返回 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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Checks if the spreadsheet has hidden gridelines and logs the result to the
// console.
console.log(sheet.hasHiddenGridlines());

Boolean - 如果网格线处于隐藏状态，则为 true；否则为 false。

授权

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

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

`hideColumn(column)`

隐藏指定范围中的列。

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

// This hides the first column
let range = sheet.getRange('A1');
sheet.hideColumn(range);

// This hides the first 3 columns
range = sheet.getRange('A:C');
sheet.hideColumn(range);

参数

名称	类型	说明
`column`	`Range`	要隐藏的列范围。

授权

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

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

`hideColumns(columnIndex)`

隐藏给定索引处的单个列。此方法使用 1 编号。

如需使用索引隐藏多列，请使用 hideColumns(columnIndex, numColumns)。

如需使用范围隐藏多列，请使用 hideColumn()。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Hides the first column
sheet.hideColumns(1);

参数

名称	类型	说明
`columnIndex`	`Integer`	要隐藏的列的索引。

授权

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

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

`hideColumns(columnIndex, numColumns)`

隐藏从给定索引开始的连续一列或多列。此方法使用 1 编号。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Hides the first three columns
sheet.hideColumns(1, 3);

参数

名称	类型	说明
`columnIndex`	`Integer`	要隐藏的列的起始索引。
`numColumns`	`Integer`	要隐藏的列数。

授权

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

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

`hideRow(row)`

隐藏给定范围中的行。

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

// This hides the first row
const range = sheet.getRange('A1');
sheet.hideRow(range);

参数

名称	类型	说明
`row`	`Range`	要隐藏的行范围。

授权

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

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

`hideRows(rowIndex)`

隐藏指定索引处的行。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Hides the first row
sheet.hideRows(1);

参数

名称	类型	说明
`rowIndex`	`Integer`	要隐藏的行索引。

授权

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

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

`hideRows(rowIndex, numRows)`

隐藏从给定索引开始的一条或多条连续行。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Hides the first three rows
sheet.hideRows(1, 3);

参数

名称	类型	说明
`rowIndex`	`Integer`	要隐藏的行数的起始索引。
`numRows`	`Integer`	要隐藏的行数。

授权

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

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

`hideSheet()`

隐藏此工作表。如果工作表已隐藏，则无效。如果对唯一可见的工作表调用此方法，则会抛出异常。

const sheet = SpreadsheetApp.getActiveSheet();
sheet.hideSheet();

Sheet - 当前工作表。

授权

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

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

`insertChart(chart)`

向此工作表添加新图表。

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

// This creates a simple bar chart from the first three rows
// of the first two columns of the spreadsheet
const chart = sheet.newChart()
                  .setChartType(Charts.ChartType.BAR)
                  .addRange(sheet.getRange('A1:B4'))
                  .setPosition(5, 5, 0, 0)
                  .setOption('title', 'Dynamic Chart')
                  .build();
sheet.insertChart(chart);

参数

名称	类型	说明
`chart`	`EmbeddedChart`	要插入的图表。

授权

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

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

`insertColumnAfter(afterPosition)`

在指定列位置后插入一列。

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

// This inserts a column after the first column position
sheet.insertColumnAfter(1);

参数

名称	类型	说明
`afterPosition`	`Integer`	新列应添加在该列后面。

Sheet - 工作表，适用于方法链接

授权

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

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

`insertColumnBefore(beforePosition)`

在指定列位置之前插入一列。

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

// This inserts a column in the first column position
sheet.insertColumnBefore(1);

参数

名称	类型	说明
`beforePosition`	`Integer`	新列应添加在该列之前。

Sheet - 工作表，适用于方法链接

授权

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

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

`insertColumns(columnIndex)`

在工作表的指定位置插入空白列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Shifts all columns by one
sheet.insertColumns(1);

参数

名称	类型	说明
`columnIndex`	`Integer`	指示要插入列的位置的索引。

授权

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

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

`insertColumns(columnIndex, numColumns)`

在工作表中从指定位置开始插入一个或多个连续的空白列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Shifts all columns by three
sheet.insertColumns(1, 3);

参数

名称	类型	说明
`columnIndex`	`Integer`	指示要插入列的位置的索引。
`numColumns`	`Integer`	要插入的列数。

授权

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

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

`insertColumnsAfter(afterPosition, howMany)`

在指定列位置后插入指定数量的列。

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

// Inserts two columns after the first column on the first sheet of the
// spreadsheet.
sheet.insertColumnsAfter(1, 2);

参数

名称	类型	说明
`afterPosition`	`Integer`	新列应添加在该列后面。
`howMany`	`Integer`	要插入的列数。

Sheet - 工作表，适用于方法链接

授权

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

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

`insertColumnsBefore(beforePosition, howMany)`

在指定列位置之前插入多列。

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

// This inserts five columns before the first column
sheet.insertColumnsBefore(1, 5);

参数

名称	类型	说明
`beforePosition`	`Integer`	新列应添加在该列之前。
`howMany`	`Integer`	要插入的列数。

Sheet - 工作表，适用于方法链接

授权

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

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

`insertImage(blobSource, column, row)`

将 BlobSource 作为图片插入文档中的指定行和列。系统会从 blob 内容中检索图片大小。支持的 BLOB 大小上限为 2MB。

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

const binaryData = [];  // TODO(developer): Replace with your binary data.
const blob = Utilities.newBlob(binaryData, 'image/png', 'MyImageName');
sheet.insertImage(blob, 1, 1);

参数

名称	类型	说明
`blobSource`	`BlobSource`	包含图片内容、MIME 类型和（可选）名称的 Blob。
`column`	`Integer`	列位置。
`row`	`Integer`	行位置。

OverGridImage - 插入的图片。

授权

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

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

`insertImage(blobSource, column, row, offsetX, offsetY)`

将 BlobSource 作为图片插入文档中的给定行和列，并带有像素偏移。系统会从 blob 内容中检索图片大小。支持的 BLOB 大小上限为 2MB。

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

const binaryData = [];  // TODO(developer): Replace with your binary data.
const blob = Utilities.newBlob(binaryData, 'image/png', 'MyImageName');
sheet.insertImage(blob, 1, 1, 10, 10);

参数

名称	类型	说明
`blobSource`	`BlobSource`	包含图片内容、MIME 类型和（可选）名称的 Blob。
`column`	`Integer`	列位置。
`row`	`Integer`	行位置。
`offsetX`	`Integer`	相对于单元格角的水平偏移量（以像素为单位）。
`offsetY`	`Integer`	相对于单元格角的垂直偏移量（以像素为单位）。

OverGridImage - 插入的图片。

授权

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

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

`insertImage(url, column, row)`

在文档中指定的行和列中插入图片。

提供的网址必须可公开访问。

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

sheet.insertImage('https://www.google.com/images/srpr/logo3w.png', 1, 1);

参数

名称	类型	说明
`url`	`String`	图片的网址。
`column`	`Integer`	网格列位置。
`row`	`Integer`	网格行位置。

OverGridImage - 插入的图片。

授权

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

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

`insertImage(url, column, row, offsetX, offsetY)`

在文档中指定行和列（并带有像素偏移量）插入图片。

提供的网址必须可公开访问。

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

sheet.insertImage(
    'https://www.google.com/images/srpr/logo3w.png',
    1,
    1,
    10,
    10,
);

参数

名称	类型	说明
`url`	`String`	图片的网址。
`column`	`Integer`	列位置。
`row`	`Integer`	行位置。
`offsetX`	`Integer`	相对于单元格角的水平偏移量（以像素为单位）。
`offsetY`	`Integer`	相对于单元格角的垂直偏移量（以像素为单位）。

OverGridImage - 插入的图片。

授权

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

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

`insertRowAfter(afterPosition)`

在指定的行位置后插入一行。

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

// This inserts a row after the first row position
sheet.insertRowAfter(1);

参数

名称	类型	说明
`afterPosition`	`Integer`	应在其后添加新行的行。

Sheet - 工作表，适用于方法链接

授权

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

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

`insertRowBefore(beforePosition)`

在给定行位置之前插入一行。

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

// This inserts a row before the first row position
sheet.insertRowBefore(1);

参数

名称	类型	说明
`beforePosition`	`Integer`	应在其前面添加新行的行。

Sheet - 工作表，适用于方法链接

授权

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

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

`insertRows(rowIndex)`

在工作表的指定位置插入空白行。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Shifts all rows down by one
sheet.insertRows(1);

参数

名称	类型	说明
`rowIndex`	`Integer`	用于指明要插入行的位置的编号。

授权

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

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

`insertRows(rowIndex, numRows)`

在工作表中从指定位置开始插入一个或多个连续的空白行。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Shifts all rows down by three
sheet.insertRows(1, 3);

参数

名称	类型	说明
`rowIndex`	`Integer`	用于指明要插入行的位置的编号。
`numRows`	`Integer`	要插入的行数。

授权

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

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

`insertRowsAfter(afterPosition, howMany)`

在指定的行位置后面插入多行。

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

// This inserts five rows after the first row
sheet.insertRowsAfter(1, 5);

参数

名称	类型	说明
`afterPosition`	`Integer`	应在其后添加新行的行。
`howMany`	`Integer`	要插入的行数。

Sheet - 工作表，适用于方法链接

授权

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

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

`insertRowsBefore(beforePosition, howMany)`

在指定的行位置之前插入多行。

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

// This inserts five rows before the first row
sheet.insertRowsBefore(1, 5);

参数

名称	类型	说明
`beforePosition`	`Integer`	应在其前面添加新行的行。
`howMany`	`Integer`	要插入的行数。

Sheet - 工作表，适用于方法链接

授权

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

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

`insertSlicer(range, anchorRowPos, anchorColPos)`

向此工作表添加新的切片器。

// 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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

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

// Inserts the slicer with a random range into the sheet.
const insertSlicers = sheet.insertSlicer(range.randomize(), 1, 10);

// Logs the insert slicer result to the console.
console.log(insertSlicers);

参数

名称	类型	说明
`range`	`Range`	用于创建 Slicer 的范围。
`anchorRowPos`	`Integer`	分屏器的顶部会固定在此行中。
`anchorColPos`	`Integer`	分屏的顶部会固定在此列中。

Slicer - 新插入的 Slicer。

授权

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

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

`insertSlicer(range, anchorRowPos, anchorColPos, offsetX, offsetY)`

向此工作表添加新的切片器。

// 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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

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

// Inserts a slicer using the random range function.
const insertSlicers = sheet.insertSlicer(range.randomize(), 1, 10, 0, 0);

// Logs the insert slicer result to the console.
console.log(insertSlicers);

参数

名称	类型	说明
`range`	`Range`	用于创建 Slicer 的范围。
`anchorRowPos`	`Integer`	分屏器的顶部会固定在此行中。
`anchorColPos`	`Integer`	分屏的顶部会固定在此列中。
`offsetX`	`Integer`	相对于单元格角的水平偏移量（以像素为单位）。
`offsetY`	`Integer`	相对于单元格角的垂直偏移量（以像素为单位）。

Slicer - 新插入的 Slicer。

授权

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

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

`isColumnHiddenByUser(columnPosition)`

返回指定列是否已被用户隐藏。

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

// Columns start at 1
Logger.log(sheet.isColumnHiddenByUser(1));

参数

名称	类型	说明
`columnPosition`	`Integer`	要检查的列的位置。

Boolean - 如果列处于隐藏状态，则为 true；否则为 false。

授权

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

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

`isRightToLeft()`

如果此工作表布局为从右到左，则返回 true。如果工作表使用默认的从左到右布局，则返回 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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Checks if a spreadsheet is ordered from right to left and logs the result to
// the console.
console.log(sheet.isRightToLeft());

Boolean - 如果是从右到左，则为 true；否则为 false。

授权

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

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

`isRowHiddenByFilter(rowPosition)`

返回给定行是否被过滤器（而非过滤器视图）隐藏。

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

// Rows start at 1
Logger.log(sheet.isRowHiddenByFilter(1));

参数

名称	类型	说明
`rowPosition`	`Integer`	要检查的行的位置。

Boolean - 如果行处于隐藏状态，则为 true；否则为 false。

授权

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

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

`isRowHiddenByUser(rowPosition)`

返回指定行是否已被用户隐藏。

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

// Rows start at 1
Logger.log(sheet.isRowHiddenByUser(1));

参数

名称	类型	说明
`rowPosition`	`Integer`	要检查的行的位置。

Boolean - 如果行处于隐藏状态，则为 true；否则为 false。

授权

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

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

`isSheetHidden()`

如果工作表当前处于隐藏状态，则返回 true。

const sheet = SpreadsheetApp.getActiveSheet();
if (sheet.isSheetHidden()) {
  // do something...
}

Boolean - 如果工作表处于隐藏状态，则为 true；否则为 false。

授权

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

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

`moveColumns(columnSpec, destinationIndex)`

将通过给定范围选择的列移至 destinationIndex 指示的位置。columnSpec 本身不必完全代表要移动的整列或一组列，它会选择该范围涵盖的所有列。

// The code below moves rows A-B to destination index 5.
// This results in those columns becoming columns C-D.
const sheet = SpreadsheetApp.getActiveSheet();
// Selects column A and column B to be moved.
const columnSpec = sheet.getRange('A1:B1');
sheet.moveColumns(columnSpec, 5);

参数

名称	类型	说明
`columnSpec`	`Range`	涵盖要移动的列的范围。
`destinationIndex`	`Integer`	列应移到的索引。请注意，此索引基于列移动前的坐标。现有数据会向右偏移，为移动的列腾出空间，同时源列会从网格中移除。因此，数据最终的索引可能与原先指定的索引不同。

授权

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

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

`moveRows(rowSpec, destinationIndex)`

将通过给定范围选择的行移至 destinationIndex 指示的位置。rowSpec 本身不必确切表示要移动的整行或一组行，它会选择该范围涵盖的所有行。

// The code below moves rows 1-2 to destination index 5.
// This results in those rows becoming rows 3-4.
const sheet = SpreadsheetApp.getActiveSheet();
// Selects row 1 and row 2 to be moved.
const rowSpec = sheet.getRange('A1:A2');
sheet.moveRows(rowSpec, 5);

参数

名称	类型	说明
`rowSpec`	`Range`	涵盖应移动的行范围。
`destinationIndex`	`Integer`	应将行移到的索引。请注意，此索引基于行移动前的坐标。现有数据会向下移，为移动的行腾出空间，同时源行会从网格中移除。因此，数据最终的索引可能与原先指定的索引不同。

授权

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

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

`newChart()`

返回一个构建器，用于为此工作表创建新图表。

以下示例展示了如何创建新图表：

const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('A1:B8');
const chartBuilder = sheet.newChart();
chartBuilder.addRange(range)
    .setChartType(Charts.ChartType.LINE)
    .setPosition(2, 2, 0, 0)
    .setOption('title', 'My Line Chart!');
sheet.insertChart(chartBuilder.build());

EmbeddedChartBuilder - 用于创建新图表的构建器。

`protect()`

创建一个对象，可保护工作表免遭修改，除非用户拥有相应权限。在脚本实际更改工作表的编辑者列表（通过调用 Protection.removeEditor(emailAddress)、Protection.removeEditor(user)、Protection.removeEditors(emailAddresses)、Protection.addEditor(emailAddress)、Protection.addEditor(user)、Protection.addEditors(emailAddresses) 或为 Protection.setDomainEdit(editable) 设置新值）之前，权限会与电子表格本身的权限保持一致，这实际上意味着工作表仍处于未保护状态。如果工作表已受保护，此方法会返回一个对象，表示其现有的保护设置。受保护的工作表可以包含不受保护的区域。

// Protect the active sheet, then remove all other users from the list of
// editors.
const sheet = SpreadsheetApp.getActiveSheet();
const protection = sheet.protect().setDescription('Sample protected sheet');

// Ensure the current user is an editor before removing others. Otherwise, if
// the user's edit permission comes from a group, the script throws an exception
// upon removing the group.
const me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

Protection - 表示保护设置的对象。

授权

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

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

`removeChart(chart)`

从父工作表中移除图表。

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

// This removes all the embedded charts from the spreadsheet
const charts = sheet.getCharts();
for (const i in charts) {
  sheet.removeChart(charts[i]);
}

参数

名称	类型	说明
`chart`	`EmbeddedChart`	要移除的图表。

授权

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

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

`setActiveRange(range)`

将指定范围设置为活动工作表中的 active range，并将该范围的左上角单元格设置为 current cell。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
const range = sheet.getRange('A1:D4');
sheet.setActiveRange(range);

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

参数

名称	类型	说明
`range`	`Range`	要设置为有效范围的范围。

Range - 新启用的范围

授权

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

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

`setActiveRangeList(rangeList)`

将指定的范围列表设置为活动工作表中的 active ranges。列表中的最后一个范围设为 active range。

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

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

参数

名称	类型	说明
`rangeList`	`RangeList`	要选择的范围列表。

RangeList - 新选择的范围列表

授权

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

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

`setActiveSelection(range)`

设置此工作表的有效选择区域。

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

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

参数

名称	类型	说明
`range`	`Range`	要设置为有效选择的范围。

Range - 新启用的范围

授权

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

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

`setActiveSelection(a1Notation)`

设置 A1 或 R1C1 表示法中指定的有效选择。

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

sheet.setActiveSelection('A1:D4');

参数

名称	类型	说明
`a1Notation`	`String`	要设置为有效的范围，以 A1 表示法或 R1C1 表示法指定。

Range - 新启用的范围

授权

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

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

`setColumnGroupControlPosition(position)`

设置工作表中列组控件切换开关的位置。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
sheet.setColumnGroupControlPosition(
    SpreadsheetApp.GroupControlTogglePosition.AFTER,
);

参数

名称	类型	说明
`position`	`GroupControlTogglePosition`	列组控件切换开关的位置。

Sheet - 此工作表，用于链式调用。

授权

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

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

`setColumnWidth(columnPosition, width)`

设置给定列的宽度（以像素为单位）。

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

// Sets the first column to a width of 200 pixels
sheet.setColumnWidth(1, 200);

参数

名称	类型	说明
`columnPosition`	`Integer`	要设置的给定列的位置。
`width`	`Integer`	要将其设置为的宽度（以像素为单位）。

Sheet - 工作表，适用于方法链接

授权

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

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

`setColumnWidths(startColumn, numColumns, width)`

设置给定列的宽度（以像素为单位）。

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

// Sets the first three columns to a width of 200 pixels
sheet.setColumnWidths(1, 3, 200);

参数

名称	类型	说明
`startColumn`	`Integer`	要更改的起始列位置。
`numColumns`	`Integer`	要更改的列数。
`width`	`Integer`	要将其设置为的宽度（以像素为单位）。

Sheet - 此工作表，用于链式调用。

授权

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

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

`setConditionalFormatRules(rules)`

将工作表中当前存在的所有条件格式规则替换为输入规则。系统会按照输入顺序评估规则。

// Remove one of the existing conditional format rules.
const sheet = SpreadsheetApp.getActiveSheet();
const rules = sheet.getConditionalFormatRules();
rules.splice(1, 1);  // Deletes the 2nd format rule.
sheet.setConditionalFormatRules(rules);

参数

名称	类型	说明
`rules`	`ConditionalFormatRule[]`	新的条件格式规则。

授权

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

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

`setCurrentCell(cell)`

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

如果指定的单元格位于已选范围内，则该范围会成为活动范围，该单元格会成为当前单元格。

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

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

const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
const cell = sheet.getRange('B5');
sheet.setCurrentCell(cell);

const selection = sheet.getSelection();
// Current cell: B5
const currentCell = selection.getCurrentCell();

参数

名称	类型	说明
`cell`	`Range`	要设置为当前单元格的单元格。

Range - 新设置的当前单元格

授权

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

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

`setFrozenColumns(columns)`

冻结指定数量的列。如果为零，则不会冻结任何列。

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

// Freezes the first column
sheet.setFrozenColumns(1);

参数

名称	类型	说明
`columns`	`Integer`	要冻结的列数。

授权

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

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

`setFrozenRows(rows)`

冻结指定的行数。如果为零，则不会冻结任何行。

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

// Freezes the first row
sheet.setFrozenRows(1);

参数

名称	类型	说明
`rows`	`Integer`	要冻结的行数。

授权

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

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

`setHiddenGridlines(hideGridlines)`

隐藏或显示工作表网格线。

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

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

// Hides the gridlines in the sheet.
sheet.setHiddenGridlines(true);

参数

名称	类型	说明
`hideGridlines`	`Boolean`	如果为 `true`，则隐藏此工作表中的网格线；否则显示网格线。

Sheet - 此工作表，用于链式调用。

授权

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

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

`setName(name)`

设置工作表名称。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.setName('not first anymore');

参数

名称	类型	说明
`name`	`String`	工作表的新名称。

Sheet - 此工作表，用于链式调用。

授权

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

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

`setRightToLeft(rightToLeft)`

将工作表布局设置为从右到左或取消设置。

// 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 a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Sets the sheet layout, so that the sheet is ordered from right to left.
sheet.setRightToLeft(true);

参数

名称	类型	说明
`rightToLeft`	`Boolean`	如果为 `true`，则工作表布局设为从右到左，单元格 A1 位于右上角。如果为 `false`，则工作表布局会设为默认的从左到右，其中单元格 A1 位于左上角。

Sheet - 此工作表，用于链式调用。

授权

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

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

`setRowGroupControlPosition(position)`

设置工作表中行组控件切换开关的位置。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
sheet.setRowGroupControlPosition(
    SpreadsheetApp.GroupControlTogglePosition.AFTER,
);

参数

名称	类型	说明
`position`	`GroupControlTogglePosition`	行组控件切换开关的位置。

Sheet - 此工作表，用于链式调用。

授权

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

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

`setRowHeight(rowPosition, height)`

以像素为单位设置指定行的行高。默认情况下，行会扩展以适应单元格内容。如果您想强制将行设为指定高度，请使用 setRowHeightsForced(startRow, numRows, height)。

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

// Sets the first row to a height of 200 pixels
sheet.setRowHeight(1, 200);

参数

名称	类型	说明
`rowPosition`	`Integer`	要更改的行位置。
`height`	`Integer`	要设置的高度（以像素为单位）。

Sheet - 工作表，适用于方法链接。

授权

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

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

`setRowHeights(startRow, numRows, height)`

以像素为单位设置指定行的高度。默认情况下，行会扩展以适应单元格内容。如果您想强制将行设为指定的高度，请使用 setRowHeightsForced(startRow, numRows, height)。

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

// Sets the first three rows to a height of 20 pixels
sheet.setRowHeights(1, 3, 20);

参数

名称	类型	说明
`startRow`	`Integer`	要更改的起始行位置。
`numRows`	`Integer`	要更改的行数。
`height`	`Integer`	要设置的高度（以像素为单位）。

Sheet - 此工作表，用于链式调用。

授权

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

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

`setRowHeightsForced(startRow, numRows, height)`

以像素为单位设置指定行的高度。默认情况下，行会扩展以适应单元格内容。使用 setRowHeightsForced 时，系统会强制将行设为指定高度，即使单元格内容的高度高于行高也是如此。

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

// Sets the first three rows to a height of 5 pixels.
sheet.setRowHeightsForced(1, 3, 5);

参数

名称	类型	说明
`startRow`	`Integer`	要更改的起始行位置。
`numRows`	`Integer`	要更改的行数。
`height`	`Integer`	要设置的高度（以像素为单位）。

Sheet - 此工作表，用于链式调用。

授权

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

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

`setTabColor(color)`

设置工作表标签页颜色。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.setTabColor('ff0000');  // Set the color to red.
first.setTabColor(null);      // Unset the color.

参数

名称	类型	说明
`color`	`String`	CSS 表示法中的颜色代码（例如 `'#ffffff'` 或 `'white'`），或 `null` 以重置标签页颜色。

Sheet - 此工作表，用于链式调用。

授权

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

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

`setTabColorObject(color)`

设置工作表标签页颜色。

// This example assumes there is a sheet named "Sheet1"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('Sheet1');
const color = SpreadsheetApp.newColor()
                  .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
                  .build();
first.setTabColorObject(color);  // Set the color to theme accent 1.
first.setTabColorObject(null);   // Unset the color.

参数

名称	类型	说明
`color`	`Color`	要设置的电子表格标签页颜色。

Sheet - 此工作表，用于链式调用。

授权

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

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

`showColumns(columnIndex)`

取消隐藏指定索引处的列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Unhides the first column
sheet.showColumns(1);

参数

名称	类型	说明
`columnIndex`	`Integer`	要取消隐藏的列的索引。

授权

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

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

`showColumns(columnIndex, numColumns)`

取消隐藏从给定编号开始的连续一列或多列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Unhides the first three columns
sheet.showColumns(1, 3);

参数

名称	类型	说明
`columnIndex`	`Integer`	要取消隐藏的列的起始索引。
`numColumns`	`Integer`	要取消隐藏的列数。

授权

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

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

`showRows(rowIndex)`

取消隐藏指定索引处的行。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Unhides the first row
sheet.showRows(1);

参数

名称	类型	说明
`rowIndex`	`Integer`	要取消隐藏的行索引。

授权

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

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

`showRows(rowIndex, numRows)`

取消隐藏从给定索引开始的一个或多个连续行。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Unhides the first three rows
sheet.showRows(1, 3);

参数

名称	类型	说明
`rowIndex`	`Integer`	要取消隐藏的行起始索引。
`numRows`	`Integer`	要取消隐藏的行数。

授权

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

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

`showSheet()`

使工作表可见。如果工作表已显示，则不会产生任何影响。

const sheet = SpreadsheetApp.getActiveSheet();
sheet.showSheet();

Sheet - 当前工作表。

授权

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

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

`sort(columnPosition)`

按列（升序）对工作表进行排序。

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

// Sorts the sheet by the first column, ascending
sheet.sort(1);

参数

名称	类型	说明
`columnPosition`	`Integer`	要用作排序依据的列。

Sheet - 工作表，适用于方法链接

授权

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

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

`sort(columnPosition, ascending)`

按列对工作表进行排序。接受一个参数来指定升序或降序。

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

// Sorts the sheet by the first column, descending
sheet.sort(1, false);

参数

名称	类型	说明
`columnPosition`	`Integer`	要用作排序依据的列。
`ascending`	`Boolean`	`true` 表示升序排序，`false` 表示降序排序。

Sheet - 工作表，适用于方法链接

授权

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

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

`unhideColumn(column)`

取消隐藏给定范围内的列。

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

// This unhides the first column if it was previously hidden
const range = sheet.getRange('A1');
sheet.unhideColumn(range);

参数

名称	类型	说明
`column`	`Range`	要取消隐藏的范围（如果已隐藏）。

授权

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

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

`unhideRow(row)`

取消隐藏给定范围中的行。

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

// This unhides the first row if it was previously hidden
const range = sheet.getRange('A1');
sheet.unhideRow(range);

参数

名称	类型	说明
`row`	`Range`	要取消隐藏的范围（如果已隐藏）。

授权

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

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

`updateChart(chart)`

更新此工作表中的图表。

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

// This code is going to loop through all the charts and change them to
// column charts
const charts = sheet.getCharts();
for (const i in charts) {
  const chart = charts[i];
  const newChart = chart.modify().setChartType(Charts.ChartType.COLUMN).build();
  sheet.updateChart(newChart);
}

参数

名称	类型	说明
`chart`	`EmbeddedChart`	要更新的图表。

授权

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

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

已弃用的方法

`getSheetProtection()`

已弃用。对于在较新版本的 Google 表格中创建的电子表格，请使用 getProtections(type)，它会返回功能更强大的 Protection 类。虽然此方法已废弃，但仍可用于与旧版 Google 表格兼容

返回一个 PageProtection 实例，用于描述当前工作表的权限。

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

const permissions = sheet.getSheetProtection();

permissions.setProtected(true);
permissions.addUser('user@example.com');

// Logs the users that have access to edit this sheet. Note that this
// is different from access to the entire spreadsheet - getUsers()
// only returns users if permissions.isProtected() is set to true.
const users = permissions.getUsers();
Logger.log(users);

PageProtection - 用于描述工作表访问权限的对象

授权

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

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

`getTabColor()`

已弃用。已替换为 getTabColorObject()

获取工作表标签页的颜色；如果工作表标签页没有颜色，则返回 null。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
const color = first.getTabColor();

String - CSS 表示法中的颜色代码（例如 '#ffffff'）。

授权

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

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

`setSheetProtection(permissions)`

已弃用。对于在较新版本的 Google 表格中创建的电子表格，请使用 protect()，它会返回功能更强大的 Protection 类。虽然此方法已废弃，但仍可用于与旧版 Google 表格兼容

设置当前工作表的权限。

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

const permissions = sheet.getSheetProtection();

// This copies the permissions on the first sheet to the second sheet
const sheetToClonePermissionsTo = ss.getSheets()[1];
sheetToClonePermissionsTo.setSheetProtection(permissions);

参数

名称	类型	说明
`permissions`	`PageProtection`	要在此工作表上设置的访问权限对象。

授权

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

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