访问和创建 Google 表格文件。此类是电子表格服务的父类。
属性
媒体资源 | 类型 | 说明 |
---|---|---|
AutoFillSeries | AutoFillSeries | 用于计算自动填充值的系列类型的枚举。 |
BandingTheme | BandingTheme | 可能的条带主题的枚举。 |
BooleanCriteria | BooleanCriteria | 一个枚举,包含各种条件格式设置布尔值。 |
BorderStyle | BorderStyle | 枚举用于在 Range 上设置边框的有效样式。 |
ColorType | ColorType | 枚举可能的颜色类型。 |
CopyPasteType | CopyPasteType | 可能的粘贴类型的枚举。 |
DataExecutionErrorCode | DataExecutionErrorCode | 枚举可能的数据执行错误代码。 |
DataExecutionState | DataExecutionState | 枚举可能的数据执行状态。 |
DataSourceParameterType | DataSourceParameterType | 可能的数据源参数类型的枚举。 |
DataSourceRefreshScope | DataSourceRefreshScope | 一个枚举,列出可能的数据源刷新范围。 |
DataSourceType | DataSourceType | 对可能的数据源类型的枚举。 |
DataValidationCriteria | DataValidationCriteria | 表示可对范围设置的数据验证条件的枚举。 |
DateTimeGroupingRuleType | DateTimeGroupingRuleType | 日期时间分组规则的枚举。 |
DeveloperMetadataLocationType | DeveloperMetadataLocationType | 枚举可能的开发者元数据位置类型。 |
DeveloperMetadataVisibility | DeveloperMetadataVisibility | 枚举可能的开发者元数据可见性。 |
Dimension | Dimension | 枚举电子表格的可能维度。 |
Direction | Direction | 枚举用户在电子表格中使用箭头键可以移动的可能路线。 |
FrequencyType | FrequencyType | 枚举可能的频率类型。 |
GroupControlTogglePosition | GroupControlTogglePosition | 枚举组控件切换开关可处于的位置。 |
InterpolationType | InterpolationType | 一个枚举,包含各种条件格式渐变插值类型。 |
PivotTableSummarizeFunction | PivotTableSummarizeFunction | 可用于汇总数据透视表中的值的函数枚举。 |
PivotValueDisplayType | PivotValueDisplayType | 枚举数据透视值的显示方式。 |
ProtectionType | ProtectionType | 表示电子表格中可以防止修改的部分的枚举。 |
RecalculationInterval | RecalculationInterval | 枚举可用于重新计算电子表格的可能间隔。 |
RelativeDate | RelativeDate | 枚举相对日期选项,用于计算基于日期的 BooleanCriteria 中使用的值。 |
SheetType | SheetType | 枚举电子表格中可包含的不同表格类型。 |
SortOrder | SortOrder | 枚举排序顺序。 |
TextDirection | TextDirection | 有效文本路线的枚举。 |
TextToColumnsDelimiter | TextToColumnsDelimiter | 枚举用于将文本拆分到列的预设分隔符。 |
ThemeColorType | ThemeColorType | 枚举可能的主题颜色类型。 |
ValueType | ValueType | 由 Range.getValue() 和 Range.getValues() 从电子表格服务的 Range 类中返回的值类型的枚举。下面列出的枚举值是对 Number 、Boolean 、Date 或 String 的补充。 |
WrapStrategy | WrapStrategy | 用于换行单元格的策略的枚举。 |
方法
详细文档
create(name)
创建具有指定名称的新电子表格。
// The code below creates a new spreadsheet "Finances" and logs the URL for it var ssNew = SpreadsheetApp.create("Finances"); Logger.log(ssNew.getUrl());
参数
名称 | 类型 | 说明 |
---|---|---|
name | String | 电子表格的名称。 |
弃踢回攻
Spreadsheet
- 新电子表格
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets
create(name, rows, columns)
创建具有指定名称和指定行数和列数的新电子表格。
// The code below creates a new spreadsheet "Finances" with 50 rows and 5 columns and logs the // URL for it var ssNew = SpreadsheetApp.create("Finances", 50, 5); Logger.log(ssNew.getUrl());
参数
名称 | 类型 | 说明 |
---|---|---|
name | String | 电子表格的名称。 |
rows | Integer | 电子表格的行数。 |
columns | Integer | 电子表格的列数。 |
弃踢回攻
Spreadsheet
- 新电子表格
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets
enableAllDataSourcesExecution()
为所有类型的数据源开启数据执行功能。
如果数据源类型未开启,数据执行会抛出异常。使用此方法可为所有数据源类型开启数据执行功能。
// Turns data execution on for all types of data sources. SpreadsheetApp.enableAllDataSourcesExecution(); // 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 the first data source sheet in the spreadsheet and refreshes the data. ss.getDataSourceSheets()[0].refreshData();
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/bigquery.readonly
enableBigQueryExecution()
为 BigQuery 数据源开启数据执行功能。
如果未开启该功能,BigQuery 数据源的数据执行会抛出异常。
// Turns data execution on for BigQuery data sources. SpreadsheetApp.enableBigQueryExecution(); // 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 the first data source sheet in the spreadsheet and refreshes the BigQuery data. ss.getDataSourceSheets()[0].refreshData();
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/bigquery.readonly
flush()
应用所有待处理的电子表格更改。
为了提高性能(例如在多次调用 Range.getValue() 时),有时会将电子表格操作捆绑在一起。但是,有时您可能需要确保立即执行所有待更改项,例如在脚本执行时显示用户数据。
// The code below changes the background color of cells A1 and B1 twenty times. You should be // able to see the updates live in the spreadsheet. If flush() is not called, the updates may // be applied live or may all be applied at once when the script completes. function colors() { var sheet = SpreadsheetApp.getActiveSheet(); for (var i = 0; i < 20; i++) { if ((i % 2) == 0) { sheet.getRange('A1').setBackground('green'); sheet.getRange('B1').setBackground('red'); } else { sheet.getRange('A1').setBackground('red'); sheet.getRange('B1').setBackground('green'); } SpreadsheetApp.flush(); } }
getActive()
返回当前处于活动状态的电子表格,如果没有,则返回 null
。
通过调用此函数,在电子表格环境中运行的函数可以获取对相应电子表格对象的引用。
// The code below logs the URL for the active spreadsheet. Logger.log(SpreadsheetApp.getActive().getUrl());
弃踢回攻
Spreadsheet
- 有效的电子表格对象
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
getActiveRange()
返回当前工作表中的所选范围,如果没有有效范围,则返回 null
。如果选择了多个范围,则此方法仅返回最后选择的范围。
这通常是指用户在活动工作表中选择的范围,但在自定义函数中,它是指系统主动重新计算的单元格。
// The code below logs the background color for the active range. var colorObject = SpreadsheetApp.getActiveRange().getBackgroundObject(); // Assume the color has ColorType.RGB. Logger.log(colorObject.asRgbColor().asHexString());
弃踢回攻
Range
- 有效范围。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
getActiveRangeList()
返回活动工作表中的活动范围列表,如果未选择范围,则返回 null
。包含当前突出显示的单元格的有效范围会排在列表中的最后。
如果选择一个范围,则此行为将像 getActiveRange()
调用一样。
// Returns the list of active ranges. var rangeList = SpreadsheetApp.getActiveRangeList();
弃踢回攻
RangeList
- 有效范围的列表
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
getActiveSheet()
获取电子表格中的活动工作表。
电子表格中的有效工作表是指在电子表格界面中显示的工作表。
// The code below logs the name of the active sheet. Logger.log(SpreadsheetApp.getActiveSheet().getName());
弃踢回攻
Sheet
- 活动 Sheet 对象
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
getActiveSpreadsheet()
返回当前处于活动状态的电子表格,如果没有,则返回 null
。
在电子表格中运行的函数可以调用此函数,获取对相应 Spreadsheet
对象的引用。
// The code below logs the URL for the active spreadsheet. Logger.log(SpreadsheetApp.getActiveSpreadsheet().getUrl());
弃踢回攻
Spreadsheet
- 有效的电子表格对象
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
getCurrentCell()
返回在当前工作表中的一个活动范围中选择的当前(突出显示)单元格;如果当前没有单元格,则返回 null
。
// Returns the current highlighted cell in the one of the active ranges. var currentCell = SpreadsheetApp.getCurrentCell();
弃踢回攻
Range
- 当前单元格
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
getSelection()
getUi()
返回电子表格界面环境的实例,允许脚本添加菜单、对话框和边栏等功能。只有在脚本已绑定到电子表格的情况下,脚本才能与已打开电子表格的当前实例的界面交互。如需了解详情,请参阅菜单以及对话框和边栏指南。
// Add a custom menu to the active spreadsheet, including a separator and a sub-menu. function onOpen(e) { SpreadsheetApp.getUi() .createMenu('My Menu') .addItem('My menu item', 'myFunction') .addSeparator() .addSubMenu(SpreadsheetApp.getUi().createMenu('My sub-menu') .addItem('One sub-menu item', 'mySecondFunction') .addItem('Another sub-menu item', 'myThirdFunction')) .addToUi(); }
弃踢回攻
Ui
- 此电子表格的界面环境的实例
newCellImage()
为 CellImage
创建构建器。
// 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 on Sheet1. const range = sheet.getRange('A1'); // Builds an image using a source URL. const cellImage = SpreadsheetApp.newCellImage() .setSourceUrl('https://www.gstatic.com/images/branding/productlogos/apps_script/v10/web-64dp/logo_apps_script_color_1x_web_64dp.png') .build(); // Sets the image in cell A1. range.setValue(cellImage);
弃踢回攻
CellImageBuilder
- 新的构建器。
newColor()
为 Color
创建构建器。
var rgbColor = SpreadsheetApp.newColor().setRgbColor("#FF0000").build();
弃踢回攻
ColorBuilder
- 新的构建器。
newConditionalFormatRule()
为条件格式规则创建构建器。
// Adds a conditional format rule to a sheet that causes all cells in range A1:B3 to turn red // if they contain a number between 1 and 10. var sheet = SpreadsheetApp.getActive().getActiveSheet(); var range = sheet.getRange('A1:B3'); var rule = SpreadsheetApp.newConditionalFormatRule() .whenNumberBetween(1, 10) .setBackground("#FF0000") .setRanges([range]) .build() var rules = sheet.getConditionalFormatRules(); rules.push(rule); sheet.setConditionalFormatRules(rules);
弃踢回攻
ConditionalFormatRuleBuilder
- 新的构建器。
newDataSourceSpec()
为 DataSourceSpec
创建构建器。
// 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'); // Enables BigQuery. SpreadsheetApp.enableBigQueryExecution(); // Builds a data source specification. // TODO (developer): Update the project ID to your own Google Cloud project ID. const dataSourceSpec = SpreadsheetApp.newDataSourceSpec() .asBigQuery() .setProjectId('project-id-1') .setTableProjectId('bigquery-public-data') .setDatasetId('ncaa_basketball') .setTableId('mbb_historical_teams_games') .build(); // Adds the data source and its data to the spreadsheet. ss.insertDataSourceSheet(dataSourceSpec);
弃踢回攻
DataSourceSpecBuilder
- 新的构建器。
newDataValidation()
为数据验证规则创建构建器。
var cell = SpreadsheetApp.getActive().getRange('A1'); var rule = SpreadsheetApp.newDataValidation() .requireNumberBetween(1, 100) .setAllowInvalid(false) .setHelpText('Number must be between 1 and 100.') .build(); cell.setDataValidation(rule);
弃踢回攻
DataValidationBuilder
- 新的构建器。
newFilterCriteria()
为 FilterCriteria
创建构建器。
// 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 the range to A1:D20. const range = sheet.getRange('A1:D20'); // Creates a filter and applies it to the specified range. range.createFilter(); // Gets the current filter for the range and creates filter criteria that only shows cells // that aren't empty. const filter = range.getFilter(); const criteria = SpreadsheetApp.newFilterCriteria().whenCellNotEmpty().build(); // Sets the criteria to column C. filter.setColumnFilterCriteria(3, criteria);
弃踢回攻
FilterCriteriaBuilder
- 新的构建器
newRichTextValue()
为富文本值创建构建器。
// Sets cell A1 to have the text "Hello world", with "Hello" bolded. var cell = SpreadsheetApp.getActive().getRange('A1'); var bold = SpreadsheetApp.newTextStyle().setBold(true).build(); var value = SpreadsheetApp.newRichTextValue() .setText("Hello world") .setTextStyle(0, 5, bold) .build(); cell.setRichTextValue(value);
弃踢回攻
RichTextValueBuilder
- 新的构建器。
newTextStyle()
创建文本样式的构建器。
// Sets range A1:B3 to have red, size 22, bolded, underlined text. var range = SpreadsheetApp.getActive().getRange('A1:B3'); var style = SpreadsheetApp.newTextStyle() .setForegroundColor("red") .setFontSize(22) .setBold(true) .setUnderline(true) .build(); range.setTextStyle(style);
弃踢回攻
TextStyleBuilder
- 新的构建器。
open(file)
打开与指定 File 对象对应的电子表格。
// Get any starred spreadsheets from Google Drive, then open the spreadsheets and log the name // of the first sheet within each spreadsheet. var files = DriveApp.searchFiles( 'starred = true and mimeType = "' + MimeType.GOOGLE_SHEETS + '"'); while (files.hasNext()) { var spreadsheet = SpreadsheetApp.open(files.next()); var sheet = spreadsheet.getSheets()[0]; Logger.log(sheet.getName()); }
参数
名称 | 类型 | 说明 |
---|---|---|
file | File | 要打开的文件。 |
弃踢回攻
Spreadsheet
- 电子表格
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets
openById(id)
打开具有指定 ID 的电子表格。您可从电子表格的网址中提取电子表格 ID。例如,网址 https://docs.google.com/spreadsheets/d/abc1234567/edit#gid=0
中的电子表格 ID 为“abc1234567”。
// The code below opens a spreadsheet using its ID and logs the name for it. // Note that the spreadsheet is NOT physically opened on the client side. // It is opened on the server only (for modification by the script). var ss = SpreadsheetApp.openById("abc1234567"); Logger.log(ss.getName());
参数
名称 | 类型 | 说明 |
---|---|---|
id | String | 电子表格的唯一标识符。 |
弃踢回攻
Spreadsheet
- 具有指定 ID 的电子表格对象
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets
openByUrl(url)
打开具有指定网址的电子表格。如果网址不存在或用户无权访问,则会抛出脚本异常。
// Opens a spreadsheet by its URL and logs its name. // Note that the spreadsheet doesn't physically open on the client side. // It opens on the server only (for modification by the script). var ss = SpreadsheetApp.openByUrl( 'https://docs.google.com/spreadsheets/d/abc1234567/edit'); console.log(ss.getName());
参数
名称 | 类型 | 说明 |
---|---|---|
url | String | 电子表格的网址。 |
弃踢回攻
Spreadsheet
- 具有指定网址的电子表格对象。
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets
setActiveRange(range)
将指定范围设为 active range
,将范围左上角的单元格设为 current cell
。
电子表格界面显示包含所选范围的工作表,并选择在所选范围中定义的单元格。
// The code below sets range C1:D4 in the first sheet as the active range. var range = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0].getRange('C1:D4'); SpreadsheetApp.setActiveRange(range); var selection = SpreadsheetApp.getSelection(); // Current cell: C1 var currentCell = selection.getCurrentCell(); // Active Range: C1:D4 var activeRange = selection.getActiveRange();
参数
名称 | 类型 | 说明 |
---|---|---|
range | Range | 要设为有效范围的范围。 |
弃踢回攻
Range
- 新的有效范围
setActiveRangeList(rangeList)
将指定的范围列表设置为 active ranges
。列表中的最后一个范围被设置为 active range
。
// The code below sets ranges [D4, B2:C4] in the active sheet as the active ranges. var rangeList = SpreadsheetApp.getActiveSheet().getRanges(['D4', 'B2:C4']); SpreadsheetApp.setActiveRangeList(rangeList); var selection = SpreadsheetApp.getSelection(); // Current cell: B2 var currentCell = selection.getCurrentCell(); // Active range: B2:C4 var activeRange = selection.getActiveRange(); // Active range list: [D4, B2:C4] var activeRangeList = selection.getActiveRangeList();
参数
名称 | 类型 | 说明 |
---|---|---|
rangeList | RangeList | 要选择的范围列表。 |
弃踢回攻
RangeList
- 新选择的范围列表
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
setActiveSheet(sheet)
setActiveSheet(sheet, restoreSelection)
设置电子表格中活动工作表,并提供恢复该工作表中最近的所选内容的选项。Google 表格界面会显示所选的工作表,除非该工作表属于其他电子表格。
var spreadsheet = SpreadsheetApp.getActiveSpreadsheet(); var firstSheet = spreadsheet.getSheets()[0]; var secondSheet = spreadsheet.getSheets()[1]; // Set the first sheet as the active sheet and select the range D4:F4. spreadsheet.setActiveSheet(firstSheet).getRange('D4:F4').activate(); // Switch to the second sheet to do some work. spreadsheet.setActiveSheet(secondSheet); // Switch back to first sheet, and restore its selection. spreadsheet.setActiveSheet(firstSheet, true); // The selection of first sheet is restored, and it logs D4:F4 var range = spreadsheet.getActiveSheet().getSelection().getActiveRange(); Logger.log(range.getA1Notation());
参数
名称 | 类型 | 说明 |
---|---|---|
sheet | Sheet | 新的活动工作表。 |
restoreSelection | Boolean | 如果为 true ,则当新工作表变为活动状态时,系统会再次选择最近选择的活跃工作表;如果设置为 false ,则新工作表会变为活动状态,而不会更改当前选择。 |
弃踢回攻
Sheet
- 新的有效工作表
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets
setActiveSpreadsheet(newActiveSpreadsheet)
设置有效的电子表格。
// The code below makes the spreadsheet with key "1234567890" the active spreadsheet var ss = SpreadsheetApp.openById("1234567890"); SpreadsheetApp.setActiveSpreadsheet(ss);
参数
名称 | 类型 | 说明 |
---|---|---|
newActiveSpreadsheet | Spreadsheet | 要成为有效电子表格的电子表格。 |
setCurrentCell(cell)
将指定单元格设置为 current cell
。
如果指定单元格存在于已选择的范围内,则该范围会成为活动范围,并且该单元格是当前单元格。
如果指定的单元格不在任何选定范围内,系统会移除现有所选内容,并将该单元格变成当前单元格和活动范围。
注意:指定的 Range
必须包含一个单元格,否则此方法会抛出异常。
// The code below sets the cell B5 in the first sheet as the current cell. var cell = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0].getRange('B5'); SpreadsheetApp.setCurrentCell(cell); var selection = SpreadsheetApp.getSelection(); // Current cell: B5 var currentCell = selection.getCurrentCell();
参数
名称 | 类型 | 说明 |
---|---|---|
cell | Range | 要设为当前单元格的单元格。 |
弃踢回攻
Range
- 新设置的当前单元格
授权
使用此方法的脚本需要获得以下一个或多个范围的授权:
-
https://www.googleapis.com/auth/spreadsheets.currentonly
-
https://www.googleapis.com/auth/spreadsheets