访问和修改电子表格范围。范围可以是工作表中的单个单元格，也可以是工作表中一组相邻单元格。
方法
已弃用的方法
| 方法 | 返回类型 | 简介 |
|---|---|---|
| String | 返回范围左上角单元格的字体颜色，采用 CSS 表示法（例如 '#ffffff' 或 'white'）。 |
| String[][] | 以 CSS 表示法（例如 '#ffffff' 或 'white'）返回范围内单元格的字体颜色。 |
详细文档
activate()
将指定范围设置为 active range，并将范围中的左上角单元格设置为 current cell。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getRange('A1:D10');
range.activate();
const selection = sheet.getSelection();
// Current cell: A1
const currentCell = selection.getCurrentCell();
// Active Range: A1:D10
const activeRange = selection.getActiveRange();
返回
Range - 此范围，用于链式调用。
activateAsCurrentCell()
将指定单元格设置为 current cell。
如果指定的单元格位于现有范围内，则该范围将成为活动范围，其中该单元格为当前单元格。
如果指定的单元格不在任何现有范围内，则系统会移除现有选择，并将该单元格设为当前单元格和活动范围。
注意：指定的 Range 必须由一个单元格组成，否则会抛出异常。
// Gets the first sheet of the spreadsheet.
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
// Gets the cell B5 and sets it as the active cell.
const range = sheet.getRange('B5');
const currentCell = range.activateAsCurrentCell();
// Logs the activated cell.
console.log(currentCell.getA1Notation());
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
addDeveloperMetadata(key)
向范围添加具有指定键的开发者元数据。
// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');
// Adds the key 'NAME' to the developer metadata for row 2.
range.addDeveloperMetadata('NAME');
// Gets the metadata and logs it to the console.
const developerMetaData = range.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());
参数
| 名称 | 类型 | 说明 |
|---|---|---|
key | String | 新开发者元数据的键。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
addDeveloperMetadata(key, visibility)
向范围添加具有指定键和公开范围的开发者元数据。
// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Gets row 2 on Sheet1.
const range = sheet.getRange('2:2');
// Adds the key 'NAME' and sets the developer metadata visibility to 'DOCUMENT'
// for row 2 on Sheet1.
range.addDeveloperMetadata(
'NAME',
SpreadsheetApp.DeveloperMetadataVisibility.DOCUMENT,
);
// Gets the updated metadata info and logs it to the console.
const developerMetaData = range.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getVisibility().toString());
参数
| 名称 | 类型 | 说明 |
|---|---|---|
key | String | 新开发者元数据的键。 |
visibility | Developer | 新开发者元数据的公开范围。 |
返回
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 | Developer | 新开发者元数据的公开范围。 |
返回
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(),
);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
banding | Banding | 要应用于范围内列的颜色主题。 |
返回
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(),
);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
banding | Banding | 要应用于范围内列的颜色主题。 |
show | Boolean | 如果为 true，则将带状主题标题颜色应用于第一列。 |
show | 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);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
banding | Banding | 要应用于范围内行的颜色主题。 |
返回
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);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
banding | Banding | 要应用于范围内行的颜色主题。 |
show | Boolean | 如果为 true，则将带状主题标题颜色应用于第一行。 |
show | Boolean | 如果为 true，则将带状主题页脚颜色应用于最后一行。 |
返回
Banding - 新的分屏。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
autoFill(destination, series)
根据此范围内的数据，使用数据填充 destination。新值也由指定的 series 类型决定。目标范围必须包含此范围，并且只能将其向一个方向扩展。例如，以下代码会根据 A1:A4 中的当前值，使用一系列递增数字填充 A1:A20：
const sheet = SpreadsheetApp.getActiveSheet();
// Has values [1, 2, 3, 4].
const sourceRange = sheet.getRange('A1:A4');
// The range to fill with values.
const destination = sheet.getRange('A1:A20');
// Inserts new values in A5:A20, continuing the pattern expressed in A1:A4
sourceRange.autoFill(destination, SpreadsheetApp.AutoFillSeries.DEFAULT_SERIES);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
destination | Range | 要自动填充值的范围。目标范围应包含此范围，并且只能向一个方向（向上、向下、向左或向右）扩展。 |
series | Auto | 应用于计算新值的自动填充系列的类型。此系列的效果因源数据的类型和数量而异。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
autoFillToNeighbor(series)
计算要根据相邻单元格填充新数据的范围，并根据此范围中包含的数据自动用新值填充该范围。这些新值还取决于指定的 series 类型。
计算的目标范围会考虑周围数据，以确定应将新值插入到何处：如果自动填充的列的左侧或右侧有数据，则新值只会延伸到相邻数据。
例如，如果 A1:A20 填充了一系列递增的数字，并且对包含一系列日期的范围 B1:B4 调用了此方法，则新值只会插入 B5:B20。这样，这些新值就会“粘贴”到包含 A 列值的单元格中。
const sheet = SpreadsheetApp.getActiveSheet();
// A1:A20 has values [1, 2, 3, ... 20].
// B1:B4 has values [1/1/2017, 1/2/2017, ...]
const sourceRange = sheet.getRange('B1:B4');
// Results in B5:B20 having values [1/5/2017, ... 1/20/2017]
sourceRange.autoFillToNeighbor(SpreadsheetApp.AutoFillSeries.DEFAULT_SERIES);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
series | Auto | 应用于计算新值的自动填充系列的类型。此系列的效果因源数据的类型和数量而异。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
breakApart()
再次将范围中的所有多列单元格拆分为单个单元格。
对范围调用此函数相当于选择一个范围，然后依次点击格式 > 合并单元格 > 取消合并。
// Opens the spreadsheet by its URL. If you created your script from within a
// Google Sheets spreadsheet, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Gets the range A1:C6 on Sheet1.
const range = sheet.getRange('A1:C6');
// Unmerges the range A1:C6 into individual cells.
range.breakApart();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
canEdit()
确定用户是否有权修改范围内的每个单元格。电子表格所有者始终可以修改受保护的范围和工作表。
// Opens the spreadsheet by its URL. If you created your script from within a
// Google Sheets spreadsheet, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Gets the range A1:C6 on Sheet1.
const range = sheet.getRange('A1:C6');
// Logs whether the user has permission to edit every cell in the range.
console.log(range.canEdit());
返回
Boolean - 如果用户有权修改范围内的每个单元格，则返回 true；否则，返回 false。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
check()
将范围内复选框的状态更改为“已选中”。忽略范围内当前不包含已选中或未选中值的单元格。
// Changes the state of cells which currently contain either the checked or
// unchecked value configured in the range A1:B10 to 'checked'.
const range = SpreadsheetApp.getActive().getRange('A1:B10');
range.check();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
clear()
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 对象，如下所列。 |
高级参数
| 名称 | 类型 | 说明 |
|---|---|---|
comments | Boolean | 是否仅清除评论。 |
contents | Boolean | 是否仅清除内容。 |
format | Boolean | 是否仅清除格式；请注意，清除格式也会清除数据验证规则。 |
validations | Boolean | 是否仅清除数据验证规则。 |
skip | Boolean | 是否避免清除过滤后的行。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
clearContent()
清除范围的内容，但保留格式。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:D10');
range.clearContent();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
clearDataValidations()
清除相应范围的数据验证规则。
// Clear the data validation rules for cells A1:B5.
const range = SpreadsheetApp.getActive().getRange('A1:B5');
range.clearDataValidations();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
clearFormat()
清除此范围的格式。
这会清除范围中单元格或单元格的文本格式，但不会重置任何数字格式规则。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:D10');
range.clearFormat();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
clearNote()
清除给定单元格或单元格中的备注。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:D10');
range.clearNote();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
collapseGroups()
收起完全包含在范围内的所有组。如果没有任何组完全在范围内，则系统会收起部分位于范围内的最深展开的组。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getActiveRange();
// All row and column groups within the range are collapsed.
range.collapseGroups();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
copyFormatToRange(gridId, column, columnEnd, row, rowEnd)
将范围的格式复制到给定位置。如果目标范围大于或小于来源范围，则系统会相应地重复或截断来源。请注意，此方法仅复制格式。
如需详细了解 gridId 参数，请参阅 get。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const source = ss.getSheets()[0];
const range = source.getRange('B2:D4');
// This copies the formatting in B2:D4 in the source sheet to
// D4:F6 in the sheet with gridId 1555299895. Note that you can get the gridId
// of a sheet by calling sheet.getSheetId() or range.getGridId().
range.copyFormatToRange(1555299895, 4, 6, 4, 6);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
grid | Integer | 电子表格中工作表的唯一 ID，不考虑位置。 |
column | Integer | 目标范围的第一列。 |
column | Integer | 目标范围的结束列。 |
row | Integer | 目标范围的起始行。 |
row | Integer | 目标范围的结束行。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
另请参阅
copyFormatToRange(sheet, column, columnEnd, row, rowEnd)
将范围的格式复制到给定位置。如果目标范围大于或小于来源范围，则系统会相应地重复或截断来源。请注意，此方法仅复制格式。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const source = ss.getSheets()[0];
const destination = ss.getSheets()[1];
const range = source.getRange('B2:D4');
// This copies the formatting in B2:D4 in the source sheet to
// D4:F6 in the second sheet
range.copyFormatToRange(destination, 4, 6, 4, 6);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
sheet | Sheet | 目标工作表。 |
column | Integer | 目标范围的第一列。 |
column | Integer | 目标范围的结束列。 |
row | Integer | 目标范围的起始行。 |
row | Integer | 目标范围的结束行。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
copyTo(destination)
将数据从一个单元格范围复制到另一个单元格范围。系统会复制值和格式。
// The code below copies the first 5 columns over to the 6th column.
const sheet = SpreadsheetApp.getActiveSheet();
const rangeToCopy = sheet.getRange(1, 1, sheet.getMaxRows(), 5);
rangeToCopy.copyTo(sheet.getRange(1, 6));
参数
| 名称 | 类型 | 说明 |
|---|---|---|
destination | Range | 要复制到的目标范围；只有左上角的单元格位置相关。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
copyTo(destination, copyPasteType, transposed)
将数据从一个单元格范围复制到另一个单元格范围。
// The code below copies only the values of the first 5 columns over to the 6th
// column.
const sheet = SpreadsheetApp.getActiveSheet();
sheet.getRange('A:E').copyTo(
sheet.getRange('F1'),
SpreadsheetApp.CopyPasteType.PASTE_VALUES,
false,
);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
destination | Range | 要复制到的目标范围；只有左上角的单元格位置相关。 |
copy | Copy | 用于指定如何将范围内容粘贴到目标位置的类型。 |
transposed | Boolean | 是否应以转置的方向粘贴范围。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
copyTo(destination, options)
将数据从一个单元格范围复制到另一个单元格范围。默认情况下，系统会复制值和格式，但您可以使用高级实参替换此设置。
// The code below copies only the values of the first 5 columns over to the 6th
// column.
const sheet = SpreadsheetApp.getActiveSheet();
sheet.getRange('A:E').copyTo(sheet.getRange('F1'), {contentsOnly: true});
参数
| 名称 | 类型 | 说明 |
|---|---|---|
destination | Range | 要复制到的目标范围；只有左上角的单元格位置相关。 |
options | Object | 用于指定高级参数的 JavaScript 对象，如下所列。 |
高级参数
| 名称 | 类型 | 说明 |
|---|---|---|
format | Boolean | 表示应仅复制格式 |
contents | Boolean | 表示应仅复制内容 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
copyValuesToRange(gridId, column, columnEnd, row, rowEnd)
将范围的内容复制到给定位置。如果目标范围大于或小于来源范围，则会相应地重复或截断来源。
如需详细了解 gridId 参数，请参阅 get。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const source = ss.getSheets()[0];
const range = source.getRange('B2:D4');
// This copies the data in B2:D4 in the source sheet to
// D4:F6 in the sheet with gridId 0
range.copyValuesToRange(0, 4, 6, 4, 6);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
grid | Integer | 电子表格中工作表的唯一 ID，不考虑位置。 |
column | Integer | 目标范围的第一列。 |
column | Integer | 目标范围的结束列。 |
row | Integer | 目标范围的起始行。 |
row | Integer | 目标范围的结束行。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
另请参阅
copyValuesToRange(sheet, column, columnEnd, row, rowEnd)
将范围的内容复制到给定位置。如果目标范围大于或小于来源范围，则会相应地重复或截断来源。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const source = ss.getSheets()[0];
const destination = ss.getSheets()[1];
const range = source.getRange('B2:D4');
// This copies the data in B2:D4 in the source sheet to
// D4:F6 in the second sheet
range.copyValuesToRange(destination, 4, 6, 4, 6);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
sheet | Sheet | 目标工作表。 |
column | Integer | 目标范围的第一列。 |
column | Integer | 目标范围的结束列。 |
row | Integer | 目标范围的起始行。 |
row | Integer | 目标范围的结束行。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
createDataSourcePivotTable(dataSource)
根据数据源创建一个空的数据源数据透视表，并将其锚定在此范围内的第一个单元格。
此示例展示了如何创建和配置新的“数据源”数据透视表。
const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
const anchorCell = spreadsheet.getSheets()[0].getRange('A1');
const dataSource = spreadsheet.getDataSources()[0];
const pivotTable = anchorCell.createDataSourcePivotTable(dataSource);
pivotTable.addRowGroup('dataColumnA');
pivotTable.addColumnGroup('dataColumnB');
pivotTable.addPivotValue(
'dataColumnC',
SpreadsheetApp.PivotTableSummarizeFunction.SUM,
);
pivotTable.addFilter(
'dataColumnA',
SpreadsheetApp.newFilterCriteria().whenTextStartsWith('A').build(),
);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
data | Data | 用于创建数据透视表的数据源。 |
返回
Data - 新创建的数据源数据透视表。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
createDataSourceTable(dataSource)
根据数据源创建一个空数据源表，并将其锚定在此范围内的第一个单元格。
此示例展示了如何创建和配置新的数据源表。
const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
const anchorCell = spreadsheet.getSheets()[0].getRange('A1');
const dataSource = spreadsheet.getDataSources()[0];
const dataSourceTable =
anchorCell.createDataSourceTable(dataSource)
.addColumns('dataColumnA', 'dataColumnB', 'dataColumnC')
.addSortSpec('dataColumnA', true) // ascending=true
.addSortSpec('dataColumnB', false); // ascending=false
参数
| 名称 | 类型 | 说明 |
|---|---|---|
data | Data | 用于创建数据透视表的数据源。 |
返回
Data - 新创建的数据源表。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
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());
返回
Developer - 用于搜索此范围内的元数据的开发者元数据查找器。
createFilter()
创建一个过滤器，并将其应用于工作表中的指定范围。您无法在一个工作表中创建多个过滤器。如需在创建过滤条件后访问和修改过滤条件，请使用 get 或 Sheet.getFilter()。
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
// Creates a new filter and applies it to the range A1:C20 on the active sheet.
function createFilter() {
range.createFilter();
}
// Gets the filter and applies criteria that only shows cells that aren't empty.
function getFilterAddCriteria() {
const filter = range.getFilter();
const criteria =
SpreadsheetApp.newFilterCriteria().whenCellNotEmpty().build();
filter.setColumnFilterCriteria(2, criteria);
}
Grid 工作表（默认的工作表类型）创建过滤条件。网格工作表是指未连接到数据库的工作表。如需创建其他类型的过滤条件，请参阅以下内容：
- 使用
Pivot创建数据透视表过滤条件Table.addFilter(sourceDataColumn, filterCriteria) - 使用
Data为与数据库关联的工作表创建过滤条件Source Sheet.addFilter(columnName, filterCriteria) - 使用
Data为与数据库关联的数据透视表创建过滤器Source Pivot Table.addFilter(columnName, filterCriteria)
返回
Filter - 新过滤条件。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
createPivotTable(sourceData)
根据锚定在此范围内第一个单元格的指定 source 创建空数据透视表。
// 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());
参数
| 名称 | 类型 | 说明 |
|---|---|---|
source | Range | 用于创建数据透视表的数据。 |
返回
Pivot - 新创建的 Pivot。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
createTextFinder(findText)
为范围创建文本查找器，该查找器可查找和替换此范围中的文本。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getActiveRange();
// Creates a text finder for the range.
const textFinder = range.createTextFinder('dog');
// Returns the first occurrence of 'dog'.
const firstOccurrence = textFinder.findNext();
// Replaces the last found occurrence of 'dog' with 'cat' and returns the number
// of occurrences replaced.
const numOccurrencesReplaced = textFinder.replaceWith('cat');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
find | String | 要搜索的文本。 |
返回
Text - 范围的 Text
deleteCells(shiftDimension)
删除此单元格范围。工作表中按所提供维度排列的现有数据会向被删除的范围偏移。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:D10');
range.deleteCells(SpreadsheetApp.Dimension.COLUMNS);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
shift | Dimension | 要沿其移位现有数据的维度。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
expandGroups()
展开范围或控件切换开关与此范围相交的收起的组。控件切换开关位置是指控件切换开关显示的索引，该索引位于组的正前方或正后方，具体取决于设置。如果同一位置有多个组，系统会展开最浅层级的组。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getActiveRange();
// All row and column groups within the range are expanded.
range.expandGroups();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getA1Notation()
返回范围的字符串说明（采用 A1 表示法）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange(1, 1, 2, 5);
// Logs "A1:E2"
Logger.log(range.getA1Notation());
返回
String - 范围的字符串说明（采用 A1 表示法）。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getBackground()
返回范围（例如 '#ffffff'）中左上角单元格的背景颜色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B5');
Logger.log(cell.getBackground());
返回
String - 背景的颜色代码。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getBackgroundObject()
返回范围中左上角单元格的背景颜色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B5');
Logger.log(cell.getBackgroundObject().asRgbColor().asHexString());
返回
Color - 范围中左上角单元格的背景颜色。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getBackgroundObjects()
返回指定范围内单元格的背景颜色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B5:C6');
const bgColors = range.getBackgroundObjects();
for (const i in bgColors) {
for (const j in bgColors[i]) {
Logger.log(bgColors[i][j].asRgbColor().asHexString());
}
}
返回
Color[][] - 背景颜色的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getBackgrounds()
返回范围内单元格的背景颜色（例如 '#ffffff'）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B5:C6');
const bgColors = range.getBackgrounds();
for (const i in bgColors) {
for (const j in bgColors[i]) {
Logger.log(bgColors[i][j]);
}
}
返回
String[][] - 背景颜色代码的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getBandings()
返回应用于此范围中的任何单元格的所有条带。
// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Sets a range.
const range = sheet.getRange('A1:K50');
// Gets the banding info for the range.
const bandings = range.getBandings();
// Logs the second row color for each banding to the console.
for (const banding of bandings) {
console.log(banding.getSecondRowColor());
}
返回
Banding[] - 应用于此范围中的任何单元格的所有条带。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getCell(row, column)
返回范围内的给定单元格。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
// The row and column here are relative to the range
// getCell(1,1) in this code returns the cell at B2
const cell = range.getCell(1, 1);
Logger.log(cell.getValue());
参数
| 名称 | 类型 | 说明 |
|---|---|---|
row | Integer | 相对于范围的单元格行。 |
column | Integer | 相对于范围的单元格列。 |
返回
Range - 一个范围，其中包含指定坐标处的单个单元格。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getColumn()
返回此范围的起始列位置。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
// Logs "2.0"
Logger.log(range.getColumn());
返回
Integer - 范围在电子表格中的起始列位置。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getDataRegion()
返回在四个基准 Direction 中展开的范围的副本，以覆盖包含数据的所有相邻单元格。如果范围被空单元格（不包括对角线上的单元格）包围，则返回范围本身。这类似于在编辑器中选择范围并输入 Ctrl+A。
// Assume the active spreadsheet is blank.
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
sheet.getRange('C2').setValue(100);
sheet.getRange('B3').setValue(100);
sheet.getRange('D3').setValue(100);
sheet.getRange('C4').setValue(100);
// Logs "B2:D4"
Logger.log(sheet.getRange('C3').getDataRegion().getA1Notation());
返回
Range - 范围的数据区域或整个电子表格的范围。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getDataRegion(dimension)
如果指定的维度为 Dimension.ROWS，则返回展开的范围的副本（Direction.UP 和 Direction.DOWN）；如果维度为 Dimension.COLUMNS，则返回展开的范围的副本（Direction.NEXT 和 Direction.PREVIOUS）。范围的展开基于检测范围旁边的数据，这些数据的组织方式类似于表格。展开后的范围涵盖指定维度（包括表格边界）上包含数据的所有相邻单元格。如果原始范围在指定维度上被空单元格包围，则返回该范围本身。此方法类似于在编辑器中选择范围，然后为列输入
Ctrl+Space，或为行输入 Shift+Space。
// Assume the active spreadsheet is blank.
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
sheet.getRange('C2').setValue(100);
sheet.getRange('B3').setValue(100);
sheet.getRange('D3').setValue(100);
sheet.getRange('C4').setValue(100);
// Logs "C2:C4"
Logger.log(
sheet.getRange('C3')
.getDataRegion(SpreadsheetApp.Dimension.ROWS)
.getA1Notation(),
);
// Logs "B3:D3"
Logger.log(
sheet.getRange('C3')
.getDataRegion(SpreadsheetApp.Dimension.COLUMNS)
.getA1Notation(),
);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
dimension | Dimension | 要沿其展开范围的维度。 |
返回
Range - 范围的数据区域，或涵盖原始范围所跨列或行的范围。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getDataSourceFormula()
返回范围中第一个单元格的 Data；如果该单元格不包含数据源公式，则返回 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);
返回
Data - 单元格的 Data。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getDataSourceFormulas()
返回范围内单元格的 Data。
// 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());
返回
Data - Data 的数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
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());
返回
Data - 数据源数据透视表的列表。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
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());
返回
Data - 数据源表的列表。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getDataSourceUrl()
返回此范围内数据的网址，可用于创建图表和查询。
function doGet() {
const ss = SpreadsheetApp.openById(
'1khO6hBWTNNyvyyxvob7aoZTI9ZvlqqASNeq0e29Tw2c',
);
const sheet = ss.getSheetByName('ContinentData');
const range = sheet.getRange('A1:B8');
const template = HtmlService.createTemplateFromFile('piechart');
template.dataSourceUrl = range.getDataSourceUrl();
return template.evaluate();
}
<!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();
返回
Data - 数据以数据表格形式提供。
getDataTable(firstRowIsHeader)
将此范围内的数据作为 DataTable 返回。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:B7');
// Calling this method with "true" sets the first line to be the title of the
// axes
const datatable = range.getDataTable(true);
// Note that this doesn't build an EmbeddedChart, so you can't just use
// Sheet#insertChart(). To do that, use sheet.newChart().addRange() instead.
const chart = Charts.newBarChart()
.setDataTable(datatable)
.setOption('title', 'Your Title Here')
.build();
参数
| 名称 | 类型 | 说明 |
|---|---|---|
first | Boolean | 是否将第一行视为标题。 |
返回
Data - 数据以数据表格形式提供。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getDataValidation()
返回范围中左上角单元格的数据验证规则。如果未对单元格设置数据验证，此方法会返回 null。
// Log information about the data validation rule for cell A1.
const cell = SpreadsheetApp.getActive().getRange('A1');
const rule = cell.getDataValidation();
if (rule != null) {
const criteria = rule.getCriteriaType();
const args = rule.getCriteriaValues();
Logger.log('The data validation rule is %s %s', criteria, args);
} else {
Logger.log('The cell does not have a data validation rule.');
}
返回
Data - 范围中左上角单元格的数据验证规则。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getDataValidations()
返回范围中所有单元格的数据验证规则。如果未对给定单元格设置数据验证，此方法会针对该单元格在数组中的位置返回 null。
// Change existing data validation rules that require a date in 2013 to require
// a date in 2014.
const oldDates = [new Date('1/1/2013'), new Date('12/31/2013')];
const newDates = [new Date('1/1/2014'), new Date('12/31/2014')];
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange(1, 1, sheet.getMaxRows(), sheet.getMaxColumns());
const rules = range.getDataValidations();
for (let i = 0; i < rules.length; i++) {
for (let j = 0; j < rules[i].length; j++) {
const rule = rules[i][j];
if (rule != null) {
const criteria = rule.getCriteriaType();
const args = rule.getCriteriaValues();
if (criteria === SpreadsheetApp.DataValidationCriteria.DATE_BETWEEN &&
args[0].getTime() === oldDates[0].getTime() &&
args[1].getTime() === oldDates[1].getTime()) {
// Create a builder from the existing rule, then change the dates.
rules[i][j] = rule.copy().withCriteria(criteria, newDates).build();
}
}
}
}
range.setDataValidations(rules);
返回
Data - 与范围中的单元格关联的数据验证规则的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
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()}`);
}
返回
Developer - 与此范围关联的开发者元数据。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getDisplayValue()
返回范围中左上角单元格的显示值。该值为 String。显示的值会考虑日期、时间和货币格式，包括电子表格的语言区域设置自动应用的格式。空单元格会返回空字符串。
// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Gets cell A30 and sets its value to 'Test code.'
const cell = sheet.getRange('A30');
cell.setValue('Test code');
// Gets the value and logs it to the console.
console.log(cell.getDisplayValue());
返回
String - 此单元格中显示的值。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getDisplayValues()
返回此范围的值矩形网格。
返回显示值的二维数组，按行编制索引，然后按列编制索引。值是 String 对象。显示的值会考虑日期、时间和货币格式，包括电子表格的语言区域设置自动应用的格式。空单元格在数组中以空字符串表示。请注意，虽然范围索引从 1, 1 开始，但 JavaScript 数组的索引从 [0][0] 开始。
// The code below gets the displayed values for the range C2:G8
// in the active spreadsheet. Note that this is a JavaScript array.
const values =
SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getDisplayValues();
Logger.log(values[0][0]);
返回
String[][] - 值的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFilter()
返回此范围所属的工作表中的过滤条件；如果工作表中没有过滤条件，则返回 null。
const ss = SpreadsheetApp.getActiveSheet();
const range = ss.getRange('A1:C20');
// Gets the existing filter on the sheet that the given range belongs to.
const filter = range.getFilter();
返回
Filter - 过滤器。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontColorObject()
返回范围左上角单元格的字体颜色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getFontColorObject().asRgbColor().asHexString());
返回
Color - 范围中左上角单元格的字体颜色。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontColorObjects()
返回指定范围内单元格的字体颜色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
const results = range.getFontColorObjects();
for (const i in results) {
for (const j in results[i]) {
Logger.log(results[i][j].asRgbColor().asHexString());
}
}
返回
Color[][] - 与范围内的单元格关联的字体颜色的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontFamilies()
返回指定范围内单元格的字体系列。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
const results = range.getFontFamilies();
for (const i in results) {
for (const j in results[i]) {
Logger.log(results[i][j]);
}
}
返回
String[][] - 与范围中的单元格关联的字体系列的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontFamily()
返回范围左上角单元格的字体系列。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getFontFamily());
返回
String - 单元格的字体系列。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontLine()
获取范围左上角单元格的线条样式（'underline'、'line-through' 或 'none'）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getFontLine());
返回
String - 字体线。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontLines()
获取范围内单元格的线条样式（'underline'、'line-through' 或 'none'）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
const results = range.getFontLines();
for (const i in results) {
for (const j in results[i]) {
Logger.log(results[i][j]);
}
}
返回
String[][] - 与范围内的单元格关联的字体线条的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontSize()
返回范围左上角单元格的字体大小（以点为单位）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getFontSize());
返回
Integer - 字号（以磅为单位）。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontSizes()
返回指定范围内单元格的字体大小。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
const results = range.getFontSizes();
for (const i in results) {
for (const j in results[i]) {
Logger.log(results[i][j]);
}
}
返回
Integer[][] - 与范围内的单元格关联的文本字体大小的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontStyle()
返回范围左上角单元格的字体样式（'italic' 或 'normal'）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getFontStyle());
返回
String - 单元格中文本的字体样式。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontStyles()
返回指定范围内单元格的字体样式。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
const results = range.getFontStyles();
for (const i in results) {
for (const j in results[i]) {
Logger.log(results[i][j]);
}
}
返回
String[][] - 与范围内的单元格关联的文本字体样式的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontWeight()
返回范围左上角单元格的字体粗细（正常/粗体）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getFontWeight());
返回
String - 单元格中文本的字体粗细。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontWeights()
返回指定范围内单元格的字体粗细。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
const results = range.getFontWeights();
for (const i in results) {
for (const j in results[i]) {
Logger.log(results[i][j]);
}
}
返回
String[][] - 与范围内的单元格关联的文本的字体粗细的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFormula()
返回范围左上角单元格的公式（A1 表示法），如果单元格为空或不包含公式，则返回空字符串。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// This assumes you have a function in B5 that sums up
// B2:B4
const range = sheet.getRange('B5');
// Logs the calculated value and the formula
Logger.log(
'Calculated value: %s Formula: %s',
range.getValue(),
range.getFormula(),
);
返回
String - 单元格的公式。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFormulaR1C1()
返回给定单元格的公式（R1C1 表示法），如果没有，则返回 null。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B5');
const formula = range.getFormulaR1C1();
Logger.log(formula);
返回
String - 采用 R1C1 表示法的公式。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFormulas()
返回范围内单元格的公式（A1 表示法）。对于不含公式的单元格，二维数组中的条目为空字符串。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B5:C6');
const formulas = range.getFormulas();
for (const i in formulas) {
for (const j in formulas[i]) {
Logger.log(formulas[i][j]);
}
}
返回
String[][] - 字符串格式的公式二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFormulasR1C1()
返回范围中单元格的公式（R1C1 表示法）。对于没有公式的单元格，二维数组中的条目为 null。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B5:C6');
const formulas = range.getFormulasR1C1();
for (const i in formulas) {
for (const j in formulas[i]) {
Logger.log(formulas[i][j]);
}
}
返回
String[][] - 采用 R1C1 表示法的公式二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getGridId()
返回范围父工作表的网格 ID。ID 是随机的非负整数值。
// Log the grid ID of the first sheet (by tab position) in the spreadsheet.
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getGridId());
返回
Integer - 父工作表的网格 ID。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getHeight()
返回范围的高度。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
// logs 3.0
Logger.log(range.getHeight());
返回
Integer - 范围的高度。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getHorizontalAlignment()
返回范围左上角单元格的文本水平对齐方式（左/居中/右）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getHorizontalAlignment());
返回
String - 单元格中文本的水平对齐方式。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getHorizontalAlignments()
返回指定范围内单元格的水平对齐方式。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
const results = range.getHorizontalAlignments();
for (const i in results) {
for (const j in results[i]) {
Logger.log(results[i][j]);
}
}
返回
String[][] - 与范围中的单元格关联的文本水平对齐方式的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getLastColumn()
返回结束列位置。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
// Logs "4.0"
Logger.log(range.getLastColumn());
返回
Integer - 范围在电子表格中的结束列位置。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getLastRow()
返回结束行位置。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
// Logs "4.0"
Logger.log(range.getLastRow());
返回
Integer - 范围在电子表格中的结束行位置。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getMergedRanges()
返回一个 Range 对象数组，表示完全位于当前范围内或包含当前范围内至少一个单元格的合并单元格。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:B3');
const mergedRanges = range.getMergedRanges();
for (let i = 0; i < mergedRanges.length; i++) {
Logger.log(mergedRanges[i].getA1Notation());
Logger.log(mergedRanges[i].getDisplayValue());
}
返回
getNextDataCell(direction)
从范围的第一个列和行中的单元格开始，返回指定方向中的下一个单元格，该单元格是包含数据的连续单元格范围的边缘，或者是电子表格中相应方向的边缘单元格。这相当于在编辑器中输入
Ctrl+[arrow key]。
// Assume the active spreadsheet is blank.
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('C3:E5');
// Logs "C1"
Logger.log(range.getNextDataCell(SpreadsheetApp.Direction.UP).getA1Notation());
参数
| 名称 | 类型 | 说明 |
|---|---|---|
direction | Direction | 查找下一个数据区域边缘单元格的方向。 |
返回
Range - 数据区域边缘单元格或电子表格边缘的单元格。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getNote()
返回与给定范围关联的备注。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getNote());
返回
String - 与给定单元格关联的备注。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getNotes()
返回与范围中的单元格关联的备注。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
const results = range.getNotes();
for (const i in results) {
for (const j in results[i]) {
Logger.log(results[i][j]);
}
}
返回
String[][] - 与范围内的单元格关联的备注的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getNumColumns()
返回此范围中的列数。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D5');
Logger.log(range.getNumColumns());
返回
Integer - 此范围中的列数。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getNumRows()
返回此范围中的行数。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D5');
Logger.log(range.getNumRows());
返回
Integer - 此范围中的行数。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getNumberFormat()
获取给定范围左上角单元格的数字或日期格式。Google 表格 API 文档介绍了返回的格式模式。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('C4');
Logger.log(cell.getNumberFormat());
返回
String - 范围左上角单元格的数字格式。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getNumberFormats()
返回范围内单元格的数字或日期格式。Google 表格 API 文档中介绍了返回的格式模式。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B5:C6');
const formats = range.getNumberFormats();
for (const i in formats) {
for (const j in formats[i]) {
Logger.log(formats[i][j]);
}
}
返回
String[][] - 数字格式的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getRichTextValue()
返回范围左上角单元格的富文本值；如果单元格值不是文本，则返回 null。
// Gets the Rich Text value of cell D4.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('D4:F6');
const richText = range.getRichTextValue();
console.log(richText.getText());
返回
Rich - 范围中左上角单元格的富文本值；如果单元格值不是文本，则为 null。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getRichTextValues()
返回指定范围中单元格的富文本值。
// Gets the Rich Text values for all cells in range B5:C6
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B5:C6');
const values = range.getRichTextValues();
for (let i = 0; i < values.length; i++) {
for (let j = 0; j < values[i].length; j++) {
console.log(values[i][j].getText());
}
}
返回
Rich - 富文本值的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getRow()
返回此范围的行位置。与 get
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2');
Logger.log(range.getRow());
返回
Integer - 范围的行位置。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getRowIndex()
返回此范围的行位置。与 get
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2');
Logger.log(range.getRowIndex());
返回
Integer - 范围的行位置。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
另请参阅
getSheet()
返回此范围所属的工作表。
// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');
// Gets the sheet that the range belongs to.
const rangeSheet = range.getSheet();
// Gets the sheet name and logs it to the console.
console.log(rangeSheet.getName());
返回
Sheet - 此范围所属的工作表。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getTextDirection()
返回范围左上角单元格的文本方向。如果通过自动检测确定单元格文本方向，则返回 null。
// Get the text direction of cell B1.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B1:D4');
Logger.log(range.getTextDirection());
返回
Text - 范围中左上角单元格的文本方向。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getTextDirections()
返回指定范围内单元格的文本方向。对于使用自动检测的单元格，二维数组中的条目为 null。
// Get the text directions for all cells in range B5:C6
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B5:C6');
const directions = range.getTextDirections();
for (let i = 0; i < directions.length; i++) {
for (let j = 0; j < directions[i].length; j++) {
Logger.log(directions[i][j]);
}
}
返回
Text - 文本方向的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getTextRotation()
返回范围左上角单元格的文本旋转设置。
// Log the text rotation settings for a cell.
const sheet = SpreadsheetApp.getActiveSheet();
const cell = sheet.getRange('A1');
Logger.log(cell.getTextRotation());
返回
Text - 文本旋转设置。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getTextRotations()
返回指定范围内单元格的文本旋转设置。
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B2:D4');
const results = range.getTextRotations();
for (const i in results) {
for (const j in results[i]) {
const rotation = results[i][j];
Logger.log('Cell [%s, %s] has text rotation: %v', i, j, rotation);
}
}
返回
Text - 与范围中的单元格关联的文本旋转的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getTextStyle()
返回范围左上角单元格的文本样式。
// Get the text style of cell D4.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('D4:F6');
const style = range.getTextStyle();
Logger.log(style);
返回
Text - 范围中左上角单元格的文本样式。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getTextStyles()
返回指定范围内单元格的文本样式。
// Get the text styles for all cells in range B5:C6
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B5:C6');
const styles = range.getTextStyles();
for (let i = 0; i < styles.length; i++) {
for (let j = 0; j < styles[i].length; j++) {
Logger.log(styles[i][j]);
}
}
返回
Text - 文本样式的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getValue()
返回范围中左上角单元格的值。值的类型可以是 Number、Boolean、Date 或 String，具体取决于单元格的值。空单元格会返回空字符串。
// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');
// Gets the value of the top-left cell in the range and logs it to the console.
console.log(range.getValue());
返回
Object - 此单元格中的值。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getValues()
返回此范围的值矩形网格。
返回一个二维数组，其中值按行编号，然后按列编号。值的类型可以是 Number、Boolean、Date 或 String，具体取决于单元格的值。空单元格在数组中以空字符串表示。请注意，虽然范围索引从 1, 1 开始，但 JavaScript 数组的索引从 [0][0] 开始。
// The code below gets the values for the range C2:G8
// in the active spreadsheet. Note that this is a JavaScript array.
const values = SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getValues();
Logger.log(values[0][0]);
Date 值不是合法参数。如果范围包含值为 Date 的单元格，getValues() 将无法向 Web 应用返回数据。而是将从工作表中检索的所有值转换为受支持的 JavaScript 基元，例如 Number、Boolean 或 String。返回
Object[][] - 值的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getVerticalAlignment()
返回范围左上角单元格的垂直对齐方式（上/中/下）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getVerticalAlignment());
返回
String - 单元格中文本的垂直对齐方式。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getVerticalAlignments()
返回指定范围内单元格的垂直对齐方式。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
const results = range.getVerticalAlignments();
for (const i in results) {
for (const j in results[i]) {
Logger.log(results[i][j]);
}
}
返回
String[][] - 与范围中的单元格关联的文本垂直对齐方式的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getWidth()
返回范围的列数。
// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');
// Gets the width of the range in number of columns and logs it to the console.
console.log(range.getWidth());
返回
Integer - 范围中的列数。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getWrap()
返回单元格中的文本是否会换行。如需获取更精细的封装策略，请使用 get。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getWrap());
返回
Boolean - 此单元格中的文本是否换行。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getWrapStrategies()
返回范围内单元格的文本换行策略。
// Get the text wrapping strategies for all cells in range B5:C6
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B5:C6');
const strategies = range.getWrapStrategies();
for (let i = 0; i < strategies.length; i++) {
for (let j = 0; j < strategies[i].length; j++) {
Logger.log(strategies[i][j]);
}
}
返回
Wrap - 文本换行策略的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getWrapStrategy()
返回范围左上角单元格的文本换行策略。
// Get the text wrapping strategy of cell B1.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B1:D4');
Logger.log(range.getWrapStrategy());
返回
Wrap - 范围中左上角单元格的文本换行策略。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getWraps()
返回单元格中的文本是否换行。如需获取更精细的封装策略，请使用 get。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
const results = range.getVerticalAlignments();
for (const i in results) {
for (const j in results[i]) {
const isWrapped = results[i][j];
if (isWrapped) {
Logger.log('Cell [%s, %s] has wrapped text', i, j);
}
}
}
返回
Boolean[][] - 与范围中的单元格关联的文本垂直对齐方式的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
insertCells(shiftDimension)
将空白单元格插入此范围。新单元格会保留之前占据此范围的单元格中的所有格式设置。工作表中沿所提供维度的数据会从插入的范围移出。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:D10');
range.insertCells(SpreadsheetApp.Dimension.COLUMNS);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
shift | Dimension | 要沿其移位现有数据的维度。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
insertCheckboxes()
将复选框插入到范围中的每个单元格中，并将其配置为 true（已选中）和 false（未选中）。将范围内所有单元格的值设置为 false。
const range = SpreadsheetApp.getActive().getRange('A1:B10');
// Inserts checkboxes into each cell in the range A1:B10 configured with 'true'
// for checked and 'false' for unchecked. Also, sets the value of each cell in
// the range A1:B10 to 'false'.
range.insertCheckboxes();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
insertCheckboxes(checkedValue)
在范围内的每个单元格中插入复选框，并为勾选状态配置自定义值，为未勾选状态配置空字符串。将范围中每个单元的值设置为空字符串。
const range = SpreadsheetApp.getActive().getRange('A1:B10');
// Inserts checkboxes into each cell in the range A1:B10 configured with 'yes'
// for checked and the empty string for unchecked. Also, sets the value of each
// cell in the range A1:B10 to
// the empty string.
range.insertCheckboxes('yes');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
checked | Object | 复选框数据验证的已选值。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
insertCheckboxes(checkedValue, uncheckedValue)
在范围内的每个单元格中插入复选框，并为勾选和未勾选状态配置自定义值。将范围中每个单元格的值设置为自定义未选中值。
const range = SpreadsheetApp.getActive().getRange('A1:B10');
// Inserts checkboxes into each cell in the range A1:B10 configured with 'yes'
// for checked and 'no' for unchecked. Also, sets the value of each cell in the
// range A1:B10 to 'no'.
range.insertCheckboxes('yes', 'no');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
checked | Object | 复选框数据验证的已选值。 |
unchecked | Object | 复选框数据验证的未选中值。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
isBlank()
如果范围完全为空，则返回 true。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.isBlank());
返回
Boolean - 如果范围为空，则为 true；否则为 false。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
isChecked()
返回范围内所有单元格的复选框状态是否为“已选中”。如果某些单元格处于选中状态，而其余单元格处于未选中状态，或者某些单元格没有复选框数据验证，则返回 null。
const range = SpreadsheetApp.getActive().getRange('A1:A3');
// Inserts checkboxes and sets each cell value to 'no' in the range A1:A3.
range.insertCheckboxes('yes', 'no');
const range1 = SpreadsheetApp.getActive().getRange('A1');
range1.setValue('yes');
// Sets the value of isRange1Checked as true as it contains the checked value.
const isRange1Checked = range1.isChecked();
const range2 = SpreadsheetApp.getActive().getRange('A2');
range2.setValue('no');
// Sets the value of isRange2Checked as false as it contains the unchecked
// value.
const isRange2Checked = range2.isChecked();
const range3 = SpreadsheetApp.getActive().getRange('A3');
range3.setValue('random');
// Sets the value of isRange3Checked as null, as it contains an invalid checkbox
// value.
const isRange3Checked = range3.isChecked();
返回
Boolean - 如果范围内的所有单元格均已选中，则为 true；如果范围内的所有单元格均未选中，则为 false；如果任何单元格均未选中或未设置复选框数据验证，则为 null。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
isEndColumnBounded()
确定范围的结束位置是否绑定到特定列。例如，对于范围 A1:B10 或 B:B（绑定到范围末尾的列），此方法会返回 true；对于范围 3:7 或 A1:5（仅绑定到范围末尾的特定行），此方法会返回 false。
// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');
// Determines if the end of the range is bound to a particular column and logs
// it to the console.
console.log(range.isEndColumnBounded());
返回
Boolean - 如果范围的结束绑定到特定列，则为 true；否则为 false。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
isEndRowBounded()
确定范围的结束位置是否绑定到特定行。例如，对于范围 A1:B10 或 3:7（绑定到范围末尾的行），此方法会返回 true；对于范围 B:B 或 A1:C（仅绑定到范围末尾的特定列），此方法会返回 false。
// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');
// Determines if the end of the range is bound to a particular row and logs it
// to the console.
console.log(range.isEndRowBounded());
返回
Boolean - 如果范围的结束绑定到特定行，则为 true；否则为 false。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
isPartOfMerge()
如果当前范围中的单元格与任何合并的单元格重叠，则返回 true。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:B3');
// True if any of the cells in A1:B3 is included in a merge.
const isPartOfMerge = range.isPartOfMerge();
返回
Boolean - 如果范围与任何合并的单元格重叠，则返回 true；否则，返回 false。
isStartColumnBounded()
确定范围的起始位置是否绑定到特定列。例如，对于范围 A1:B10 或 B:B（绑定到范围开头的列），此方法会返回 true；对于范围 3:7（仅绑定到范围开头的行），此方法会返回 false。
// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');
// Determines if the start of the range is bound to a particular column and logs
// it to the console.
console.log(range.isStartColumnBounded());
返回
Boolean - 如果范围的起始位置绑定到特定列，则为 true；否则为 false。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
isStartRowBounded()
确定范围的起始位置是否绑定到特定行。例如，对于范围 A1:B10 或 3:7（绑定到范围开头的行），此方法会返回 true；对于范围 B:B（仅绑定到范围开头的特定列），此方法会返回 false。
// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
'https://docs.google.com/spreadsheets/d/abc123456/edit',
);
// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');
// Gets the range A1:D10 on Sheet1.
const range = sheet.getRange('A1:D10');
// Determines if the start of the range is bound to a particular row and logs it
// to the console.
console.log(range.isStartRowBounded());
返回
Boolean - 如果范围的起始位置绑定到特定行，则为 true；否则为 false。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
merge()
将范围中的单元格合并为一个单元格块。
const sheet = SpreadsheetApp.getActiveSheet();
// The code below 2-dimensionally merges the cells in A1 to B3
sheet.getRange('A1:B3').merge();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
mergeAcross()
合并范围中各列中的单元格。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// The code below merges cells C5:E5 into one cell
const range1 = sheet.getRange('C5:E5');
range1.mergeAcross();
// The code below creates 2 horizontal cells, F5:H5 and F6:H6
const range2 = sheet.getRange('F5:H6');
range2.mergeAcross();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
mergeVertically()
将范围中的单元格合并在一起。
const sheet = SpreadsheetApp.getActiveSheet();
// The code below vertically merges the cells in A1 to A10
sheet.getRange('A1:A10').mergeVertically();
// The code below creates 3 merged columns: B1 to B10, C1 to C10, and D1 to D10
sheet.getRange('B1:D10').mergeVertically();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
moveTo(target)
将此范围的内容（格式和值）剪切并粘贴到目标范围。
// The code below moves the first 5 columns over to the 6th column
const sheet = SpreadsheetApp.getActiveSheet();
sheet.getRange('A1:E').moveTo(sheet.getRange('F1'));
参数
| 名称 | 类型 | 说明 |
|---|---|---|
target | Range | 要将此范围复制到的目标范围；只有左上角单元格位置相关。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
offset(rowOffset, columnOffset)
返回一个新的范围，该范围相对于此范围向右偏移了指定的行数和列数（可以为负数）。新范围的大小与原始范围相同。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('A1');
// newCell references B2
const newCell = cell.offset(1, 1);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
row | Integer | 从范围的左上角单元格向下数的行数；负值表示从范围的左上角单元格向上数的行数。 |
column | Integer | 范围左上角单元格右侧的列数；负值表示范围左上角单元格左侧的列数。 |
返回
Range - 此范围，用于链式调用。
offset(rowOffset, columnOffset, numRows)
返回一个相对于当前范围的新范围，其左上角相对于当前范围向右偏移了指定的行数和列数，并且单元格高度为指定值。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('A1');
// newCell references B2:B3
const newRange = cell.offset(1, 1, 2);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
row | Integer | 从范围的左上角单元格向下数的行数；负值表示从范围的左上角单元格向上数的行数。 |
column | Integer | 范围左上角单元格右侧的列数；负值表示范围左上角单元格左侧的列数。 |
num | Integer | 新范围的行高。 |
返回
Range - 此范围，用于链式调用。
offset(rowOffset, columnOffset, numRows, numColumns)
返回相对于当前范围的新范围，其左上角相对于当前范围向右偏移了指定的行数和列数，并且单元格的高度和宽度为指定值。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('A1');
// newCell references B2:C3
const newRange = cell.offset(1, 1, 2, 2);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
row | Integer | 从范围的左上角单元格向下数的行数；负值表示从范围的左上角单元格向上数的行数。 |
column | Integer | 范围左上角单元格右侧的列数；负值表示范围左上角单元格左侧的列数。 |
num | Integer | 新范围的行高。 |
num | Integer | 新范围的列宽。 |
返回
Range - 此范围，用于链式调用。
protect()
创建一个对象，可保护相应范围免遭修改，除非用户拥有相应权限。在脚本实际更改范围的编辑者列表（通过调用 Protection.removeEditor(emailAddress)、Protection.removeEditor(user)、Protection.removeEditors(emailAddresses)、Protection.addEditor(emailAddress)、Protection.addEditor(user)、Protection.addEditors(emailAddresses) 或为 Protection.setDomainEdit(editable) 设置新值）之前，权限会与电子表格本身的权限保持一致，这实际上意味着该范围仍处于未保护状态。如果相应范围已受保护，此方法会创建与现有范围重叠的新受保护范围。如果某个单元格由多个受保护的范围保护，并且其中任一范围都阻止特定用户修改该单元格，则该用户将无法修改该单元格。
// Protect range A1:B10, then remove all other users from the list of editors.
const ss = SpreadsheetApp.getActive();
const range = ss.getRange('A1:B10');
const protection = range.protect().setDescription('Sample protected range');
// Ensure the current user is an editor before removing others. Otherwise, if
// the user's edit permission comes from a group, the script throws an exception
// upon removing the group.
const me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
protection.setDomainEdit(false);
}
返回
Protection - 表示保护设置的对象。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
randomize()
对指定范围内的行进行随机排序。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:C7');
// Randomizes the range
range.randomize();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
removeCheckboxes()
从范围中移除所有复选框。清除每个单元格的数据验证，如果单元格包含已选中或未选中值，还会清除其值。
const range = SpreadsheetApp.getActive().getRange('A1:B10');
// Inserts checkboxes and sets each cell value to 'no' in the range A1:B10.
range.insertCheckboxes('yes', 'no');
const range1 = SpreadsheetApp.getActive().getRange('A1');
range1.setValue('yes');
// Removes the checkbox data validation in cell A1 and clears its value.
range1.removeCheckboxes();
const range2 = SpreadsheetApp.getActive().getRange('A2');
range2.setValue('random');
// Removes the checkbox data validation in cell A2 but does not clear its value.
range2.removeCheckboxes();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
removeDuplicates()
移除此范围内包含与任何前一行值重复的值的行。即使行内的值字母大小写、格式设置、所用公式不一样，但是值相同，则均会被视为重复内容。此方法还会移除从视图中隐藏的重复行（例如，由于过滤器）。不在此范围内的内容不会被移除。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B1:D7');
// Remove duplicate rows in the range.
range.removeDuplicates();
返回
Range - 移除重复项后的结果范围。每次移除一行，范围的大小就会减少一行。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
removeDuplicates(columnsToCompare)
移除此范围内包含指定列中与任何前一行的值重复的值的行。即使行内的值字母大小写、格式设置、所用公式不一样，但是值相同，则均会被视为重复内容。此方法还会移除隐藏在视图中（例如，由于过滤器）的重复行。不在此范围内的内容不会被移除。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B1:D7');
// Remove rows which have duplicate values in column B.
range.removeDuplicates([2]);
// Remove rows which have duplicate values in both columns B and D.
range.removeDuplicates([2, 4]);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
columns | Integer[] | 要分析是否存在重复值的列。如果未提供任何列，则系统会分析所有列以查找重复项。 |
返回
Range - 移除重复项后的结果范围。每次移除一行，范围的大小就会减少一行。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setBackground(color)
使用 CSS 表示法（例如 '#ffffff' 或 'white'）设置范围内所有单元格的背景颜色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D5');
range.setBackground('red');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
color | String | CSS 表示法中的颜色代码（例如 '#ffffff' 或 'white'）；null 值会重置颜色。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setBackgroundObject(color)
设置范围内所有单元格的背景颜色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const bgColor = SpreadsheetApp.newColor()
.setThemeColor(SpreadsheetApp.ThemeColorType.BACKGROUND)
.build();
const range = sheet.getRange('B2:D5');
range.setBackgroundObject(bgColor);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
color | Color | 要设置的背景颜色；null 值会重置背景颜色。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setBackgroundObjects(color)
设置矩形背景颜色网格（必须与此范围的尺寸一致）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const colorAccent1 = SpreadsheetApp.newColor()
.setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
.build();
const colorAccent2 = SpreadsheetApp.newColor()
.setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
.build();
const colorAccent3 = SpreadsheetApp.newColor()
.setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
.build();
const colorAccent4 = SpreadsheetApp.newColor()
.setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4)
.build();
const colors = [
[colorAccent1, colorAccent2],
[colorAccent3, colorAccent4],
];
const cell = sheet.getRange('B5:C6');
cell.setBackgroundObjects(colors);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
color | Color[][] | 颜色的二维数组；null 值会重置颜色。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setBackgroundRGB(red, green, blue)
使用 RGB 值（介于 0 到 255 之间的整数）将背景设置为指定颜色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
// Sets the background to white
cell.setBackgroundRGB(255, 255, 255);
// Sets the background to red
cell.setBackgroundRGB(255, 0, 0);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
red | Integer | 采用 RGB 表示法的红色值。 |
green | Integer | 采用 RGB 表示法的绿色值。 |
blue | Integer | 蓝色值（采用 RGB 表示法）。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setBackgrounds(color)
设置矩形背景颜色网格（必须与此范围的尺寸一致）。颜色采用 CSS 表示法（例如 '#ffffff' 或 'white'）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const colors = [
['red', 'white', 'blue'],
['#FF0000', '#FFFFFF', '#0000FF'], // These are the hex equivalents
];
const cell = sheet.getRange('B5:D6');
cell.setBackgrounds(colors);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
color | String[][] | 采用 CSS 表示法（例如 '#ffffff' 或 'white'）的颜色二维数组；null 值会重置颜色。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setBorder(top, left, bottom, right, vertical, horizontal)
设置边框属性。有效值为 true（开启）、false（关闭）和 null（不更改）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
// Sets borders on the top and bottom, but leaves the left and right unchanged
cell.setBorder(true, null, true, null, false, false);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
top | Boolean | true 表示边框，false 表示无边框，null 表示无变化。 |
left | Boolean | true 表示边框，false 表示无边框，null 表示无变化。 |
bottom | Boolean | true 表示边框，false 表示无边框，null 表示无变化。 |
right | Boolean | true 表示边框，false 表示无边框，null 表示无变化。 |
vertical | Boolean | true 表示内部垂直边框，false 表示无边框，null 表示无变化。 |
horizontal | Boolean | true 表示内部水平边框，false 表示无边框，null 表示无变化。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setBorder(top, left, bottom, right, vertical, horizontal, color, style)
使用颜色和/或样式设置边框属性。有效值为 true（开启）、false（关闭）和 null（不更改）。对于颜色，请使用 CSS 表示法中的颜色（例如 '#ffffff' 或 'white'）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
// Sets borders on the top and bottom, but leaves the left and right unchanged
// Also sets the color to "red", and the border to "DASHED".
cell.setBorder(
true,
null,
true,
null,
false,
false,
'red',
SpreadsheetApp.BorderStyle.DASHED,
);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
top | Boolean | true 表示边框，false 表示无边框，null 表示无变化。 |
left | Boolean | true 表示边框，false 表示无边框，null 表示无变化。 |
bottom | Boolean | true 表示边框，false 表示无边框，null 表示无变化。 |
right | Boolean | true 表示边框，false 表示无边框，null 表示无变化。 |
vertical | Boolean | true 表示内部垂直边框，false 表示无边框，null 表示无变化。 |
horizontal | Boolean | true 表示内部水平边框，false 表示无边框，null 表示无变化。 |
color | String | CSS 表示法中的颜色（例如 '#ffffff' 或 'white'），null 表示默认颜色（黑色）。 |
style | Border | 边框的样式，null 表示默认样式（实线）。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setDataValidation(rule)
为范围内的所有单元格设置一条数据验证规则。
// Set the data validation rule for cell A1 to require a value from B1:B10.
const cell = SpreadsheetApp.getActive().getRange('A1');
const range = SpreadsheetApp.getActive().getRange('B1:B10');
const rule =
SpreadsheetApp.newDataValidation().requireValueInRange(range).build();
cell.setDataValidation(rule);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
rule | Data | 要设置的数据验证规则，或 null 以移除数据验证。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setDataValidations(rules)
为范围中的所有单元格设置数据验证规则。此方法接受一个二维数组的数据验证，按行编制索引，然后按列编制索引。数组维度必须与范围维度相对应。
// Set the data validation rules for Sheet1!A1:B5 to require a value from
// Sheet2!A1:A10.
const destinationRange =
SpreadsheetApp.getActive().getSheetByName('Sheet1').getRange('A1:B5');
const sourceRange =
SpreadsheetApp.getActive().getSheetByName('Sheet2').getRange('A1:A10');
const rule =
SpreadsheetApp.newDataValidation().requireValueInRange(sourceRange).build();
const rules = destinationRange.getDataValidations();
for (let i = 0; i < rules.length; i++) {
for (let j = 0; j < rules[i].length; j++) {
rules[i][j] = rule;
}
}
destinationRange.setDataValidations(rules);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
rules | Data | 要设置的数据验证规则的二维数组；null 值会移除数据验证。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontColor(color)
以 CSS 标记（例如 '#ffffff' 或 'white'）的形式设置字体颜色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
cell.setFontColor('red');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
color | String | CSS 表示法中的字体颜色（例如 '#ffffff' 或 'white'）；null 值会重置颜色。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontColorObject(color)
设置给定范围的字体颜色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const color = SpreadsheetApp.newColor()
.setThemeColor(SpreadsheetApp.ThemeColorType.TEXT)
.build();
const cell = sheet.getRange('B2');
cell.setFontColor(color);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
color | Color | 要设置的字体颜色；值为 null 会重置颜色。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontColorObjects(colors)
设置字体颜色的矩形网格（必须与此范围的尺寸一致）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const colorAccent1 = SpreadsheetApp.newColor()
.setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
.build();
const colorAccent2 = SpreadsheetApp.newColor()
.setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
.build();
const colorAccent3 = SpreadsheetApp.newColor()
.setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
.build();
const colorAccent4 = SpreadsheetApp.newColor()
.setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4)
.build();
const colors = [
[colorAccent1, colorAccent2],
[colorAccent3, colorAccent4],
];
const cell = sheet.getRange('B5:C6');
cell.setFontColorObjects(colors);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
colors | Color[][] | 颜色的二维数组；null 值会重置字体颜色。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontColors(colors)
设置字体颜色的矩形网格（必须与此范围的尺寸一致）。颜色采用 CSS 表示法（例如 '#ffffff' 或 'white'）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const colors = [
['red', 'white', 'blue'],
['#FF0000', '#FFFFFF', '#0000FF'], // These are the hex equivalents
];
const cell = sheet.getRange('B5:D6');
cell.setFontColors(colors);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
colors | Object[][] | 采用 CSS 表示法（例如 '#ffffff' 或 'white'）的颜色二维数组；null 值会重置颜色。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontFamilies(fontFamilies)
设置字体系列的矩形网格（必须与此范围的尺寸一致）。字体系列示例包括“Arial”或“Helvetica”。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const fonts = [
['Arial', 'Helvetica', 'Verdana'],
['Courier New', 'Arial', 'Helvetica'],
];
const cell = sheet.getRange('B2:D3');
cell.setFontFamilies(fonts);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
font | Object[][] | 字体系列的二维数组；null 值会重置字体系列。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontFamily(fontFamily)
设置字体系列，例如“Arial”或“Helvetica”。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
cell.setFontFamily('Helvetica');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
font | String | 要设置的字体系列；null 值会重置字体系列。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontLine(fontLine)
设置给定范围的字体线条样式（'underline'、'line-through' 或 'none'）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
cell.setFontLine('line-through');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
font | String | 字体线条样式，可选值为 'underline'、'line-through' 或 'none'；null 值会重置字体线条样式。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontLines(fontLines)
设置线条样式的矩形网格（必须与此范围的尺寸一致）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// The size of the two-dimensional array must match the size of the range.
const fontLines = [['underline', 'line-through', 'none']];
const range = sheet.getRange('B2:D2');
range.setFontLines(fontLines);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
font | Object[][] | 字体线条样式（'underline'、'line-through' 或 'none'）的二维数组；null 值会重置字体线条样式。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontSize(size)
设置字体大小，大小为要使用的点大小。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
cell.setFontSize(20);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
size | Integer | 字号（以磅为单位）。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontSizes(sizes)
设置字体大小的矩形网格（必须与此范围的尺寸一致）。尺寸以点为单位。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// The size of the two-dimensional array must match the size of the range.
const fontSizes = [[16, 20, 24]];
const range = sheet.getRange('B2:D2');
range.setFontSizes(fontSizes);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
sizes | Object[][] | 尺寸的二维数组。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontStyle(fontStyle)
为指定范围设置字体样式（'italic' 或 'normal'）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
cell.setFontStyle('italic');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
font | String | 字体样式，即 'italic' 或 'normal'；null 值会重置字体样式。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontStyles(fontStyles)
设置字体样式的矩形网格（必须与此范围的尺寸一致）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// The size of the two-dimensional array must match the size of the range.
const fontStyles = [['italic', 'normal']];
const range = sheet.getRange('B2:C2');
range.setFontStyles(fontStyles);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
font | Object[][] | 一个二维字体样式数组，值为 'italic' 或 'normal'；null 值会重置字体样式。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontWeight(fontWeight)
为指定范围设置字体粗细（正常/粗体）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
cell.setFontWeight('bold');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
font | String | 字体粗细，值为 'bold' 或 'normal'；null 值会重置字体粗细。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFontWeights(fontWeights)
设置字体粗细的矩形网格（必须与此范围的尺寸一致）。例如，“粗体”就是一种字体粗细。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// The size of the two-dimensional array must match the size of the range.
const fontStyles = [['bold', 'bold', 'normal']];
const range = sheet.getRange('B2:D2');
range.setFontWeights(fontStyles);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
font | Object[][] | 一个二维数组，其中包含字体粗细（'bold' 或 'normal'）；null 值会重置字体粗细。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFormula(formula)
更新此范围的公式。给定公式必须采用 A1 表示法。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B5');
cell.setFormula('=SUM(B3:B4)');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
formula | String | 表示要为单元格设置的公式的字符串。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFormulaR1C1(formula)
更新此范围的公式。给定公式必须采用 R1C1 表示法。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B5');
// This sets the formula to be the sum of the 3 rows above B5
cell.setFormulaR1C1('=SUM(R[-3]C[0]:R[-1]C[0])');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
formula | String | 字符串公式。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFormulas(formulas)
设置矩形公式网格（必须与此范围的尺寸一致）。给定公式必须采用 A1 表示法。此方法接受一个公式的二维数组，该数组按行编制索引，然后按列编制索引。数组维度必须与范围维度相对应。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// This sets the formulas to be a row of sums, followed by a row of averages
// right below. The size of the two-dimensional array must match the size of the
// range.
const formulas = [
['=SUM(B2:B4)', '=SUM(C2:C4)', '=SUM(D2:D4)'],
['=AVERAGE(B2:B4)', '=AVERAGE(C2:C4)', '=AVERAGE(D2:D4)'],
];
const cell = sheet.getRange('B5:D6');
cell.setFormulas(formulas);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
formulas | String[][] | 公式的二维字符串数组。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setFormulasR1C1(formulas)
设置矩形公式网格（必须与此范围的尺寸一致）。给定公式必须采用 R1C1 表示法。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// This creates formulas for a row of sums, followed by a row of averages.
const sumOfRowsAbove = '=SUM(R[-3]C[0]:R[-1]C[0])';
const averageOfRowsAbove = '=AVERAGE(R[-4]C[0]:R[-2]C[0])';
// The size of the two-dimensional array must match the size of the range.
const formulas = [
[sumOfRowsAbove, sumOfRowsAbove, sumOfRowsAbove],
[averageOfRowsAbove, averageOfRowsAbove, averageOfRowsAbove],
];
const cell = sheet.getRange('B5:D6');
// This sets the formula to be the sum of the 3 rows above B5.
cell.setFormulasR1C1(formulas);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
formulas | String[][] | 采用 R1C1 格式的公式二维数组。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setHorizontalAlignment(alignment)
为指定范围设置水平（从左到右）对齐方式（左/居中/右）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
cell.setHorizontalAlignment('center');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
alignment | String | 对齐方式，可以是 'left'、'center' 或 'normal'；null 值会重置对齐方式。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setHorizontalAlignments(alignments)
设置水平对齐的矩形网格。请参阅 set
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// The size of the two-dimensional array must match the size of the range.
const horizontalAlignments = [['left', 'right', 'center']];
const range = sheet.getRange('B2:D2');
range.setHorizontalAlignments(horizontalAlignments);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
alignments | Object[][] | 对齐方式的二维数组，值为 'left'、'center' 或 'normal'；null 值会重置对齐方式。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
另请参阅
setNote(note)
将备注设置为给定值。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
cell.setNote('This is a note');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
note | String | 要为范围设置的备注值；如果值为 null，则会移除备注。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setNotes(notes)
设置矩形的记事网格（必须与此范围的尺寸一致）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// The size of the two-dimensional array must match the size of the range.
const notes = [
['it goes', 'like this', 'the fourth, the fifth'],
['the minor fall', 'and the', 'major lift'],
];
const cell = sheet.getRange('B2:D3');
cell.setNotes(notes);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
notes | Object[][] | 备注的二维数组；null 值会移除备注。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
另请参阅
setNumberFormat(numberFormat)
将数字或日期格式设置为指定的格式字符串。Google 表格 API 文档中介绍了接受的格式模式。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
// Always show 3 decimal points
cell.setNumberFormat('0.000');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
number | String | 数字格式字符串。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setNumberFormats(numberFormats)
设置采用数字或日期格式的矩形网格（必须与此范围的尺寸一致）。这些值是格式模式字符串，如 Google 表格 API 文档中所述。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// The size of the two-dimensional array must match the size of the range.
const formats = [['0.000', '0,000,000', '$0.00']];
const range = sheet.getRange('B2:D2');
range.setNumberFormats(formats);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
number | Object[][] | 一个二维数组，其中包含数字格式。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setRichTextValue(value)
为范围内的单元格设置富文本值。
// Sets all cells in range B2:D4 to have the text "Hello world", with "Hello"
// bolded.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B2:D4');
const bold = SpreadsheetApp.newTextStyle().setBold(true).build();
const richText = SpreadsheetApp.newRichTextValue()
.setText('Hello world')
.setTextStyle(0, 5, bold)
.build();
range.setRichTextValue(richText);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
value | Rich | 所需的富文本值。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setRichTextValues(values)
设置由富文本值组成的矩形网格。
// Sets the cells in range A1:A2 to have Rich Text values.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('A1:A2');
const bold = SpreadsheetApp.newTextStyle().setBold(true).build();
const italic = SpreadsheetApp.newTextStyle().setItalic(true).build();
const richTextA1 = SpreadsheetApp.newRichTextValue()
.setText('This cell is bold')
.setTextStyle(bold)
.build();
const richTextA2 = SpreadsheetApp.newRichTextValue()
.setText('bold words, italic words')
.setTextStyle(0, 11, bold)
.setTextStyle(12, 24, italic)
.build();
range.setRichTextValues([[richTextA1], [richTextA2]]);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
values | Rich | 所需的富文本值。 |
返回
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);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
show | Boolean | 是否显示超链接。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setTextDirection(direction)
为范围内的单元格设置文本方向。如果指定的方向为 null，系统会推断方向，然后进行设置。
// Sets right-to-left text direction for the range.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B5:C6');
range.setTextDirection(SpreadsheetApp.TextDirection.RIGHT_TO_LEFT);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
direction | Text | 所需的文本方向；如果为 null，系统会在设置前推断方向。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setTextDirections(directions)
设置文本方向的矩形网格。如果指定的方向为 null，系统会推断方向，然后进行设置。
// Copies all of the text directions from range A1:B2 over to range C5:D6.
const sheet = SpreadsheetApp.getActiveSheet();
const range1 = sheet.getRange('A1:B2');
const range2 = sheet.getRange('C5:D6');
range2.setTextRotations(range1.getTextDirections());
参数
| 名称 | 类型 | 说明 |
|---|---|---|
directions | Text | 所需的文本方向；如果指定的方向为 null，则系统会在设置之前推断出方向。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setTextRotation(degrees)
为范围内的单元格设置文本旋转设置。输入值对应于标准文本方向与所需方向之间的角度。输入零表示文本设置为标准方向。
对于从左到右的文本方向，正角度为逆时针方向，而对于从右到左的文本方向，正角度为顺时针方向。
// Sets all cell's in range B2:D4 to have text rotated up 45 degrees.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B2:D4');
range.setTextRotation(45);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
degrees | Integer | 标准屏幕方向与所需屏幕方向之间的所需角度。 对于从左到右的文本，正角度为逆时针方向。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setTextRotation(rotation)
为范围内的单元格设置文本旋转设置。
// Sets all cell's in range B2:D4 to have the same text rotation settings as
// cell A1.
const sheet = SpreadsheetApp.getActiveSheet();
const rotation = sheet.getRange('A1').getTextRotation();
sheet.getRange('B2:D4').setTextRotation(rotation);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
rotation | Text | 所需的文字旋转设置。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setTextRotations(rotations)
设置文本旋转的矩形网格。
// Copies all of the text rotations from range A1:B2 over to range C5:D6.
const sheet = SpreadsheetApp.getActiveSheet();
const range1 = sheet.getRange('A1:B2');
const range2 = sheet.getRange('C5:D6');
range2.setTextRotations(range1.getTextRotations());
参数
| 名称 | 类型 | 说明 |
|---|---|---|
rotations | Text | 所需的文字旋转设置。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setTextStyle(style)
为范围内的单元格设置文本样式。
// Sets the cells in range C5:D6 to have underlined size 15 font.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('C5:D6');
const style =
SpreadsheetApp.newTextStyle().setFontSize(15).setUnderline(true).build();
range.setTextStyle(style);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
style | Text | 所需的文本样式。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setTextStyles(styles)
设置文本样式的矩形网格。
// Sets text styles for cells in range A1:B2
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('A1:B2');
const bold = SpreadsheetApp.newTextStyle().setBold(true).build();
const otherStyle = SpreadsheetApp.newTextStyle()
.setBold(true)
.setUnderline(true)
.setItalic(true)
.setForegroundColor('#335522')
.setFontSize(44)
.build();
range.setTextStyles([
[bold, otherStyle],
[otherStyle, bold],
]);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
styles | Text | 所需的文本样式。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setValue(value)
设置范围的值。值可以是数字、字符串、布尔值或日期。如果以 '=' 开头，则会被解读为公式。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
cell.setValue(100);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
value | Object | 范围的值。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setValues(values)
设置值的矩形网格（必须与此范围的维度一致）。如果值以 = 开头，则会被解读为公式。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// The size of the two-dimensional array must match the size of the range.
const values = [['2.000', '1,000,000', '$2.99']];
const range = sheet.getRange('B2:D2');
range.setValues(values);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
values | Object[][] | 值的二维数组。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setVerticalAlignment(alignment)
为给定范围（顶部/中间/底部）设置垂直（从上到下）对齐方式。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
cell.setVerticalAlignment('middle');
参数
| 名称 | 类型 | 说明 |
|---|---|---|
alignment | String | 对齐方式，可以是 'top'、'middle' 或 'bottom'；null 值会重置对齐方式。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setVerticalAlignments(alignments)
设置垂直对齐的矩形网格（必须与此范围的尺寸一致）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// The size of the two-dimensional array must match the size of the range.
const alignments = [['top', 'middle', 'bottom']];
const range = sheet.getRange('B2:D2');
range.setVerticalAlignments(alignments);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
alignments | Object[][] | 对齐方式的二维数组，值为 'top'、'middle' 或 'bottom'；null 值会重置对齐方式。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
另请参阅
setVerticalText(isVertical)
设置是否为范围内的单元格堆叠文本。如果文本是垂直堆叠的，系统会忽略文本旋转角度设置。
// Sets all cell's in range B2:D4 to have vertically stacked text.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B2:D4');
range.setVerticalText(true);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
is | Boolean | 是否堆叠文本。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setWrap(isWrapEnabled)
设置指定范围的单元格换行。
启用自动换行（默认）的单元格会调整大小以显示其完整内容。停用换行功能的单元格会在单元格中尽可能显示，而不会调整大小或换行。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('B2');
cell.setWrap(true);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
is | Boolean | 是否换行文本。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setWrapStrategies(strategies)
设置一个矩形网格的换行策略。
// Copies all of the wrap strategies from range A1:B2 over to range C5:D6.
const sheet = SpreadsheetApp.getActiveSheet();
const range1 = sheet.getRange('A1:B2');
const range2 = sheet.getRange('C5:D6');
range2.setWrapStrategies(range1.getWrapStrategies());
参数
| 名称 | 类型 | 说明 |
|---|---|---|
strategies | Wrap | 所需的换行策略。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setWrapStrategy(strategy)
为范围内的单元格设置文本换行策略。
// Sets all cells in range B2:D4 to use the clip wrap strategy.
const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('B2:D4');
range.setWrapStrategy(SpreadsheetApp.WrapStrategy.CLIP);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
strategy | Wrap | 所需的换行策略。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
setWraps(isWrapEnabled)
设置一个由换行政策组成的矩形网格（必须与此范围的尺寸一致）。启用自动换行（默认）的单元格会调整大小以显示其完整内容。停用换行功能的单元格会尽可能在单元格中显示，而不会调整大小或换行。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// The size of the two-dimensional array must match the size of the range.
const wraps = [[true, true, false]];
const range = sheet.getRange('B2:D2');
range.setWraps(wraps);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
is | Object[][] | 一个由换行变量组成的二维数组，用于确定是否在单元格中换行文本。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
另请参阅
shiftColumnGroupDepth(delta)
按指定的量更改范围的列分组深度。
这会创建、修改或删除与范围相交的组。对于正增量，系统会创建和/或修改组；对于负增量，系统会销毁和/或修改组。
如果将组深度减小到零以下或八以上，则不会产生任何影响。
如果 column group control position 为 BEFORE，则在尝试移位第一行的深度时会抛出错误。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getActiveRange();
// The column grouping depth is increased by 1.
range.shiftColumnGroupDepth(1);
// The column grouping depth is decreased by 1.
range.shiftColumnGroupDepth(-1);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
delta | Integer | 要更改此范围的列组深度的量。 |
返回
Range - 此范围，用于链式调用。
抛出
Error - 当控制位置为 Group 时，尝试移位第一列的深度
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
shiftRowGroupDepth(delta)
按指定的量更改范围的行分组深度。
这会创建、修改或删除与范围相交的组。对于正增量，系统会创建和/或修改组；对于负增量，系统会销毁和/或修改组。
如果将组深度减小到零以下或八以上，则不会产生任何影响。
如果 row group control position 为 BEFORE，则在尝试移位第一行的深度时会抛出错误。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getActiveRange();
// The row grouping depth is increased by 1.
range.shiftRowGroupDepth(1);
// The row grouping depth is decreased by 1.
range.shiftRowGroupDepth(-1);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
delta | Integer | 要更改此范围的行组深度的量。 |
返回
Range - 此范围，用于链式调用。
抛出
Error - 当控制位置为 Group 时，尝试移位第一行的深度
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
sort(sortSpecObj)
按指定的列和顺序对给定范围中的单元格进行排序。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('A1:C7');
// Sorts by the values in the first column (A)
range.sort(1);
// Sorts by the values in the second column (B)
range.sort(2);
// Sorts descending by column B
range.sort({column: 2, ascending: false});
// Sorts descending by column B, then ascending by column A
// Note the use of an array
range.sort([
{column: 2, ascending: false},
{column: 1, ascending: true},
]);
// For rows that are sorted in ascending order, the "ascending" parameter is
// optional, and just an integer with the column can be used instead. Note that
// in general, keeping the sort specification consistent results in more
// readable code. You can express the earlier sort as:
range.sort([{column: 2, ascending: false}, 1]);
// Alternatively, if you want all columns to be in ascending order, you can use
// the following (this makes column 2 ascending)
range.sort([2, 1]);
// ... which is equivalent to
range.sort([
{column: 2, ascending: true},
{column: 1, ascending: true},
]);
参数
| 名称 | 类型 | 说明 |
|---|---|---|
sort | Object | 要按其排序的列。 |
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
splitTextToColumns()
根据自动检测到的分隔符，将一列文本拆分为多列。
// A1:A3 has the following values:
// A B C
// 1 |one,one,one | | |
// 2 |two,two,two | | |
// 3 |three,three,three| | |
const range = SpreadsheetApp.getActiveSheet().getRange('A1:A3');
range.splitTextToColumns();
// Result after splitting the text to columns:
// A B C
// 1 |one |one |one |
// 2 |two |two |two |
// 3 |three |three |three |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
splitTextToColumns(delimiter)
使用指定字符串作为自定义分隔符，将一列文本拆分为多列。
// A1:A3 has the following values:
// A B C
// 1 |one#one#one | | |
// 2 |two#two#two | | |
// 3 |three#three#three| | |
const range = SpreadsheetApp.getActiveSheet().getRange('A1:A3');
range.splitTextToColumns('#');
// Result after splitting the text to columns:
// A B C
// 1 |one |one |one |
// 2 |two |two |two |
// 3 |three |three |three |
参数
| 名称 | 类型 | 说明 |
|---|---|---|
delimiter | String | 用于拆分的自定义分隔符。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
splitTextToColumns(delimiter)
根据指定的分隔符将一列文本拆分为多列。
// A1:A3 has the following values:
// A B C
// 1 |one;one;one | | |
// 2 |two;two;two | | |
// 3 |three;three;three| | |
const range = SpreadsheetApp.getActiveSheet().getRange('A1:A3');
range.splitTextToColumns(SpreadsheetApp.TextToColumnsDelimiter.SEMICOLON);
// Result after splitting the text to columns:
// A B C
// 1 |one |one |one |
// 2 |two |two |two |
// 3 |three |three |three |
参数
| 名称 | 类型 | 说明 |
|---|---|---|
delimiter | Text | 用于拆分的预设分隔符。 |
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
trimWhitespace()
剪除此范围中每个单元格中的空白（例如空格、制表符或换行符）。移除每个单元格文本开头和结尾的所有空格，并将剩余空格字符的任何子序列缩减为一个空格。
const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
const range = sheet.getRange('A1:A4');
range.activate();
range.setValues([
' preceding space',
'following space ',
'two middle spaces',
' =SUM(1,2)',
]);
range.trimWhitespace();
const values = range.getValues();
// Values are ['preceding space', 'following space', 'two middle spaces',
// '=SUM(1,2)']
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
uncheck()
将范围内复选框的状态更改为“未选中”。忽略范围内当前不包含已配置的选中或未选中值的单元格。
// Changes the state of cells which currently contain either the checked or
// unchecked value configured in the range A1:B10 to 'unchecked'.
const range = SpreadsheetApp.getActive().getRange('A1:B10');
range.uncheck();
返回
Range - 此范围，用于链式调用。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
已弃用的方法
getFontColor()
getFontColor()
已弃用。已替换为 get
返回范围左上角单元格的字体颜色，采用 CSS 表示法（例如 '#ffffff' 或 'white'）。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
Logger.log(range.getFontColor());
返回
String - CSS 表示法中的字体颜色（例如 '#ffffff' 或 'white'）。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets
getFontColors()
getFontColors()
已弃用。已替换为 get
以 CSS 表示法（例如 '#ffffff' 或 'white'）返回范围内单元格的字体颜色。
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange('B2:D4');
const results = range.getFontColors();
for (const i in results) {
for (const j in results[i]) {
Logger.log(results[i][j]);
}
}
返回
String[][] - 与范围内的单元格关联的字体颜色的二维数组。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权：
-
https://www.googleapis.com/auth/spreadsheets.currentonly -
https://www.googleapis.com/auth/spreadsheets