* // The code below creates a new spreadsheet "Finances" and logs the URL for it
* var ssNew = SpreadsheetApp.create("Finances");
* Logger.log(ssNew.getUrl());
*
* // 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());
* Data execution throws an exception if the data source type is not enabled. Use this method * to enable data execution for all data source types. */ function enableAllDataSourcesExecution(): void /** * Enables data execution for BigQuery data source. * *
Data execution for BigQuery data source throws an expection if not enabled. */ function enableBigQueryExecution(): void /** * Applies all pending Spreadsheet changes. * *
Spreadsheet operations are sometimes bundled together to improve performance, such as when * doing multiple calls to Range.getValue(). However, sometimes you may want to make sure that all * pending changes are made right away, for instance to show users data as a script is executing. * *
* // 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();
* }
* }
* null if there is none.
*
* Functions that are run in the context of a spreadsheet can get a reference to the * corresponding Spreadsheet object by calling this function. * *
* // The code below logs the URL for the active spreadsheet.
* Logger.log(SpreadsheetApp.getActive().getUrl());
* null if there is no active range. If
* multiple ranges are selected this method returns only the last selected range.
*
* This generally means the range that a user has selected in the active sheet, but in a custom * function it refers to the cell being actively recalculated. * *
* // The code below logs the background color for the active range.
* var color = SpreadsheetApp.getActiveRange().getBackgroundColor();
* Logger.log(color);
* null if there are no ranges
* selected. The active range containing the current highlighted cell is placed last in the list.
*
* If there is a single range selected, this behaves as a getActiveRange() call.
*
*
* // Returns the list of active ranges.
* var rangeList = SpreadsheetApp.getActiveRangeList();
* The active sheet in a spreadsheet is the sheet that is being displayed in the spreadsheet * UI. * *
* // The code below logs the name of the active sheet.
* Logger.log(SpreadsheetApp.getActiveSheet().getName());
* null if there is none.
*
* Functions that are run in the context of a spreadsheet can get a reference to the
* corresponding Spreadsheet object by calling this function.
*
*
* // The code below logs the URL for the active spreadsheet.
* Logger.log(SpreadsheetApp.getActiveSpreadsheet().getUrl());
* null if there is no current cell.
*
*
* // Returns the current highlighted cell in the one of the active ranges.
* var currentCell = SpreadsheetApp.getCurrentCell();
* Selection in the spreadsheet.
*
*
* var selection = SpreadsheetApp.getSelection();
* var currentCell = selection.getCurrentCell();
*
* // 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();
* }
*
*
* @returns an instance of this spreadsheet's user-interface environment
*/
function getUi(): Ui
/**
* Creates a builder for a Color.
*
*
* var rgbColor = SpreadsheetApp.newColor().setRgbColor("#FF0000").build();
*
* // 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)
* .setBackgroundColor("#FF0000")
* .setRanges([range])
* .build()
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* DataSourceSpec.
*
* @returns The new builder.
*/
function newDataSourceSpec(): SpreadsheetApp.DataSourceSpecBuilder
/**
* Creates a builder for a data validation rule.
*
*
* 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);
* FilterCriteria.
*
* @returns the new builder
*/
function newFilterCriteria(): SpreadsheetApp.FilterCriteriaBuilder
/**
* Creates a builder for a Rich Text value.
*
*
* // 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);
*
* // 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);
*
* // 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());
* }
* https://docs.google.com/spreadsheets/d/abc1234567/edit#gid=0 is "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());
*
* // 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.openByUrl(
* 'https://docs.google.com/spreadsheets/d/abc1234567/edit');
* Logger.log(ss.getName());
* active range, with the top
* left cell in the range as the current cell.
*
* The spreadsheet UI displays the sheet that contains the chosen range and selects the cells * defined in the chosen range. * *
* // 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();
* active ranges. The last
* range in the list is set as the 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();
*
* // The code below makes the 2nd sheet active in the active spreadsheet.
* var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
* SpreadsheetApp.setActiveSheet(spreadsheet.getSheets()[1]);
*
* 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());
* true, the most recent selection of the new active sheet
* becomes selected again as the new sheet becomes active; if false, the new sheet
* becomes active without changing the current selection.
*
* @returns the new active sheet
*/
function setActiveSheet(
sheet: SpreadsheetApp.Sheet,
restoreSelection: Boolean
): SpreadsheetApp.Sheet
/**
* Sets the active spreadsheet.
*
*
* // The code below makes the spreadsheet with key "1234567890" the active spreadsheet
* var ss = SpreadsheetApp.openById("1234567890");
* SpreadsheetApp.setActiveSpreadsheet(ss);
* current cell.
*
* If the specified cell is present in an already selected range, then that range becomes the * active range with the cell as the current cell. * *
If the specified cell is not present in any selected range, then the existing selection is * removed and the cell becomes the current cell and the active range. * *
Note:The specified Range must consist of one cell, otherwise this method
* throws an exception.
*
*
* // 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();
* null if no color is set.
*
* @returns The color code in CSS notation (such as '#ffffff' or 'white'), or
* null if no color is set.
*/
getFirstColumnColor(): string
/**
* Returns the first alternating column color in the banding, or null if no color is set.
*
* @returns The first alternating column color in the banding, or null if no color is set.
*/
getFirstColumnColorObject(): SpreadsheetApp.Color
/**
* Returns the first row color that is alternating or null if no color is set.
*
* @returns The color code in CSS notation (such as '#ffffff' or 'white'), or
* null if no color is set.
*/
getFirstRowColor(): string
/**
* Returns the first alternating row color, or null if no color is set.
*
* @returns The first alternating row color in the banding, or null if no color is set.
*/
getFirstRowColorObject(): SpreadsheetApp.Color
/**
* Returns the color of the last column, or null if no color is set.
*
* @returns The color code in CSS notation (such as '#ffffff' or 'white'), or
* null if no color is set.
*/
getFooterColumnColor(): string
/**
* Returns the color of the last column in the banding, or null if no color is set.
*
* @returns The last column color in the banding, or null if no color is set.
*/
getFooterColumnColorObject(): SpreadsheetApp.Color
/**
* Returns the color of the last row, or null if no color is set.
*
* @returns The color code in CSS notation (such as '#ffffff' or 'white'), or
* null if no color is set.
*/
getFooterRowColor(): string
/**
* Returns the last row color in the banding, or null if no color is set.
*
* @returns The footer row color in the banding, or null if no color is set.
*/
getFooterRowColorObject(): SpreadsheetApp.Color
/**
* Returns the color of the header column, or null if no color is set.
*
* @returns The color code in CSS notation (such as '#ffffff' or 'white'), or
* null if no color is set.
*/
getHeaderColumnColor(): string
/**
* Returns the color of the first column in the banding, or null if no color is set.
*
* @returns The first column color in the banding, or null if no color is set.
*/
getHeaderColumnColorObject(): SpreadsheetApp.Color
/**
* Returns the color of the header row or null if no color is set.
*
* @returns The color code in CSS notation (such as '#ffffff' or 'white'), or
* null if no color is set.
*/
getHeaderRowColor(): string
/**
* Returns the color of the header row or null if no color is set.
*
* @returns The color of the header row; returns null if no color is set.
*/
getHeaderRowColorObject(): SpreadsheetApp.Color
/**
* Returns the range for this banding.
*
* @returns The range for this banding.
*/
getRange(): SpreadsheetApp.Range
/**
* Returns the second column color that is alternating, or null if no color is set.
*
* @returns The HEX color or null if no color is set.
*/
getSecondColumnColor(): string
/**
* Returns the second alternating column color in the banding, or null if no color is set.
*
* @returns The second alternating column color in the banding, or null if no color is set.
*/
getSecondColumnColorObject(): SpreadsheetApp.Color
/**
* Returns the second row color that is alternating or null if no color is set.
*
* @returns The color code in CSS notation (such as '#ffffff' or 'white'), or
* null if no color is set.
*/
getSecondRowColor(): string
/**
* Returns the second alternating row color, or null if no color is set.
*
* @returns The second alternating row color in the banding, or null if no color is set.
*/
getSecondRowColorObject(): SpreadsheetApp.Color
/**
* Removes this banding.
*/
remove(): void
/**
* Sets the first column color that is alternating.
*
* @param color - The color code in CSS notation (such as '#ffffff' or 'white'), or
* null to clear the color.
*
* @returns This banding, for chaining.
*/
setFirstColumnColor(
color: string
): SpreadsheetApp.Banding
/**
* Sets the first alternating column color in the banding.
*
* @param color - The new first alternating column color in the banding; setting to null
* clears the color.
*
* @returns This banding, for chaining.
*/
setFirstColumnColorObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.Banding
/**
* Sets the first row color that is alternating.
*
* @param color - The color code in CSS notation (such as '#ffffff' or 'white'), or
* null to clear the color.
*
* @returns This banding, for chaining.
*/
setFirstRowColor(
color: string
): SpreadsheetApp.Banding
/**
* Sets the first alternating row color in the banding.
*
* @param color - The new first alternating color in the banding; setting to null clears the
* color.
*
* @returns This banding, for chaining.
*/
setFirstRowColorObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.Banding
/**
* Sets the color of the last column.
*
* @param color - The color code in CSS notation (such as '#ffffff' or 'white'), or
* null to clear the color.
*
* @returns This banding, for chaining.
*/
setFooterColumnColor(
color: string
): SpreadsheetApp.Banding
/**
* Sets the color of the last column in the banding.
*
* @param color - The new color of the last column in the banding; setting to null clears
* the color.
*
* @returns This banding, for chaining.
*/
setFooterColumnColorObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.Banding
/**
* Sets the color of the last row.
*
* @param color - The color code in CSS notation (such as '#ffffff' or 'white'), or
* null to clear the color.
*
* @returns This banding, for chaining.
*/
setFooterRowColor(
color: string
): SpreadsheetApp.Banding
/**
* Sets the color of the footer row in the banding.
*
* @param color - The new footer row color; setting to null clears the color.
*
* @returns This banding, for chaining.
*/
setFooterRowColorObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.Banding
/**
* Sets the color of the header column.
*
* @param color - The color code in CSS notation (such as '#ffffff' or 'white'), or
* null to clear the color.
*
* @returns This banding, for chaining.
*/
setHeaderColumnColor(
color: string
): SpreadsheetApp.Banding
/**
* Sets the color of the header column.
*
* @param color - The new header column color; setting to null clears the color.
*
* @returns This banding, for chaining.
*/
setHeaderColumnColorObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.Banding
/**
* Sets the color of the header row.
*
* @param color - The color code in CSS notation (such as '#ffffff' or 'white'), or
* null to clear the color.
*
* @returns This banding, for chaining.
*/
setHeaderRowColor(
color: string
): SpreadsheetApp.Banding
/**
* Sets the color of the header row.
*
* @param color - The new header row color; setting to null clears the color.
*
* @returns This banding, for chaining.
*/
setHeaderRowColorObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.Banding
/**
* Sets the range for this banding.
*
* @param range - The new range for this banding.
*
* @returns This banding, for chaining.
*/
setRange(
range: SpreadsheetApp.Range
): SpreadsheetApp.Banding
/**
* Sets the second column color that is alternating.
*
* @param color - The color code in CSS notation (such as '#ffffff' or 'white'), or
* null to clear the color.
*
* @returns This banding, for chaining.
*/
setSecondColumnColor(
color: string
): SpreadsheetApp.Banding
/**
* Sets the second alternating column color in the banding.
*
* @param color - The new second alternating column color in the banding; setting to null
* clears the color.
*
* @returns This banding, for chaining.
*/
setSecondColumnColorObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.Banding
/**
* Sets the second row color that is alternating.
*
* @param color - The color code in CSS notation (such as '#ffffff' or 'white'), or
* null to clear the color.
*
* @returns This banding, for chaining.
*/
setSecondRowColor(
color: string
): SpreadsheetApp.Banding
/**
* Sets the second alternating color in the banding.
*
* @param color - The new second alternating color in the banding; setting to null clears
* the color.
*
* @returns This banding, for chaining.
*/
setSecondRowColorObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.Banding
}
enum BandingTheme {
/**
* A blue banding theme.
*/
BLUE = "BLUE",
/**
* A brown banding theme.
*/
BROWN = "BROWN",
/**
* A cyan banding theme.
*/
CYAN = "CYAN",
/**
* A green banding theme.
*/
GREEN = "GREEN",
/**
* A grey banding theme.
*/
GREY = "GREY",
/**
* An indigo banding theme.
*/
INDIGO = "INDIGO",
/**
* A light green banding theme.
*/
LIGHT_GREEN = "LIGHT_GREEN",
/**
* A light grey banding theme.
*/
LIGHT_GREY = "LIGHT_GREY",
/**
* An orange banding theme.
*/
ORANGE = "ORANGE",
/**
* A pink banding theme.
*/
PINK = "PINK",
/**
* A teal banding theme.
*/
TEAL = "TEAL",
/**
* A yellow banding theme.
*/
YELLOW = "YELLOW",
}
class BigQueryDataSourceSpec {
private constructor();
/**
* Creates a DataSourceSpecBuilder based on this data source's settings.
*
* @returns The builder.
*/
copy(): SpreadsheetApp.DataSourceSpecBuilder
/**
* Gets the BigQuery dataset ID.
*
* @returns The dataset ID, or an empty string if the data source spec is defined by a raw query.
*/
getDatasetId(): string
/**
* Gets the parameters of the data source.
*
* @returns The parameter list.
*/
getParameters(): SpreadsheetApp.DataSourceParameter[]
/**
* Gets the billing project ID.
*
* @returns The project ID.
*/
getProjectId(): string
/**
* Gets the raw query string.
*
* @returns The raw query string.
*/
getRawQuery(): string
/**
* Gets the BigQuery table ID.
*
* @returns The table ID, or an empty string if the data source spec is defined by a raw query.
*/
getTableId(): string
/**
* Gets the BigQuery project ID for the table.
*
* @returns The table project ID, or an empty string if the data source spec is defined by a raw
* query.
*/
getTableProjectId(): string
/**
* Gets the type of the data source.
*
* @returns The data source type.
*/
getType(): SpreadsheetApp.DataSourceType
}
class BigQueryDataSourceSpecBuilder {
private constructor();
/**
* Builds a data source specification from the settings in this builder. Must use as...()
* to specify a data source type before building.
*
* @returns The data source specification.
*/
build(): SpreadsheetApp.DataSourceSpec
/**
* Creates a DataSourceSpecBuilder based on this data source's settings.
*
* @returns The builder.
*/
copy(): SpreadsheetApp.DataSourceSpecBuilder
/**
* Gets the BigQuery dataset ID.
*
* @returns The dataset ID, or an empty string if the data source spec is defined by a raw query.
*/
getDatasetId(): string
/**
* Gets the parameters of the data source.
*
* @returns The parameter list.
*/
getParameters(): SpreadsheetApp.DataSourceParameter[]
/**
* Gets the billing project ID.
*
* @returns The project ID.
*/
getProjectId(): string
/**
* Gets the raw query string.
*
* @returns The raw query string.
*/
getRawQuery(): string
/**
* Gets the BigQuery table ID.
*
* @returns The table ID, or an empty string if the data source spec is defined by a raw query.
*/
getTableId(): string
/**
* Gets the BigQuery project ID for the table.
*
* @returns The table project ID, or an empty string if the data source spec is defined by a raw
* query.
*/
getTableProjectId(): string
/**
* Gets the type of the data source.
*
* @returns The data source type.
*/
getType(): SpreadsheetApp.DataSourceType
/**
* Removes all the parameters.
*
* @returns The builder, for chaining.
*/
removeAllParameters(): SpreadsheetApp.BigQueryDataSourceSpecBuilder
/**
* Removes the specified parameter.
*
* @param parameterName - The name of the parameter to remove.
*
* @returns The builder, for chaining.
*/
removeParameter(
parameterName: string
): SpreadsheetApp.BigQueryDataSourceSpecBuilder
/**
* Sets the BigQuery dataset ID.
*
* @param datasetId - The ID of the dataset.
*
* @returns This builder, for chaining.
*/
setDatasetId(
datasetId: string
): SpreadsheetApp.BigQueryDataSourceSpecBuilder
/**
* Adds a parameter, or if the parameter with the name exists, updates its source cell.
*
* @param parameterName - The parameter name.
* @param sourceCell - The source cell, as specified in A1 notation.
*
* @returns The builder, for chaining.
*/
setParameterFromCell(
parameterName: string,
sourceCell: string
): SpreadsheetApp.BigQueryDataSourceSpecBuilder
/**
* Sets the billing BigQuery project ID.
*
* @param projectId - The ID of the billing project.
*
* @returns The builder, for chaining.
*/
setProjectId(
projectId: string
): SpreadsheetApp.BigQueryDataSourceSpecBuilder
/**
* Sets the raw query string.
*
* @param rawQuery - The raw query string.
*
* @returns The builder, for chaining.
*/
setRawQuery(
rawQuery: string
): SpreadsheetApp.BigQueryDataSourceSpecBuilder
/**
* Sets the BigQuery table ID.
*
* @param tableId - The ID of the table.
*
* @returns This builder, for chaining.
*/
setTableId(
tableId: string
): SpreadsheetApp.BigQueryDataSourceSpecBuilder
/**
* Sets the BigQuery project ID for the table.
*
* @param projectId - The project ID of the BigQuery table.
*
* @returns The builder, for chaining.
*/
setTableProjectId(
projectId: string
): SpreadsheetApp.BigQueryDataSourceSpecBuilder
}
class BooleanCondition {
private constructor();
/**
* Gets the background color string for this boolean condition. Returns null if not set.
*
*
* // Logs the boolean condition background color for each conditional format rule on a sheet.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rules = sheet.getConditionalFormatRules();
* for (int i = 0; i < rules.length; i++) {
* var color = rules[i].getBooleanCondition().getBackground();
* Logger.log("The background color for rule %s is %s", i, color);
* }
* null if not set for this condition
*/
getBackground(): string
/**
* Gets the background color for this boolean condition. Returns null if not set.
*
*
* // Logs the boolean condition background color for each conditional format rule on a sheet.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rules = sheet.getConditionalFormatRules();
* for (int i = 0; i < rules.length; i++) {
* var color = rules[i].getBooleanCondition().getBackgroundObject();
* Logger.log("The background color for rule %s is %s", i, color.asRgbColor().asHexString());
* }
* null if not set for this condition.
*/
getBackgroundObject(): SpreadsheetApp.Color
/**
* Returns true if this boolean condition bolds the text and returns false if this
* boolean condition removes bolding from the text. Returns null if bolding is unaffected.
*
*
* // Logs the boolean condition font weight for each conditional format rule on a sheet.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rules = sheet.getConditionalFormatRules();
* for (int i = 0; i < rules.length; i++) {
* var bold = rules[i].getBooleanCondition().getBold();
* Logger.log("The font bold setting for rule %s is %b", i, weight);
* }
* null if bolding is
* unaffected
*/
getBold(): Boolean
/**
* Gets the rule's criteria type as defined in the BooleanCriteria enum. To get the
* arguments for the criteria, use getCriteriaValues(). To use these values to create or
* modify a conditional formatting rule, see ConditionalFormatRuleBuilder.withCriteria(criteria, args).
*
*
* // Log information about the conditional formats on the active sheet that use
* // boolean conditions.
* var sheet = SpreadsheetApp.getActiveSheet;
* var formats = sheet.getConditionalFormats();
* sheet.getConditionalFormats().forEach(function(format) {
* var booleanCondition = format.getBooleanCondition();
* if (booleanCondition) {
* var criteria = booleanCondition.getCriteriaType();
* var args = booleanCondition.getCriteriaValues();
* Logger.log('The conditional format rule is %s %s', criteria, args);
* }
* });
*
*
* @returns the type of conditional formatting criteria
*/
getCriteriaType(): SpreadsheetApp.BooleanCriteria
/**
* Gets an array of arguments for the rule's criteria. To get the criteria type, use getCriteriaType(). To use these values to create or modify a conditional formatting rule, see
* ConditionalFormatRuleBuilder.withCriteria(criteria, args).
*
*
* // Log information about the conditional formats on the active sheet that use
* // boolean conditions.
* var sheet = SpreadsheetApp.getActiveSheet;
* var formats = sheet.getConditionalFormats();
* sheet.getConditionalFormats().forEach(function(format) {
* var booleanCondition = format.getBooleanCondition();
* if (booleanCondition) {
* var criteria = booleanCondition.getCriteriaType();
* var args = booleanCondition.getCriteriaValues();
* Logger.log('The conditional format rule is %s %s', criteria, args);
* }
* });
*
*
* @returns an array of arguments appropriate to the rule's criteria type; the number of arguments
* and their type match the corresponding when...() method of the ConditionalFormatRuleBuilder class
*/
getCriteriaValues(): object[]
/**
* Gets the font color string for this boolean condition. Returns null if not set.
*
*
* // Logs the boolean condition font color for each conditional format rule on a sheet.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rules = sheet.getConditionalFormatRules();
* for (int i = 0; i < rules.length; i++) {
* var color = rules[i].getBooleanCondition().getFontColor();
* Logger.log("The font color for rule %s is %s", i, color);
* }
* null if not set for this condition
*/
getFontColor(): string
/**
* Gets the font color for this boolean condition. Returns null if not set.
*
*
* // Logs the boolean condition font color for each conditional format rule on a sheet.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rules = sheet.getConditionalFormatRules();
* for (int i = 0; i < rules.length; i++) {
* var color = rules[i].getBooleanCondition().getFontColorObject();
* Logger.log("The font color for rule %s is %s", i, color.asRgbColor().asHexString());
* }
* null if not set for this condition.
*/
getFontColorObject(): SpreadsheetApp.Color
/**
* Returns true if this boolean condition italicises the text and returns false if
* this boolean condition removes italics from the text. Returns null if italics are
* unaffected.
*
*
* // Logs the boolean condition font style for each conditional format rule on a sheet.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rules = sheet.getConditionalFormatRules();
* for (int i = 0; i < rules.length; i++) {
* var italic = rules[i].getBooleanCondition().getItalic();
* Logger.log("The font italic setting for rule %s is %b", i, italic);
* }
* null if
* italicising is unaffected
*/
getItalic(): Boolean
/**
* Returns true if this boolean condition strikes through the text and returns false if this boolean condition removes strikethrough from the text. Returns null if
* strikethrough is unaffected.
*
*
* // Logs the boolean condition strikethrough setting for each conditional format rule on a
* // sheet.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rules = sheet.getConditionalFormatRules();
* for (int i = 0; i < rules.length; i++) {
* var strikethrough = rules[i].getBooleanCondition().getStrikethrough();
* Logger.log("The font strikethrough setting for rule %s is %b", i, strikethrough);
* }
* null if
* strikethrough is unaffected
*/
getStrikethrough(): Boolean
/**
* Returns true if this boolean condition underlines the text and returns false if
* this boolean condition removes underlining from the text. Returns null if underlining
* is unaffected.
*
*
* // Logs the boolean condition underline setting for each conditional format rule on a sheet.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rules = sheet.getConditionalFormatRules();
* for (int i = 0; i < rules.length; i++) {
* var underline = rules[i].getBooleanCondition().getUnderline();
* Logger.log("The font underline setting for rule %s is %b", i, underline);
* }
* null if
* underlining is unaffected
*/
getUnderline(): Boolean
}
enum BooleanCriteria {
/**
* The criteria is met when a cell is empty.
*/
CELL_EMPTY = "CELL_EMPTY",
/**
* The criteria is met when a cell is not empty.
*/
CELL_NOT_EMPTY = "CELL_NOT_EMPTY",
/**
* The criteria is met when the input makes the given formula evaluate to true.
*/
CUSTOM_FORMULA = "CUSTOM_FORMULA",
/**
* The criteria is met when a date is after the given value.
*/
DATE_AFTER = "DATE_AFTER",
/**
* The criteria is met when a date is after the relative date value.
*/
DATE_AFTER_RELATIVE = "DATE_AFTER_RELATIVE",
/**
* The criteria is met when a date is before the given value.
*/
DATE_BEFORE = "DATE_BEFORE",
/**
* The criteria is met when a date is before the relative date value.
*/
DATE_BEFORE_RELATIVE = "DATE_BEFORE_RELATIVE",
/**
* The criteria is met when a date is equal to the given value.
*/
DATE_EQUAL_TO = "DATE_EQUAL_TO",
/**
* The criteria is met when a date is equal to the relative date value.
*/
DATE_EQUAL_TO_RELATIVE = "DATE_EQUAL_TO_RELATIVE",
/**
* The criteria is met when a date is not equal to the given value.
*/
DATE_NOT_EQUAL_TO = "DATE_NOT_EQUAL_TO",
/**
* The criteria is met when a number that is between the given values.
*/
NUMBER_BETWEEN = "NUMBER_BETWEEN",
/**
* The criteria is met when a number that is equal to the given value.
*/
NUMBER_EQUAL_TO = "NUMBER_EQUAL_TO",
/**
* The criteria is met when a number that is greater than the given value.
*/
NUMBER_GREATER_THAN = "NUMBER_GREATER_THAN",
/**
* The criteria is met when a number that is greater than or equal to the given value.
*/
NUMBER_GREATER_THAN_OR_EQUAL_TO = "NUMBER_GREATER_THAN_OR_EQUAL_TO",
/**
* The criteria is met when a number that is less than the given value.
*/
NUMBER_LESS_THAN = "NUMBER_LESS_THAN",
/**
* The criteria is met when a number that is less than or equal to the given value.
*/
NUMBER_LESS_THAN_OR_EQUAL_TO = "NUMBER_LESS_THAN_OR_EQUAL_TO",
/**
* The criteria is met when a number that is not between the given values.
*/
NUMBER_NOT_BETWEEN = "NUMBER_NOT_BETWEEN",
/**
* The criteria is met when a number that is not equal to the given value.
*/
NUMBER_NOT_EQUAL_TO = "NUMBER_NOT_EQUAL_TO",
/**
* The criteria is met when the input contains the given value.
*/
TEXT_CONTAINS = "TEXT_CONTAINS",
/**
* The criteria is met when the input does not contain the given value.
*/
TEXT_DOES_NOT_CONTAIN = "TEXT_DOES_NOT_CONTAIN",
/**
* The criteria is met when the input ends with the given value.
*/
TEXT_ENDS_WITH = "TEXT_ENDS_WITH",
/**
* The criteria is met when the input is equal to the given value.
*/
TEXT_EQUAL_TO = "TEXT_EQUAL_TO",
/**
* The criteria is met when the input is not equal to the given value.
*/
TEXT_NOT_EQUAL_TO = "TEXT_NOT_EQUAL_TO",
/**
* The criteria is met when the input begins with the given value.
*/
TEXT_STARTS_WITH = "TEXT_STARTS_WITH",
}
enum BorderStyle {
/**
* Dashed line borders.
*/
DASHED = "DASHED",
/**
* Dotted line borders.
*/
DOTTED = "DOTTED",
/**
* Two solid line borders.
*/
DOUBLE = "DOUBLE",
/**
* Thin solid line borders.
*/
SOLID = "SOLID",
/**
* Medium solid line borders.
*/
SOLID_MEDIUM = "SOLID_MEDIUM",
/**
* Thick solid line borders.
*/
SOLID_THICK = "SOLID_THICK",
}
class Color {
private constructor();
/**
* Converts this color to an RgbColor.
*
* @returns The RGB color.
*/
asRgbColor(): RgbColor
/**
* Converts this color to a ThemeColor.
*
* @returns The theme color.
*/
asThemeColor(): SpreadsheetApp.ThemeColor
/**
* Get the type of this color.
*
* @returns The color type.
*/
getColorType(): ColorType
}
class ColorBuilder {
private constructor();
/**
* Converts this color to an RgbColor.
*
* @returns The RGB color.
*/
asRgbColor(): RgbColor
/**
* Converts this color to a ThemeColor.
*
* @returns The theme color.
*/
asThemeColor(): SpreadsheetApp.ThemeColor
/**
* Creates a color object from the settings supplied to the builder.
*
* @returns A color object created from this builder.
*/
build(): SpreadsheetApp.Color
/**
* Get the type of this color.
*
* @returns The color type.
*/
getColorType(): ColorType
/**
* Sets as RGB color.
*
* @param cssString - The RGB color in CSS notation (such as '#ffffff').
*
* @returns This builder, for chaining.
*/
setRgbColor(
cssString: string
): SpreadsheetApp.ColorBuilder
/**
* Sets as theme color.
*
* @param themeColorType - The theme color type.
*
* @returns This builder, for chaining.
*/
setThemeColor(
themeColorType: SpreadsheetApp.ThemeColorType
): SpreadsheetApp.ColorBuilder
}
class ConditionalFormatRule {
private constructor();
/**
* Returns a rule builder preset with this rule's settings.
*
* @returns a builder based on this rule's settings
*/
copy(): SpreadsheetApp.ConditionalFormatRuleBuilder
/**
* Retrieves the rule's BooleanCondition information if this rule uses
* boolean condition criteria. Otherwise returns null.
*
*
* // Log the boolean criteria type of the first conditional format rules of a sheet.
* var rule = SpreadsheetApp.getActiveSheet().getConditionalFormatRules()[0];
* var booleanCondition = rule.getBooleanCondition();
* if (booleanCondition != null) {
* Logger.log(booleanCondition.getCriteriaType());
* }
* null if the rule does not use a boolean
* condition.
*/
getBooleanCondition(): SpreadsheetApp.BooleanCondition
/**
* Retrieves the rule's GradientCondition information, if this rule
* uses gradient condition criteria. Otherwise returns null.
*
*
* // Log the gradient minimum color of the first conditional format rule of a sheet.
* var rule = SpreadsheetApp.getActiveSheet().getConditionalFormatRules()[0];
* var gradientCondition = rule.getGradientCondition();
* if (gradientCondition != null) {
* Logger.log(gradientCondition.getMinColor());
* }
* null if the rule does not use a gradient
* condition.
*/
getGradientCondition(): SpreadsheetApp.GradientCondition
/**
* Retrieves the ranges to which this conditional format rule is applied.
*
*
* // Log each range of the first conditional format rule of a sheet.
* var rule = SpreadsheetApp.getActiveSheet().getConditionalFormatRules()[0];
* var ranges = rule.getRanges();
* for (int i = 0; i < ranges.length; i++) {
* Logger.log(ranges[i].getA1Notation());
* }
* BooleanCondition information if this rule uses
* boolean condition criteria. Otherwise returns null.
*
*
* // Log the boolean criteria type of the first conditional format rules of a sheet.
* var rule = SpreadsheetApp.getActiveSheet().getConditionalFormatRules()[0];
* var booleanCondition = rule.getBooleanCondition();
* if (booleanCondition != null) {
* Logger.log(booleanCondition.getCriteriaType());
* }
* null if the rule does not use a boolean
* condition.
*/
getBooleanCondition(): SpreadsheetApp.BooleanCondition
/**
* Retrieves the rule's GradientCondition information, if this rule
* uses gradient condition criteria. Otherwise returns null.
*
*
* // Log the gradient minimum color of the first conditional format rule of a sheet.
* var rule = SpreadsheetApp.getActiveSheet().getConditionalFormatRules()[0];
* var gradientCondition = rule.getGradientCondition();
* if (gradientCondition != null) {
* Logger.log(gradientCondition.getMinColor());
* }
* null if the rule does not use a gradient
* condition.
*/
getGradientCondition(): SpreadsheetApp.GradientCondition
/**
* Retrieves the ranges to which this conditional format rule is applied.
*
*
* // Log each range of the first conditional format rule of a sheet.
* var rule = SpreadsheetApp.getActiveSheet().getConditionalFormatRules()[0];
* var ranges = rule.getRanges();
* for (int i = 0; i < ranges.length; i++) {
* Logger.log(ranges[i].getA1Notation());
* }
* null
* removes the background color format setting from the rule.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their
* // background color to red if the cell has text equal to "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextEqualTo("hello")
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* null to clear.
*
* @returns the builder, for chaining
*/
setBackground(
color: string
): SpreadsheetApp.ConditionalFormatRuleBuilder
/**
* Sets the background color for the conditional format rule's format. Passing in null
* removes the background color format setting from the rule.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their
* // background color to theme background color if the cell has text equal to "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var color = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.BACKGROUND)
* .build();
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextEqualTo("hello")
* .setBackground(color)
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* null to clear.
*
* @returns The builder, for chaining.
*/
setBackgroundObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.ConditionalFormatRuleBuilder
/**
* Sets text bolding for the conditional format rule's format. If bold is true,
* the rule bolds text if the condition is met; if false, the rule removes any existing
* bolding if the condition is met. Passing in null removes the bold format setting from
* the rule.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn their
* // text bold if the cell has text equal to "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextEqualTo("hello")
* .setBold(true)
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* null removes this setting.
*
* @returns the builder, for chaining
*/
setBold(
bold: Boolean
): SpreadsheetApp.ConditionalFormatRuleBuilder
/**
* Sets the font color for the conditional format rule's format. Passing in null removes
* the font color format setting from the rule.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their font
* // color to red if the cell has text equal to "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextEqualTo("hello")
* .setFontColor("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* null to clear.
*
* @returns the builder, for chaining
*/
setFontColor(
color: string
): SpreadsheetApp.ConditionalFormatRuleBuilder
/**
* Sets the font color for the conditional format rule's format. Passing in null removes
* the font color format setting from the rule.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their font
* // color to theme text color if the cell has text equal to "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var color = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.TEXT)
* .build();
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextEqualTo("hello")
* .setFontColor(color)
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* null to clear.
*
* @returns The builder, for chaining.
*/
setFontColorObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.ConditionalFormatRuleBuilder
/**
* Clears the conditional format rule's gradient maxpoint value, and instead uses the maximum
* value in the rule's ranges. Also sets the gradient's maxpoint color to the input color.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their
* // background color somewhere between white and red, based on their values in comparison to
* // the ranges minimum and maximum values.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .setGradientMaxpoint("#FF0000")
* .setGradientMinpoint("#FFFFFF")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their
* // background color somewhere between theme text and background colors, based on their values
* // in comparison to the ranges minimum and maximum values.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var textColor = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.TEXT)
* .build();
* var backgroundColor = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.BACKGROUND)
* .build();
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .setGradientMaxpoint(textColor)
* .setGradientMinpoint(backgroundColor)
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their
* // background color somewhere from theme accent 1, accent 2 to accent 3 colors, based on their
* // values in comparison to the values 0, 50, and 100.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var color1 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
* .build();
* var color2 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
* .build();
* var color3 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
* .build();
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .setGradientMaxpointWithValue(color1, SpreadsheetApp.InterpolationType.NUMBER, "100")
* .setGradientMidpointWithValue(color2, SpreadsheetApp.InterpolationType.NUMBER, "50")
* .setGradientMinpointWithValue(color3, SpreadsheetApp.InterpolationType.NUMBER, "0")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their
* // background color somewhere from red green to blue, based on their values in comparison to
* // the values 0, 50, and 100.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .setGradientMaxpointWithValue("#0000FF", SpreadsheetApp.InterpolationType.NUMBER, "100")
* .setGradientMidpointWithValue("#00FF00", SpreadsheetApp.InterpolationType.NUMBER, "50")
* .setGradientMinpointWithValue("#FF0000", SpreadsheetApp.InterpolationType.NUMBER, "0")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* null.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their
* // background color somewhere from theme accent 1 to accent 2 to accent 3 colors, based on
* // their values in comparison to the values 0, 50, and 100.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var color1 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
* .build();
* var color2 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
* .build();
* var color3 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
* .build();
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .setGradientMaxpointWithValue(color1, SpreadsheetApp.InterpolationType.NUMBER, "100")
* .setGradientMidpointWithValue(color2, SpreadsheetApp.InterpolationType.NUMBER, "50")
* .setGradientMinpointWithValue(color3, SpreadsheetApp.InterpolationType.NUMBER, "0")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* null to clear.
* @param value - The midpoint value to set.
*
* @returns The builder, for chaining.
*/
setGradientMidpointObjectWithValue(
color: SpreadsheetApp.Color,
type: SpreadsheetApp.InterpolationType,
value: string
): SpreadsheetApp.ConditionalFormatRuleBuilder
/**
* Sets the conditional format rule's gradient midpoint fields. Clears all of the midpoint fields
* if the passed in interpolation type is null.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their
* // background color somewhere from red green to blue, based on their values in comparison to
* // the values 0, 50, and 100.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .setGradientMaxpointWithValue("#0000FF", SpreadsheetApp.InterpolationType.NUMBER, "100")
* .setGradientMidpointWithValue("#00FF00", SpreadsheetApp.InterpolationType.NUMBER, "50")
* .setGradientMinpointWithValue("#FF0000", SpreadsheetApp.InterpolationType.NUMBER, "0")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* null to clear.
* @param value - The midpoint value to set.
*
* @returns the builder, for chaining
*/
setGradientMidpointWithValue(
color: string,
type: SpreadsheetApp.InterpolationType,
value: string
): SpreadsheetApp.ConditionalFormatRuleBuilder
/**
* Clears the conditional format rule's gradient minpoint value, and instead uses the minimum
* value in the rule's ranges. Also sets the gradient's minpoint color to the input color.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their
* // background color somewhere between white and red, based on their values in comparison to
* // the ranges minimum and maximum values.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .setGradientMaxpoint("#FF0000")
* .setGradientMinpoint("#FFFFFF")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their
* // background color somewhere between theme text and background colors, based on their values
* // in comparison to the ranges minimum and maximum values.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var textColor = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.TEXT)
* .build();
* var backgroundColor = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.BACKGROUND)
* .build();
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .setGradientMaxpoint(textColor)
* .setGradientMinpoint(backgroundColor)
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their
* // background color somewhere from theme accent 1 to accent 2 to accent 3 colors, based on
* // their values in comparison to the values 0, 50, and 100.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var color1 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
* .build();
* var color2 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
* .build();
* var color3 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
* .build();
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .setGradientMaxpointWithValue(color1, SpreadsheetApp.InterpolationType.NUMBER, "100")
* .setGradientMidpointWithValue(color2, SpreadsheetApp.InterpolationType.NUMBER, "50")
* .setGradientMinpointWithValue(color3, SpreadsheetApp.InterpolationType.NUMBER, "0")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to set their
* // background color somewhere from red to green to blue, based on their values in comparison to
* // the values 0, 50, and 100.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .setGradientMaxpointWithValue("#0000FF", SpreadsheetApp.InterpolationType.NUMBER, "100")
* .setGradientMidpointWithValue("#00FF00", SpreadsheetApp.InterpolationType.NUMBER, "50")
* .setGradientMinpointWithValue("#FF0000", SpreadsheetApp.InterpolationType.NUMBER, "0")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* italic is true,
* the rule italicises text if the condition is met; if false, the rule removes any
* existing italicization if the condition is met. Passing in null removes the italic
* format setting from the rule.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn their
* // text italic if the cell has text equal to "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextEqualTo("hello")
* .setItalic(true)
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* null removes this setting.
*
* @returns the builder, for chaining
*/
setItalic(
italic: Boolean
): SpreadsheetApp.ConditionalFormatRuleBuilder
/**
* Sets one or more ranges to which this conditional format rule is applied. This operation
* replaces any existing ranges. Setting an empty array clears any existing ranges. A rule must
* have at least one range.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 and range D4:F6
* // to turn red if they contain a number between 1 and 10.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeOne = sheet.getRange("A1:B3");
* var rangeTwo = sheet.getRange("D4:F6");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenNumberBetween(1, 10)
* .setBackground("#FF0000")
* .setRanges([rangeOne, rangeTwo])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* strikethrough is
* true, the rule strikesthrough text if the condition is met; if false, the rule
* removes any existing strikethrough formatting if the condition is met. Passing in null
* removes the strikethrough format setting from the rule.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to strikethrough
* // their text if the cell has text equal to "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextEqualTo("hello")
* .setStrikethrough(true)
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* null removes this setting.
*
* @returns the builder, for chaining
*/
setStrikethrough(
strikethrough: Boolean
): SpreadsheetApp.ConditionalFormatRuleBuilder
/**
* Sets text underlining for the conditional format rule's format. If underline is true, the rule underlines text if the condition is met; if false, the rule removes any
* existing underlines if the condition is met. Passing in null removes the underline
* format setting from the rule.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to underline
* // their text if the cell has text equal to "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextEqualTo("hello")
* .setUnderline(true)
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* null removes this setting.
*
* @returns the builder, for chaining
*/
setUnderline(
underline: Boolean
): SpreadsheetApp.ConditionalFormatRuleBuilder
/**
* Sets the conditional format rule to trigger when the cell is empty.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they are empty.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenCellEmpty()
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they are not empty.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenCellNotEmpty()
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain a date after 11/4/1993.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenDateAfter(new Date("11/4/1993"))
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain a date after today.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenDateAfter(SpreadsheetApp.RelativeDate.TODAY)
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain a date before 11/4/1993.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenDateBefore(new Date("11/4/1993"))
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain a date before today.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenDateBefore(SpreadsheetApp.RelativeDate.TODAY)
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain the date 11/4/1993.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenDateEqualTo(new Date("11/4/1993"))
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain todays date.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenDateEqualTo(SpreadsheetApp.RelativeDate.TODAY)
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* true.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they satisfy the condition "=EQ(B4, C3)".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenFormulaSatisfied("=EQ(B4, C3)")
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* true if the input is valid.
*
* @returns the builder, for chaining
*/
whenFormulaSatisfied(
formula: string
): SpreadsheetApp.ConditionalFormatRuleBuilder
/**
* Sets the conditional format rule to trigger when a number falls between, or is either of, two
* specified values.
*
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain a number between 1 and 10.
*
* var sheet = SpreadsheetApp.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);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain the number 10.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenNumberEqualTo(10)
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red
* // if they contain a number greater than 10.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenNumberGreaterThan(10)
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain a number greater than or equal to 10.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenNumberGreaterThanOrEqualTo(10)
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain a number less than 10.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenNumberLessThan(10)
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain a number less than or equal to 10.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenNumberLessThanOrEqualTo(10)
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain a number not between 1 and 10.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenNumberNotBetween(1, 10)
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they don't contain the number 10.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenNumberNotEqualTo(10)
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they contain the text "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextContains("hello")
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they don't contain the text "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextDoesNotContain("hello")
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they end with the text "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextEndsWith("hello")
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they have text equal to "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextEqualTo("hello")
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
*
* // Adds a conditional format rule to a sheet that causes cells in range A1:B3 to turn red if
* // they start with the text "hello".
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B3");
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .whenTextStartsWith("hello")
* .setBackground("#FF0000")
* .setRanges([range])
* .build();
* var rules = sheet.getConditionalFormatRules();
* rules.push(rule);
* sheet.setConditionalFormatRules(rules);
* BooleanCriteria values,
* typically taken from the criteria and arguments of an
* existing rule.
*
*
* // Adds a new conditional format rule that is a copy of the first active
* // conditional format rule, except it instead sets its cells to have a black
* // background color.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rules = sheet.getConditionalFormatRules();
* var booleanCondition = rules[0].getBooleanCondition();
* if (booleanCondition != null) {
* var rule = SpreadsheetApp.newConditionalFormatRule()
* .withCriteria(booleanCondition.getCriteriaType(),
* booleanCondition.getCriteriaValues())
* .setBackground("#000000")
* .build();
* rules.push(rule);
* }
* sheet.setConditionalFormatRules(rules);
* when...() method above.
*
* @returns the builder, for chaining
*/
withCriteria(
criteria: SpreadsheetApp.BooleanCriteria,
args: object[]
): SpreadsheetApp.ConditionalFormatRuleBuilder
}
class ContainerInfo {
private constructor();
/**
* The chart's left side is anchored in this column.
*
* @returns 1-indexed column (that is, column C is 3)
*/
getAnchorColumn(): number
/**
* The chart's top side is anchored in this row.
*
* @returns 1-indexed row (that is, row 5 returns 5)
*/
getAnchorRow(): number
/**
* The chart's upper left hand corner is offset from the anchor column by this many pixels.
*
* @returns the horizontal offset in pixels for the upper left hand corner of the chart
*/
getOffsetX(): number
/**
* The chart's upper left hand corner is offset from the anchor row by this many pixels.
*
* @returns the vertical offset in pixels for the upper left hand corner of the chart
*/
getOffsetY(): number
}
enum CopyPasteType {
/**
* Paste the column widths only.
*/
PASTE_COLUMN_WIDTHS = "PASTE_COLUMN_WIDTHS",
/**
* Paste the color rules only.
*/
PASTE_CONDITIONAL_FORMATTING = "PASTE_CONDITIONAL_FORMATTING",
/**
* Paste the data validation only.
*/
PASTE_DATA_VALIDATION = "PASTE_DATA_VALIDATION",
/**
* Paste the format and data validation only.
*/
PASTE_FORMAT = "PASTE_FORMAT",
/**
* Paste the formulas only.
*/
PASTE_FORMULA = "PASTE_FORMULA",
/**
* Paste values, formulas, formats and merges.
*/
PASTE_NORMAL = "PASTE_NORMAL",
/**
* Paste values, formulas, formats and merges but without borders.
*/
PASTE_NO_BORDERS = "PASTE_NO_BORDERS",
/**
* Paste the values ONLY without formats, formulas or merges.
*/
PASTE_VALUES = "PASTE_VALUES",
}
enum DataExecutionErrorCode {
/**
* A data execution error code that is not supported in Apps Script.
*/
DATA_EXECUTION_ERROR_CODE_UNSUPPORTED = "DATA_EXECUTION_ERROR_CODE_UNSUPPORTED",
/**
* The database referenced by the data source is not found. Please update the data source specification.
*/
DATA_NOT_FOUND = "DATA_NOT_FOUND",
/**
* The data execution returns duplicate column names. Please update the data source specification.
*/
DUPLICATE_COLUMN_NAMES = "DUPLICATE_COLUMN_NAMES",
/**
* Data execution engine error. Use DataExecutionStatus.getErrorMessage() for details.
*/
ENGINE = "ENGINE",
/**
* The data execution is interrupted. Please refresh later.
*/
INTERRUPTED = "INTERRUPTED",
/**
* The data execution has no error.
*/
NONE = "NONE",
/**
* Other errors.
*/
OTHER = "OTHER",
/**
* Invalid data execution parameter. The source cell must exist and contain only a number or text.
* Please update the data source specification.
*/
PARAMETER_INVALID = "PARAMETER_INVALID",
/**
* The user does not have access to the database referenced by the data source. Please update the
* data source specification or contact the owner of the billing
* project to request access.
*/
PERMISSION_DENIED = "PERMISSION_DENIED",
/**
* The data execution timed out. Please update the data source specification.
*/
TIME_OUT = "TIME_OUT",
/**
* The data execution returns more cells than the limit. Please update the data source specification.
*/
TOO_MANY_CELLS = "TOO_MANY_CELLS",
/**
* The data execution returns values that exceed the maximum characters allowed in a single cell.
* Please update the data source specification.
*/
TOO_MANY_CHARS_PER_CELL = "TOO_MANY_CHARS_PER_CELL",
/**
* The data execution returns more rows than the limit. Please update the data source specification.
*/
TOO_MANY_ROWS = "TOO_MANY_ROWS",
/**
* The data execution returns unsupported data type. Please update the data source specification.
*
* For BigQuery, ARRAY or STRUCT type is not supported.
*/
UNSUPPORTED_DATA_TYPE = "UNSUPPORTED_DATA_TYPE",
}
enum DataExecutionState {
/**
* A data execution state is not supported in Apps Script.
*/
DATA_EXECUTION_STATE_UNSUPPORTED = "DATA_EXECUTION_STATE_UNSUPPORTED",
/**
* The data execution is completed and has errors.
*/
ERROR = "ERROR",
/**
* The data execution has not started.
*/
NOT_STARTED = "NOT_STARTED",
/**
* The data execution has started and is running.
*/
RUNNING = "RUNNING",
/**
* The data execution is completed and successful.
*/
SUCCESS = "SUCCESS",
}
class DataExecutionStatus {
private constructor();
/**
* Gets the error code of the data execution.
*
* @returns The error code.
*/
getErrorCode(): SpreadsheetApp.DataExecutionErrorCode
/**
* Gets the error message of the data execution. The message may be empty.
*
* @returns The error message.
*/
getErrorMessage(): string
/**
* Gets the state of the data execution.
*
* @returns The execution state.
*/
getExecutionState(): SpreadsheetApp.DataExecutionState
/**
* Gets the time the last data execution completed regardless of the execution state.
*
* @returns The last execution time, or null if there has never been a data execution.
*/
getLastExecutionTime(): Date
/**
* Gets the time the data last successfully refreshed.
*
* @returns The last successfully refreshed time, or null if there is never a successful
* data execution.
*/
getLastRefreshedTime(): Date
/**
* Returns true if the data from last successful execution is truncated, or false
* otherwise.
*
* @returns True if the data from execution is truncated, or false otherwise.
*/
isTruncated(): Boolean
}
class DataSource {
private constructor();
/**
* Creates a calculated column.
*
* @param name - The name of the calculated column.
* @param formula - The calculated column formula.
*
* @returns The newly created calculated column.
*/
createCalculatedColumn(
name: string,
formula: string
): SpreadsheetApp.DataSourceColumn
/**
* Creates a data source pivot table from this data source in the first cell of a new sheet. As a
* side effect, makes the new sheet the active sheet.
*
* @returns The newly created data source pivot table.
*/
createDataSourcePivotTableOnNewSheet(): SpreadsheetApp.DataSourcePivotTable
/**
* Creates a data source table from this data source in the first cell of a new sheet. As a side
* effect, makes the new sheet the active sheet.
*
* @returns The newly created data source table.
*/
createDataSourceTableOnNewSheet(): SpreadsheetApp.DataSourceTable
/**
* Returns the calculated column in the data source that matches the column name.
*
* @param columnName - The name of the calculated column to get.
*
* @returns The calculated column that matches the column name, or null if there is no such
* calculated column.
*/
getCalculatedColumnByName(
columnName: string
): SpreadsheetApp.DataSourceColumn
/**
* Returns all the calculated columns in the data source.
*
* @returns An array of all the calculated columns in the data source.
*/
getCalculatedColumns(): SpreadsheetApp.DataSourceColumn[]
/**
* Returns all the columns in the data source.
*
* @returns An array of all the DataSourceColumn in the data source.
*/
getColumns(): SpreadsheetApp.DataSourceColumn[]
/**
* Returns the data source sheets associated with this data source.
*
* @returns An array of data source sheets.
*/
getDataSourceSheets(): SpreadsheetApp.DataSourceSheet[]
/**
* Gets the data source specification.
*
* @returns The data source specification.
*/
getSpec(): SpreadsheetApp.DataSourceSpec
/**
* Refreshes all data source objects linked to the data source.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for the specific data
* source type.
*/
refreshAllLinkedDataSourceObjects(): void
/**
* Updates the data source specification and refreshes the data source objects linked with this
* data source with the new specification.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for the specific data
* source type.
*
* @param spec - The data source specification to update with.
*
* @returns The data source.
*/
updateSpec(
spec: SpreadsheetApp.DataSourceSpec
): SpreadsheetApp.DataSource
/**
* Updates the data source specification and refreshes the linked data
* source sheets with the new specification.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for the specific data
* source type.
*
* @param spec - The data source specification to update with.
* @param refreshAllLinkedObjects - If true, also refreshes all the data source objects
* linked with this data source.
*
* @returns The data source.
*/
updateSpec(
spec: SpreadsheetApp.DataSourceSpec,
refreshAllLinkedObjects: Boolean
): SpreadsheetApp.DataSource
/**
* Waits until all the current executions of the linked data source objects complete, timing out
* after the provided number of seconds. Throws an exception if the executions are not completed
* when timing out, but does not cancel the data executions.
*
* @param timeoutInSeconds - The time to wait for data executions, in seconds. The maximum is 300
* seconds.
*/
waitForAllDataExecutionsCompletion(
timeoutInSeconds: number
): void
}
class DataSourceChart {
private constructor();
/**
* Refreshes the data of this object regardless of the current state. See refreshData() for
* more details.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for specific data source
* type.
*
* @returns The data object.
*/
forceRefreshData(): SpreadsheetApp.DataSourceChart
/**
* Gets the data source the object is linked to.
*
* @returns The data source.
*/
getDataSource(): SpreadsheetApp.DataSource
/**
* Gets the data execution status of the object.
*
* @returns The data execution status.
*/
getStatus(): SpreadsheetApp.DataExecutionStatus
/**
* Refreshes the data of the object.
*
*
Throws an exception if currently in error state. Use DataSource#updateSpec() to update the specification. The method is
* preferred over forceRefreshData() to prevent unexpected edits on data source.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for specific data source
* type.
*
* @returns The data object.
*/
refreshData(): SpreadsheetApp.DataSourceChart
/**
* Waits until the current execution completes, timing out after the provided number of seconds.
* Throws an exception if the execution is not completed when timing out, but does not cancel the
* data execution.
*
* @param timeoutInSeconds - The time to wait for data execution, in seconds. The maximum is 300
* seconds.
*
* @returns The data execution status.
*/
waitForCompletion(
timeoutInSeconds: number
): SpreadsheetApp.DataExecutionStatus
}
class DataSourceColumn {
private constructor();
/**
* Gets the data source associated with the data source column.
*
* @returns The data source.
*/
getDataSource(): SpreadsheetApp.DataSource
/**
* Gets the formula for the data source column. Returns an empty string if the data source column
* is not a calculated column.
*
* @returns The formula.
*/
getFormula(): string
/**
* Gets the name for the data source column.
*
* @returns The column name.
*/
getName(): string
/**
* Returns whether the column has an array dependency.
*
* @returns true if the column has an array dependency, or false otherwise.
*/
hasArrayDependency(): Boolean
/**
* Returns whether the column is a calculated column.
*
* @returns true if the column is a calculated column, or false otherwise.
*/
isCalculatedColumn(): Boolean
/**
* Removes the data source column.
*
*
Only supported for calculated columns.
*/
remove(): void
/**
* Sets the formula for the data source column.
*
*
Only supported for calculated columns.
*
* @param formula - The new formula.
*
* @returns The data source column, for chaining.
*/
setFormula(
formula: string
): SpreadsheetApp.DataSourceColumn
/**
* Sets the name of the data source column.
*
*
Only supported for calculated columns.
*
* @param name - The name to set.
*
* @returns The data source column, for chaining.
*/
setName(
name: string
): SpreadsheetApp.DataSourceColumn
}
class DataSourceFormula {
private constructor();
/**
* Refreshes the data of this object regardless of the current state. See refreshData() for
* more details.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for specific data source
* type.
*
* @returns The data object.
*/
forceRefreshData(): SpreadsheetApp.DataSourceFormula
/**
* Returns the Range representing the cell where this data source formula is anchored.
*
* @returns The anchor cell.
*/
getAnchorCell(): SpreadsheetApp.Range
/**
* Gets the data source the object is linked to.
*
* @returns The data source.
*/
getDataSource(): SpreadsheetApp.DataSource
/**
* Returns the display value of the data source formula.
*
* @returns The display value.
*/
getDisplayValue(): string
/**
* Returns the formula for this data source formula.
*
* @returns The formula.
*/
getFormula(): string
/**
* Gets the data execution status of the object.
*
* @returns The data execution status.
*/
getStatus(): SpreadsheetApp.DataExecutionStatus
/**
* Refreshes the data of the object.
*
*
Throws an exception if currently in error state. Use DataSource#updateSpec() to update the specification. The method is
* preferred over forceRefreshData() to prevent unexpected edits on data source.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for specific data source
* type.
*
* @returns The data object.
*/
refreshData(): SpreadsheetApp.DataSourceFormula
/**
* Updates the formula.
*
* @param formula - The new formula.
*
* @returns The data source formula, for chaining.
*/
setFormula(
formula: string
): SpreadsheetApp.DataSourceFormula
/**
* Waits until the current execution completes, timing out after the provided number of seconds.
* Throws an exception if the execution is not completed when timing out, but does not cancel the
* data execution.
*
* @param timeoutInSeconds - The time to wait for data execution, in seconds. The maximum is 300
* seconds.
*
* @returns The data execution status.
*/
waitForCompletion(
timeoutInSeconds: number
): SpreadsheetApp.DataExecutionStatus
}
class DataSourceParameter {
private constructor();
/**
* Gets the parameter name.
*
* @returns The parameter name.
*/
getName(): string
/**
* Gets the source cell the parameter is valued based on, or null if the parameter type is
* not DataSourceParameterType.CELL.
*
* @returns The source cell, as specified in A1 notation.
*/
getSourceCell(): string
/**
* Gets the parameter type.
*
* @returns The parameter type.
*/
getType(): SpreadsheetApp.DataSourceParameterType
}
enum DataSourceParameterType {
/**
* The data source parameter is valued based on a cell.
*/
CELL = "CELL",
/**
* A data source parameter type that is not supported in Apps Script.
*/
DATA_SOURCE_PARAMETER_TYPE_UNSUPPORTED = "DATA_SOURCE_PARAMETER_TYPE_UNSUPPORTED",
}
class DataSourcePivotTable {
private constructor();
/**
* Adds a new pivot column group based on the specified data source column.
*
* @param columnName - The data souce column name the pivot group is based on.
*
* @returns The new pivot group.
*/
addColumnGroup(
columnName: string
): SpreadsheetApp.PivotGroup
/**
* Adds a new filter based on the specified data source column with the specified filter criteria.
*
* @param columnName - The data souce column name the filter is based on.
* @param filterCriteria - The criteria the filter uses.
*
* @returns The new filter.
*/
addFilter(
columnName: string,
filterCriteria: SpreadsheetApp.FilterCriteria
): SpreadsheetApp.PivotFilter
/**
* Adds a new pivot value based on the specified data source column with the specified summarize
* function.
*
* @param columnName - The data souce column name the pivot value is based on.
* @param summarizeFunction - The summarize function the pivot value uses.
*
* @returns The new pivot value.
*/
addPivotValue(
columnName: string,
summarizeFunction: SpreadsheetApp.PivotTableSummarizeFunction
): SpreadsheetApp.PivotValue
/**
* Adds a new pivot row group based on the specified data source column.
*
* @param columnName - The data souce column name the pivot group is based on.
*
* @returns The new pivot group.
*/
addRowGroup(
columnName: string
): SpreadsheetApp.PivotGroup
/**
* Returns the data source pivot table as a regular pivot table object.
*
* @returns The pivot table.
*/
asPivotTable(): SpreadsheetApp.PivotTable
/**
* Refreshes the data of this object regardless of the current state. See refreshData() for
* more details.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for specific data source
* type.
*
* @returns The data object.
*/
forceRefreshData(): SpreadsheetApp.DataSourcePivotTable
/**
* Gets the data source the object is linked to.
*
* @returns The data source.
*/
getDataSource(): SpreadsheetApp.DataSource
/**
* Gets the data execution status of the object.
*
* @returns The data execution status.
*/
getStatus(): SpreadsheetApp.DataExecutionStatus
/**
* Refreshes the data of the object.
*
*
Throws an exception if currently in error state. Use DataSource#updateSpec() to update the specification. The method is
* preferred over forceRefreshData() to prevent unexpected edits on data source.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for specific data source
* type.
*
* @returns The data object.
*/
refreshData(): SpreadsheetApp.DataSourcePivotTable
/**
* Waits until the current execution completes, timing out after the provided number of seconds.
* Throws an exception if the execution is not completed when timing out, but does not cancel the
* data execution.
*
* @param timeoutInSeconds - The time to wait for data execution, in seconds. The maximum is 300
* seconds.
*
* @returns The data execution status.
*/
waitForCompletion(
timeoutInSeconds: number
): SpreadsheetApp.DataExecutionStatus
}
class DataSourceRefreshSchedule {
private constructor();
/**
* Gets the refresh schedule frequency, which specifies how often and when to refresh.
*
* @returns The refresh schedule frequency.
*/
getFrequency(): SpreadsheetApp.DataSourceRefreshScheduleFrequency
/**
* Gets the scope of this refresh schedule.
*
* @returns The refresh scope.
*/
getScope(): SpreadsheetApp.DataSourceRefreshScope
/**
* Gets the time window of the next run of this refresh schedule. Only applies if this refresh
* schedule is enabled.
*
* @returns The time window of the next run.
*/
getTimeIntervalOfNextRun(): TimeInterval
/**
* Determines whether this refresh schedule is enabled.
*
* @returns Whether this refresh schedule is enabled.
*/
isEnabled(): Boolean
}
class DataSourceRefreshScheduleFrequency {
private constructor();
/**
* Gets the days of the month as numbers (1-28) on which to refresh the data source. Only applies
* if frequency type is monthly.
*
* @returns The days of the month on which to refresh.
*/
getDaysOfTheMonth(): number[]
/**
* Gets the days of the week on which to refresh the data source. Only applies if the frequency
* type is weekly.
*
* @returns The days of the week on which to refresh.
*/
getDaysOfTheWeek(): Weekday[]
/**
* Gets the frequency type.
*
* @returns The frequency type.
*/
getFrequencyType(): SpreadsheetApp.FrequencyType
/**
* Gets the start hour (as a number 0-23) of the time interval during which the refresh schedule
* runs. For example, if the start hour is 13 and the time interval's duration is 4 hours, then
* the data source is refreshed between 1 p.m. and 5 p.m. The hour is in the timezone of the
* spreadsheet.
*
* @returns The start hour.
*/
getStartHour(): number
}
enum DataSourceRefreshScope {
/**
* The refresh applies to all data sources in the spreadsheet.
*/
ALL_DATA_SOURCES = "ALL_DATA_SOURCES",
/**
* The data source refresh scope is unsupported.
*/
DATA_SOURCE_REFRESH_SCOPE_UNSUPPORTED = "DATA_SOURCE_REFRESH_SCOPE_UNSUPPORTED",
}
class DataSourceSheet {
private constructor();
/**
* Adds a filter applied to the data source sheet.
*
* @param columnName - The name of the column to apply this filter to.
* @param filterCriteria - The filter criteria to apply.
*
* @returns The data source sheet, for method chaining.
*/
addFilter(
columnName: string,
filterCriteria: SpreadsheetApp.FilterCriteria
): SpreadsheetApp.DataSourceSheet
/**
* Returns the data source sheet as a regular sheet object.
*
* @returns The regular sheet.
*/
asSheet(): SpreadsheetApp.Sheet
/**
* Auto resizes the width of the specified column.
*
* @param columnName - The column name.
*
* @returns This data source sheet, for chaining.
*/
autoResizeColumn(
columnName: string
): SpreadsheetApp.DataSourceSheet
/**
* Auto resizes the width of the specified columns.
*
* @param columnNames - The list of column names to update.
*
* @returns This data source sheet, for chaining.
*/
autoResizeColumns(
columnNames: string[]
): SpreadsheetApp.DataSourceSheet
/**
* Refreshes the data of this object regardless of the current state. See refreshData() for
* more details.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for specific data source
* type.
*
* @returns The data object.
*/
forceRefreshData(): SpreadsheetApp.DataSourceSheet
/**
* Returns the width of the specified column.
*
* @param columnName - The column name.
*
* @returns The column's width, or null if the column uses the default width.
*/
getColumnWidth(
columnName: string
): number
/**
* Gets the data source the object is linked to.
*
* @returns The data source.
*/
getDataSource(): SpreadsheetApp.DataSource
/**
* Returns all filters applied to the data source sheet.
*
* @returns An array of all filters applied to the data source sheet.
*/
getFilters(): SpreadsheetApp.DataSourceSheetFilter[]
/**
* Returns all the values for the data source sheet for the provided column name.
*
* @param columnName - The data source column name to fetch values for.
*
* @returns A one-dimensional array of values.
*/
getSheetValues(
columnName: string
): object[]
/**
* Returns all the values for the data source sheet for the provided column name from the provided
* start row (based-1) and up to the provided numRows.
*
* @param columnName - The data source column name to fetch values for.
* @param startRow - The row position to start fetching values from.
* @param numRows - The number of rows to fetch.
*
* @returns A one-dimensional array of values.
*/
getSheetValues(
columnName: string,
startRow: number,
numRows: number
): object[]
/**
* Gets all the sort specs in the data source sheet.
*
* @returns A list of sort specs.
*/
getSortSpecs(): SpreadsheetApp.SortSpec[]
/**
* Gets the data execution status of the object.
*
* @returns The data execution status.
*/
getStatus(): SpreadsheetApp.DataExecutionStatus
/**
* Refreshes the data of the object.
*
*
Throws an exception if currently in error state. Use DataSource#updateSpec() to update the specification. The method is
* preferred over forceRefreshData() to prevent unexpected edits on data source.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for specific data source
* type.
*
* @returns The data object.
*/
refreshData(): SpreadsheetApp.DataSourceSheet
/**
* Removes all filters applied to the data source sheet column.
*
* @param columnName - The name of the column to remove filters from.
*
* @returns The data source sheet, for method chaining.
*/
removeFilters(
columnName: string
): SpreadsheetApp.DataSourceSheet
/**
* Removes the sort spec on a column in the data source sheet.
*
* @param columnName - The name of the column.
*
* @returns The data source sheet, for chaining.
*/
removeSortSpec(
columnName: string
): SpreadsheetApp.DataSourceSheet
/**
* Sets the width of the specified column.
*
* @param columnName - The column name.
* @param width - The new width for the column.
*
* @returns This data source sheet, for chaining.
*/
setColumnWidth(
columnName: string,
width: number
): SpreadsheetApp.DataSourceSheet
/**
* Sets the width of the specified columns.
*
* @param columnNames - The list of column names to update.
* @param width - The new width for the columns.
*
* @returns This data source sheet, for chaining.
*/
setColumnWidths(
columnNames: string[],
width: number
): SpreadsheetApp.DataSourceSheet
/**
* Sets the sort spec on a column in the data source sheet.
*
* @param columnName - The name of the column to sort.
* @param ascending - If true, sort the column in ascending order; if false, sort
* the column in descending order.
*
* @returns The data source sheet, for chaining.
*/
setSortSpec(
columnName: string,
ascending: Boolean
): SpreadsheetApp.DataSourceSheet
/**
* Sets the sort spec on a column in the data source sheet.
*
* @param columnName - The name of the column to sort.
* @param sortOrder - The sort order.
*
* @returns The data source sheet, for chaining.
*/
setSortSpec(
columnName: string,
sortOrder: SpreadsheetApp.SortOrder
): SpreadsheetApp.DataSourceSheet
/**
* Waits until the current execution completes, timing out after the provided number of seconds.
* Throws an exception if the execution is not completed when timing out, but does not cancel the
* data execution.
*
* @param timeoutInSeconds - The time to wait for data execution, in seconds. The maximum is 300
* seconds.
*
* @returns The data execution status.
*/
waitForCompletion(
timeoutInSeconds: number
): SpreadsheetApp.DataExecutionStatus
}
class DataSourceSheetFilter {
private constructor();
/**
* Returns the data source column this filter applies to.
*
* @returns The data source column.
*/
getDataSourceColumn(): SpreadsheetApp.DataSourceColumn
/**
* Returns the DataSourceSheet that this filter belongs to.
*
* @returns The data source sheet, to which this filter belongs.
*/
getDataSourceSheet(): SpreadsheetApp.DataSourceSheet
/**
* Returns the filter criteria for this filter.
*
* @returns The filter criteria for this filter.
*/
getFilterCriteria(): SpreadsheetApp.FilterCriteria
/**
* Removes this filter from the data source object.
*/
remove(): void
/**
* Sets the filter criteria for this filter.
*
* @param filterCriteria - The filter criteria to set.
*
* @returns The filter for chaining.
*/
setFilterCriteria(
filterCriteria: SpreadsheetApp.FilterCriteria
): SpreadsheetApp.DataSourceSheetFilter
}
class DataSourceSpec {
private constructor();
/**
* Gets the spec for BigQuery data source.
*
* @returns The BigQuery data source spec.
*/
asBigQuery(): SpreadsheetApp.BigQueryDataSourceSpec
/**
* Creates a DataSourceSpecBuilder based on this data source's settings.
*
* @returns The builder.
*/
copy(): SpreadsheetApp.DataSourceSpecBuilder
/**
* Gets the parameters of the data source.
*
* @returns The parameter list.
*/
getParameters(): SpreadsheetApp.DataSourceParameter[]
/**
* Gets the type of the data source.
*
* @returns The data source type.
*/
getType(): SpreadsheetApp.DataSourceType
}
class DataSourceSpecBuilder {
private constructor();
/**
* Gets the builder for BigQuery data source.
*
* @returns The BigQuery data source specification builder.
*/
asBigQuery(): SpreadsheetApp.BigQueryDataSourceSpecBuilder
/**
* Builds a data source specification from the settings in this builder. Must use as...()
* to specify a data source type before building.
*
* @returns The data source specification.
*/
build(): SpreadsheetApp.DataSourceSpec
/**
* Creates a DataSourceSpecBuilder based on this data source's settings.
*
* @returns The builder.
*/
copy(): SpreadsheetApp.DataSourceSpecBuilder
/**
* Gets the parameters of the data source.
*
* @returns The parameter list.
*/
getParameters(): SpreadsheetApp.DataSourceParameter[]
/**
* Gets the type of the data source.
*
* @returns The data source type.
*/
getType(): SpreadsheetApp.DataSourceType
/**
* Removes all the parameters.
*
* @returns The builder, for chaining.
*/
removeAllParameters(): SpreadsheetApp.DataSourceSpecBuilder
/**
* Removes the specified parameter.
*
* @param parameterName - The name of the parameter to remove.
*
* @returns The builder, for chaining.
*/
removeParameter(
parameterName: string
): SpreadsheetApp.DataSourceSpecBuilder
/**
* Adds a parameter, or if the parameter with the name exists, updates its source cell.
*
* @param parameterName - The parameter name.
* @param sourceCell - The source cell, as specified in A1 notation.
*
* @returns The builder, for chaining.
*/
setParameterFromCell(
parameterName: string,
sourceCell: string
): SpreadsheetApp.DataSourceSpecBuilder
}
class DataSourceTable {
private constructor();
/**
* Adds columns to the data source table.
*
* @param columnNames - The list of the names of the columns to add.
*
* @returns The data source table, for chaining.
*/
addColumns(
columnNames: string[]
): SpreadsheetApp.DataSourceTable
/**
* Adds a filter applied to the data source table.
*
* @param columnName - The name of the column to apply this filter to.
* @param filterCriteria - The filter criteria to apply.
*
* @returns The data source table, for chaining.
*/
addFilter(
columnName: string,
filterCriteria: SpreadsheetApp.FilterCriteria
): SpreadsheetApp.DataSourceTable
/**
* Adds a sort spec on a column in the data source table.
*
* @param columnName - The name of the column to sort.
* @param ascending - If true, sort the column in ascending order; if false, sort
* the column in descending order.
*
* @returns The data source sheet, for chaining.
*/
addSortSpec(
columnName: string,
ascending: Boolean
): SpreadsheetApp.DataSourceTable
/**
* Adds a sort spec on a column in the data source table.
*
* @param columnName - The name of the column to sort.
* @param sortOrder - The sort order.
*
* @returns The data source sheet, for chaining.
*/
addSortSpec(
columnName: string,
sortOrder: SpreadsheetApp.SortOrder
): SpreadsheetApp.DataSourceTable
/**
* Refreshes the data of this object regardless of the current state. See refreshData() for
* more details.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for specific data source
* type.
*
* @returns The data object.
*/
forceRefreshData(): SpreadsheetApp.DataSourceTable
/**
* Gets all the data source columns added to the data source table.
*
* @returns A list of data source table columns.
*/
getColumns(): SpreadsheetApp.DataSourceTableColumn[]
/**
* Gets the data source the object is linked to.
*
* @returns The data source.
*/
getDataSource(): SpreadsheetApp.DataSource
/**
* Returns all filters applied to the data source table.
*
* @returns An array of all filters applied to the data source table.
*/
getFilters(): SpreadsheetApp.DataSourceTableFilter[]
/**
* Gets the Range this data source table spans.
*
* @returns The range.
*/
getRange(): SpreadsheetApp.Range
/**
* Returns the row limit for the data source table.
*
* @returns The row limit for the data source table, or null if no limit is set and the
* table uses the default max limit as in Google Sheets UI.
*/
getRowLimit(): number
/**
* Gets all the sort specs in the data source table.
*
* @returns A list of sort specs.
*/
getSortSpecs(): SpreadsheetApp.SortSpec[]
/**
* Gets the data execution status of the object.
*
* @returns The data execution status.
*/
getStatus(): SpreadsheetApp.DataExecutionStatus
/**
* Returns whether the data source table is syncing all columns in the associated data source.
*
* @returns True if the data source table is syncing all columns in the associated data
* source, or false otherwise.
*/
isSyncingAllColumns(): Boolean
/**
* Refreshes the data of the object.
*
*
Throws an exception if currently in error state. Use DataSource#updateSpec() to update the specification. The method is
* preferred over forceRefreshData() to prevent unexpected edits on data source.
*
*
Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for specific data source
* type.
*
* @returns The data object.
*/
refreshData(): SpreadsheetApp.DataSourceTable
/**
* Removes all the columns in the data source table.
*
* @returns The data source table, for chaining.
*/
removeAllColumns(): SpreadsheetApp.DataSourceTable
/**
* Removes all the sort specs in the data source table.
*
* @returns The data source sheet, for chaining.
*/
removeAllSortSpecs(): SpreadsheetApp.DataSourceTable
/**
* Updates the row limit for the data source table. If the provided row limit is null,
* then updates the data source table to use the default max row limit as in Google Sheets UI.
*
* @param rowLimit - The new row limit for the data table. If null, updates the table to use
* the default row limit.
*
* @returns The data source table, for chaining.
*/
setRowLimit(
rowLimit: number
): SpreadsheetApp.DataSourceTable
/**
* Sync all current and future columns in the associated data source to the data source table.
*
* @returns The data source table, for chaining.
*/
syncAllColumns(): SpreadsheetApp.DataSourceTable
/**
* Waits until the current execution completes, timing out after the provided number of seconds.
* Throws an exception if the execution is not completed when timing out, but does not cancel the
* data execution.
*
* @param timeoutInSeconds - The time to wait for data execution, in seconds. The maximum is 300
* seconds.
*
* @returns The data execution status.
*/
waitForCompletion(
timeoutInSeconds: number
): SpreadsheetApp.DataExecutionStatus
}
class DataSourceTableColumn {
private constructor();
/**
* Gets the data souce column.
*
* @returns The data source column.
*/
getDataSourceColumn(): SpreadsheetApp.DataSourceColumn
/**
* Removes the column from the DataSourceTable.
*/
remove(): void
}
class DataSourceTableFilter {
private constructor();
/**
* Returns the data source column this filter applies to.
*
* @returns The data source column.
*/
getDataSourceColumn(): SpreadsheetApp.DataSourceColumn
/**
* Returns the DataSourceTable that this filter belongs to.
*
* @returns The data source table, to which this filter belongs.
*/
getDataSourceTable(): SpreadsheetApp.DataSourceTable
/**
* Returns the filter criteria for this filter.
*
* @returns The filter criteria for this filter.
*/
getFilterCriteria(): SpreadsheetApp.FilterCriteria
/**
* Removes this filter from the data source object.
*/
remove(): void
/**
* Sets the filter criteria for this filter.
*
* @param filterCriteria - The filter criteria to set.
*
* @returns The filter for chaining.
*/
setFilterCriteria(
filterCriteria: SpreadsheetApp.FilterCriteria
): SpreadsheetApp.DataSourceTableFilter
}
enum DataSourceType {
/**
* A BigQuery data source.
*/
BIGQUERY = "BIGQUERY",
/**
* A data source type that is not supported in Apps Script.
*/
DATA_SOURCE_TYPE_UNSUPPORTED = "DATA_SOURCE_TYPE_UNSUPPORTED",
}
class DataValidation {
private constructor();
/**
* Creates a builder for a data validation rule based on this rule's settings.
*
*
* // Change existing data validation rules that require a date in 2013 to require a date in 2014.
* var oldDates = [new Date('1/1/2013'), new Date('12/31/2013')];
* var newDates = [new Date('1/1/2014'), new Date('12/31/2014')];
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange(1, 1, sheet.getMaxRows(), sheet.getMaxColumns());
* var rules = range.getDataValidations();
*
* for (var i = 0; i < rules.length; i++) {
* for (var j = 0; j < rules[i].length; j++) {
* var rule = rules[i][j];
*
* if (rule != null) {
* var criteria = rule.getCriteriaType();
* var args = rule.getCriteriaValues();
*
* if (criteria == SpreadsheetApp.DataValidationCriteria.DATE_BETWEEN
* && args[0].getTime() == oldDates[0].getTime()
* && args[1].getTime() == oldDates[1].getTime()) {
* // Create a builder from the existing rule, then change the dates.
* rules[i][j] = rule.copy().withCriteria(criteria, newDates).build();
* }
* }
* }
* }
* range.setDataValidations(rules);
* true if the rule shows a warning when input fails data validation, or false if it rejects the input entirely. The default for new data validation rules is true.
*
* @returns true if the rule allows input that fails data validation; false if not
*/
getAllowInvalid(): Boolean
/**
* Gets the rule's criteria type as defined in the DataValidationCriteria enum. To get the
* arguments for the criteria, use getCriteriaValues(). To use these values to create or
* modify a data validation rule, see DataValidationBuilder.withCriteria(criteria, args).
*
*
* // Log information about the data validation rule for cell A1.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = cell.getDataValidation();
* if (rule != null) {
* var criteria = rule.getCriteriaType();
* var args = rule.getCriteriaValues();
* Logger.log('The data validation rule is %s %s', criteria, args);
* } else {
* Logger.log('The cell does not have a data validation rule.')
* }
*
*
* @returns the type of data validation criteria
*/
getCriteriaType(): SpreadsheetApp.DataValidationCriteria
/**
* Gets an array of arguments for the rule's criteria. To get the criteria type, use getCriteriaType(). To use these values to create or modify a data validation rule, see DataValidationBuilder.withCriteria(criteria, args).
*
*
* // Log information about the data validation rule for cell A1.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = cell.getDataValidation();
* if (rule != null) {
* var criteria = rule.getCriteriaType();
* var args = rule.getCriteriaValues();
* Logger.log('The data validation rule is %s %s', criteria, args);
* } else {
* Logger.log('The cell does not have a data validation rule.')
* }
*
*
* @returns an array of arguments appropriate to the rule's criteria type; the number of arguments
* and their type match the corresponding require...() method of the DataValidation class
*/
getCriteriaValues(): object[]
/**
* Gets the rule's help text, or null if no help text is set.
*
* @returns the rule's help text, or null if no help text is set
*/
getHelpText(): string
}
class DataValidationBuilder {
private constructor();
/**
* Constructs a data validation rule from the settings applied to the builder.
*
* @returns a representation of the data validation rule
*/
build(): SpreadsheetApp.DataValidation
/**
* Creates a builder for a data validation rule based on this rule's settings.
*
*
* // Change existing data validation rules that require a date in 2013 to require a date in 2014.
* var oldDates = [new Date('1/1/2013'), new Date('12/31/2013')];
* var newDates = [new Date('1/1/2014'), new Date('12/31/2014')];
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange(1, 1, sheet.getMaxRows(), sheet.getMaxColumns());
* var rules = range.getDataValidations();
*
* for (var i = 0; i < rules.length; i++) {
* for (var j = 0; j < rules[i].length; j++) {
* var rule = rules[i][j];
*
* if (rule != null) {
* var criteria = rule.getCriteriaType();
* var args = rule.getCriteriaValues();
*
* if (criteria == SpreadsheetApp.DataValidationCriteria.DATE_BETWEEN
* && args[0].getTime() == oldDates[0].getTime()
* && args[1].getTime() == oldDates[1].getTime()) {
* // Create a builder from the existing rule, then change the dates.
* rules[i][j] = rule.copy().withCriteria(criteria, newDates).build();
* }
* }
* }
* }
* range.setDataValidations(rules);
* true if the rule shows a warning when input fails data validation, or false if it rejects the input entirely. The default for new data validation rules is true.
*
* @returns true if the rule allows input that fails data validation; false if not
*/
getAllowInvalid(): Boolean
/**
* Gets the rule's criteria type as defined in the DataValidationCriteria enum. To get the
* arguments for the criteria, use getCriteriaValues(). To use these values to create or
* modify a data validation rule, see withCriteria(criteria, args).
*
*
* // Log information about the data validation rule for cell A1.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = cell.getDataValidation();
* if (rule != null) {
* var criteria = rule.getCriteriaType();
* var args = rule.getCriteriaValues();
* Logger.log('The data validation rule is %s %s', criteria, args);
* } else {
* Logger.log('The cell does not have a data validation rule.')
* }
*
*
* @returns the type of data validation criteria
*/
getCriteriaType(): SpreadsheetApp.DataValidationCriteria
/**
* Gets an array of arguments for the rule's criteria. To get the criteria type, use getCriteriaType(). To use these values to create or modify a data validation rule, see withCriteria(criteria, args).
*
*
* // Log information about the data validation rule for cell A1.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = cell.getDataValidation();
* if (rule != null) {
* var criteria = rule.getCriteriaType();
* var args = rule.getCriteriaValues();
* Logger.log('The data validation rule is %s %s', criteria, args);
* } else {
* Logger.log('The cell does not have a data validation rule.')
* }
*
*
* @returns an array of arguments appropriate to the rule's criteria type; the number of arguments
* and their type match the corresponding require...() method of the DataValidationBuilder class
*/
getCriteriaValues(): object[]
/**
* Gets the rule's help text, or null if no help text is set.
*
* @returns the rule's help text, or null if no help text is set
*/
getHelpText(): string
/**
* Sets the data validation rule to require that the input is a boolean value; this value is
* rendered as a checkbox.
*
*
* // Set the data validation for cell A1 to require a boolean value; the value is rendered as a
* // checkbox.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireCheckbox().build();
* cell.setDataValidation(rule);
*
*
* @returns this builder, for chaining
*/
requireCheckbox(): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require that the input is the specified value or blank. When
* the input matches the specified value the cell is rendered as a checked checkbox. When the
* input is blank the cell is rendered as an unchecked checkbox.
*
*
* // Set the data validation for cell A1 to require a custom checked value that is rendered as a
* // checkbox.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireCheckbox('APPROVED').build();
* cell.setDataValidation(rule);
*
*
* @param checkedValue - The value assigned to a checked box.
*
* @returns this builder, for chaining
*/
requireCheckbox(
checkedValue: object
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require that the input is one of the specified values. When
* the input is checkedValue the cell is rendered as a checked checkbox. When the
* input is uncheckedValue the cell is rendered as an unchecked checkbox.
*
*
* // Set the data validation for cell A1 to require custom checked values that are rendered as a
* // checkbox.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireCheckbox('APPROVED', 'PENDING').build();
* cell.setDataValidation(rule);
*
*
* @param checkedValue - The value assigned to a checked box.
* @param uncheckedValue - The value assigned to an unchecked box.
*
* @returns this builder, for chaining
*/
requireCheckbox(
checkedValue: object,
uncheckedValue: object
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a date.
*
*
* // Set the data validation for cell A1 to require a date.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireDate().build();
* cell.setDataValidation(rule);
*
*
* @returns this builder, for chaining
*/
requireDate(): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a date after the given value. The time fields of the
* Date object are ignored; only the day, month, and year fields are used.
*
*
* // Set the data validation for cell A1 to require a date after January 1, 2013.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireDateAfter(new Date('1/1/2013')).build();
* cell.setDataValidation(rule);
*
*
* @param date - The latest unacceptable date.
*
* @returns this builder, for chaining
*/
requireDateAfter(
date: Date
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a date before the given value. The time fields of the
* Date object are ignored; only the day, month, and year fields are used.
*
*
* // Set the data validation for cell A1 to require a date before January 1, 2013.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireDateBefore(new Date('1/1/2013')).build();
* cell.setDataValidation(rule);
*
*
* @param date - The earliest unacceptable date.
*
* @returns this builder, for chaining
*/
requireDateBefore(
date: Date
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a date that falls between, or is either of, two
* specified dates. The time fields of the Date objects are ignored; only the day, month,
* and year fields are used.
*
*
* // Set the data validation for cell A1 to require a date in 2013.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation()
* .requireDateBetween(new Date('1/1/2013'), new Date('12/31/2013')).build();
* cell.setDataValidation(rule);
*
*
* @param start - The earliest acceptable date.
* @param end - The latest acceptable date.
*
* @returns this builder, for chaining
*/
requireDateBetween(
start: Date,
end: Date
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a date equal to the given value. The time fields of
* the Date object are ignored; only the day, month, and year fields are used.
*
*
* // Set the data validation for cell A1 to require a date equal to January 1, 2013.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireDateEqualTo(new Date('1/1/2013'))
* .build();
* cell.setDataValidation(rule);
*
*
* @param date - The sole acceptable date.
*
* @returns this builder, for chaining
*/
requireDateEqualTo(
date: Date
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a date that does not fall between, and is neither of,
* two specified dates. The time fields of the Date objects are ignored; only the day,
* month, and year fields are used.
*
*
* // Set the data validation for cell A1 to require a date not in 2013.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation()
* .requireDateNotBetween(new Date('1/1/2013'), new Date('12/31/2013')).build();
* cell.setDataValidation(rule);
*
*
* @param start - The earliest unacceptable date.
* @param end - The latest unacceptable date.
*
* @returns this builder, for chaining
*/
requireDateNotBetween(
start: Date,
end: Date
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a date on or after the given value. The time fields of
* the Date object are ignored; only the day, month, and year fields are used.
*
*
* // Set the data validation for cell A1 to require a date on or after January 1, 2013.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation()
* .requireDateOnOrAfter(new Date('1/1/2013')).build();
* cell.setDataValidation(rule);
*
*
* @param date - The earliest acceptable date.
*
* @returns this builder, for chaining
*/
requireDateOnOrAfter(
date: Date
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a date on or before the given value. The time fields
* of the Date object are ignored; only the day, month, and year fields are used.
*
*
* // Set the data validation for cell A1 to require a date on or before January 1, 2013.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation()
* .requireDateOnOrBefore(new Date('1/1/2013')).build();
* cell.setDataValidation(rule);
*
*
* @param date - The latest acceptable date.
*
* @returns this builder, for chaining
*/
requireDateOnOrBefore(
date: Date
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require that the given formula evaluates to true.
*
*
* // Set the data validation for cell A1 to equal B1 with a custom formula.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireFormulaSatisfied('=EQ(A1,B1)').build();
* cell.setDataValidation(rule);
*
*
* @param formula - A custom formula that evaluates to true if the input is valid.
*
* @returns this builder, for chaining
*/
requireFormulaSatisfied(
formula: string
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a number that falls between, or is either of, two
* specified numbers.
*
*
* // Set the data validation for cell A1 to require a number between 1 and 10.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireNumberBetween(1, 10).build();
* cell.setDataValidation(rule);
*
*
* @param start - The lowest acceptable value.
* @param end - The highest acceptable value.
*
* @returns this builder, for chaining
*/
requireNumberBetween(
start: Number,
end: Number
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a number equal to the given value.
*
*
* // Set the data validation for cell A1 to require a number equal to 3.1415926536.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireNumberEqualTo(3.1415926536).build();
* cell.setDataValidation(rule);
*
*
* @param number - The sole acceptable value.
*
* @returns this builder, for chaining
*/
requireNumberEqualTo(
number: Number
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a number greater than the given value.
*
*
* // Set the data validation for cell A1 to require a number greater than 0.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireNumberGreaterThan(0).build();
* cell.setDataValidation(rule);
*
*
* @param number - The highest unacceptable value.
*
* @returns this builder, for chaining
*/
requireNumberGreaterThan(
number: Number
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a number greater than or equal to the given value.
*
*
* // Set the data validation for cell A1 to require a number greater than or equal to 0.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireNumberGreaterThanOrEqualTo(0).build();
* cell.setDataValidation(rule);
*
*
* @param number - The lowest acceptable value.
*
* @returns this builder, for chaining
*/
requireNumberGreaterThanOrEqualTo(
number: Number
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a number less than the given value.
*
*
* // Set the data validation for cell A1 to require a number less than 0.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireNumberLessThan(0).build();
* cell.setDataValidation(rule);
*
*
* @param number - The lowest unacceptable value.
*
* @returns this builder, for chaining
*/
requireNumberLessThan(
number: Number
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a number less than or equal to the given value.
*
*
* // Set the data validation for cell A1 to require a number less than or equal to 0.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireNumberLessThanOrEqualTo(0).build();
* cell.setDataValidation(rule);
*
*
* @param number - The highest acceptable value.
*
* @returns this builder, for chaining
*/
requireNumberLessThanOrEqualTo(
number: Number
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a number that does not fall between, and is neither
* of, two specified numbers.
*
*
* // Set the data validation for cell A1 to require a number not between 1 and 10.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireNumberNotBetween(1, 10).build();
* cell.setDataValidation(rule);
*
*
* @param start - The lowest unacceptable value.
* @param end - The highest unacceptable value.
*
* @returns this builder, for chaining
*/
requireNumberNotBetween(
start: Number,
end: Number
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require a number not equal to the given value.
*
*
* // Set the data validation for cell A1 to require a number not equal to 0.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireNumberNotEqualTo(0).build();
* cell.setDataValidation(rule);
*
*
* @param number - The sole unacceptable value.
*
* @returns this builder, for chaining
*/
requireNumberNotEqualTo(
number: Number
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require that the input contains the given value.
*
*
* // Set the data validation for cell A1 to require any value that includes "Google".
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireTextContains('Google').build();
* cell.setDataValidation(rule);
*
*
* @param text - The value that the input must contain.
*
* @returns this builder, for chaining
*/
requireTextContains(
text: string
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require that the input does not contain the given value.
*
*
* // Set the data validation for cell A1 to require any value that does not include "@".
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireTextDoesNotContain('@').build();
* cell.setDataValidation(rule);
*
*
* @param text - The value that the input must not contain.
*
* @returns this builder, for chaining
*/
requireTextDoesNotContain(
text: string
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require that the input is equal to the given value.
*
*
* // Set the data validation for cell A1 to require "Yes".
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireTextEqualTo('Yes').build();
* cell.setDataValidation(rule);
*
*
* @param text - The sole acceptable value.
*
* @returns this builder, for chaining
*/
requireTextEqualTo(
text: string
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require that the input is in the form of an email address.
*
*
* // Set the data validation for cell A1 to require text in the form of an email address.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireTextIsEmail().build();
* cell.setDataValidation(rule);
*
*
* @returns this builder, for chaining
*/
requireTextIsEmail(): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require that the input is in the form of a URL.
*
*
* // Set the data validation for cell A1 to require text in the form of a URL.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireTextIsUrl().build();
* cell.setDataValidation(rule);
*
*
* @returns this builder, for chaining
*/
requireTextIsUrl(): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require that the input is equal to one of the given values.
*
*
* // Set the data validation for cell A1 to require "Yes" or "No", with a dropdown menu.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireValueInList(['Yes', 'No']).build();
* cell.setDataValidation(rule);
*
*
* @param values - An array of acceptable values.
*
* @returns this builder, for chaining
*/
requireValueInList(
values: string[]
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require that the input is equal to one of the given values,
* with an option to hide the dropdown menu.
*
*
* // Set the data validation for cell A1 to require "Yes" or "No", with no dropdown menu.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = SpreadsheetApp.newDataValidation().requireValueInList(['Yes', 'No'], false).build();
* cell.setDataValidation(rule);
*
*
* @param values - An array of acceptable values.
* @param showDropdown - true if the spreadsheet should show a dropdown menu for the values;
* false if not.
*
* @returns this builder, for chaining
*/
requireValueInList(
values: string[],
showDropdown: Boolean
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require that the input is equal to a value in the given range.
*
*
* // Set the data validation for cell A1 to require a value from B1:B10, with a dropdown menu.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var range = SpreadsheetApp.getActive().getRange('B1:B10');
* var rule = SpreadsheetApp.newDataValidation().requireValueInRange(range).build();
* cell.setDataValidation(rule);
*
*
* @param range - A range that contains the acceptable values.
*
* @returns this builder, for chaining
*/
requireValueInRange(
range: SpreadsheetApp.Range
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to require that the input is equal to a value in the given range,
* with an option to hide the dropdown menu.
*
*
* // Set the data validation for cell A1 to require value from B1:B10, with no dropdown menu.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var range = SpreadsheetApp.getActive().getRange('B1:B10');
* var rule = SpreadsheetApp.newDataValidation().requireValueInRange(range, false).build();
* cell.setDataValidation(rule);
*
*
* @param range - A range that contains the acceptable values.
* @param showDropdown - true if the spreadsheet should show a dropdown menu for the values;
* false if not.
*
* @returns this builder, for chaining
*/
requireValueInRange(
range: SpreadsheetApp.Range,
showDropdown: Boolean
): SpreadsheetApp.DataValidationBuilder
/**
* Sets whether to show a warning when input fails data validation or whether to reject the input
* entirely. The default for new data validation rules is true.
*
* @param allowInvalidData - true if the rule should allow input that fails data validation;
* false if not.
*
* @returns this builder, for chaining
*/
setAllowInvalid(
allowInvalidData: Boolean
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the help text that appears when the user hovers over the cell on which data validation is
* set.
*
* @param helpText - The help text to set.
*
* @returns this builder, for chaining
*/
setHelpText(
helpText: string
): SpreadsheetApp.DataValidationBuilder
/**
* Sets the data validation rule to criteria defined by DataValidationCriteria values,
* typically taken from the criteria and arguments of an existing rule.
*
*
* // Change existing data validation rules that require a date in 2013 to require a date in 2014.
* var oldDates = [new Date('1/1/2013'), new Date('12/31/2013')];
* var newDates = [new Date('1/1/2014'), new Date('12/31/2014')];
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange(1, 1, sheet.getMaxRows(), sheet.getMaxColumns());
* var rules = range.getDataValidations();
*
* for (var i = 0; i < rules.length; i++) {
* for (var j = 0; j < rules[i].length; j++) {
* var rule = rules[i][j];
*
* if (rule != null) {
* var criteria = rule.getCriteriaType();
* var args = rule.getCriteriaValues();
*
* if (criteria == SpreadsheetApp.DataValidationCriteria.DATE_BETWEEN
* && args[0].getTime() == oldDates[0].getTime()
* && args[1].getTime() == oldDates[1].getTime()) {
* // Create a builder from the existing rule, then change the dates.
* rules[i][j] = rule.copy().withCriteria(criteria, newDates).build();
* }
* }
* }
* }
* range.setDataValidations(rules);
* require...() method above.
*
* @returns this builder, for chaining
*/
withCriteria(
criteria: SpreadsheetApp.DataValidationCriteria,
args: object[]
): SpreadsheetApp.DataValidationBuilder
}
enum DataValidationCriteria {
/**
* Requires that the input is a custom value or a boolean; rendered as a checkbox.
*/
CHECKBOX = "CHECKBOX",
/**
* Requires that the input makes the given formula evaluate to true.
*/
CUSTOM_FORMULA = "CUSTOM_FORMULA",
/**
* Requires a date that is after the given value.
*/
DATE_AFTER = "DATE_AFTER",
/**
* Requires a date that is before the given value.
*/
DATE_BEFORE = "DATE_BEFORE",
/**
* Requires a date that is between the given values.
*/
DATE_BETWEEN = "DATE_BETWEEN",
/**
* Requires a date that is equal to the given value.
*/
DATE_EQUAL_TO = "DATE_EQUAL_TO",
/**
* Requires a date.
*/
DATE_IS_VALID_DATE = "DATE_IS_VALID_DATE",
/**
* Requires a date that is not between the given values.
*/
DATE_NOT_BETWEEN = "DATE_NOT_BETWEEN",
/**
* Require a date that is on or after the given value.
*/
DATE_ON_OR_AFTER = "DATE_ON_OR_AFTER",
/**
* Requires a date that is on or before the given value.
*/
DATE_ON_OR_BEFORE = "DATE_ON_OR_BEFORE",
/**
* Requires a number that is between the given values.
*/
NUMBER_BETWEEN = "NUMBER_BETWEEN",
/**
* Requires a number that is equal to the given value.
*/
NUMBER_EQUAL_TO = "NUMBER_EQUAL_TO",
/**
* Require a number that is greater than the given value.
*/
NUMBER_GREATER_THAN = "NUMBER_GREATER_THAN",
/**
* Requires a number that is greater than or equal to the given value.
*/
NUMBER_GREATER_THAN_OR_EQUAL_TO = "NUMBER_GREATER_THAN_OR_EQUAL_TO",
/**
* Requires a number that is less than the given value.
*/
NUMBER_LESS_THAN = "NUMBER_LESS_THAN",
/**
* Requires a number that is less than or equal to the given value.
*/
NUMBER_LESS_THAN_OR_EQUAL_TO = "NUMBER_LESS_THAN_OR_EQUAL_TO",
/**
* Requires a number that is not between the given values.
*/
NUMBER_NOT_BETWEEN = "NUMBER_NOT_BETWEEN",
/**
* Requires a number that is not equal to the given value.
*/
NUMBER_NOT_EQUAL_TO = "NUMBER_NOT_EQUAL_TO",
/**
* Requires that the input contains the given value.
*/
TEXT_CONTAINS = "TEXT_CONTAINS",
/**
* Requires that the input does not contain the given value.
*/
TEXT_DOES_NOT_CONTAIN = "TEXT_DOES_NOT_CONTAIN",
/**
* Requires that the input is equal to the given value.
*/
TEXT_EQUAL_TO = "TEXT_EQUAL_TO",
/**
* Requires that the input is in the form of an email address.
*/
TEXT_IS_VALID_EMAIL = "TEXT_IS_VALID_EMAIL",
/**
* Requires that the input is in the form of a URL.
*/
TEXT_IS_VALID_URL = "TEXT_IS_VALID_URL",
/**
* Requires that the input is equal to one of the given values.
*/
VALUE_IN_LIST = "VALUE_IN_LIST",
/**
* Requires that the input is equal to a value in the given range.
*/
VALUE_IN_RANGE = "VALUE_IN_RANGE",
}
class DateTimeGroupingRule {
private constructor();
/**
* Gets the type of the date-time grouping rule.
*
* @returns The rule type.
*/
getRuleType(): SpreadsheetApp.DateTimeGroupingRuleType
}
enum DateTimeGroupingRuleType {
/**
* Group date-time by day and month, for example 22-Nov.
*/
DAY_MONTH = "DAY_MONTH",
/**
* Group date-time by day of month, from 1 to 31.
*/
DAY_OF_MONTH = "DAY_OF_MONTH",
/**
* Group date-time by day of week, for example Sunday.
*/
DAY_OF_WEEK = "DAY_OF_WEEK",
/**
* Group date-time by day of year, from 1 to 366.
*/
DAY_OF_YEAR = "DAY_OF_YEAR",
/**
* Group date-time by hour using a 24-hour system, from 0 to 23.
*/
HOUR = "HOUR",
/**
* Group date-time by hour and minute using a 24-hour system, for example 19:45.
*/
HOUR_MINUTE = "HOUR_MINUTE",
/**
* Group date-time by hour and minute using a 12-hour system, for example 7:45 PM.
*/
HOUR_MINUTE_AMPM = "HOUR_MINUTE_AMPM",
/**
* Group date-time by minute, from 0 to 59.
*/
MINUTE = "MINUTE",
/**
* Group date-time by month, for example Nov.
*/
MONTH = "MONTH",
/**
* Group date-time by quarter, for example Q1 (which represents Jan-Mar).
*/
QUARTER = "QUARTER",
/**
* Group date-time by second, from 0 to 59.
*/
SECOND = "SECOND",
/**
* A date-time grouping rule type that is not supported.
*/
UNSUPPORTED = "UNSUPPORTED",
/**
* Group date-time by year, for example 2008.
*/
YEAR = "YEAR",
/**
* Group date-time by year and month, for example 2008-Nov.
*/
YEAR_MONTH = "YEAR_MONTH",
/**
* Group date-time by year, month, and day, for example 2008-11-22.
*/
YEAR_MONTH_DAY = "YEAR_MONTH_DAY",
/**
* Group date-time by year and quarter, for example 2008 Q4 .
*/
YEAR_QUARTER = "YEAR_QUARTER",
}
class DeveloperMetadata {
private constructor();
/**
* Returns the unique ID associated with this developer metadata.
*
* @returns The unique ID associated with this developer metadata.
*/
getId(): number
/**
* Returns the key associated with this developer metadata.
*
* @returns The key associated with this developer metadata.
*/
getKey(): string
/**
* Returns the location of this developer metadata.
*
* @returns The location of this developer metadata.
*/
getLocation(): SpreadsheetApp.DeveloperMetadataLocation
/**
* Returns the value associated with this developer metadata, or null if this metadata has
* no value.
*
* @returns The value associated with this developer metadata, or null if this metadata has
* no value.
*/
getValue(): string
/**
* Returns the visibility of this developer metadata.
*
* @returns The visibility of this developer metadata.
*/
getVisibility(): SpreadsheetApp.DeveloperMetadataVisibility
/**
* Moves this developer metadata to the specified column. If the specified range does not
* represent a single column this throws an exception.
*
* @param column - The range representing the column that is the new location for this developer
* metadata.
*
* @returns The developer metadata, for chaining.
*/
moveToColumn(
column: SpreadsheetApp.Range
): SpreadsheetApp.DeveloperMetadata
/**
* Moves this developer metadata to the specified row. If the specified range does not represent a
* single row this throws an exception.
*
* @param row - The range representing the row that is the new location for this developer metadata.
*
* @returns The developer metadata, for chaining.
*/
moveToRow(
row: SpreadsheetApp.Range
): SpreadsheetApp.DeveloperMetadata
/**
* Moves this developer metadata to the specified sheet.
*
* @param sheet - The sheet that is the new location for this developer metata.
*
* @returns The developer metadata, for chaining.
*/
moveToSheet(
sheet: SpreadsheetApp.Sheet
): SpreadsheetApp.DeveloperMetadata
/**
* Moves this developer metadata to the top-level spreadsheet.
*
* @returns The developer metadata, for chaining.
*/
moveToSpreadsheet(): SpreadsheetApp.DeveloperMetadata
/**
* Deletes this metadata.
*/
remove(): void
/**
* Sets the key of this developer metadata to the specified value.
*
* @param key - The new key to set for this metadata.
*
* @returns The developer metadata, for chaining.
*/
setKey(
key: string
): SpreadsheetApp.DeveloperMetadata
/**
* Sets the value associated with this developer metadata to the specified value.
*
* @param value - The new value to set for this metadata.
*
* @returns The developer metadata, for chaining.
*/
setValue(
value: string
): SpreadsheetApp.DeveloperMetadata
/**
* Sets the visibility of this developer metadata to the specified visibility.
*
* @param visibility - The new visibility to set for this metadata.
*
* @returns The developer metadata, for chaining.
*/
setVisibility(
visibility: SpreadsheetApp.DeveloperMetadataVisibility
): SpreadsheetApp.DeveloperMetadata
}
class DeveloperMetadataFinder {
private constructor();
/**
* Executes this search and returns the matching metadata.
*
* @returns The developer metadata that match the search criteria.
*/
find(): SpreadsheetApp.DeveloperMetadata[]
/**
* Configures the search to consider intersecting locations that have metadata. This option is
* only valid for range-scoped searches.
*
* @returns The developer metadata finder, for chaining.
*/
onIntersectingLocations(): SpreadsheetApp.DeveloperMetadataFinder
/**
* Limits this search to consider only metadata that match the specified ID.
*
* @param id - The ID to match when searching for metadata.
*
* @returns The developer metadata finder, for chaining.
*/
withId(
id: number
): SpreadsheetApp.DeveloperMetadataFinder
/**
* Limits this search to consider only metadata that match the specified key.
*
* @param key - The key to match when searching for metadata.
*
* @returns The developer metadata finder, for chaining.
*/
withKey(
key: string
): SpreadsheetApp.DeveloperMetadataFinder
/**
* Limits this search to consider only metadata that match the specified location type.
*
* @param locationType - The location type to match when searching for metadata.
*
* @returns The developer metadata finder, for chaining.
*/
withLocationType(
locationType: SpreadsheetApp.DeveloperMetadataLocationType
): SpreadsheetApp.DeveloperMetadataFinder
/**
* Limits this search to consider only metadata that match the specified value.
*
* @param value - The value to match when searching for metadata.
*
* @returns The developer metadata finder, for chaining.
*/
withValue(
value: string
): SpreadsheetApp.DeveloperMetadataFinder
/**
* Limits this search to consider only metadata that match the specified visibility.
*
* @param visibility - The visibility to match when searching for metadata.
*
* @returns The developer metadata finder, for chaining.
*/
withVisibility(
visibility: SpreadsheetApp.DeveloperMetadataVisibility
): SpreadsheetApp.DeveloperMetadataFinder
}
class DeveloperMetadataLocation {
private constructor();
/**
* Returns the Range for the column location of this metadata, or null if the
* location type is not DeveloperMetadataLocationType.COLUMN.
*
* @returns The Range for the column location of this metadata, or null if the
* location type is not DeveloperMetadataLocationType.COLUMN.
*/
getColumn(): SpreadsheetApp.Range
/**
* Gets the type of location.
*
* @returns The location type.
*/
getLocationType(): SpreadsheetApp.DeveloperMetadataLocationType
/**
* Returns the Range for the row location of this metadata, or null if the
* location type is not DeveloperMetadataLocationType.ROW.
*
* @returns The Range for the row location of this metadata, or null if the
* location type is not DeveloperMetadataLocationType.ROW.
*/
getRow(): SpreadsheetApp.Range
/**
* Returns the Sheet location of this metadata, or null if the location type is
* not DeveloperMetadataLocationType.SHEET.
*
* @returns The Sheet location of this metadata, or null if the location type is
* not DeveloperMetadataLocationType.SHEET.
*/
getSheet(): SpreadsheetApp.Sheet
/**
* Returns the Spreadsheet location of this metadata, or null if the location
* type is not DeveloperMetadataLocationType.SPREADSHEET.
*
* @returns The Spreadsheet location of this metadata, or null if the location
* type is not DeveloperMetadataLocationType.SPREADSHEET.
*/
getSpreadsheet(): SpreadsheetApp.Spreadsheet
}
enum DeveloperMetadataLocationType {
/**
* The location type for developer metadata associated with a column.
*/
COLUMN = "COLUMN",
/**
* The location type for developer metadata associated with a row.
*/
ROW = "ROW",
/**
* The location type for developer metadata associated with a whole sheet.
*/
SHEET = "SHEET",
/**
* The location type for developer metadata associated with the top-level spreadsheet.
*/
SPREADSHEET = "SPREADSHEET",
}
enum DeveloperMetadataVisibility {
/**
* Document-visible metadata is accessible from any developer project with access to the document.
*/
DOCUMENT = "DOCUMENT",
/**
* Project-visible metadata is only visible to and accessible by the developer project that
* created the metadata. Do not use project-visible developer metadata as a security mechanism or
* to store secrets. It can be exposed to users with view access to the document.
*/
PROJECT = "PROJECT",
}
enum Dimension {
/**
* The column (vertical) dimension.
*/
COLUMNS = "COLUMNS",
/**
* The row (horizontal) dimension.
*/
ROWS = "ROWS",
}
enum Direction {
/**
* The direction of increasing row indices.
*/
DOWN = "DOWN",
/**
* The direction of increasing column indices.
*/
NEXT = "NEXT",
/**
* The direction of decreasing column indices.
*/
PREVIOUS = "PREVIOUS",
/**
* The direction of decreasing row indices.
*/
UP = "UP",
}
class Drawing {
private constructor();
/**
* Gets information about where the drawing is positioned in the sheet.
*
* @returns An object containing the drawing's container position.
*/
getContainerInfo(): SpreadsheetApp.ContainerInfo
/**
* Returns the actual height of this drawing in pixels.
*
*
* // Logs the height of all drawings in a sheet
* var drawings = SpreadsheetApp.getActiveSheet().getDrawings();
* for (var i = 0; i < drawings.length; i++) {
* Logger.log(drawings[i].getHeight());
* }
*
* // Logs the macro name of all drawings on the active sheet.
* var drawings = SpreadsheetApp.getActiveSheet().getDrawings();
* for (var i = 0; i < drawings.length; i++) {
* Logger.log(drawings[i].getOnAction());
* }
*
* // Logs the parent sheet of all drawings on the active sheet.
* var drawings = SpreadsheetApp.getActiveSheet().getDrawings();
* for (var i = 0; i < drawings.length; i++) {
* Logger.log(drawings[i].getSheet());
* }
*
* // Logs the width of all drawings in a sheet
* var drawings = SpreadsheetApp.getActiveSheet().getDrawings();
* for (var i = 0; i < drawings.length; i++) {
* Logger.log(drawings[i].getWidth());
* }
*
* // Logs the z-index of all drawings on the active sheet.
* var drawings = SpreadsheetApp.getActiveSheet().getDrawings();
* for (var i = 0; i < drawings.length; i++) {
* Logger.log(drawings[i].getZIndex());
* }
*
* // Deletes all drawings from the active sheet.
* var drawings = SpreadsheetApp.getActiveSheet().getDrawings();
* for (var i = 0; i < drawings.length; i++) {
* drawings[i].remove();
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* EmbeddedAreaChartBuilder.
*
* @returns a builder for an area chart
*/
asAreaChart(): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets the chart type to BarChart and returns an EmbeddedBarChartBuilder.
*
* @returns a builder for a bar chart
*/
asBarChart(): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets the chart type to ColumnChart and returns an EmbeddedColumnChartBuilder.
*
* @returns a builder for a column chart
*/
asColumnChart(): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets the chart type to ComboChart and returns an EmbeddedComboChartBuilder.
*
* @returns a builder for a combo chart
*/
asComboChart(): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets the chart type to HistogramChart and returns an EmbeddedHistogramChartBuilder.
*
* @returns a builder for a histogram chart
*/
asHistogramChart(): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets the chart type to LineChart and returns an EmbeddedLineChartBuilder.
*
* @returns a builder for a line chart
*/
asLineChart(): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets the chart type to PieChart and returns an EmbeddedPieChartBuilder.
*
* @returns a builder for a pie chart
*/
asPieChart(): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Sets the chart type to ScatterChart and returns an EmbeddedScatterChartBuilder.
*
* @returns a builder for a scatter chart
*/
asScatterChart(): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the chart type to TableChart and returns an EmbeddedTableChartBuilder.
*
* @returns a builder for a table chart
*/
asTableChart(): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Builds the chart to reflect all changes made to it.
*
* This method does not automatically draw the chart on top of the spreadsheet. A new chart
* must be inserted via sheet.insertChart(chart), and an existing chart should be updated
* via sheet.updateChart(chart).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This code updates the chart to use only the new ranges while preserving the existing
* // formatting of the chart.
* var chart = sheet.getCharts()[0];
* var newChart = chart
* .modify()
* .clearRanges()
* .addRange(sheet.getRange("A1:A5"))
* .addRange(sheet.getRange("B1:B5"))
* .build();
* sheet.updateChart(newChart);
* ContainerInfo, which encapsulates where the chart appears on the
* sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* // This method returns the exact same data as Chart#getContainerInfo()
* var containerInfo = chartBuilder.getContainer();
*
* // Logs the values we used in setPosition()
* Logger.log("Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s",
* containerInfo.getAnchorColumn(),
* containerInfo.getAnchorRow(),
* containerInfo.getOffsetX(),
* containerInfo.getOffsetY());
* addRange(range) and removeRange(range) to modify this list.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* var ranges = chartBuilder.getRanges();
*
* // There's only one range as a data source for this chart,
* // so this logs "A1:B8"
* for (var i in ranges) {
* var range = ranges[i];
* Logger.log(range.getA1Notation());
* }
* The range removed must match up with a range added via addRange(range);
* otherwise no change is made to the chart. This method cannot be used to partially remove values
* from a range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var firstRange = sheet.getRange("A1:B5");
* var secondRange = sheet.getRange("A6:B8");
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(firstRange)
* // This range will render in a different color
* .addRange(secondRange)
* .setPosition(5, 5, 0, 0);
*
* // Note that you can use either of these two formats, but the range
* // MUST match up with a range that was added via addRange(), or it
* // will not be removed, and will not throw an exception
* chartBuilder.removeRange(firstRange);
* chartBuilder.removeRange(sheet.getRange("A6:B8"));
*
* var chart = chartBuilder.build();
*
* sheet.insertChart(chart);
*
* // Creates a pie chart builder and sets drawing of the slices in a counter-clockwise manner.
* var builder = Charts.newPieChart();
* builder.reverseCategories();
*
* // Creates a line chart builder and sets the background color to gray
* var builder = Charts.newLineChart();
* builder.setBackgroundColor("gray");
* "blue" or "#00f").
*
* @returns This builder, useful for chaining.
*/
setBackgroundColor(
cssValue: string
): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Changes the type of chart. Not all embedded chart types are currently supported. See ChartType.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the first two lines to be drawn in green and red,
* // respectively.
* var builder = Charts.newLineChart();
* builder.setColors(["green", "red"]);
* ["red", "#acf"]. The nth element
* in the array represents the color of the nth line in the chart.
*
* @returns This builder, useful for chaining.
*/
setColors(
cssValues: string[]
): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets the strategy to use for hidden rows and columns. Defaults to IGNORE_ROWS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the legend position to right.
* var builder = Charts.newLineChart();
* builder.setLegendPosition(Charts.Position.RIGHT);
*
* // Creates a line chart builder and sets it up for a blue, 26-point legend.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setLegendTextStyle(style);
* MERGE_ROWS, rows are merged; if MERGE_COLUMNS, columns are merged. Defaults to MERGE_COLUMNS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B10");
* var range2 = sheet.getRange("C:C10");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .addRange(range2)
* .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setNumHeaders(1)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* This method does not validate the option you specify is valid for this chart type nor if the * value is of the correct format/structure. * *
This example shows how to change the animation duration to 1 second and set a legend. * *
* builder.setOption('title', 'Earnings projections');
* builder.setOption('animation.duration', 1000);
* builder.setOption('legend', {position: 'top', textStyle: {color: 'blue', fontSize: 16}});
*
* // Creates a line chart builder and sets large point style.
* var builder = Charts.newLineChart();
* builder.setPointStyle(Charts.PointStyle.LARGE);
* anchorRowPos and
* anchorColPos are 1-indexed.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* If any data points fall outside the range, the range is expanded to include those data * points. * * @param start - The value for the lowest grid line of the range axis. * @param end - The value for the highest grid line of the range axis. * * @returns This builder, useful for chaining. */ setRange( start: Number, end: Number ): SpreadsheetApp.EmbeddedAreaChartBuilder /** * Uses stacked lines, meaning that line and bar values are stacked (accumulated). By default, * there is no stacking. * * @returns This builder, useful for chaining. */ setStacked(): SpreadsheetApp.EmbeddedAreaChartBuilder /** * Sets the title of the chart. The title is displayed centered above the chart. * *
* // Creates a line chart builder and title to 'My Line Chart'.
* var builder = Charts.newLineChart();
* builder.setTitle('My Line Chart')
*
* // Creates a line chart builder and sets it up for a blue, 26-point title.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setTitleTextStyle(style);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets whether the chart's rows and columns are transposed. If set to true, the rows and
* columns are switched. Defaults to false.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setTransposeRowsAndColumns(true)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* true, the rows and columns used to construct the chart are
* transposed.
*
* @returns this builder, for chaining
*/
setTransposeRowsAndColumns(
transpose: Boolean
): SpreadsheetApp.EmbeddedChartBuilder
/**
* Sets the horizontal axis text style.
*
*
* // Creates a line chart builder and sets the X-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Adds a title to the horizontal axis. The title is centered and appears below the axis value
* labels.
*
*
* // Creates a line chart builder and sets the X-axis title.
* var builder = Charts.newLineChart();
* builder.setTitle('X-axis Title')
*
* // Creates a line chart builder and sets the X-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets the vertical axis text style.
*
*
* // Creates a line chart builder and sets the Y-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Adds a title to the vertical axis. The title is centered and appears to the left of the value
* labels.
*
*
* // Creates a line chart builder and sets the Y-axis title.
* var builder = Charts.newLineChart();
* builder.setYAxisTitle('Y-axis Title')
*
* // Creates a line chart builder and sets the Y-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Makes the range axis into a logarithmic scale (requires all values to be positive). The range
* axis are the vertical axis for vertical charts (such as line, area, or column) and the
* horizontal axis for horizontal charts (such as bar).
*
* @returns This builder, useful for chaining.
*/
useLogScale(): SpreadsheetApp.EmbeddedAreaChartBuilder
}
class EmbeddedBarChartBuilder {
private constructor();
/**
* Adds a range to the chart this builder modifies. Does not add the range if it has already been
* added to the chart.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* EmbeddedAreaChartBuilder.
*
* @returns a builder for an area chart
*/
asAreaChart(): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets the chart type to BarChart and returns an EmbeddedBarChartBuilder.
*
* @returns a builder for a bar chart
*/
asBarChart(): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets the chart type to ColumnChart and returns an EmbeddedColumnChartBuilder.
*
* @returns a builder for a column chart
*/
asColumnChart(): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets the chart type to ComboChart and returns an EmbeddedComboChartBuilder.
*
* @returns a builder for a combo chart
*/
asComboChart(): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets the chart type to HistogramChart and returns an EmbeddedHistogramChartBuilder.
*
* @returns a builder for a histogram chart
*/
asHistogramChart(): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets the chart type to LineChart and returns an EmbeddedLineChartBuilder.
*
* @returns a builder for a line chart
*/
asLineChart(): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets the chart type to PieChart and returns an EmbeddedPieChartBuilder.
*
* @returns a builder for a pie chart
*/
asPieChart(): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Sets the chart type to ScatterChart and returns an EmbeddedScatterChartBuilder.
*
* @returns a builder for a scatter chart
*/
asScatterChart(): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the chart type to TableChart and returns an EmbeddedTableChartBuilder.
*
* @returns a builder for a table chart
*/
asTableChart(): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Builds the chart to reflect all changes made to it.
*
* This method does not automatically draw the chart on top of the spreadsheet. A new chart
* must be inserted via sheet.insertChart(chart), and an existing chart should be updated
* via sheet.updateChart(chart).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This code updates the chart to use only the new ranges while preserving the existing
* // formatting of the chart.
* var chart = sheet.getCharts()[0];
* var newChart = chart
* .modify()
* .clearRanges()
* .addRange(sheet.getRange("A1:A5"))
* .addRange(sheet.getRange("B1:B5"))
* .build();
* sheet.updateChart(newChart);
* ContainerInfo, which encapsulates where the chart appears on the
* sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* // This method returns the exact same data as Chart#getContainerInfo()
* var containerInfo = chartBuilder.getContainer();
*
* // Logs the values we used in setPosition()
* Logger.log("Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s",
* containerInfo.getAnchorColumn(),
* containerInfo.getAnchorRow(),
* containerInfo.getOffsetX(),
* containerInfo.getOffsetY());
* addRange(range) and removeRange(range) to modify this list.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* var ranges = chartBuilder.getRanges();
*
* // There's only one range as a data source for this chart,
* // so this logs "A1:B8"
* for (var i in ranges) {
* var range = ranges[i];
* Logger.log(range.getA1Notation());
* }
* The range removed must match up with a range added via addRange(range);
* otherwise no change is made to the chart. This method cannot be used to partially remove values
* from a range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var firstRange = sheet.getRange("A1:B5");
* var secondRange = sheet.getRange("A6:B8");
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(firstRange)
* // This range will render in a different color
* .addRange(secondRange)
* .setPosition(5, 5, 0, 0);
*
* // Note that you can use either of these two formats, but the range
* // MUST match up with a range that was added via addRange(), or it
* // will not be removed, and will not throw an exception
* chartBuilder.removeRange(firstRange);
* chartBuilder.removeRange(sheet.getRange("A6:B8"));
*
* var chart = chartBuilder.build();
*
* sheet.insertChart(chart);
*
* // Creates a pie chart builder and sets drawing of the slices in a counter-clockwise manner.
* var builder = Charts.newPieChart();
* builder.reverseCategories();
*
* // Creates a line chart builder and sets the background color to gray
* var builder = Charts.newLineChart();
* builder.setBackgroundColor("gray");
* "blue" or "#00f").
*
* @returns This builder, useful for chaining.
*/
setBackgroundColor(
cssValue: string
): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Changes the type of chart. Not all embedded chart types are currently supported. See ChartType.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the first two lines to be drawn in green and red,
* // respectively.
* var builder = Charts.newLineChart();
* builder.setColors(["green", "red"]);
* ["red", "#acf"]. The nth element
* in the array represents the color of the nth line in the chart.
*
* @returns This builder, useful for chaining.
*/
setColors(
cssValues: string[]
): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets the strategy to use for hidden rows and columns. Defaults to IGNORE_ROWS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the legend position to right.
* var builder = Charts.newLineChart();
* builder.setLegendPosition(Charts.Position.RIGHT);
*
* // Creates a line chart builder and sets it up for a blue, 26-point legend.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setLegendTextStyle(style);
* MERGE_ROWS, rows are merged; if MERGE_COLUMNS, columns are merged. Defaults to MERGE_COLUMNS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B10");
* var range2 = sheet.getRange("C:C10");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .addRange(range2)
* .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setNumHeaders(1)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* This method does not validate the option you specify is valid for this chart type nor if the * value is of the correct format/structure. * *
This example shows how to change the animation duration to 1 second and set a legend. * *
* builder.setOption('title', 'Earnings projections');
* builder.setOption('animation.duration', 1000);
* builder.setOption('legend', {position: 'top', textStyle: {color: 'blue', fontSize: 16}});
* anchorRowPos and
* anchorColPos are 1-indexed.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* If any data points fall outside the range, the range is expanded to include those data * points. * * @param start - The value for the lowest grid line of the range axis. * @param end - The value for the highest grid line of the range axis. * * @returns This builder, useful for chaining. */ setRange( start: Number, end: Number ): SpreadsheetApp.EmbeddedBarChartBuilder /** * Uses stacked lines, meaning that line and bar values are stacked (accumulated). By default, * there is no stacking. * * @returns This builder, useful for chaining. */ setStacked(): SpreadsheetApp.EmbeddedBarChartBuilder /** * Sets the title of the chart. The title is displayed centered above the chart. * *
* // Creates a line chart builder and title to 'My Line Chart'.
* var builder = Charts.newLineChart();
* builder.setTitle('My Line Chart')
*
* // Creates a line chart builder and sets it up for a blue, 26-point title.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setTitleTextStyle(style);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets whether the chart's rows and columns are transposed. If set to true, the rows and
* columns are switched. Defaults to false.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setTransposeRowsAndColumns(true)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* true, the rows and columns used to construct the chart are
* transposed.
*
* @returns this builder, for chaining
*/
setTransposeRowsAndColumns(
transpose: Boolean
): SpreadsheetApp.EmbeddedChartBuilder
/**
* Sets the horizontal axis text style.
*
*
* // Creates a line chart builder and sets the X-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Adds a title to the horizontal axis. The title is centered and appears below the axis value
* labels.
*
*
* // Creates a line chart builder and sets the X-axis title.
* var builder = Charts.newLineChart();
* builder.setTitle('X-axis Title')
*
* // Creates a line chart builder and sets the X-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets the vertical axis text style.
*
*
* // Creates a line chart builder and sets the Y-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Adds a title to the vertical axis. The title is centered and appears to the left of the value
* labels.
*
*
* // Creates a line chart builder and sets the Y-axis title.
* var builder = Charts.newLineChart();
* builder.setYAxisTitle('Y-axis Title')
*
* // Creates a line chart builder and sets the Y-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Makes the range axis into a logarithmic scale (requires all values to be positive). The range
* axis are the vertical axis for vertical charts (such as line, area, or column) and the
* horizontal axis for horizontal charts (such as bar).
*
* @returns This builder, useful for chaining.
*/
useLogScale(): SpreadsheetApp.EmbeddedBarChartBuilder
}
class EmbeddedChart {
private constructor();
/**
* Casts to a data source chart instance if the chart is a data source chart, or null
* otherwise.
*
* @returns The data source chart.
*/
asDataSourceChart(): SpreadsheetApp.DataSourceChart
/**
* Return the data inside this object as a blob converted to the specified content type. This
* method adds the appropriate extension to the filename—for example, "myfile.pdf". However, it
* assumes that the part of the filename that follows the last period (if any) is an existing
* extension that should be replaced. Consequently, "ShoppingList.12.25.2014" becomes
* "ShoppingList.12.25.pdf".
*
* To view the daily quotas for conversions, see Quotas for Google
* Services. Newly created G Suite domains might be temporarily subject to stricter quotas.
*
* @param contentType - The MIME type to convert to. For most blobs, 'application/pdf' is
* the only valid option. For images in BMP, GIF, JPEG, or PNG format, any of 'image/bmp', 'image/gif', 'image/jpeg', or 'image/png' are also
* valid.
*
* @returns The data as a blob.
*/
getAs(
contentType: string
): Blob
/**
* Return the data inside this object as a blob.
*
* @returns The data as a blob.
*/
getBlob(): Blob
/**
* Returns a stable identifier for the chart that is unique across the spreadsheet containing the
* chart or null if the chart is not in a spreadsheet.
*
* @returns A stable chart identifier.
*/
getChartId(): number
/**
* Returns information about where the chart is positioned within a sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0)
* .build();
*
* var containerInfo = chart.getContainerInfo();
*
* // Logs the values we used in setPosition()
* Logger.log("Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s",
* containerInfo.getAnchorColumn(),
* containerInfo.getAnchorRow(),
* containerInfo.getOffsetX(),
* containerInfo.getOffsetY());
* IGNORE_ROWS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
* .setPosition(5, 5, 0, 0)
* .build()
*
* // Logs the strategy to use for hidden rows and columns which is
* // Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS in this case.
* Logger.log(chart.getHiddenDimensionStrategy());
* MERGE_ROWS, row are merged; if MERGE_COLUMNS, columns are merged. Defaults to MERGE_COLUMNS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B10");
* var range2 = sheet.getRange("C1:C10");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .addRange(range2)
* .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)
* .setPosition(5, 5, 0, 0)
* .build()
*
* // Logs whether rows of multiple ranges are merged, which is MERGE_ROWS in this case.
* Logger.log(chart.getMergeStrategy());
* MERGE_ROWS if rows are merged across multiple
* ranges; MERGE_COLUMNS if columns are merged
* across multiple ranges
*/
getMergeStrategy(): Charts.ChartMergeStrategy
/**
* Returns the number of rows or columns the range that are treated as headers.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setNumHeaders(1)
* .setPosition(5, 5, 0, 0)
* .build()
*
* // Logs the number of rows or columns to use as headers, which is 1 in this case.
* Logger.log(chart.getHeaders());
* The returned options are immutable. * * @returns The options for this chart, such as height, colors, and axes. */ getOptions(): Charts.ChartOptions /** * Returns the ranges that this chart uses as a data source. * *
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0)
* .build();
*
* var ranges = chart.getRanges();
*
* // There's only one range as a data source for this chart,
* // so this logs "A1:B8"
* for (var i in ranges) {
* var range = ranges[i];
* Logger.log(range.getA1Notation());
* }
* true, the rows and columns used to populate the chart are switched. Defaults to
* false.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .addRange(range)
* .setChartType(Charts.ChartType.BAR)
* .setTransposeRowsAndColumns(true)
* .setPosition(5, 5, 0, 0)
* .build()
*
* // Logs whether rows and columns should be transposed, which is true in this case.
* Logger.log(chart.getTransposeRowsAndColumns());
* true if the rows and columns used to construct the chart are transposed.
*/
getTransposeRowsAndColumns(): Boolean
/**
* Returns an EmbeddedChartBuilder that can be used to modify this chart. Invoke sheet.updateChart(chart) to save any changes.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var chart = sheet.getCharts()[0];
* chart = chart.modify()
* .setOption('width', 800)
* .setOption('height', 640)
* .setPosition(5, 5, 0, 0)
* .build();
* sheet.updateChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* EmbeddedAreaChartBuilder.
*
* @returns a builder for an area chart
*/
asAreaChart(): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets the chart type to BarChart and returns an EmbeddedBarChartBuilder.
*
* @returns a builder for a bar chart
*/
asBarChart(): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets the chart type to ColumnChart and returns an EmbeddedColumnChartBuilder.
*
* @returns a builder for a column chart
*/
asColumnChart(): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets the chart type to ComboChart and returns an EmbeddedComboChartBuilder.
*
* @returns a builder for a combo chart
*/
asComboChart(): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets the chart type to HistogramChart and returns an EmbeddedHistogramChartBuilder.
*
* @returns a builder for a histogram chart
*/
asHistogramChart(): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets the chart type to LineChart and returns an EmbeddedLineChartBuilder.
*
* @returns a builder for a line chart
*/
asLineChart(): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets the chart type to PieChart and returns an EmbeddedPieChartBuilder.
*
* @returns a builder for a pie chart
*/
asPieChart(): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Sets the chart type to ScatterChart and returns an EmbeddedScatterChartBuilder.
*
* @returns a builder for a scatter chart
*/
asScatterChart(): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the chart type to TableChart and returns an EmbeddedTableChartBuilder.
*
* @returns a builder for a table chart
*/
asTableChart(): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Builds the chart to reflect all changes made to it.
*
* This method does not automatically draw the chart on top of the spreadsheet. A new chart
* must be inserted via sheet.insertChart(chart), and an existing chart should be updated
* via sheet.updateChart(chart).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This code updates the chart to use only the new ranges while preserving the existing
* // formatting of the chart.
* var chart = sheet.getCharts()[0];
* var newChart = chart
* .modify()
* .clearRanges()
* .addRange(sheet.getRange("A1:A5"))
* .addRange(sheet.getRange("B1:B5"))
* .build();
* sheet.updateChart(newChart);
* ContainerInfo, which encapsulates where the chart appears on the
* sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* // This method returns the exact same data as Chart#getContainerInfo()
* var containerInfo = chartBuilder.getContainer();
*
* // Logs the values we used in setPosition()
* Logger.log("Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s",
* containerInfo.getAnchorColumn(),
* containerInfo.getAnchorRow(),
* containerInfo.getOffsetX(),
* containerInfo.getOffsetY());
* addRange(range) and removeRange(range) to modify this list.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* var ranges = chartBuilder.getRanges();
*
* // There's only one range as a data source for this chart,
* // so this logs "A1:B8"
* for (var i in ranges) {
* var range = ranges[i];
* Logger.log(range.getA1Notation());
* }
* The range removed must match up with a range added via addRange(range);
* otherwise no change is made to the chart. This method cannot be used to partially remove values
* from a range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var firstRange = sheet.getRange("A1:B5");
* var secondRange = sheet.getRange("A6:B8");
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(firstRange)
* // This range will render in a different color
* .addRange(secondRange)
* .setPosition(5, 5, 0, 0);
*
* // Note that you can use either of these two formats, but the range
* // MUST match up with a range that was added via addRange(), or it
* // will not be removed, and will not throw an exception
* chartBuilder.removeRange(firstRange);
* chartBuilder.removeRange(sheet.getRange("A6:B8"));
*
* var chart = chartBuilder.build();
*
* sheet.insertChart(chart);
* ChartType.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* IGNORE_ROWS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* MERGE_ROWS, rows are merged; if MERGE_COLUMNS, columns are merged. Defaults to MERGE_COLUMNS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B10");
* var range2 = sheet.getRange("C:C10");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .addRange(range2)
* .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setNumHeaders(1)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* This method does not validate the option you specify is valid for this chart type nor if the * value is of the correct format/structure. * *
This example shows how to change the animation duration to 1 second and set a legend. * *
* builder.setOption('title', 'Earnings projections');
* builder.setOption('animation.duration', 1000);
* builder.setOption('legend', {position: 'top', textStyle: {color: 'blue', fontSize: 16}});
* anchorRowPos and
* anchorColPos are 1-indexed.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* true, the rows and
* columns are switched. Defaults to false.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setTransposeRowsAndColumns(true)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* true, the rows and columns used to construct the chart are
* transposed.
*
* @returns this builder, for chaining
*/
setTransposeRowsAndColumns(
transpose: Boolean
): SpreadsheetApp.EmbeddedChartBuilder
}
class EmbeddedColumnChartBuilder {
private constructor();
/**
* Adds a range to the chart this builder modifies. Does not add the range if it has already been
* added to the chart.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* EmbeddedAreaChartBuilder.
*
* @returns a builder for an area chart
*/
asAreaChart(): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets the chart type to BarChart and returns an EmbeddedBarChartBuilder.
*
* @returns a builder for a bar chart
*/
asBarChart(): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets the chart type to ColumnChart and returns an EmbeddedColumnChartBuilder.
*
* @returns a builder for a column chart
*/
asColumnChart(): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets the chart type to ComboChart and returns an EmbeddedComboChartBuilder.
*
* @returns a builder for a combo chart
*/
asComboChart(): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets the chart type to HistogramChart and returns an EmbeddedHistogramChartBuilder.
*
* @returns a builder for a histogram chart
*/
asHistogramChart(): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets the chart type to LineChart and returns an EmbeddedLineChartBuilder.
*
* @returns a builder for a line chart
*/
asLineChart(): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets the chart type to PieChart and returns an EmbeddedPieChartBuilder.
*
* @returns a builder for a pie chart
*/
asPieChart(): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Sets the chart type to ScatterChart and returns an EmbeddedScatterChartBuilder.
*
* @returns a builder for a scatter chart
*/
asScatterChart(): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the chart type to TableChart and returns an EmbeddedTableChartBuilder.
*
* @returns a builder for a table chart
*/
asTableChart(): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Builds the chart to reflect all changes made to it.
*
* This method does not automatically draw the chart on top of the spreadsheet. A new chart
* must be inserted via sheet.insertChart(chart), and an existing chart should be updated
* via sheet.updateChart(chart).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This code updates the chart to use only the new ranges while preserving the existing
* // formatting of the chart.
* var chart = sheet.getCharts()[0];
* var newChart = chart
* .modify()
* .clearRanges()
* .addRange(sheet.getRange("A1:A5"))
* .addRange(sheet.getRange("B1:B5"))
* .build();
* sheet.updateChart(newChart);
* ContainerInfo, which encapsulates where the chart appears on the
* sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* // This method returns the exact same data as Chart#getContainerInfo()
* var containerInfo = chartBuilder.getContainer();
*
* // Logs the values we used in setPosition()
* Logger.log("Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s",
* containerInfo.getAnchorColumn(),
* containerInfo.getAnchorRow(),
* containerInfo.getOffsetX(),
* containerInfo.getOffsetY());
* addRange(range) and removeRange(range) to modify this list.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* var ranges = chartBuilder.getRanges();
*
* // There's only one range as a data source for this chart,
* // so this logs "A1:B8"
* for (var i in ranges) {
* var range = ranges[i];
* Logger.log(range.getA1Notation());
* }
* The range removed must match up with a range added via addRange(range);
* otherwise no change is made to the chart. This method cannot be used to partially remove values
* from a range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var firstRange = sheet.getRange("A1:B5");
* var secondRange = sheet.getRange("A6:B8");
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(firstRange)
* // This range will render in a different color
* .addRange(secondRange)
* .setPosition(5, 5, 0, 0);
*
* // Note that you can use either of these two formats, but the range
* // MUST match up with a range that was added via addRange(), or it
* // will not be removed, and will not throw an exception
* chartBuilder.removeRange(firstRange);
* chartBuilder.removeRange(sheet.getRange("A6:B8"));
*
* var chart = chartBuilder.build();
*
* sheet.insertChart(chart);
*
* // Creates a pie chart builder and sets drawing of the slices in a counter-clockwise manner.
* var builder = Charts.newPieChart();
* builder.reverseCategories();
*
* // Creates a line chart builder and sets the background color to gray
* var builder = Charts.newLineChart();
* builder.setBackgroundColor("gray");
* "blue" or "#00f").
*
* @returns This builder, useful for chaining.
*/
setBackgroundColor(
cssValue: string
): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Changes the type of chart. Not all embedded chart types are currently supported. See ChartType.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the first two lines to be drawn in green and red,
* // respectively.
* var builder = Charts.newLineChart();
* builder.setColors(["green", "red"]);
* ["red", "#acf"]. The nth element
* in the array represents the color of the nth line in the chart.
*
* @returns This builder, useful for chaining.
*/
setColors(
cssValues: string[]
): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets the strategy to use for hidden rows and columns. Defaults to IGNORE_ROWS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the legend position to right.
* var builder = Charts.newLineChart();
* builder.setLegendPosition(Charts.Position.RIGHT);
*
* // Creates a line chart builder and sets it up for a blue, 26-point legend.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setLegendTextStyle(style);
* MERGE_ROWS, rows are merged; if MERGE_COLUMNS, columns are merged. Defaults to MERGE_COLUMNS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B10");
* var range2 = sheet.getRange("C:C10");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .addRange(range2)
* .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setNumHeaders(1)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* This method does not validate the option you specify is valid for this chart type nor if the * value is of the correct format/structure. * *
This example shows how to change the animation duration to 1 second and set a legend. * *
* builder.setOption('title', 'Earnings projections');
* builder.setOption('animation.duration', 1000);
* builder.setOption('legend', {position: 'top', textStyle: {color: 'blue', fontSize: 16}});
* anchorRowPos and
* anchorColPos are 1-indexed.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* If any data points fall outside the range, the range is expanded to include those data * points. * * @param start - The value for the lowest grid line of the range axis. * @param end - The value for the highest grid line of the range axis. * * @returns This builder, useful for chaining. */ setRange( start: Number, end: Number ): SpreadsheetApp.EmbeddedColumnChartBuilder /** * Uses stacked lines, meaning that line and bar values are stacked (accumulated). By default, * there is no stacking. * * @returns This builder, useful for chaining. */ setStacked(): SpreadsheetApp.EmbeddedColumnChartBuilder /** * Sets the title of the chart. The title is displayed centered above the chart. * *
* // Creates a line chart builder and title to 'My Line Chart'.
* var builder = Charts.newLineChart();
* builder.setTitle('My Line Chart')
*
* // Creates a line chart builder and sets it up for a blue, 26-point title.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setTitleTextStyle(style);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets whether the chart's rows and columns are transposed. If set to true, the rows and
* columns are switched. Defaults to false.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setTransposeRowsAndColumns(true)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* true, the rows and columns used to construct the chart are
* transposed.
*
* @returns this builder, for chaining
*/
setTransposeRowsAndColumns(
transpose: Boolean
): SpreadsheetApp.EmbeddedChartBuilder
/**
* Sets the horizontal axis text style.
*
*
* // Creates a line chart builder and sets the X-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Adds a title to the horizontal axis. The title is centered and appears below the axis value
* labels.
*
*
* // Creates a line chart builder and sets the X-axis title.
* var builder = Charts.newLineChart();
* builder.setTitle('X-axis Title')
*
* // Creates a line chart builder and sets the X-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets the vertical axis text style.
*
*
* // Creates a line chart builder and sets the Y-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Adds a title to the vertical axis. The title is centered and appears to the left of the value
* labels.
*
*
* // Creates a line chart builder and sets the Y-axis title.
* var builder = Charts.newLineChart();
* builder.setYAxisTitle('Y-axis Title')
*
* // Creates a line chart builder and sets the Y-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Makes the range axis into a logarithmic scale (requires all values to be positive). The range
* axis are the vertical axis for vertical charts (such as line, area, or column) and the
* horizontal axis for horizontal charts (such as bar).
*
* @returns This builder, useful for chaining.
*/
useLogScale(): SpreadsheetApp.EmbeddedColumnChartBuilder
}
class EmbeddedComboChartBuilder {
private constructor();
/**
* Adds a range to the chart this builder modifies. Does not add the range if it has already been
* added to the chart.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* EmbeddedAreaChartBuilder.
*
* @returns a builder for an area chart
*/
asAreaChart(): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets the chart type to BarChart and returns an EmbeddedBarChartBuilder.
*
* @returns a builder for a bar chart
*/
asBarChart(): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets the chart type to ColumnChart and returns an EmbeddedColumnChartBuilder.
*
* @returns a builder for a column chart
*/
asColumnChart(): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets the chart type to ComboChart and returns an EmbeddedComboChartBuilder.
*
* @returns a builder for a combo chart
*/
asComboChart(): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets the chart type to HistogramChart and returns an EmbeddedHistogramChartBuilder.
*
* @returns a builder for a histogram chart
*/
asHistogramChart(): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets the chart type to LineChart and returns an EmbeddedLineChartBuilder.
*
* @returns a builder for a line chart
*/
asLineChart(): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets the chart type to PieChart and returns an EmbeddedPieChartBuilder.
*
* @returns a builder for a pie chart
*/
asPieChart(): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Sets the chart type to ScatterChart and returns an EmbeddedScatterChartBuilder.
*
* @returns a builder for a scatter chart
*/
asScatterChart(): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the chart type to TableChart and returns an EmbeddedTableChartBuilder.
*
* @returns a builder for a table chart
*/
asTableChart(): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Builds the chart to reflect all changes made to it.
*
* This method does not automatically draw the chart on top of the spreadsheet. A new chart
* must be inserted via sheet.insertChart(chart), and an existing chart should be updated
* via sheet.updateChart(chart).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This code updates the chart to use only the new ranges while preserving the existing
* // formatting of the chart.
* var chart = sheet.getCharts()[0];
* var newChart = chart
* .modify()
* .clearRanges()
* .addRange(sheet.getRange("A1:A5"))
* .addRange(sheet.getRange("B1:B5"))
* .build();
* sheet.updateChart(newChart);
* ContainerInfo, which encapsulates where the chart appears on the
* sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* // This method returns the exact same data as Chart#getContainerInfo()
* var containerInfo = chartBuilder.getContainer();
*
* // Logs the values we used in setPosition()
* Logger.log("Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s",
* containerInfo.getAnchorColumn(),
* containerInfo.getAnchorRow(),
* containerInfo.getOffsetX(),
* containerInfo.getOffsetY());
* addRange(range) and removeRange(range) to modify this list.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* var ranges = chartBuilder.getRanges();
*
* // There's only one range as a data source for this chart,
* // so this logs "A1:B8"
* for (var i in ranges) {
* var range = ranges[i];
* Logger.log(range.getA1Notation());
* }
* The range removed must match up with a range added via addRange(range);
* otherwise no change is made to the chart. This method cannot be used to partially remove values
* from a range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var firstRange = sheet.getRange("A1:B5");
* var secondRange = sheet.getRange("A6:B8");
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(firstRange)
* // This range will render in a different color
* .addRange(secondRange)
* .setPosition(5, 5, 0, 0);
*
* // Note that you can use either of these two formats, but the range
* // MUST match up with a range that was added via addRange(), or it
* // will not be removed, and will not throw an exception
* chartBuilder.removeRange(firstRange);
* chartBuilder.removeRange(sheet.getRange("A6:B8"));
*
* var chart = chartBuilder.build();
*
* sheet.insertChart(chart);
*
* // Creates a pie chart builder and sets drawing of the slices in a counter-clockwise manner.
* var builder = Charts.newPieChart();
* builder.reverseCategories();
*
* // Creates a line chart builder and sets the background color to gray
* var builder = Charts.newLineChart();
* builder.setBackgroundColor("gray");
* "blue" or "#00f").
*
* @returns This builder, useful for chaining.
*/
setBackgroundColor(
cssValue: string
): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Changes the type of chart. Not all embedded chart types are currently supported. See ChartType.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the first two lines to be drawn in green and red,
* // respectively.
* var builder = Charts.newLineChart();
* builder.setColors(["green", "red"]);
* ["red", "#acf"]. The nth element
* in the array represents the color of the nth line in the chart.
*
* @returns This builder, useful for chaining.
*/
setColors(
cssValues: string[]
): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets the strategy to use for hidden rows and columns. Defaults to IGNORE_ROWS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the legend position to right.
* var builder = Charts.newLineChart();
* builder.setLegendPosition(Charts.Position.RIGHT);
*
* // Creates a line chart builder and sets it up for a blue, 26-point legend.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setLegendTextStyle(style);
* MERGE_ROWS, rows are merged; if MERGE_COLUMNS, columns are merged. Defaults to MERGE_COLUMNS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B10");
* var range2 = sheet.getRange("C:C10");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .addRange(range2)
* .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setNumHeaders(1)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* This method does not validate the option you specify is valid for this chart type nor if the * value is of the correct format/structure. * *
This example shows how to change the animation duration to 1 second and set a legend. * *
* builder.setOption('title', 'Earnings projections');
* builder.setOption('animation.duration', 1000);
* builder.setOption('legend', {position: 'top', textStyle: {color: 'blue', fontSize: 16}});
* anchorRowPos and
* anchorColPos are 1-indexed.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* If any data points fall outside the range, the range is expanded to include those data * points. * * @param start - The value for the lowest grid line of the range axis. * @param end - The value for the highest grid line of the range axis. * * @returns This builder, useful for chaining. */ setRange( start: Number, end: Number ): SpreadsheetApp.EmbeddedComboChartBuilder /** * Uses stacked lines, meaning that line and bar values are stacked (accumulated). By default, * there is no stacking. * * @returns This builder, useful for chaining. */ setStacked(): SpreadsheetApp.EmbeddedComboChartBuilder /** * Sets the title of the chart. The title is displayed centered above the chart. * *
* // Creates a line chart builder and title to 'My Line Chart'.
* var builder = Charts.newLineChart();
* builder.setTitle('My Line Chart')
*
* // Creates a line chart builder and sets it up for a blue, 26-point title.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setTitleTextStyle(style);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets whether the chart's rows and columns are transposed. If set to true, the rows and
* columns are switched. Defaults to false.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setTransposeRowsAndColumns(true)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* true, the rows and columns used to construct the chart are
* transposed.
*
* @returns this builder, for chaining
*/
setTransposeRowsAndColumns(
transpose: Boolean
): SpreadsheetApp.EmbeddedChartBuilder
/**
* Sets the horizontal axis text style.
*
*
* // Creates a line chart builder and sets the X-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Adds a title to the horizontal axis. The title is centered and appears below the axis value
* labels.
*
*
* // Creates a line chart builder and sets the X-axis title.
* var builder = Charts.newLineChart();
* builder.setTitle('X-axis Title')
*
* // Creates a line chart builder and sets the X-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets the vertical axis text style.
*
*
* // Creates a line chart builder and sets the Y-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Adds a title to the vertical axis. The title is centered and appears to the left of the value
* labels.
*
*
* // Creates a line chart builder and sets the Y-axis title.
* var builder = Charts.newLineChart();
* builder.setYAxisTitle('Y-axis Title')
*
* // Creates a line chart builder and sets the Y-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Makes the range axis into a logarithmic scale (requires all values to be positive). The range
* axis are the vertical axis for vertical charts (such as line, area, or column) and the
* horizontal axis for horizontal charts (such as bar).
*
* @returns This builder, useful for chaining.
*/
useLogScale(): SpreadsheetApp.EmbeddedComboChartBuilder
}
class EmbeddedHistogramChartBuilder {
private constructor();
/**
* Adds a range to the chart this builder modifies. Does not add the range if it has already been
* added to the chart.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* EmbeddedAreaChartBuilder.
*
* @returns a builder for an area chart
*/
asAreaChart(): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets the chart type to BarChart and returns an EmbeddedBarChartBuilder.
*
* @returns a builder for a bar chart
*/
asBarChart(): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets the chart type to ColumnChart and returns an EmbeddedColumnChartBuilder.
*
* @returns a builder for a column chart
*/
asColumnChart(): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets the chart type to ComboChart and returns an EmbeddedComboChartBuilder.
*
* @returns a builder for a combo chart
*/
asComboChart(): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets the chart type to HistogramChart and returns an EmbeddedHistogramChartBuilder.
*
* @returns a builder for a histogram chart
*/
asHistogramChart(): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets the chart type to LineChart and returns an EmbeddedLineChartBuilder.
*
* @returns a builder for a line chart
*/
asLineChart(): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets the chart type to PieChart and returns an EmbeddedPieChartBuilder.
*
* @returns a builder for a pie chart
*/
asPieChart(): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Sets the chart type to ScatterChart and returns an EmbeddedScatterChartBuilder.
*
* @returns a builder for a scatter chart
*/
asScatterChart(): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the chart type to TableChart and returns an EmbeddedTableChartBuilder.
*
* @returns a builder for a table chart
*/
asTableChart(): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Builds the chart to reflect all changes made to it.
*
* This method does not automatically draw the chart on top of the spreadsheet. A new chart
* must be inserted via sheet.insertChart(chart), and an existing chart should be updated
* via sheet.updateChart(chart).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This code updates the chart to use only the new ranges while preserving the existing
* // formatting of the chart.
* var chart = sheet.getCharts()[0];
* var newChart = chart
* .modify()
* .clearRanges()
* .addRange(sheet.getRange("A1:A5"))
* .addRange(sheet.getRange("B1:B5"))
* .build();
* sheet.updateChart(newChart);
* ContainerInfo, which encapsulates where the chart appears on the
* sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* // This method returns the exact same data as Chart#getContainerInfo()
* var containerInfo = chartBuilder.getContainer();
*
* // Logs the values we used in setPosition()
* Logger.log("Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s",
* containerInfo.getAnchorColumn(),
* containerInfo.getAnchorRow(),
* containerInfo.getOffsetX(),
* containerInfo.getOffsetY());
* addRange(range) and removeRange(range) to modify this list.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* var ranges = chartBuilder.getRanges();
*
* // There's only one range as a data source for this chart,
* // so this logs "A1:B8"
* for (var i in ranges) {
* var range = ranges[i];
* Logger.log(range.getA1Notation());
* }
* The range removed must match up with a range added via addRange(range);
* otherwise no change is made to the chart. This method cannot be used to partially remove values
* from a range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var firstRange = sheet.getRange("A1:B5");
* var secondRange = sheet.getRange("A6:B8");
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(firstRange)
* // This range will render in a different color
* .addRange(secondRange)
* .setPosition(5, 5, 0, 0);
*
* // Note that you can use either of these two formats, but the range
* // MUST match up with a range that was added via addRange(), or it
* // will not be removed, and will not throw an exception
* chartBuilder.removeRange(firstRange);
* chartBuilder.removeRange(sheet.getRange("A6:B8"));
*
* var chart = chartBuilder.build();
*
* sheet.insertChart(chart);
*
* // Creates a pie chart builder and sets drawing of the slices in a counter-clockwise manner.
* var builder = Charts.newPieChart();
* builder.reverseCategories();
*
* // Creates a line chart builder and sets the background color to gray
* var builder = Charts.newLineChart();
* builder.setBackgroundColor("gray");
* "blue" or "#00f").
*
* @returns This builder, useful for chaining.
*/
setBackgroundColor(
cssValue: string
): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Changes the type of chart. Not all embedded chart types are currently supported. See ChartType.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the first two lines to be drawn in green and red,
* // respectively.
* var builder = Charts.newLineChart();
* builder.setColors(["green", "red"]);
* ["red", "#acf"]. The nth element
* in the array represents the color of the nth line in the chart.
*
* @returns This builder, useful for chaining.
*/
setColors(
cssValues: string[]
): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets the strategy to use for hidden rows and columns. Defaults to IGNORE_ROWS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the legend position to right.
* var builder = Charts.newLineChart();
* builder.setLegendPosition(Charts.Position.RIGHT);
*
* // Creates a line chart builder and sets it up for a blue, 26-point legend.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setLegendTextStyle(style);
* MERGE_ROWS, rows are merged; if MERGE_COLUMNS, columns are merged. Defaults to MERGE_COLUMNS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B10");
* var range2 = sheet.getRange("C:C10");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .addRange(range2)
* .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setNumHeaders(1)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* This method does not validate the option you specify is valid for this chart type nor if the * value is of the correct format/structure. * *
This example shows how to change the animation duration to 1 second and set a legend. * *
* builder.setOption('title', 'Earnings projections');
* builder.setOption('animation.duration', 1000);
* builder.setOption('legend', {position: 'top', textStyle: {color: 'blue', fontSize: 16}});
* anchorRowPos and
* anchorColPos are 1-indexed.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* If any data points fall outside the range, the range is expanded to include those data * points. * * @param start - The value for the lowest grid line of the range axis. * @param end - The value for the highest grid line of the range axis. * * @returns This builder, useful for chaining. */ setRange( start: Number, end: Number ): SpreadsheetApp.EmbeddedHistogramChartBuilder /** * Uses stacked lines, meaning that line and bar values are stacked (accumulated). By default, * there is no stacking. * * @returns This builder, useful for chaining. */ setStacked(): SpreadsheetApp.EmbeddedHistogramChartBuilder /** * Sets the title of the chart. The title is displayed centered above the chart. * *
* // Creates a line chart builder and title to 'My Line Chart'.
* var builder = Charts.newLineChart();
* builder.setTitle('My Line Chart')
*
* // Creates a line chart builder and sets it up for a blue, 26-point title.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setTitleTextStyle(style);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets whether the chart's rows and columns are transposed. If set to true, the rows and
* columns are switched. Defaults to false.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setTransposeRowsAndColumns(true)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* true, the rows and columns used to construct the chart are
* transposed.
*
* @returns this builder, for chaining
*/
setTransposeRowsAndColumns(
transpose: Boolean
): SpreadsheetApp.EmbeddedChartBuilder
/**
* Sets the horizontal axis text style.
*
*
* // Creates a line chart builder and sets the X-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Adds a title to the horizontal axis. The title is centered and appears below the axis value
* labels.
*
*
* // Creates a line chart builder and sets the X-axis title.
* var builder = Charts.newLineChart();
* builder.setTitle('X-axis Title')
*
* // Creates a line chart builder and sets the X-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets the vertical axis text style.
*
*
* // Creates a line chart builder and sets the Y-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Adds a title to the vertical axis. The title is centered and appears to the left of the value
* labels.
*
*
* // Creates a line chart builder and sets the Y-axis title.
* var builder = Charts.newLineChart();
* builder.setYAxisTitle('Y-axis Title')
*
* // Creates a line chart builder and sets the Y-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Makes the range axis into a logarithmic scale (requires all values to be positive). The range
* axis are the vertical axis for vertical charts (such as line, area, or column) and the
* horizontal axis for horizontal charts (such as bar).
*
* @returns This builder, useful for chaining.
*/
useLogScale(): SpreadsheetApp.EmbeddedHistogramChartBuilder
}
class EmbeddedLineChartBuilder {
private constructor();
/**
* Adds a range to the chart this builder modifies. Does not add the range if it has already been
* added to the chart.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* EmbeddedAreaChartBuilder.
*
* @returns a builder for an area chart
*/
asAreaChart(): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets the chart type to BarChart and returns an EmbeddedBarChartBuilder.
*
* @returns a builder for a bar chart
*/
asBarChart(): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets the chart type to ColumnChart and returns an EmbeddedColumnChartBuilder.
*
* @returns a builder for a column chart
*/
asColumnChart(): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets the chart type to ComboChart and returns an EmbeddedComboChartBuilder.
*
* @returns a builder for a combo chart
*/
asComboChart(): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets the chart type to HistogramChart and returns an EmbeddedHistogramChartBuilder.
*
* @returns a builder for a histogram chart
*/
asHistogramChart(): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets the chart type to LineChart and returns an EmbeddedLineChartBuilder.
*
* @returns a builder for a line chart
*/
asLineChart(): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets the chart type to PieChart and returns an EmbeddedPieChartBuilder.
*
* @returns a builder for a pie chart
*/
asPieChart(): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Sets the chart type to ScatterChart and returns an EmbeddedScatterChartBuilder.
*
* @returns a builder for a scatter chart
*/
asScatterChart(): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the chart type to TableChart and returns an EmbeddedTableChartBuilder.
*
* @returns a builder for a table chart
*/
asTableChart(): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Builds the chart to reflect all changes made to it.
*
* This method does not automatically draw the chart on top of the spreadsheet. A new chart
* must be inserted via sheet.insertChart(chart), and an existing chart should be updated
* via sheet.updateChart(chart).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This code updates the chart to use only the new ranges while preserving the existing
* // formatting of the chart.
* var chart = sheet.getCharts()[0];
* var newChart = chart
* .modify()
* .clearRanges()
* .addRange(sheet.getRange("A1:A5"))
* .addRange(sheet.getRange("B1:B5"))
* .build();
* sheet.updateChart(newChart);
* ContainerInfo, which encapsulates where the chart appears on the
* sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* // This method returns the exact same data as Chart#getContainerInfo()
* var containerInfo = chartBuilder.getContainer();
*
* // Logs the values we used in setPosition()
* Logger.log("Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s",
* containerInfo.getAnchorColumn(),
* containerInfo.getAnchorRow(),
* containerInfo.getOffsetX(),
* containerInfo.getOffsetY());
* addRange(range) and removeRange(range) to modify this list.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* var ranges = chartBuilder.getRanges();
*
* // There's only one range as a data source for this chart,
* // so this logs "A1:B8"
* for (var i in ranges) {
* var range = ranges[i];
* Logger.log(range.getA1Notation());
* }
* The range removed must match up with a range added via addRange(range);
* otherwise no change is made to the chart. This method cannot be used to partially remove values
* from a range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var firstRange = sheet.getRange("A1:B5");
* var secondRange = sheet.getRange("A6:B8");
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(firstRange)
* // This range will render in a different color
* .addRange(secondRange)
* .setPosition(5, 5, 0, 0);
*
* // Note that you can use either of these two formats, but the range
* // MUST match up with a range that was added via addRange(), or it
* // will not be removed, and will not throw an exception
* chartBuilder.removeRange(firstRange);
* chartBuilder.removeRange(sheet.getRange("A6:B8"));
*
* var chart = chartBuilder.build();
*
* sheet.insertChart(chart);
*
* // Creates a pie chart builder and sets drawing of the slices in a counter-clockwise manner.
* var builder = Charts.newPieChart();
* builder.reverseCategories();
*
* // Creates a line chart builder and sets the background color to gray
* var builder = Charts.newLineChart();
* builder.setBackgroundColor("gray");
* "blue" or "#00f").
*
* @returns This builder, useful for chaining.
*/
setBackgroundColor(
cssValue: string
): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Changes the type of chart. Not all embedded chart types are currently supported. See ChartType.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the first two lines to be drawn in green and red,
* // respectively.
* var builder = Charts.newLineChart();
* builder.setColors(["green", "red"]);
* ["red", "#acf"]. The nth element
* in the array represents the color of the nth line in the chart.
*
* @returns This builder, useful for chaining.
*/
setColors(
cssValues: string[]
): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets the style to use for curves in the chart. See CurveStyle for allowed curve
* styles.
*
*
* // Creates a line chart builder and curves the lines in the chart.
* var builder = Charts.newLineChart();
* builder.setCurveStyle(Charts.CurveStyle.SMOOTH)
* IGNORE_ROWS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the legend position to right.
* var builder = Charts.newLineChart();
* builder.setLegendPosition(Charts.Position.RIGHT);
*
* // Creates a line chart builder and sets it up for a blue, 26-point legend.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setLegendTextStyle(style);
* MERGE_ROWS, rows are merged; if MERGE_COLUMNS, columns are merged. Defaults to MERGE_COLUMNS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B10");
* var range2 = sheet.getRange("C:C10");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .addRange(range2)
* .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setNumHeaders(1)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* This method does not validate the option you specify is valid for this chart type nor if the * value is of the correct format/structure. * *
This example shows how to change the animation duration to 1 second and set a legend. * *
* builder.setOption('title', 'Earnings projections');
* builder.setOption('animation.duration', 1000);
* builder.setOption('legend', {position: 'top', textStyle: {color: 'blue', fontSize: 16}});
*
* // Creates a line chart builder and sets large point style.
* var builder = Charts.newLineChart();
* builder.setPointStyle(Charts.PointStyle.LARGE);
* anchorRowPos and
* anchorColPos are 1-indexed.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* If any data points fall outside the range, the range is expanded to include those data * points. * * @param start - The value for the lowest grid line of the range axis. * @param end - The value for the highest grid line of the range axis. * * @returns This builder, useful for chaining. */ setRange( start: Number, end: Number ): SpreadsheetApp.EmbeddedLineChartBuilder /** * Sets the title of the chart. The title is displayed centered above the chart. * *
* // Creates a line chart builder and title to 'My Line Chart'.
* var builder = Charts.newLineChart();
* builder.setTitle('My Line Chart')
*
* // Creates a line chart builder and sets it up for a blue, 26-point title.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setTitleTextStyle(style);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets whether the chart's rows and columns are transposed. If set to true, the rows and
* columns are switched. Defaults to false.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setTransposeRowsAndColumns(true)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* true, the rows and columns used to construct the chart are
* transposed.
*
* @returns this builder, for chaining
*/
setTransposeRowsAndColumns(
transpose: Boolean
): SpreadsheetApp.EmbeddedChartBuilder
/**
* Sets the horizontal axis text style.
*
*
* // Creates a line chart builder and sets the X-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Adds a title to the horizontal axis. The title is centered and appears below the axis value
* labels.
*
*
* // Creates a line chart builder and sets the X-axis title.
* var builder = Charts.newLineChart();
* builder.setTitle('X-axis Title')
*
* // Creates a line chart builder and sets the X-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets the vertical axis text style.
*
*
* // Creates a line chart builder and sets the Y-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Adds a title to the vertical axis. The title is centered and appears to the left of the value
* labels.
*
*
* // Creates a line chart builder and sets the Y-axis title.
* var builder = Charts.newLineChart();
* builder.setYAxisTitle('Y-axis Title')
*
* // Creates a line chart builder and sets the Y-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Makes the range axis into a logarithmic scale (requires all values to be positive). The range
* axis are the vertical axis for vertical charts (such as line, area, or column) and the
* horizontal axis for horizontal charts (such as bar).
*
* @returns This builder, useful for chaining.
*/
useLogScale(): SpreadsheetApp.EmbeddedLineChartBuilder
}
class EmbeddedPieChartBuilder {
private constructor();
/**
* Adds a range to the chart this builder modifies. Does not add the range if it has already been
* added to the chart.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* EmbeddedAreaChartBuilder.
*
* @returns a builder for an area chart
*/
asAreaChart(): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets the chart type to BarChart and returns an EmbeddedBarChartBuilder.
*
* @returns a builder for a bar chart
*/
asBarChart(): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets the chart type to ColumnChart and returns an EmbeddedColumnChartBuilder.
*
* @returns a builder for a column chart
*/
asColumnChart(): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets the chart type to ComboChart and returns an EmbeddedComboChartBuilder.
*
* @returns a builder for a combo chart
*/
asComboChart(): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets the chart type to HistogramChart and returns an EmbeddedHistogramChartBuilder.
*
* @returns a builder for a histogram chart
*/
asHistogramChart(): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets the chart type to LineChart and returns an EmbeddedLineChartBuilder.
*
* @returns a builder for a line chart
*/
asLineChart(): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets the chart type to PieChart and returns an EmbeddedPieChartBuilder.
*
* @returns a builder for a pie chart
*/
asPieChart(): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Sets the chart type to ScatterChart and returns an EmbeddedScatterChartBuilder.
*
* @returns a builder for a scatter chart
*/
asScatterChart(): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the chart type to TableChart and returns an EmbeddedTableChartBuilder.
*
* @returns a builder for a table chart
*/
asTableChart(): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Builds the chart to reflect all changes made to it.
*
* This method does not automatically draw the chart on top of the spreadsheet. A new chart
* must be inserted via sheet.insertChart(chart), and an existing chart should be updated
* via sheet.updateChart(chart).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This code updates the chart to use only the new ranges while preserving the existing
* // formatting of the chart.
* var chart = sheet.getCharts()[0];
* var newChart = chart
* .modify()
* .clearRanges()
* .addRange(sheet.getRange("A1:A5"))
* .addRange(sheet.getRange("B1:B5"))
* .build();
* sheet.updateChart(newChart);
* ContainerInfo, which encapsulates where the chart appears on the
* sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* // This method returns the exact same data as Chart#getContainerInfo()
* var containerInfo = chartBuilder.getContainer();
*
* // Logs the values we used in setPosition()
* Logger.log("Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s",
* containerInfo.getAnchorColumn(),
* containerInfo.getAnchorRow(),
* containerInfo.getOffsetX(),
* containerInfo.getOffsetY());
* addRange(range) and removeRange(range) to modify this list.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* var ranges = chartBuilder.getRanges();
*
* // There's only one range as a data source for this chart,
* // so this logs "A1:B8"
* for (var i in ranges) {
* var range = ranges[i];
* Logger.log(range.getA1Notation());
* }
* The range removed must match up with a range added via addRange(range);
* otherwise no change is made to the chart. This method cannot be used to partially remove values
* from a range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var firstRange = sheet.getRange("A1:B5");
* var secondRange = sheet.getRange("A6:B8");
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(firstRange)
* // This range will render in a different color
* .addRange(secondRange)
* .setPosition(5, 5, 0, 0);
*
* // Note that you can use either of these two formats, but the range
* // MUST match up with a range that was added via addRange(), or it
* // will not be removed, and will not throw an exception
* chartBuilder.removeRange(firstRange);
* chartBuilder.removeRange(sheet.getRange("A6:B8"));
*
* var chart = chartBuilder.build();
*
* sheet.insertChart(chart);
*
* // Creates a pie chart builder and sets drawing of the slices in a counter-clockwise manner.
* var builder = Charts.newPieChart();
* builder.reverseCategories();
*
* // Creates a line chart builder and sets the background color to gray
* var builder = Charts.newLineChart();
* builder.setBackgroundColor("gray");
* "blue" or "#00f").
*
* @returns This builder, useful for chaining.
*/
setBackgroundColor(
cssValue: string
): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Changes the type of chart. Not all embedded chart types are currently supported. See ChartType.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the first two lines to be drawn in green and red,
* // respectively.
* var builder = Charts.newLineChart();
* builder.setColors(["green", "red"]);
* ["red", "#acf"]. The nth element
* in the array represents the color of the nth line in the chart.
*
* @returns This builder, useful for chaining.
*/
setColors(
cssValues: string[]
): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Sets the strategy to use for hidden rows and columns. Defaults to IGNORE_ROWS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the legend position to right.
* var builder = Charts.newLineChart();
* builder.setLegendPosition(Charts.Position.RIGHT);
*
* // Creates a line chart builder and sets it up for a blue, 26-point legend.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setLegendTextStyle(style);
* MERGE_ROWS, rows are merged; if MERGE_COLUMNS, columns are merged. Defaults to MERGE_COLUMNS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B10");
* var range2 = sheet.getRange("C:C10");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .addRange(range2)
* .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setNumHeaders(1)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* This method does not validate the option you specify is valid for this chart type nor if the * value is of the correct format/structure. * *
This example shows how to change the animation duration to 1 second and set a legend. * *
* builder.setOption('title', 'Earnings projections');
* builder.setOption('animation.duration', 1000);
* builder.setOption('legend', {position: 'top', textStyle: {color: 'blue', fontSize: 16}});
* anchorRowPos and
* anchorColPos are 1-indexed.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and title to 'My Line Chart'.
* var builder = Charts.newLineChart();
* builder.setTitle('My Line Chart')
*
* // Creates a line chart builder and sets it up for a blue, 26-point title.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setTitleTextStyle(style);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Sets whether the chart's rows and columns are transposed. If set to true, the rows and
* columns are switched. Defaults to false.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setTransposeRowsAndColumns(true)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* true, the rows and columns used to construct the chart are
* transposed.
*
* @returns this builder, for chaining
*/
setTransposeRowsAndColumns(
transpose: Boolean
): SpreadsheetApp.EmbeddedChartBuilder
}
class EmbeddedScatterChartBuilder {
private constructor();
/**
* Adds a range to the chart this builder modifies. Does not add the range if it has already been
* added to the chart.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* EmbeddedAreaChartBuilder.
*
* @returns a builder for an area chart
*/
asAreaChart(): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets the chart type to BarChart and returns an EmbeddedBarChartBuilder.
*
* @returns a builder for a bar chart
*/
asBarChart(): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets the chart type to ColumnChart and returns an EmbeddedColumnChartBuilder.
*
* @returns a builder for a column chart
*/
asColumnChart(): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets the chart type to ComboChart and returns an EmbeddedComboChartBuilder.
*
* @returns a builder for a combo chart
*/
asComboChart(): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets the chart type to HistogramChart and returns an EmbeddedHistogramChartBuilder.
*
* @returns a builder for a histogram chart
*/
asHistogramChart(): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets the chart type to LineChart and returns an EmbeddedLineChartBuilder.
*
* @returns a builder for a line chart
*/
asLineChart(): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets the chart type to PieChart and returns an EmbeddedPieChartBuilder.
*
* @returns a builder for a pie chart
*/
asPieChart(): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Sets the chart type to ScatterChart and returns an EmbeddedScatterChartBuilder.
*
* @returns a builder for a scatter chart
*/
asScatterChart(): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the chart type to TableChart and returns an EmbeddedTableChartBuilder.
*
* @returns a builder for a table chart
*/
asTableChart(): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Builds the chart to reflect all changes made to it.
*
* This method does not automatically draw the chart on top of the spreadsheet. A new chart
* must be inserted via sheet.insertChart(chart), and an existing chart should be updated
* via sheet.updateChart(chart).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This code updates the chart to use only the new ranges while preserving the existing
* // formatting of the chart.
* var chart = sheet.getCharts()[0];
* var newChart = chart
* .modify()
* .clearRanges()
* .addRange(sheet.getRange("A1:A5"))
* .addRange(sheet.getRange("B1:B5"))
* .build();
* sheet.updateChart(newChart);
* ContainerInfo, which encapsulates where the chart appears on the
* sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* // This method returns the exact same data as Chart#getContainerInfo()
* var containerInfo = chartBuilder.getContainer();
*
* // Logs the values we used in setPosition()
* Logger.log("Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s",
* containerInfo.getAnchorColumn(),
* containerInfo.getAnchorRow(),
* containerInfo.getOffsetX(),
* containerInfo.getOffsetY());
* addRange(range) and removeRange(range) to modify this list.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* var ranges = chartBuilder.getRanges();
*
* // There's only one range as a data source for this chart,
* // so this logs "A1:B8"
* for (var i in ranges) {
* var range = ranges[i];
* Logger.log(range.getA1Notation());
* }
* The range removed must match up with a range added via addRange(range);
* otherwise no change is made to the chart. This method cannot be used to partially remove values
* from a range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var firstRange = sheet.getRange("A1:B5");
* var secondRange = sheet.getRange("A6:B8");
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(firstRange)
* // This range will render in a different color
* .addRange(secondRange)
* .setPosition(5, 5, 0, 0);
*
* // Note that you can use either of these two formats, but the range
* // MUST match up with a range that was added via addRange(), or it
* // will not be removed, and will not throw an exception
* chartBuilder.removeRange(firstRange);
* chartBuilder.removeRange(sheet.getRange("A6:B8"));
*
* var chart = chartBuilder.build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the background color to gray
* var builder = Charts.newLineChart();
* builder.setBackgroundColor("gray");
* "blue" or "#00f").
*
* @returns This builder, useful for chaining.
*/
setBackgroundColor(
cssValue: string
): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Changes the type of chart. Not all embedded chart types are currently supported. See ChartType.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the first two lines to be drawn in green and red,
* // respectively.
* var builder = Charts.newLineChart();
* builder.setColors(["green", "red"]);
* ["red", "#acf"]. The nth element
* in the array represents the color of the nth line in the chart.
*
* @returns This builder, useful for chaining.
*/
setColors(
cssValues: string[]
): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the strategy to use for hidden rows and columns. Defaults to IGNORE_ROWS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and sets the legend position to right.
* var builder = Charts.newLineChart();
* builder.setLegendPosition(Charts.Position.RIGHT);
*
* // Creates a line chart builder and sets it up for a blue, 26-point legend.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setLegendTextStyle(style);
* MERGE_ROWS, rows are merged; if MERGE_COLUMNS, columns are merged. Defaults to MERGE_COLUMNS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B10");
* var range2 = sheet.getRange("C:C10");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .addRange(range2)
* .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setNumHeaders(1)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* This method does not validate the option you specify is valid for this chart type nor if the * value is of the correct format/structure. * *
This example shows how to change the animation duration to 1 second and set a legend. * *
* builder.setOption('title', 'Earnings projections');
* builder.setOption('animation.duration', 1000);
* builder.setOption('legend', {position: 'top', textStyle: {color: 'blue', fontSize: 16}});
*
* // Creates a line chart builder and sets large point style.
* var builder = Charts.newLineChart();
* builder.setPointStyle(Charts.PointStyle.LARGE);
* anchorRowPos and
* anchorColPos are 1-indexed.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* // Creates a line chart builder and title to 'My Line Chart'.
* var builder = Charts.newLineChart();
* builder.setTitle('My Line Chart')
*
* // Creates a line chart builder and sets it up for a blue, 26-point title.
* var textStyleBuilder = Charts.newTextStyle().setColor('#0000FF').setFontSize(26);
* var style = textStyleBuilder.build();
* var builder = Charts.newLineChart();
* builder.setTitleTextStyle(style);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets whether the chart's rows and columns are transposed. If set to true, the rows and
* columns are switched. Defaults to false.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setTransposeRowsAndColumns(true)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* true, the rows and columns used to construct the chart are
* transposed.
*
* @returns this builder, for chaining
*/
setTransposeRowsAndColumns(
transpose: Boolean
): SpreadsheetApp.EmbeddedChartBuilder
/**
* Makes the horizontal axis into a logarithmic scale (requires all values to be positive).
*
* @returns This builder, useful for chaining.
*/
setXAxisLogScale(): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the range for the horizontal axis of the chart.
*
* If any data points fall outside the range, the range is expanded to include those data * points. * *
* // Creates a scatter chart builder and sets the X-axis range to be 0 to 100.
* var builder = Charts.newTableChart();
* builder.setXAxisRange(0, 100);
*
* // Creates a line chart builder and sets the X-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Adds a title to the horizontal axis. The title is centered and appears below the axis value
* labels.
*
*
* // Creates a line chart builder and sets the X-axis title.
* var builder = Charts.newLineChart();
* builder.setTitle('X-axis Title')
*
* // Creates a line chart builder and sets the X-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setXAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setXAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Makes the vertical axis into a logarithmic scale (requires all values to be positive).
*
* @returns This builder, useful for chaining.
*/
setYAxisLogScale(): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the range for the vertical axis of the chart. If any data points fall outside the range,
* the range is expanded to include those data points.
*
*
* // Creates a scatter chart builder and sets the Y-axis range to be 0 to 100.
* var builder = Charts.newTableChart();
* builder.setYAxisRange(0, 100);
*
* // Creates a line chart builder and sets the Y-axis text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Adds a title to the vertical axis. The title is centered and appears to the left of the value
* labels.
*
*
* // Creates a line chart builder and sets the Y-axis title.
* var builder = Charts.newLineChart();
* builder.setYAxisTitle('Y-axis Title')
*
* // Creates a line chart builder and sets the Y-axis title text style to blue, 18-point font.
* var textStyle = Charts.newTextStyle().setColor('blue').setFontSize(18).build();
* var builder = Charts.newLineChart();
* builder.setYAxisTitleTextStyle(textStyle);
* TextStyleBuilder object by calling Charts.newTextStyle().
*
* @returns This builder, useful for chaining.
*/
setYAxisTitleTextStyle(
textStyle: Charts.TextStyle
): SpreadsheetApp.EmbeddedScatterChartBuilder
}
class EmbeddedTableChartBuilder {
private constructor();
/**
* Adds a range to the chart this builder modifies. Does not add the range if it has already been
* added to the chart.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* EmbeddedAreaChartBuilder.
*
* @returns a builder for an area chart
*/
asAreaChart(): SpreadsheetApp.EmbeddedAreaChartBuilder
/**
* Sets the chart type to BarChart and returns an EmbeddedBarChartBuilder.
*
* @returns a builder for a bar chart
*/
asBarChart(): SpreadsheetApp.EmbeddedBarChartBuilder
/**
* Sets the chart type to ColumnChart and returns an EmbeddedColumnChartBuilder.
*
* @returns a builder for a column chart
*/
asColumnChart(): SpreadsheetApp.EmbeddedColumnChartBuilder
/**
* Sets the chart type to ComboChart and returns an EmbeddedComboChartBuilder.
*
* @returns a builder for a combo chart
*/
asComboChart(): SpreadsheetApp.EmbeddedComboChartBuilder
/**
* Sets the chart type to HistogramChart and returns an EmbeddedHistogramChartBuilder.
*
* @returns a builder for a histogram chart
*/
asHistogramChart(): SpreadsheetApp.EmbeddedHistogramChartBuilder
/**
* Sets the chart type to LineChart and returns an EmbeddedLineChartBuilder.
*
* @returns a builder for a line chart
*/
asLineChart(): SpreadsheetApp.EmbeddedLineChartBuilder
/**
* Sets the chart type to PieChart and returns an EmbeddedPieChartBuilder.
*
* @returns a builder for a pie chart
*/
asPieChart(): SpreadsheetApp.EmbeddedPieChartBuilder
/**
* Sets the chart type to ScatterChart and returns an EmbeddedScatterChartBuilder.
*
* @returns a builder for a scatter chart
*/
asScatterChart(): SpreadsheetApp.EmbeddedScatterChartBuilder
/**
* Sets the chart type to TableChart and returns an EmbeddedTableChartBuilder.
*
* @returns a builder for a table chart
*/
asTableChart(): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Builds the chart to reflect all changes made to it.
*
* This method does not automatically draw the chart on top of the spreadsheet. A new chart
* must be inserted via sheet.insertChart(chart), and an existing chart should be updated
* via sheet.updateChart(chart).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This code updates the chart to use only the new ranges while preserving the existing
* // formatting of the chart.
* var chart = sheet.getCharts()[0];
* var newChart = chart
* .modify()
* .clearRanges()
* .addRange(sheet.getRange("A1:A5"))
* .addRange(sheet.getRange("B1:B5"))
* .build();
* sheet.updateChart(newChart);
* The default behavior is paging disabled. If paging is enabled the default page size is 10.
*
* @param enablePaging - true if paging should be enabled, false otherwise.
*
* @returns This builder, useful for chaining.
*/
enablePaging(
enablePaging: Boolean
): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Enables paging and sets the number of rows in each page.
*
*
The default page size is 10. * *
* // Creates a table chart builder and enables paging with page size of 5.
* var builder = Charts.newTableChart();
* builder.enablePaging(5);
* The default page size is 10, and the default start page is 0. * *
* // Creates a table chart builder and enables paging with page size of 5 and displays page 2
* // first.
* var builder = Charts.newTableChart();
* builder.enablePaging(5, 2);
* This does not affect the column index in the underlying data, only the order of display.
* Full bi-directional (BiDi) language display is not supported by the table visualization even
* with this option. This option is ignored if you enable paging (using the page option), or if
* the table has scroll bars because you have specified height and width options smaller than the
* required table size. The default behavior is RTL support disabled.
*
* @param rtlEnabled - true if right-to-left support should be enabled, false
* otherwise.
*
* @returns This builder, useful for chaining.
*/
enableRtlTable(
rtlEnabled: Boolean
): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Sets whether to sort columns when the user clicks a column heading.
*
*
If sorting is enabled, when users click on the column header the rows are automatically
* sorted. The default behavior is sorting enabled.
*
* @param enableSorting - true to enable sorting by clicking on column headers, false otherwise.
*
* @returns This builder, useful for chaining.
*/
enableSorting(
enableSorting: Boolean
): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Returns the current chart type.
*
* @returns the chart type
*/
getChartType(): Charts.ChartType
/**
* Return the chart ContainerInfo, which encapsulates where the chart appears on the
* sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* // This method returns the exact same data as Chart#getContainerInfo()
* var containerInfo = chartBuilder.getContainer();
*
* // Logs the values we used in setPosition()
* Logger.log("Anchor Column: %s\r\nAnchor Row %s\r\nOffset X %s\r\nOffset Y %s",
* containerInfo.getAnchorColumn(),
* containerInfo.getAnchorRow(),
* containerInfo.getOffsetX(),
* containerInfo.getOffsetY());
* addRange(range) and removeRange(range) to modify this list.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B8"))
* .setPosition(5, 5, 0, 0);
*
* var ranges = chartBuilder.getRanges();
*
* // There's only one range as a data source for this chart,
* // so this logs "A1:B8"
* for (var i in ranges) {
* var range = ranges[i];
* Logger.log(range.getA1Notation());
* }
* The range removed must match up with a range added via addRange(range);
* otherwise no change is made to the chart. This method cannot be used to partially remove values
* from a range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var firstRange = sheet.getRange("A1:B5");
* var secondRange = sheet.getRange("A6:B8");
*
* var chartBuilder = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(firstRange)
* // This range will render in a different color
* .addRange(secondRange)
* .setPosition(5, 5, 0, 0);
*
* // Note that you can use either of these two formats, but the range
* // MUST match up with a range that was added via addRange(), or it
* // will not be removed, and will not throw an exception
* chartBuilder.removeRange(firstRange);
* chartBuilder.removeRange(sheet.getRange("A6:B8"));
*
* var chart = chartBuilder.build();
*
* sheet.insertChart(chart);
* ChartType.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* The default row number of the first row is 1. * *
* // Creates a table chart builder and sets the first row to be 2.
* var builder = Charts.newTableChart();
* builder.setFirstRowNumber(2);
* IGNORE_ROWS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setHiddenDimensionStrategy(Charts.ChartHiddenDimensionStrategy.IGNORE_COLUMNS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* The column os sorted in ascending order and is marked with a small arrow indicating that. * *
* // Creates a table chart builder and sorts it by the second column (ascending).
* var builder = Charts.newTableChart();
* builder.setInitialSortingAscending(2);
* The column os sorted in descending order and is marked with a a small arrow indicating that. * *
* // Creates a table chart builder and sorts it by the second column (descending).
* var builder = Charts.newTableChart();
* builder.setInitialSortingDescending(2);
* MERGE_ROWS, rows are merged; if MERGE_COLUMNS, columns are merged. Defaults to MERGE_COLUMNS.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B10");
* var range2 = sheet.getRange("C:C10");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .addRange(range2)
* .setMergeStrategy(Charts.ChartMergeStrategy.MERGE_ROWS)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setNumHeaders(1)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* This method does not validate the option you specify is valid for this chart type nor if the * value is of the correct format/structure. * *
This example shows how to change the animation duration to 1 second and set a legend. * *
* builder.setOption('title', 'Earnings projections');
* builder.setOption('animation.duration', 1000);
* builder.setOption('legend', {position: 'top', textStyle: {color: 'blue', fontSize: 16}});
* anchorRowPos and
* anchorColPos are 1-indexed.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* true, the rows and
* columns are switched. Defaults to false.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B5");
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(range)
* .setTransposeRowsAndColumns(true)
* .setPosition(5, 5, 0, 0)
* .build();
*
* sheet.insertChart(chart);
* true, the rows and columns used to construct the chart are
* transposed.
*
* @returns this builder, for chaining
*/
setTransposeRowsAndColumns(
transpose: Boolean
): SpreadsheetApp.EmbeddedChartBuilder
/**
* Sets whether to show the row number as the first column of the table.
*
* The default behavior is not showing row numbers.
*
* @param showRowNumber - true if the first column of the table should show the row number,
* false otherwise.
*
* @returns This builder, useful for chaining.
*/
showRowNumberColumn(
showRowNumber: Boolean
): SpreadsheetApp.EmbeddedTableChartBuilder
/**
* Sets whether alternating color style is assigned to odd and even rows of a table chart.
*
*
The default behavior is the rows having alternating color style.
*
* @param alternate - true if color styles should be alternating, false otherwise.
*
* @returns This builder, useful for chaining.
*/
useAlternatingRowStyle(
alternate: Boolean
): SpreadsheetApp.EmbeddedTableChartBuilder
}
class Filter {
private constructor();
/**
* Gets the filter criteria on the specified column, or null if no filter criteria is set.
*
* @param columnPosition - The 1-indexed position of the column.
*
* @returns the filter criteria
*/
getColumnFilterCriteria(
columnPosition: number
): SpreadsheetApp.FilterCriteria
/**
* Gets the range this filter is applied to.
*
* @returns the range
*/
getRange(): SpreadsheetApp.Range
/**
* Removes this filter.
*/
remove(): void
/**
* Removes the filter criteria from the specified column.
*
* @param columnPosition - The 1-indexed position of the column.
*
* @returns the filter, for chaining
*/
removeColumnFilterCriteria(
columnPosition: number
): SpreadsheetApp.Filter
/**
* Sets the filter criteria on the specified column.
*
* @param columnPosition - The 1-indexed position of the column.
* @param filterCriteria - The filter criteria to set. If null, remove filter criteria from
* the specified column; alternatively, use removeColumnFilterCriteria(columnPosition).
*
* @returns the filter, for chaining
*/
setColumnFilterCriteria(
columnPosition: number,
filterCriteria: SpreadsheetApp.FilterCriteria
): SpreadsheetApp.Filter
/**
* Sorts the filtered range by the specified column, excluding the first row (the header row) in
* the range this filter is applied to.
*
* @param columnPosition - The 1-indexed position of the column.
* @param ascending - If true, sort the filtered range in ascending order; if false,
* sort the filtered range in descending order.
*
* @returns the filter, for chaining
*/
sort(
columnPosition: number,
ascending: Boolean
): SpreadsheetApp.Filter
/**
* Gets the sort specification on the specified column, or null if no sort spec is set.
*
* @param columnPosition - The 1-indexed position of the column.
*
* @returns The sort specification.
*/
getColumnSortSpec(
columnPosition: number
): SpreadsheetApp.SortSpec
}
class FilterCriteria {
private constructor();
/**
* Creates a builder for a filter criteria based on this filter criteria's settings.
*
* @returns a filter criteria builder based on this filter criteria
*/
copy(): SpreadsheetApp.FilterCriteriaBuilder
/**
* Returns the boolean criteria type as defined in the BooleanCriteria enum. To get the
* arguments for the criteria, use getCriteriaValues(). To use these values to create or
* modify a filter criteria, see FilterCriteriaBuilder.withCriteria(criteria, args).
*
* @returns the type of boolean criteria
*/
getCriteriaType(): SpreadsheetApp.BooleanCriteria
/**
* Returns an array of arguments for the boolean criteria. To get the boolean criteria type, use
* getCriteriaType(). To use these values to create or modify a filter criteria, see FilterCriteriaBuilder.withCriteria(criteria, args).
*
* @returns an array of arguments appropriate to the boolean criteria type; the number of arguments
* and their type match the corresponding when...() method of the FilterCriteriaBuilder class
*/
getCriteriaValues(): object[]
/**
* Returns the values to hide.
*
* @returns an array of values to hide
*/
getHiddenValues(): string[]
/**
* Returns the background color used as a filter criteria. Cells with this background color remain
* visible.
*
* @returns The background color used as a filter criteria.
*/
getVisibleBackgroundColor(): SpreadsheetApp.Color
/**
* Returns the foreground color used as a filter criteria. Cells with this foreground color remain
* visible.
*
* @returns The foreground color used as a filter criteria.
*/
getVisibleForegroundColor(): SpreadsheetApp.Color
/**
* Returns the values to show.
*
* @returns an array of values to show
*/
getVisibleValues(): string[]
}
class FilterCriteriaBuilder {
private constructor();
/**
* Constructs a filter criteria from the settings supplied to the builder.
*
* @returns A representation of the filter criteria.
*/
build(): SpreadsheetApp.FilterCriteria
/**
* Creates a builder for a filter criteria based on this filter criteria's settings.
*
* @returns a filter criteria builder based on this filter criteria
*/
copy(): SpreadsheetApp.FilterCriteriaBuilder
/**
* Returns the boolean criteria type as defined in the BooleanCriteria enum. To get the
* arguments for the criteria, use getCriteriaValues(). To use these values to create or
* modify a filter criteria, see withCriteria(criteria, args).
*
* @returns the type of boolean criteria
*/
getCriteriaType(): SpreadsheetApp.BooleanCriteria
/**
* Returns an array of arguments for the boolean criteria. To get the boolean criteria type, use
* getCriteriaType(). To use these values to create or modify a filter criteria, see withCriteria(criteria, args).
*
* @returns an array of arguments appropriate to the boolean criteria type; the number of arguments
* and their type match the corresponding when...() method of the FilterCriteriaBuilder class
*/
getCriteriaValues(): object[]
/**
* Returns the values to hide.
*
* @returns an array of values to hide
*/
getHiddenValues(): string[]
/**
* Returns the background color used as a filter criteria. Cells with this background color remain
* visible.
*
* @returns The background color used as a filter criteria.
*/
getVisibleBackgroundColor(): SpreadsheetApp.Color
/**
* Returns the foreground color used as a filter criteria. Cells with this foreground color remain
* visible.
*
* @returns The foreground color used as a filter criteria.
*/
getVisibleForegroundColor(): SpreadsheetApp.Color
/**
* Returns the values to show.
*
* @returns an array of values to show
*/
getVisibleValues(): string[]
/**
* Sets the values to hide. Clears any existing visible or hidden values.
*
* @param values - The list of values to hide.
*
* @returns This builder, for chaining.
*/
setHiddenValues(
values: string[]
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the background color used as a filter criteria. Cells with this background color remain
* visible. Setting a background color filter criteria removes the current color filter criteria
* from this builder.
*
* @param visibleBackgroundColor - The background color to set. This must be an RGB-style color,
* theme colors are not supported.
*
* @returns This builder, for chaining.
*/
setVisibleBackgroundColor(
visibleBackgroundColor: SpreadsheetApp.Color
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the foreground color used as a filter criteria. Cells with this foreground color remain
* visible. Setting a foreground color filter criteria removes the current color filter criteria
* from this builder.
*
* @param visibleForegroundColor - The foreground color to set. This must be an RGB-style color,
* theme colors are not supported.
*
* @returns This builder, for chaining.
*/
setVisibleForegroundColor(
visibleForegroundColor: SpreadsheetApp.Color
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the values to show. It clears any existing visible or hidden values.
*
* @param values - The list of values to show.
*
* @returns This builder, for chaining.
*/
setVisibleValues(
values: string[]
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell is empty.
*
* @returns This builder, for chaining.
*/
whenCellEmpty(): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell is not empty.
*
* @returns This builder, for chaining.
*/
whenCellNotEmpty(): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell date is after the specified value.
*
* @param date - The latest date.
*
* @returns This builder, for chaining.
*/
whenDateAfter(
date: Date
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell date is after the specified relative
* date.
*
* @param date - The latest date relative to the date type selected.
*
* @returns This builder, for chaining.
*/
whenDateAfter(
date: SpreadsheetApp.RelativeDate
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell date is before the specified date.
*
* @param date - The earliest unacceptable date.
*
* @returns This builder, for chaining.
*/
whenDateBefore(
date: Date
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where a cell date is before the specified relative date.
*
* @param date - The latest date relative to the date type selected.
*
* @returns This builder, for chaining.
*/
whenDateBefore(
date: SpreadsheetApp.RelativeDate
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where a cell date is equal to the specified date.
*
* @param date - The sole acceptable date.
*
* @returns This builder, for chaining.
*/
whenDateEqualTo(
date: Date
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where a cell date is equal to the specified relative
* date.
*
* @param date - The latest date relative to the date type selected.
*
* @returns This builder, for chaining.
*/
whenDateEqualTo(
date: SpreadsheetApp.RelativeDate
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell date is equal to any of the specified
* dates.
*
* @param dates - The acceptable values.
*
* @returns This builder, for chaining.
*/
whenDateEqualToAny(
dates: Date[]
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell date is not equal to the specified date.
*
* @param date - The latest date relative to the date type selected.
*
* @returns This builder, for chaining.
*/
whenDateNotEqualTo(
date: Date
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell date is not equal to any of the specified
* dates.
*
* @param dates - The acceptable values.
*
* @returns This builder, for chaining.
*/
whenDateNotEqualToAny(
dates: Date[]
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the specified formula (such as =B:B<C:C)
* evaluates to true.
*
* @param formula - A custom formula that evaluates to true if the input is valid.
*
* @returns This builder, for chaining.
*/
whenFormulaSatisfied(
formula: string
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell number is falls between, or is either of,
* two specified numbers.
*
* @param start - The lowest acceptable value.
* @param end - The highest acceptable value.
*
* @returns This builder, for chaining.
*/
whenNumberBetween(
start: Number,
end: Number
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell number is equal to the specified value.
*
* @param number - The sole acceptable value.
*
* @returns This builder, for chaining.
*/
whenNumberEqualTo(
number: Number
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell number is equal to any of the specified
* numbers.
*
* @param numbers - The acceptable values.
*
* @returns This builder, for chaining.
*/
whenNumberEqualToAny(
numbers: Number[]
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell number is greater than the specified
* value.
*
* @param number - The highest unacceptable value.
*
* @returns This builder, for chaining.
*/
whenNumberGreaterThan(
number: Number
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell number is greater than or equal to the
* specified value.
*
* @param number - The lowest acceptable value.
*
* @returns This builder, for chaining.
*/
whenNumberGreaterThanOrEqualTo(
number: Number
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the conditional conditional format rule to show cells where the cell number is less than
* the specified value.
*
* @param number - The lowest unacceptable value.
*
* @returns This builder, for chaining.
*/
whenNumberLessThan(
number: Number
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell number is less than or equal to the
* specified value.
*
* @param number - The highest acceptable value.
*
* @returns This builder, for chaining.
*/
whenNumberLessThanOrEqualTo(
number: Number
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell number does not fall between, and is
* neither of, two specified numbers.
*
* @param start - The lowest unacceptable value.
* @param end - The highest unacceptable value.
*
* @returns This builder, for chaining.
*/
whenNumberNotBetween(
start: Number,
end: Number
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell number is not equal to the specified
* value.
*
* @param number - The sole unacceptable value.
*
* @returns This builder, for chaining.
*/
whenNumberNotEqualTo(
number: Number
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell number is not equal to any of the
* specified numbers.
*
* @param numbers - The unacceptable values.
*
* @returns This builder, for chaining.
*/
whenNumberNotEqualToAny(
numbers: Number[]
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell text contains the specified text.
*
* @param text - The value that the input must contain.
*
* @returns This builder, for chaining.
*/
whenTextContains(
text: string
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell text does not contain the specified text.
*
* @param text - The value that the input must not contain.
*
* @returns This builder, for chaining.
*/
whenTextDoesNotContain(
text: string
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell text ends with the specified text.
*
* @param text - Text to compare against the end of the string.
*
* @returns This builder, for chaining.
*/
whenTextEndsWith(
text: string
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell text is equal to the specified text.
*
* @param text - The sole acceptable value.
*
* @returns This builder, for chaining.
*/
whenTextEqualTo(
text: string
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell text is equal to any of the specified
* values.
*
* @param texts - The acceptable values.
*
* @returns This builder, for chaining.
*/
whenTextEqualToAny(
texts: string[]
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell text is not equal to the specified text.
*
* @param text - The unacceptable value.
*
* @returns This builder, for chaining.
*/
whenTextNotEqualTo(
text: string
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell text is not equal to any of the specified
* values.
*
* @param texts - The unacceptable values.
*
* @returns This builder, for chaining.
*/
whenTextNotEqualToAny(
texts: string[]
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the filter criteria to show cells where the cell text starts with the specified text.
*
* @param text - Text to compare against the beginning of the string.
*
* @returns This builder, for chaining.
*/
whenTextStartsWith(
text: string
): SpreadsheetApp.FilterCriteriaBuilder
/**
* Sets the boolean criteria to criteria defined by BooleanCriteria values, typically
* taken from the criteria and arguments of an existing criteria.
*
*
* // Builds a filter criteria that is based on an existing criteria.
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var criteria = sheet.getFilter().getColumnFilterCriteria(1);
* var newCriteria = SpreadsheetApp.newFilterCriteria()
* .withCriteria(criteria.getCriteriaType(), criteria.getCriteriaValues())
* .setHiddenValues(['c'])
* .build();
* when...() method above.
*
* @returns This builder, for chaining.
*/
withCriteria(
criteria: SpreadsheetApp.BooleanCriteria,
args: object[]
): SpreadsheetApp.FilterCriteriaBuilder
}
enum FrequencyType {
/**
* Refresh daily.
*/
DAILY = "DAILY",
/**
* The frequency type is unsupported.
*/
FREQUENCY_TYPE_UNSUPPORTED = "FREQUENCY_TYPE_UNSUPPORTED",
/**
* Refresh monthly, on given days of the month.
*/
MONTHLY = "MONTHLY",
/**
* Refresh weekly, on given days of the week.
*/
WEEKLY = "WEEKLY",
}
class GradientCondition {
private constructor();
/**
* Gets the color set for the maximum value of this gradient condition. Returns an empty string if
* the color hasn't been set.
*
* @returns the color set for the maximum value of this gradient condition or an empty string
*/
getMaxColor(): string
/**
* Gets the color set for the maximum value of this gradient condition. Returns null if
* the color hasn't been set.
*
* @returns The color set for the maximum value of this gradient condition or null.
*/
getMaxColorObject(): SpreadsheetApp.Color
/**
* Gets the interpolation type for the maximum value of this gradient condition. Returns null if the gradient max type hasn't been set.
*
* @returns the interpolation type for the maximum value of this gradient condition or null
*/
getMaxType(): SpreadsheetApp.InterpolationType
/**
* Gets the max value of this gradient condition. Returns an empty string if the InterpolationType is MAX or if the max value hasn't been
* set.
*
* @returns the maximum value if specified or an empty string
*/
getMaxValue(): string
/**
* Gets the color set for the mid-point value of this gradient condition. Returns an empty string
* if the color hasn't been set.
*
* @returns the color set for the midpoint value of this gradient condition or an empty string
*/
getMidColor(): string
/**
* Gets the color set for the midpoint value of this gradient condition. Returns null if
* the color hasn't been set.
*
* @returns The color set for the midpoint value of this gradient condition or null.
*/
getMidColorObject(): SpreadsheetApp.Color
/**
* Gets the interpolation type for the mid-point value of this gradient condition. Returns null if the gradient mid type hasn't been set.
*
* @returns the interpolation type for the mid-point value of this gradient condition or null
*/
getMidType(): SpreadsheetApp.InterpolationType
/**
* Gets the mid-point value of this gradient condition. Returns an empty string if the gradient
* mid value hasn't been set.
*
* @returns the mid-point value or an empty string
*/
getMidValue(): string
/**
* Gets the color set for the minimum value of this gradient condition. Returns an empty string if
* the color hasn't been set.
*
* @returns the color set for the minimum value of this gradient condition or an empty string
*/
getMinColor(): string
/**
* Gets the color set for the minimum value of this gradient condition. Returns null if
* the color hasn't been set.
*
* @returns The color set for the minimum value of this gradient condition or null.
*/
getMinColorObject(): SpreadsheetApp.Color
/**
* Gets the interpolation type for the minimum value of this gradient condition. Returns null if the gradient min type hasn't been set.
*
* @returns the interpolation type for the minimum value of this gradient condition or null
*/
getMinType(): SpreadsheetApp.InterpolationType
/**
* Gets the minimum value of this gradient condition. Returns an empty string if the InterpolationType is MIN or if the min value hasn't been
* set.
*
* @returns the minimum value if specified or an empty string
*/
getMinValue(): string
}
class Group {
private constructor();
/**
* Collapses this group.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getRange(2:3);
* range.shiftRowGroupDepth(1);
* var group = sheet.getRowGroupAt(2, 1);
*
* // Collapses this group.
* group.collapse();
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getRange(2:3);
* range.shiftRowGroupDepth(1);
* var group = sheet.getRowGroupAt(2, 1);
*
* // Expands this group.
* group.expand();
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* sheet.setRowGroupControlAfter(true);
* var range = sheet.getRange(2:3);
* range.shiftRowGroupDepth(1);
* var group = sheet.getRowGroupAt(2, 1);
*
* // Returns 4
* var controlIndex = group.getControlIndex();
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getRange(2:3);
* range.shiftRowGroupDepth(1);
* var group = sheet.getRowGroupAt(2, 1);
*
* // Returns 1 if the group is at depth 1.
* var depth = group.getDepth();
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getRange(2:3);
* range.shiftRowGroupDepth(1);
* var group = sheet.getRowGroupAt(1, 1);
*
* // Returns the range 2:3 if the group is over rows 2:3
* range = group.getRange();
* true if this group is collapsed.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getRange(2:3);
* range.shiftRowGroupDepth(1);
* var group = sheet.getRowGroupAt(2, 1);
*
* // Returns true if the group is collapsed.
* var isCollapsed = group.isCollapsed();
* true if this group is collapsed; returns false otherwise
*/
isCollapsed(): Boolean
/**
* Removes this group from the sheet, reducing the group depth of the range by
* one. This may modify other groups. After calling this, the group object becomes invalid to use.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getRange(2:3);
* range.shiftRowGroupDepth(1);
* var group = sheet.getRowGroupAt(2, 1);
*
* // Removes this group
* var range = group.remove();
*
* // The code below deletes all the named ranges in the spreadsheet.
* var namedRanges = SpreadsheetApp.getActive().getNamedRanges();
* for (var i = 0; i < namedRanges.length; i++) {
* namedRanges[i].remove();
* }
*
* // The code below updates the name for the first named range.
* var namedRanges = SpreadsheetApp.getActiveSpreadsheet().getNamedRanges();
* if (namedRanges.length > 1) {
* namedRanges[0].setName("UpdatedNamedRange");
* }
* privateFunction_.
*
* @returns This image, for chaining.
*/
assignScript(
functionName: string
): SpreadsheetApp.OverGridImage
/**
* Returns the alt text description for this image.
*
* @returns The alt text description.
*/
getAltTextDescription(): string
/**
* Returns the alt text title for this image.
*
* @returns The alt text title.
*/
getAltTextTitle(): string
/**
* Returns the cell where an image is anchored.
*
* @returns The anchor cell.
*/
getAnchorCell(): SpreadsheetApp.Range
/**
* Returns the horizontal pixel offset from the anchor cell.
*
* @returns The horizontal pixel offset.
*/
getAnchorCellXOffset(): number
/**
* Returns the vertical pixel offset from the anchor cell.
*
* @returns The vertical pixel offset.
*/
getAnchorCellYOffset(): number
/**
* Returns the actual height of this image in pixels.
*
*
* // Logs the height of all images in a spreadsheet
* var images = SpreadsheetApp.getActiveSpreadsheet().getImages();
* for (var i = 0; i < images.length; i++) {
* Logger.log(images[i].getHeight());
* }
*
* // Logs the parent sheet of all images in a spreadsheet
* var images = SpreadsheetApp.getActiveSpreadsheet().getImages();
* for (var i = 0; i < images.length; i++) {
* Logger.log(images[i].getSheet());
* }
* null if the URL is unavailable. If the image was
* inserted by URL using an API, this method returns the URL provided during image insertion.
*
* @returns The image URL if available; returns null if the image is unavailable or doesn't
* have a source URL.
*/
getUrl(): string
/**
* Returns the actual width of this image in pixels.
*
*
* // Logs the width of all images in a spreadsheet
* var images = SpreadsheetApp.getActiveSpreadsheet().getImages();
* for (var i = 0; i < images.length; i++) {
* Logger.log(images[i].getWidth());
* }
*
* // Deletes all images in a spreadsheet
* var images = SpreadsheetApp.getActiveSpreadsheet().getImages();
* for (var i = 0; i < images.length; i++) {
* images[i].remove();
* }
* BlobSource.
*
* @param blob - The new image as a Blob.
*
* @returns This image, for chaining.
*/
replace(
blob: BlobSource
): SpreadsheetApp.OverGridImage
/**
* Replaces this image with the one from the specified URL.
*
* @param url - The URL of the new image.
*
* @returns This image, for chaining.
*/
replace(
url: string
): SpreadsheetApp.OverGridImage
/**
* Resets this image to its inherent dimensions.
*
* @returns This image, for chaining.
*/
resetSize(): SpreadsheetApp.OverGridImage
/**
* Sets the alt-text description for this image.
*
* @param description - The new alt text description for the image.
*
* @returns This image, for chaining.
*/
setAltTextDescription(
description: string
): SpreadsheetApp.OverGridImage
/**
* Sets the alt text title for this image.
*
* @param title - The new alt text title for the image.
*
* @returns This image, for chaining.
*/
setAltTextTitle(
title: string
): SpreadsheetApp.OverGridImage
/**
* Sets the cell where an image is anchored.
*
* @param cell - The new anchor cell.
*
* @returns This image, for chaining.
*/
setAnchorCell(
cell: SpreadsheetApp.Range
): SpreadsheetApp.OverGridImage
/**
* Sets the horizontal pixel offset from the anchor cell.
*
* @param offset - The new horizonal pixel offset.
*
* @returns This image, for chaining.
*/
setAnchorCellXOffset(
offset: number
): SpreadsheetApp.OverGridImage
/**
* Sets the vertical pixel offset from the anchor cell.
*
* @param offset - The new vertical pixel offset.
*
* @returns This image, for chaining.
*/
setAnchorCellYOffset(
offset: number
): SpreadsheetApp.OverGridImage
/**
* Sets the actual height of this image in pixels.
*
* @param height - The desired height in pixels.
*
* @returns The image for chaining.
*/
setHeight(
height: number
): SpreadsheetApp.OverGridImage
/**
* Sets the actual width of this image in pixels.
*
* @param width - The desired width in pixels.
*
* @returns The image for chaining.
*/
setWidth(
width: number
): SpreadsheetApp.OverGridImage
}
class PageProtection {
private constructor();
/**
* Adds a user to the list of users who can edit the sheet, if it is protected.
*
*
* // Add the "user@example.com" user to the list of users who can edit this sheet
* var sheet = SpreadsheetApp.getActiveSheet();
* var permissions = sheet.getSheetProtection();
* permissions.addUser('user@example.com');
* permissions.setProtected(true);
* sheet.setSheetProtection(permissions);
* If sheet protection is disabled, the value returned by this call is meaningless. * * @returns an array of email addresses of users who can edit this sheet */ getUsers(): string[] /** * Indicates whether the sheet has sheet protection enabled or not. * *
* // Determine whether or not sheet protection is enabled
* var sheet = SpreadsheetApp.getActiveSheet();
* var permissions = sheet.getSheetProtection();
* var isProtected = permissions.isProtected();
*
* // Remove the "user@example.com" user to the list of users who can edit this sheet
* var sheet = SpreadsheetApp.getActiveSheet();
* var permissions = sheet.getSheetProtection();
* permissions.removeUser('user@example.com');
* permissions.setProtected(true);
* sheet.setSheetProtection(permissions);
*
* // Enables sheet protection for this sheet
* var sheet = SpreadsheetApp.getActiveSheet();
* var permissions = sheet.getSheetProtection();
* permissions.setProtected(true);
* sheet.setSheetProtection(permissions);
* true to enable sheet protection, false to disable sheet
* protection.
*/
setProtected(
protection: Boolean
): void
}
class PivotFilter {
private constructor();
/**
* Returns the filter criteria for this pivot filter.
*
* @returns the filter criteria for this pivot filter
*/
getFilterCriteria(): SpreadsheetApp.FilterCriteria
/**
* Returns the PivotTable that this filter belongs to.
*
* @returns the pivot table this filter belongs to
*/
getPivotTable(): SpreadsheetApp.PivotTable
/**
* Returns the number of the source data column this filter operates on. These indices are
* 1-based, for example if this filter applies to data in column A of the spreadsheet this method
* returns "1."
*
* @returns the number of the source data column this filter applies to
*/
getSourceDataColumn(): number
/**
* Returns the data source column the filter operates on. Returns null if the pivot table
* is not a {DataSourcePivotTableApi}.
*
* @returns The data source column the filter operates on.
*/
getSourceDataSourceColumn(): SpreadsheetApp.DataSourceColumn
/**
* Removes this pivot filter from the pivot table.
*/
remove(): void
/**
* Sets the filter criteria for this pivot filter.
*
* @param filterCriteria - The filter criteria to set.
*
* @returns the pivot filter for chaining
*/
setFilterCriteria(
filterCriteria: SpreadsheetApp.FilterCriteria
): SpreadsheetApp.PivotFilter
}
class PivotGroup {
private constructor();
/**
* Adds a manual grouping rule for this pivot group.
*
* @param groupName - The name of this grouping rule.
* @param groupMembers - The values that are included in this grouping rule.
*
* @returns the pivot group for chaining.
*/
addManualGroupingRule(
groupName: string,
groupMembers: object[]
): SpreadsheetApp.PivotGroup
/**
* Returns whether labels are displayed as repeated.
*
* @returns true if labels are repeated; otherwise returns false.
*/
areLabelsRepeated(): Boolean
/**
* Removes any grouping rules from this pivot group.
*
* @returns the pivot group for chaining.
*/
clearGroupingRule(): SpreadsheetApp.PivotGroup
/**
* Removes any sorting applied to this group.
*
* @returns the pivot group for chaining.
*/
clearSort(): SpreadsheetApp.PivotGroup
/**
* Returns the date-time grouping rule on the pivot group, or null if no date-time
* grouping rule is set.
*
* @returns The date-time grouping rule.
*/
getDateTimeGroupingRule(): SpreadsheetApp.DateTimeGroupingRule
/**
* Returns whether this is a row or column group.
*
* @returns the dimension representing this group's type
*/
getDimension(): SpreadsheetApp.Dimension
/**
* Returns the pivot group limit on the pivot group. Returns null if no pivot group limit
* is set.
*
* @returns The pivot group limit.
*/
getGroupLimit(): SpreadsheetApp.PivotGroupLimit
/**
* Returns the index of this pivot group in the current group order.
*
* @returns the pivot group's index
*/
getIndex(): number
/**
* Returns the PivotTable which this grouping belongs to.
*
* @returns the pivot table this group belongs to.
*/
getPivotTable(): SpreadsheetApp.PivotTable
/**
* Returns the number of the source data column this group summarizes. This index is 1-based, if
* this group summarizes source data in column "A" of the spreadsheet this method returns 1.
*
* @returns the source data column number
*/
getSourceDataColumn(): number
/**
* Returns the data source column the pivot group operates on. Returns null if the pivot
* table is not a {DataSourcePivotTableApi}.
*
* @returns The data source column the pivot group operates on.
*/
getSourceDataSourceColumn(): SpreadsheetApp.DataSourceColumn
/**
* Hides repeated labels for this grouping. If labels are already hidden this results in a no-op.
* If this method is called before there are multiple row or column groupings, when an additional
* grouping is added repeated labels are hidden.
*
* @returns the pivot group for chaining.
*/
hideRepeatedLabels(): SpreadsheetApp.PivotGroup
/**
* Returns true if the sort is ascending, returns false if the sort order is
* descending.
*
* @returns true if the sort order is ascending.
*/
isSortAscending(): Boolean
/**
* Moves this group to the specified position in the current list of row or column groups. These
* indices are 0-based. For example, if this group should be moved to the first position this
* method should be called with 0.
*
* @param index - The index to move this grouping to.
*
* @returns the pivot group for chaining.
*/
moveToIndex(
index: number
): SpreadsheetApp.PivotGroup
/**
* Removes this pivot group from the table.
*/
remove(): void
/**
* Removes the manual grouping rule with the specified groupName.
*
* @param groupName - The name of the grouping rule to remove.
*
* @returns the pivot group for chaining.
*/
removeManualGroupingRule(
groupName: string
): SpreadsheetApp.PivotGroup
/**
* Resets the display name of this group in the pivot table to its default value.
*
* @returns the pivot group for chaining.
*/
resetDisplayName(): SpreadsheetApp.PivotGroup
/**
* Sets the date-time grouping rule on the pivot group.
*
* To remove the rule, use clearGroupingRule().
*
* @param dateTimeGroupingRuleType - The rule type to set.
*
* @returns The pivot group, for chaining.
*/
setDateTimeGroupingRule(
dateTimeGroupingRuleType: SpreadsheetApp.DateTimeGroupingRuleType
): SpreadsheetApp.PivotGroup
/**
* Sets the display name of this group in the pivot table.
*
* @param name - The display name to set.
*
* @returns the pivot group for chaining
*/
setDisplayName(
name: string
): SpreadsheetApp.PivotGroup
/**
* Sets the pivot group limit on the pivot group. The operation is only supported for DataSourcePivotTable.
*
* @param countLimit - The count limit of rows or columns to set. Must be positive.
*
* @returns The pivot group for chaining.
*/
setGroupLimit(
countLimit: number
): SpreadsheetApp.PivotGroup
/**
* Sets a histogram grouping rule for this pivot group. A histogram rule organizes values in a
* source data column into buckets of a constant size. All values from minValue to maxValue are placed into groups of size interval. All values below minValue
* are placed into one bucket, as are all values greater than maxValue.
*
* @param minValue - The minimum value for items to be placed into buckets. Values less than this
* are combined into a single bucket.
* @param maxValue - The maximum value for items to be placed into buckets. Values greater than this
* are combined into a single bucket.
* @param intervalSize
*
* @returns the pivot group for chaining.
*/
setHistogramGroupingRule(
minValue: number,
maxValue: number,
intervalSize: number
): SpreadsheetApp.PivotGroup
/**
* When there is more than one row or column grouping, this method displays this grouping's label
* for each entry of the subsequent grouping. If labels are already repeated this results in a
* no-op. If this method is called before there are multiple row or column groupings, when an
* additional grouping is added repeated labels are shown.
*
* @returns the pivot group for chaining.
*/
showRepeatedLabels(): SpreadsheetApp.PivotGroup
/**
* Sets whether to show total values for this pivot group in the table.
*
* @param showTotals - Whether to show totals or not.
*
* @returns the pivot group for chaining.
*/
showTotals(
showTotals: Boolean
): SpreadsheetApp.PivotGroup
/**
* Sets the sort order to be ascending.
*
* @returns the pivot group for chaining.
*/
sortAscending(): SpreadsheetApp.PivotGroup
/**
* Sorts this group by the specified PivotValue for the values from the oppositeGroupValues.
*
*
* // Sorts the item group by the "SUM of Quantity" pivot value for the specified salespersons.
* var sheet = SpreadsheetApp.getActiveSheet();
* var pivotTable = sheet.getPivotTables()[0];
* var itemGroup = pivotTable.getRowGroups()[0];
* var sumQuantityValue = pivotTable.getPivotValues()[0];
* itemGroup.sortBy(sumQuantityValue, ['Beth', 'Amir', 'Devyn']);
* true if total values are displayed for this pivot group; otherwise returns
* false.
*/
totalsAreShown(): Boolean
}
class PivotGroupLimit {
private constructor();
/**
* Gets the count limit on rows or columns in the pivot group.
*
* @returns The count limit on rows or columns.
*/
getCountLimit(): number
/**
* Returns the pivot group the limit belongs to.
*
* @returns The pivot group.
*/
getPivotGroup(): SpreadsheetApp.PivotGroup
/**
* Removes the pivot group limit.
*/
remove(): void
/**
* Sets the count limit on rows or columns in the pivot group.
*
* @param countLimit - The count limit on rows or columns to set. Must be positive.
*
* @returns The pivot group limit, for chaining.
*/
setCountLimit(
countLimit: number
): SpreadsheetApp.PivotGroupLimit
}
class PivotTable {
private constructor();
/**
* Creates a new pivot value in the pivot table calculated from the specified formula with
* the specified name.
*
* @param name - The name for this calculated pivot value.
* @param formula - The formula used to calculate this value.
*
* @returns the newly created PivotValue
*/
addCalculatedPivotValue(
name: string,
formula: string
): SpreadsheetApp.PivotValue
/**
* Defines a new pivot column grouping in the pivot table. The specified sourceDataColumn
* indicates the column in the source data this grouping is based on.
*
* @param sourceDataColumn - The number of the column this group summarizes. This index represents
* the absolute number of the column in the spreadsheet; 1 representing column "A,"
* 2 representing column B, etc.
*
* @returns the newly created PivotGroup
*/
addColumnGroup(
sourceDataColumn: number
): SpreadsheetApp.PivotGroup
/**
* Creates a new pivot filter for the pivot table. The specified sourceDataColumn
* indicates the column in the source data this filter operates on.
*
* @param sourceDataColumn - The number of the column this group summarizes. This index represents
* the absolute number of the column in the spreadsheet; 1 representing column "A,"
* 2 representing column B, etc.
* @param filterCriteria - The filter criteria used to perform the filtering.
*
* @returns the newly created PivotFilter
*/
addFilter(
sourceDataColumn: number,
filterCriteria: SpreadsheetApp.FilterCriteria
): SpreadsheetApp.PivotFilter
/**
* Defines a new pivot value in the pivot table with the specified summarizeFunction. The
* specified sourceDataColumn indicates the column in the source data this value is based
* on.
*
* @param sourceDataColumn - The number of the column this group summarizes. This index represents
* the absolute number of the column in the spreadsheet; 1 representing column "A,"
* 2 representing column B, etc.
* @param summarizeFunction
*
* @returns the newly created PivotValue
*/
addPivotValue(
sourceDataColumn: number,
summarizeFunction: SpreadsheetApp.PivotTableSummarizeFunction
): SpreadsheetApp.PivotValue
/**
* Defines a new pivot row grouping in the pivot table. The specified sourceDataColumn
* indicates the column in the source data this grouping is based on.
*
* @param sourceDataColumn - The number of the column this group summarizes. This index represents
* the absolute number of the column in the spreadsheet; 1 representing column "A,"
* 2 representing column B, etc.
*
* @returns the newly created PivotGroup
*/
addRowGroup(
sourceDataColumn: number
): SpreadsheetApp.PivotGroup
/**
* Returns the pivot table as a data source pivot table if the pivot table is linked to a DataSource, or null otherwise.
*
* @returns A data source pivot table.
*/
asDataSourcePivotTable(): SpreadsheetApp.DataSourcePivotTable
/**
* Returns the Range representing the cell where this pivot table is anchored.
*
* @returns this pivot table's anchor cell
*/
getAnchorCell(): SpreadsheetApp.Range
/**
* Returns an ordered list of the column groups in this pivot table.
*
* @returns the column groups in this pivot table
*/
getColumnGroups(): SpreadsheetApp.PivotGroup[]
/**
* Returns an ordered list of the filters in this pivot table.
*
* @returns the filters in this pivot table
*/
getFilters(): SpreadsheetApp.PivotFilter[]
/**
* Returns an ordered list of the pivot values in this pivot table.
*
* @returns the pivot values in this pivot table
*/
getPivotValues(): SpreadsheetApp.PivotValue[]
/**
* Returns an ordered list of the row groups in this pivot table.
*
* @returns the row groups in this pivot table
*/
getRowGroups(): SpreadsheetApp.PivotGroup[]
/**
* Returns the source data range on which the pivot table is constructed.
*
* @returns The source data range of this pivot table.
*/
getSourceDataRange(): SpreadsheetApp.Range
/**
* Returns whether values are displayed as rows or columns.
*
* @returns whether values are displayed as rows or columns
*/
getValuesDisplayOrientation(): SpreadsheetApp.Dimension
/**
* Deletes this pivot table. Further operations on this pivot table results in an error.
*/
remove(): void
/**
* Sets the layout of this pivot table to display values as columns or rows.
*
* @param dimension - The dimension indicating how to display pivot values.
*
* @returns the pivot table for chaining
*/
setValuesDisplayOrientation(
dimension: SpreadsheetApp.Dimension
): SpreadsheetApp.PivotTable
}
enum PivotTableSummarizeFunction {
/**
* The AVERAGE function
*/
AVERAGE = "AVERAGE",
/**
* The COUNT function
*/
COUNT = "COUNT",
/**
* The COUNTA function
*/
COUNTA = "COUNTA",
/**
* The COUNTUNIQUE function
*/
COUNTUNIQUE = "COUNTUNIQUE",
/**
* A custom fuction, this value is only valid for calcuated fields.
*/
CUSTOM = "CUSTOM",
/**
* The MAX function
*/
MAX = "MAX",
/**
* The MEDIAN function
*/
MEDIAN = "MEDIAN",
/**
* The MIN function
*/
MIN = "MIN",
/**
* The PRODUCT function
*/
PRODUCT = "PRODUCT",
/**
* The STDEV function
*/
STDEV = "STDEV",
/**
* The STDEVP function
*/
STDEVP = "STDEVP",
/**
* The SUM function
*/
SUM = "SUM",
/**
* The VAR function
*/
VAR = "VAR",
/**
* The VARP function
*/
VARP = "VARP",
}
class PivotValue {
private constructor();
/**
* Returns the display type describing how this pivot value is currently displayed in the table.
*
* @returns the display type for this pivot value
*/
getDisplayType(): SpreadsheetApp.PivotValueDisplayType
/**
* Returns the formula used to calculate this value. If this value is not a calculated field this
* method returns null.
*
* @returns the pivot value for chaining
*/
getFormula(): string
/**
* Returns the PivotTable which this value belongs to.
*
* @returns the pivot table this value belongs to
*/
getPivotTable(): SpreadsheetApp.PivotTable
/**
* Returns the number of the source data column the pivot value summarizes. This index is 1-based,
* if this group summarizes source data in column "A" of the spreadsheet this method returns
* 1.
*
* @returns The source data column number.
*/
getSourceDataColumn(): number
/**
* Returns the data source column the pivot value summarizes. Returns null if the pivot
* table is not a {DataSourcePivotTableApi}.
*
* @returns The source data source column the pivot value summarizes.
*/
getSourceDataSourceColumn(): SpreadsheetApp.DataSourceColumn
/**
* Returns this group’s summarization function.
*
* @returns the group's summarization function
*/
getSummarizedBy(): SpreadsheetApp.PivotTableSummarizeFunction
/**
* Remove this value from the pivot table.
*/
remove(): void
/**
* Sets the display name for this value in the pivot table.
*
* @param name - The display name to set.
*
* @returns the pivot value for chaining
*/
setDisplayName(
name: string
): SpreadsheetApp.PivotValue
/**
* Sets the formula used to calculate this value. If this value is not a calculated field this
* method results in an error.
*
* @param formula - The formula to use to calculate this value.
*
* @returns the pivot value for chaining
*/
setFormula(
formula: string
): SpreadsheetApp.PivotValue
/**
* Displays this value in the pivot table as a function of another value.
*
* @param displayType - The way to display the values.
*
* @returns the pivot value for chaining
*/
showAs(
displayType: SpreadsheetApp.PivotValueDisplayType
): SpreadsheetApp.PivotValue
/**
* Sets the summarization function.
*
* @param summarizeFunction - The function to use to summarize data in this value's source data
* column.
*
* @returns the pivot value for chaining
*/
summarizeBy(
summarizeFunction: SpreadsheetApp.PivotTableSummarizeFunction
): SpreadsheetApp.PivotValue
}
enum PivotValueDisplayType {
/**
* Default. Displays pivot values as the actual value and not as a function of another value.
*/
DEFAULT = "DEFAULT",
/**
* Displays pivot values as a percent of the total for that column.
*/
PERCENT_OF_COLUMN_TOTAL = "PERCENT_OF_COLUMN_TOTAL",
/**
* Displays pivot values as a percent of the grand total.
*/
PERCENT_OF_GRAND_TOTAL = "PERCENT_OF_GRAND_TOTAL",
/**
* Displays pivot values as a percent of the total for that row.
*/
PERCENT_OF_ROW_TOTAL = "PERCENT_OF_ROW_TOTAL",
}
class Protection {
private constructor();
/**
* Adds the given user to the list of editors for the protected sheet or range. This method does
* not automatically give the user permission to edit the spreadsheet itself; to do that in
* addition, call Spreadsheet.addEditor(emailAddress).
*
* @param emailAddress - The email address of the user to add.
*
* @returns the object representing the protection settings, for chaining
*/
addEditor(
emailAddress: string
): SpreadsheetApp.Protection
/**
* Adds the given user to the list of editors for the protected sheet or range. This method does
* not automatically give the user permission to edit the spreadsheet itself; to do that in
* addition, call Spreadsheet.addEditor(user).
*
* @param user - A representation of the user to add.
*
* @returns the object representing the protection settings, for chaining
*/
addEditor(
user: User
): SpreadsheetApp.Protection
/**
* Adds the given array of users to the list of editors for the protected sheet or range. This
* method does not automatically give the users permission to edit the spreadsheet itself; to do
* that in addition, call Spreadsheet.addEditors(emailAddresses).
*
* @param emailAddresses - An array of email addresses of the users to add.
*
* @returns the object representing the protection settings, for chaining
*/
addEditors(
emailAddresses: string[]
): SpreadsheetApp.Protection
/**
* Determines whether all users in the domain that owns the spreadsheet have permission to edit
* the protected range or sheet. Throws an exception if the user does not have permission to edit
* the protected range or sheet.
*
* @returns true if all users in the domain that owns the spreadsheet have permission to
* edit the protected range or sheet; false if not
*/
canDomainEdit(): Boolean
/**
* Determines whether the user has permission to edit the protected range or sheet. The
* spreadsheet owner is always able to edit protected ranges and sheets.
*
*
* // Remove all range protections in the spreadsheet that the user has permission to edit.
* var ss = SpreadsheetApp.getActive();
* var protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
* for (var i = 0; i < protections.length; i++) {
* var protection = protections[i];
* if (protection.canEdit()) {
* protection.remove();
* }
* }
* true if the user has permission to edit the protected range or sheet; false if not
*/
canEdit(): Boolean
/**
* Gets the description of the protected range or sheet. If no description is set, this method
* returns an empty string.
*
* @returns the description of the protected range or sheet, or an empty string if no description
* is set
*/
getDescription(): string
/**
* Gets the list of editors for the protected range or sheet. Throws an exception if the user does
* not have permission to edit the protected range or sheet.
*
*
* // Protect the active sheet, then remove all other users from the list of editors.
* var sheet = SpreadsheetApp.getActiveSheet();
* var protection = sheet.protect().setDescription('Sample protected sheet');
*
* // Ensure the current user is an editor before removing others. Otherwise, if the user's edit
* // permission comes from a group, the script throws an exception upon removing the group.
* var me = Session.getEffectiveUser();
* protection.addEditor(me);
* protection.removeEditors(protection.getEditors());
* if (protection.canDomainEdit()) {
* protection.setDomainEdit(false);
* }
* RANGE or SHEET.
*
* @returns the type of protected area, either RANGE or SHEET
*/
getProtectionType(): SpreadsheetApp.ProtectionType
/**
* Gets the range that is being protected. If the protection applies to the sheet instead of a
* range, this method returns a range that spans the entire sheet.
*
* @returns the range that is being protected
*/
getRange(): SpreadsheetApp.Range
/**
* Gets the name of the protected range if it is associated with a named range. Returns null if the protection is not associated with a named range. Note that scripts must explicitly
* call setRangeName(rangeName) to associate a protected range with a named range; calling
* Range.protect() to create a protection from a Range that happens to be a
* named range, without calling setRangeName(rangeName), is not sufficient to associate
* them. However, creating a protected range from a named range in the Google Sheets UI associates
* them automatically.
*
*
* // Protect a named range in a spreadsheet and log the name of the protected range.
* var ss = SpreadsheetApp.getActive();
* var range = ss.getRange('A1:B10');
* var protection = range.protect();
* ss.setNamedRange('Test', range); // Create a named range.
* protection.setRangeName('Test'); // Associate the protection with the named range.
* Logger.log(protection.getRangeName()); // Verify the name of the protected range.
* null if the protected range is not
* associated with a named range
*/
getRangeName(): string
/**
* Gets an array of unprotected ranges within a protected sheet. If the Protection object
* corresponds to a protected range instead of a protected sheet, this method returns an empty
* array. To change the unprotected ranges, use setUnprotectedRanges(ranges) to set a
* new array of ranges; to re-protect the entire sheet, set an empty array.
*
*
* // Unprotect cells E2:F5 in addition to any other unprotected ranges in the protected sheet.
* var sheet = SpreadsheetApp.getActiveSheet();
* var protection = sheet.protect();
* var unprotected = protection.getUnprotectedRanges();
* unprotected.push(sheet.getRange('E2:F5'));
* protection.setUnprotectedRanges(unprotected);
* setWarningOnly(warningOnly).
*
* @returns true if the protected range or sheet is only using warning-based protection
*/
isWarningOnly(): Boolean
/**
* Unprotects the range or sheet.
*
*
* // Remove all range protections in the spreadsheet that the user has permission to edit.
* var ss = SpreadsheetApp.getActive();
* var protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
* for (var i = 0; i < protections.length; i++) {
* var protection = protections[i];
* if (protection.canEdit()) {
* protection.remove();
* }
* }
*
* // Remove sheet protection from the active sheet, if the user has permission to edit it.
* var sheet = SpreadsheetApp.getActiveSheet();
* var protection = sheet.getProtections(SpreadsheetApp.ProtectionType.SHEET)[0];
* if (protection && protection.canEdit()) {
* protection.remove();
* }
*
* // Protect the active sheet, then remove all other users from the list of editors.
* var sheet = SpreadsheetApp.getActiveSheet();
* var protection = sheet.protect().setDescription('Sample protected sheet');
*
* // Ensure the current user is an editor before removing others. Otherwise, if the user's edit
* // permission comes from a group, the script throws an exception upon removing the group.
* var me = Session.getEffectiveUser();
* protection.addEditor(me);
* protection.removeEditors(protection.getEditors());
* if (protection.canDomainEdit()) {
* protection.setDomainEdit(false);
* }
* true if all users in the domain that owns the spreadsheet should have
* permission to edit the protected range or sheet; false if not.
*
* @returns the object representing the protection settings, for chaining
*/
setDomainEdit(
editable: Boolean
): SpreadsheetApp.Protection
/**
* Associates the protected range with an existing named range. If the named range covers a
* different area from the current protected range, this method moves the protection to cover the
* the named range instead. The named range must be on the same sheet as the current protected
* range. Note that scripts must explicitly call this method to associate a protected range with a
* named range; calling Range.protect() to create a protection from a Range
* that happens to be a named range, without calling setRangeName(rangeName), is not
* sufficient to associate them. However, creating a protected range from a named range in the
* Google Sheets UI associates them automatically.
*
* @param namedRange - The existing named range to associate with the protected range.
*
* @returns the object representing the protection settings, for chaining
*/
setNamedRange(
namedRange: SpreadsheetApp.NamedRange
): SpreadsheetApp.Protection
/**
* Adjusts the range that is being protected. If the given range covers a different area from the
* current protected range, this method moves the protection to cover the new range instead.
*
* @param range - The new range to protect from edits.
*
* @returns the object representing the protection settings, for chaining
*/
setRange(
range: SpreadsheetApp.Range
): SpreadsheetApp.Protection
/**
* Associates the protected range with an existing named range. If the named range covers a
* different area from the current protected range, this method moves the protection to cover the
* the named range instead. The named range must be on the same sheet as the current protected
* range. Note that scripts must explicitly call this method to associate a protected range with a
* named range; calling Range.protect() to create a protection from a Range
* that happens to be a named range, without calling setRangeName(rangeName), is not
* sufficient to associate them. However, creating a protected range from a named range in the
* Google Sheets UI associates them automatically.
*
*
* // Protect a named range in a spreadsheet and log the name of the protected range.
* var ss = SpreadsheetApp.getActive();
* var range = ss.getRange('A1:B10');
* var protection = range.protect();
* ss.setNamedRange('Test', range); // Create a named range.
* protection.setRangeName('Test'); // Associate the protection with the named range.
* Logger.log(protection.getRangeName()); // Verify the name of the protected range.
* Protection object corresponds to a protected range instead of a protected sheet or if
* any of the ranges are not on the protected sheet. To change the unprotected ranges, set a new
* array of ranges; to re-protect the entire sheet, set an empty array.
*
*
* // Protect the active sheet except B2:C5, then remove all other users from the list of editors.
* var sheet = SpreadsheetApp.getActiveSheet();
* var protection = sheet.protect().setDescription('Sample protected sheet');
* var unprotected = sheet.getRange('B2:C5');
* protection.setUnprotectedRanges([unprotected]);
*
* // Ensure the current user is an editor before removing others. Otherwise, if the user's edit
* // permission comes from a group, the script throws an exception upon removing the group.
* var me = Session.getEffectiveUser();
* protection.addEditor(me);
* protection.removeEditors(protection.getEditors());
* if (protection.canDomainEdit()) {
* protection.setDomainEdit(false);
* }
* isWarningOnly().
*
* @param warningOnly
*
* @returns the object representing the protection settings, for chaining.
*/
setWarningOnly(
warningOnly: Boolean
): SpreadsheetApp.Protection
}
enum ProtectionType {
/**
* Protection for a range.
*/
RANGE = "RANGE",
/**
* Protection for a sheet.
*/
SHEET = "SHEET",
}
class Range {
private constructor();
/**
* Sets the specified range as the active range, with the top
* left cell in the range as the current cell.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getRange('A1:D10');
* range.activate();
*
* var selection = sheet.getSelection();
* // Current cell: A1
* var currentCell = selection.getCurrentCell();
* // Active Range: A1:D10
* var activeRange = selection.getActiveRange();
* current cell.
*
* If the specified cell is present in an existing range, then that range becomes the active * range with the cell as the current cell. * *
If the specified cell is not present in any existing range, then the existing selection is * removed and the cell becomes the current cell and the active range. * *
Note: The specified Range must consist of one cell, otherwise it throws an
* exception.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getRange('B5');
* range.activate();
*
* var selection = sheet.getSelection();
* // Current cell: B5
* var currentCell = selection.getCurrentCell();
* true, the banding theme header color is applied to the first
* column.
* @param showFooter - If true, the banding theme footer color is applied to the last
* column.
*
* @returns The new banding.
*/
applyColumnBanding(
bandingTheme: SpreadsheetApp.BandingTheme,
showHeader: Boolean,
showFooter: Boolean
): SpreadsheetApp.Banding
/**
* Applies a default row banding theme to the range. By default, the banding has header and no
* footer color.
*
* @returns The new banding.
*/
applyRowBanding(): SpreadsheetApp.Banding
/**
* Applies a specified row banding theme to the range. By default, the banding has header and no
* footer color.
*
* @param bandingTheme - A color theme to apply to the rows in the range.
*
* @returns The new banding.
*/
applyRowBanding(
bandingTheme: SpreadsheetApp.BandingTheme
): SpreadsheetApp.Banding
/**
* Applies a specified row banding theme to the range with specified header and footer settings.
*
* @param bandingTheme - A color theme to apply to the rows in the range.
* @param showHeader - If true, the banding theme header color is applied to the first row.
* @param showFooter - If true, the banding theme footer color is applied to the last row.
*
* @returns The new banding.
*/
applyRowBanding(
bandingTheme: SpreadsheetApp.BandingTheme,
showHeader: Boolean,
showFooter: Boolean
): SpreadsheetApp.Banding
/**
* Fills the destinationRange with data based on the data in this range. The new values
* are also determined by the specified series type. The destination range must contain
* this range and extend it in only one direction. For example, the following fills A1:A20
* with a series of increasing numbers based on the current values in A1:A4:
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
*
* // Has values [1, 2, 3, 4].
* var sourceRange = sheet.getRange("A1:A4");
* // The range to fill with values.
* var destination = sheet.getRange("A1:A20");
*
* // Inserts new values in A5:A20, continuing the pattern expressed in A1:A4
* sourceRange.autoFill(destination, SpreadsheetApp.AutoFillSeries.DEFAULT_SERIES);
*
* series type.
*
* The calculated destination range considers the surrounding data to determine where the new * values should be inserted: if there is data to the immediate left or right of a column that is * being auto-filled, new values only extend as far as this adjacent data. * *
For example, if A1:A20 is filled with a series of increasing numbers and this method
* is called on the range B1:B4 which contains a series of dates, new values are only
* inserted into B5:B20. In this way, these new values "stick" to the cells that contain
* values in column A.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
*
* // A1:A20 has values [1, 2, 3, ... 20].
* // B1:B4 has values [1/1/2017, 1/2/2017, ...]
* var sourceRange = sheet.getRange("B1:B4");
*
* // Results in B5:B20 having values [1/5/2017, ... 1/20/2017]
* sourceRange.autoFillToNeighbor(SpreadsheetApp.AutoFillSeries.DEFAULT_SERIES);
* Calling this function on a range is equivalent to selecting a range and clicking Format ->
* Merge -> Unmerge.
*
* @returns This range, for chaining.
*/
breakApart(): SpreadsheetApp.Range
/**
* Determines whether the user has permission to edit every cell in the range. The spreadsheet
* owner is always able to edit protected ranges and sheets.
*
* @returns true if the user has permission to edit every cell in the range; false
* otherwise.
*/
canEdit(): Boolean
/**
* Changes the state of the checkboxes in the range to “checked”. Ignores the cells in the range
* which currently do not contain either the checked or unchecked value configured.
*
*
* // Changes the state of cells which currently contain either the checked or unchecked value
* // configured in the range A1:B10 to 'checked'.
* var range = SpreadsheetApp.getActive().getRange('A1:B10');
* range.check();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:D10");
* range.clear();
*
* // The code below clears range C2:G8 in the active sheet, but preserves the format,
* // data validation rules, and comments.
* SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 5).clear({contentsOnly: true});
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:D10");
* range.clearContent();
*
* // Clear the data validation rules for cells A1:B5.
* var range = SpreadsheetApp.getActive().getRange('A1:B5');
* range.clearDataValidations();
* This clears text formatting for the cell or cells in the range, but does not reset any * number formatting rules. * *
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:D10");
* range.clearFormat();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:D10");
* range.clearNote();
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getActiveRange();
*
* // All row and column groups within the range are collapsed.
* range.expandGroups();
* For a detailed description of the gridId parameter, see getGridId().
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var source = ss.getSheets()[0];
*
* var range = source.getRange("B2:D4");
*
* // This copies the formatting in B2:D4 in the source sheet to
* // D4:F6 in the sheet with gridId 1555299895. Note that you can get the gridId
* // of a sheet by calling sheet.getSheetId() or range.getGridId().
* range.copyFormatToRange(1555299895, 4, 6, 4, 6);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var source = ss.getSheets()[0];
* var destination = ss.getSheets()[1];
*
* var range = source.getRange("B2:D4");
*
* // This copies the formatting in B2:D4 in the source sheet to
* // D4:F6 in the second sheet
* range.copyFormatToRange(destination, 4, 6, 4, 6);
*
* // The code below copies the first 5 columns over to the 6th column.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeToCopy = sheet.getRange(1, 1, sheet.getMaxRows(), 5);
* rangeToCopy.copyTo(sheet.getRange(1, 6));
*
* // The code below copies only the values of the first 5 columns over to the 6th column.
* var sheet = SpreadsheetApp.getActiveSheet();
* sheet.getRange("A:E").copyTo(sheet.getRange("F1"), {contentsOnly:true});
*
* // The code below copies only the values of the first 5 columns over to the 6th column.
* var sheet = SpreadsheetApp.getActiveSheet();
* sheet.getRange("A:E").copyTo(sheet.getRange("F1"), SpreadsheetApp.CopyPasteType.PASTE_VALUES);
* For a detailed description of the gridId parameter, see getGridId().
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var source = ss.getSheets()[0];
*
* var range = source.getRange("B2:D4");
*
* // This copies the data in B2:D4 in the source sheet to
* // D4:F6 in the sheet with gridId 0
* range.copyValuesToRange(0, 4, 6, 4, 6);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var source = ss.getSheets()[0];
* var destination = ss.getSheets()[1];
*
* var range = source.getRange("B2:D4");
*
* // This copies the data in B2:D4 in the source sheet to
* // D4:F6 in the second sheet
* range.copyValuesToRange(destination, 4, 6, 4, 6);
* This example shows how to create and configure a new data source pivot table. * *
* var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
* var anchorCell = spreadsheet.getSheets()[0].getRange('A1');
* var dataSource = spreadsheet.getDataSources()[0];
*
* var pivotTable = anchorCell.createDataSourcePivotTable(dataSource);
* pivotTable.addRowGroup('dataColumnA');
* pivotTable.addColumnGroup('dataColumnB');
* pivotTable.addPivotValue('dataColumnC', SpreadsheetApp.PivotTableSummarizeFunction.SUM);
* pivotTable.addFilter('dataColumnA',
* SpreadsheetApp.newFilterCriteria().whenTextStartsWith('A').build());
* This example shows how to create and configure a new data source table. * *
* var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
* var anchorCell = spreadsheet.getSheets()[0].getRange('A1');
* var dataSource = spreadsheet.getDataSources()[0];
*
* var dataSourceTable = anchorCell.createDataSourceTable(dataSource);
* .addColumns('dataColumnA', 'dataColumnB', 'dataColumnC')
* .addSortSpec('dataColumnA', /* ascending= *\/ true)
* .addSortSpec('dataColumnB', /* ascending= *\/ false);
* sourceData anchored at the first cell
* in this range.
*
* @param sourceData - The data to create the pivot table from.
*
* @returns The newly created PivotTable.
*/
createPivotTable(
sourceData: SpreadsheetApp.Range
): SpreadsheetApp.PivotTable
/**
* Creates a text finder for the range, which can find and replace text in this range.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getActiveRange();
*
* // Creates a text finder for the range.
* var textFinder = range.createTextFinder('dog');
*
* // Returns the first occurrence of 'dog'.
* var firstOccurrence = textFinder.findNext();
*
* // Replaces the last found occurrence of 'dog' with 'cat' and returns the number
* // of occurrences replaced.
* var numOccurrencesReplaced = findOccurrence.replaceWith('cat');
* TextFinder for the range
*/
createTextFinder(
findText: string
): SpreadsheetApp.TextFinder
/**
* Deletes this range of cells. Existing data in the sheet along the provided dimension is shifted
* towards the deleted range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:D10");
* range.deleteCells(SpreadsheetApp.Dimension.COLUMNS);
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getActiveRange();
*
* // All row and column groups within the range are expanded.
* range.expandGroups();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange(1, 1, 2, 5);
*
* // Logs "A1:E2"
* Logger.log(range.getA1Notation());
* '#ffffff').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B5");
* Logger.log(cell.getBackground());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B5");
* Logger.log(cell.getBackgroundObject().asRgbColor().asHexString());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B5:C6");
* var bgColors = range.getBackgroundObjects();
* for (var i in bgColors) {
* for (var j in bgColors[i]) {
* Logger.log(bgColors[i][j].asRgbColor().asHexString());
* }
* }
* '#ffffff').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B5:C6");
* var bgColors = range.getBackgrounds();
* for (var i in bgColors) {
* for (var j in bgColors[i]) {
* Logger.log(bgColors[i][j]);
* }
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B2:D4");
*
* // The row and column here are relative to the range
* // getCell(1,1) in this code returns the cell at B2, B2
* var cell = range.getCell(1, 1);
* Logger.log(cell.getValue());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B2:D4");
* // Logs "2.0"
* Logger.log(range.getColumn());
* Directions to cover all
* adjacent cells with data in them. If the range is surrounded by empty cells not including those
* along the diagonals, the range itself is returned. This is similar to selecting the range and
* typing Ctrl+A in the editor.
*
*
* // Assume the active spreadsheet is blank.
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* sheet.getRange("C2").setValue(100);
* sheet.getRange("B3").setValue(100);
* sheet.getRange("D3").setValue(100);
* sheet.getRange("C4").setValue(100);
* // Logs "B2:D4"
* Logger.log(sheet.getRange("C3").getDataRegion().getA1Notation());
* Direction.UP and Direction.DOWN if the
* specified dimension is Dimension.ROWS, or Direction.NEXT and Direction.PREVIOUS if the dimension is Dimension.COLUMNS. The expansion of the range
* is based on detecting data next to the range that is organized like a table. The expanded range
* covers all adjacent cells with data in them along the specified dimension including the table
* boundaries. If the original range is surrounded by empty cells along the specified dimension,
* the range itself is returned. This method is similar to selecting the range and typing
* Ctrl+Space for columns or Shift+Space for rows in the editor.
*
*
* // Assume the active spreadsheet is blank.
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* sheet.getRange("C2").setValue(100);
* sheet.getRange("B3").setValue(100);
* sheet.getRange("D3").setValue(100);
* sheet.getRange("C4").setValue(100);
* // Logs "C2:C4"
* Logger.log(sheet.getRange("C3").getDataRegion(SpreadsheetApp.Dimension.ROWS).getA1Notation());
* // Logs "B3:D3"
* Logger.log(
* sheet.getRange("C3").getDataRegion(SpreadsheetApp.Dimension.COLUMNS).getA1Notation());
* DataSourceFormula for the first cell in the range, or null if
* the cell doesn't contain a data source formula.
*
* @returns The DataSourceFormula for the cell.
*/
getDataSourceFormula(): SpreadsheetApp.DataSourceFormula
/**
* Returns the DataSourceFormulas for the cells in the range.
*
* @returns An array of DataSourceFormulas.
*/
getDataSourceFormulas(): SpreadsheetApp.DataSourceFormula[]
/**
* Gets all the data source pivot tables intersecting with the range.
*
* @returns A list of data source pivot tables.
*/
getDataSourcePivotTables(): SpreadsheetApp.DataSourcePivotTable[]
/**
* Gets all the data source tables intersecting with the range.
*
* @returns A list of data source tables.
*/
getDataSourceTables(): SpreadsheetApp.DataSourceTable[]
/**
* Returns a URL for the data in this range, which can be used to create charts and queries.
*
*
* function doGet() {
* var ss = SpreadsheetApp.openById('1khO6hBWTNNyvyyxvob7aoZTI9ZvlqqASNeq0e29Tw2c');
* var sheet = ss.getSheetByName('ContinentData');
* var range = sheet.getRange('A1:B8');
*
* var template = HtmlService.createTemplateFromFile('piechart');
* template.dataSourceUrl = range.getDataSourceUrl();
* return template.evaluate();
* }
*
* <!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>
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("A1:B7");
*
* // Calling this method with "true" sets the first line to be the title of the axes
* var datatable = range.getDataTable(true);
*
* // Note that this doesn't build an EmbeddedChart, so you can't just use
* // Sheet#insertChart(). To do that, use sheet.newChart().addRange() instead.
* var chart = Charts.newBarChart()
* .setDataTable(datatable)
* .setOption("title", "Your Title Here")
* .build();
* null.
*
*
* // Log information about the data validation rule for cell A1.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var rule = cell.getDataValidation();
* if (rule != null) {
* var criteria = rule.getCriteriaType();
* var args = rule.getCriteriaValues();
* Logger.log('The data validation rule is %s %s', criteria, args);
* } else {
* Logger.log('The cell does not have a data validation rule.')
* }
* null for that cell's position in the array.
*
*
* // Change existing data validation rules that require a date in 2013 to require a date in 2014.
* var oldDates = [new Date('1/1/2013'), new Date('12/31/2013')];
* var newDates = [new Date('1/1/2014'), new Date('12/31/2014')];
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange(1, 1, sheet.getMaxRows(), sheet.getMaxColumns());
* var rules = range.getDataValidations();
*
* for (var i = 0; i < rules.length; i++) {
* for (var j = 0; j < rules[i].length; j++) {
* var rule = rules[i][j];
*
* if (rule != null) {
* var criteria = rule.getCriteriaType();
* var args = rule.getCriteriaValues();
*
* if (criteria == SpreadsheetApp.DataValidationCriteria.DATE_BETWEEN
* && args[0].getTime() == oldDates[0].getTime()
* && args[1].getTime() == oldDates[1].getTime()) {
* // Create a builder from the existing rule, then change the dates.
* rules[i][j] = rule.copy().withCriteria(criteria, newDates).build();
* }
* }
* }
* }
* range.setDataValidations(rules);
* String.
* The displayed value takes into account date, time and currency formatting formatting, including
* formats applied automatically by the spreadsheet's locale setting. Empty cells return an empty
* string.
*
* @returns The displayed value in this cell.
*/
getDisplayValue(): string
/**
* Returns the rectangular grid of values for this range.
*
* Returns a two-dimensional array of displayed values, indexed by row, then by column. The
* values are String objects. The displayed value takes into account date, time and
* currency formatting, including formats applied automatically by the spreadsheet's locale
* setting. Empty cells are represented by an empty string in the array. Remember that while a
* range index starts at 1, 1, the JavaScript array is indexed from [0][0].
*
*
* // The code below gets the displayed values for the range C2:G8
* // in the active spreadsheet. Note that this is a JavaScript array.
* var values = SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getDisplayValues();
* Logger.log(values[0][0]);
* null if there is no filter on
* the sheet.
*
* @returns The filter.
*/
getFilter(): SpreadsheetApp.Filter
/**
* Returns the font color of the cell in the top-left corner of the range, in CSS notation (such
* as '#ffffff' or 'white').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.getFontColor());
* '#ffffff' or 'white').
*/
getFontColor(): string
/**
* Returns the font color of the cell in the top-left corner of the range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.getFontColorObject().asRgbColor().asHexString());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* var results = range.getFontColorObjects();
*
* for (var i in results) {
* for (var j in results[i]) {
* Logger.log(results[i][j].asRgbColor().asHexString());
* }
* }
* '#ffffff' or
* 'white').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* var results = range.getFontColors();
*
* for (var i in results) {
* for (var j in results[i]) {
* Logger.log(results[i][j]);
* }
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* var results = range.getFontFamilies();
*
* for (var i in results) {
* for (var j in results[i]) {
* Logger.log(results[i][j]);
* }
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.getFontFamily());
* 'underline',
* 'line-through', or 'none').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.getFontLine());
* 'underline', 'line-through', or
* 'none').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* var results = range.getFontLines();
*
* for (var i in results) {
* for (var j in results[i]) {
* Logger.log(results[i][j]);
* }
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.getFontSize());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* var results = range.getFontSizes();
*
* for (var i in results) {
* for (var j in results[i]) {
* Logger.log(results[i][j]);
* }
* }
* 'italic' or 'normal') of the cell in the top-left
* corner of the range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.getFontStyle());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* var results = range.getFontStyles();
*
* for (var i in results) {
* for (var j in results[i]) {
* Logger.log(results[i][j]);
* }
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.getFontWeight());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* var results = range.getFontWeights();
*
* for (var i in results) {
* for (var j in results[i]) {
* Logger.log(results[i][j]);
* }
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This assumes you have a function in B5 that sums up
* // B2:B4
* var range = sheet.getRange("B5");
*
* // Logs the calculated value and the formula
* Logger.log("Calculated value: %s Formula: %s",
* range.getValue(),
* range.getFormula());
* null if none.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B5");
* var formula = range.getFormulaR1C1();
* Logger.log(formula);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B5:C6");
* var formulas = range.getFormulas();
* for (var i in formulas) {
* for (var j in formulas[i]) {
* Logger.log(formulas[i][j]);
* }
* }
* null for cells with no formula.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B5:C6");
* var formulas = range.getFormulasR1C1();
* for (var i in formulas) {
* for (var j in formulas[i]) {
* Logger.log(formulas[i][j]);
* }
* }
*
* // Log the grid ID of the first sheet (by tab position) in the spreadsheet.
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.getGridId());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B2:D4");
* // logs 3.0
* Logger.log(range.getHeight());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.getHorizontalAlignment());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* var results = range.getHorizontalAlignments();
*
* for (var i in results) {
* for (var j in results[i]) {
* Logger.log(results[i][j]);
* }
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B2:D4");
* // Logs "4.0"
* Logger.log(range.getLastColumn());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B2:D4");
* // Logs "4.0"
* Logger.log(range.getLastRow());
* Range objects representing merged cells that either are fully
* within the current range, or contain at least one cell in the current range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B3");
*
* var mergedRanges = range.getMergedRanges();
* for (var i = 0; i < mergedRanges.length; i++) {
* Logger.log(mergedRanges[i].getA1Notation());
* Logger.log(mergedRanges[i].getDisplayValue());
* }
* Range objects, representing merged cells overlapping the range.
*/
getMergedRanges(): SpreadsheetApp.Range[]
/**
* Starting at the cell in the first column and row of the range, returns the next cell in the
* given direction that is the edge of a contiguous range of cells with data in them or the cell
* at the edge of the spreadsheet in that direction. This is equivalent to typing
* Ctrl+[arrow key] in the editor.
*
*
* // Assume the active spreadsheet is blank.
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("C3:E5");
* // Logs "C1"
* Logger.log(range.getNextDataCell(SpreadsheetApp.Direction.UP).getA1Notation());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.getNote());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* var results = range.getNotes();
*
* for (var i in results) {
* for (var j in results[i]) {
* Logger.log(results[i][j]);
* }
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B2:D5");
* Logger.log(range.getNumColumns());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B2:D5");
* Logger.log(range.getNumRows());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("C4");
* Logger.log(cell.getNumberFormat());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B5:C6");
* var formats = range.getNumberFormats();
* for (var i in formats) {
* for (var j in formats[i]) {
* Logger.log(formats[i][j]);
* }
* }
* null if the cell
* value is not text.
*
*
* // Get the Rich Text value of cell D4.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("D4:F6");
* var richText = range.getRichTextValue();
* Logger.log(richText);
* null if the cell
* value is not text.
*/
getRichTextValue(): SpreadsheetApp.RichTextValue
/**
* Returns the Rich Text values for the cells in the range.
*
*
* // Get the Rich Text values for all cells in range B5:C6
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("B5:C6");
* var values = range.getRichTextValues();
*
* for (var i = 0; i < values.length; i++) {
* for (var j = 0; j < values[i].length; j++) {
* Logger.log(values[i][j]);
* }
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B2");
* Logger.log(range.getRow());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B2");
* Logger.log(range.getRowIndex());
* null if the cell
* text direction is determined with automatic detection.
*
*
* // Get the text direction of cell B1.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("B1:D4");
* Logger.log(range.getTextDirection());
* null for cells using automatic detection.
*
*
* // Get the text directions for all cells in range B5:C6
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("B5:C6");
* var directions = range.getTextDirections();
*
* for (var i = 0; i < directions.length; i++) {
* for (var j = 0; j < directions[i].length; j++) {
* Logger.log(directions[i][j]);
* }
* }
*
* // Log the text rotation settings for a cell.
* var sheet = SpreadsheetApp.getActiveSheet();
*
* var cell = sheet.getRange("A1");
* Logger.log(cell.getTextRotation());
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("B2:D4");
*
* var results = range.getTextRotations();
*
* for (var i in results) {
* for (var j in results[i]) {
* var rotation = results[i][j];
* Logger.log("Cell [%s, %s] has text rotation: %v", i, j, rotation);
* }
* }
*
* // Get the text style of cell D4.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("D4:F6");
* var style = range.getTextStyle();
* Logger.log(style);
*
* // Get the text styles for all cells in range B5:C6
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("B5:C6");
* var styles = range.getTextStyles();
*
* for (var i = 0; i < styles.length; i++) {
* for (var j = 0; j < styles[i].length; j++) {
* Logger.log(styles[i][j]);
* }
* }
* Number,
* Boolean, Date, or String depending on the value of the cell. Empty
* cells return an empty string.
*
* @returns The value in this cell.
*/
getValue(): object
/**
* Returns the rectangular grid of values for this range.
*
* Returns a two-dimensional array of values, indexed by row, then by column. The values may be
* of type Number, Boolean, Date, or String, depending on the
* value of the cell. Empty cells are represented by an empty string in the array. Remember that
* while a range index starts at 1, 1, the JavaScript array is indexed from [0][0].
*
*
* // The code below gets the values for the range C2:G8
* // in the active spreadsheet. Note that this is a JavaScript array.
* var values = SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getValues();
* Logger.log(values[0][0]);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.getVerticalAlignment());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* var results = range.getVerticalAlignments();
*
* for (var i in results) {
* for (var j in results[i]) {
* Logger.log(results[i][j]);
* }
* }
* true if
* the text wraps, false if the text does not.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.getWrap());
*
* // Get the text wrapping strategies for all cells in range B5:C6
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("B5:C6");
* var strategies = range.getWrapStrategies();
*
* for (var i = 0; i < strategies.length; i++) {
* for (var j = 0; j < strategies[i].length; j++) {
* Logger.log(strategies[i][j]);
* }
* }
*
* // Get the text wrapping strategy of cell B1.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("B1:D4");
* Logger.log(range.getWrapStrategy());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* var results = range.getVerticalAlignments();
*
* for (var i in results) {
* for (var j in results[i]) {
* var isWrapped = results[i][j];
* if (isWrapped) {
* Logger.log("Cell [%s, %s] has wrapped text", i, j);
* }
* }
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:D10");
* range.insertCells(SpreadsheetApp.Dimension.COLUMNS);
* true for checked and
* false for unchecked. Sets the value of all cells in the range to false.
*
*
* var range = SpreadsheetApp.getActive().getRange('A1:B10');
*
* // Inserts checkboxes into each cell in the range A1:B10 configured with 'true' for checked
* // and 'false' for unchecked. Also, sets the value of each cell in the range A1:B10 to 'false'.
* range.insertCheckboxes();
*
* var range = SpreadsheetApp.getActive().getRange('A1:B10');
*
* // Inserts checkboxes into each cell in the range A1:B10 configured with 'yes' for checked
* // and the empty string for unchecked. Also, sets the value of each cell in the range A1:B10 to
* // the empty string.
* range.insertCheckboxes('yes');
*
* var range = SpreadsheetApp.getActive().getRange('A1:B10');
*
* // Inserts checkboxes into each cell in the range A1:B10 configured with 'yes' for checked
* // and 'no' for unchecked. Also, sets the value of each cell in the range A1:B10 to 'no'.
* range.insertCheckboxes('yes', 'no');
* true if the range is totally blank.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B2:D4");
*
* Logger.log(range.isBlank());
* true if the range is blank; false otherwise.
*/
isBlank(): Boolean
/**
* Returns whether all cells in the range have their checkbox state as 'checked'. Returns null if some cells are checked and the rest unchecked, or if some cells do not have checkbox
* data validation.
*
*
* var range = SpreadsheetApp.getActive().getRange('A1:A3');
*
* // Inserts checkboxes and sets each cell value to 'no' in the range A1:A3.
* range.insertCheckboxes('yes', 'no');
*
* var range1 = SpreadsheetApp.getActive().getRange('A1');
* range1.setValue('yes');
* // Sets the value of isRange1Checked as true as it contains the checked value.
* var isRange1Checked = range1.isChecked();
*
* var range2 = SpreadsheetApp.getActive().getRange('A2');
* range2.setValue('no');
* // Sets the value of isRange2Checked as false as it contains the unchecked value.
* var isRange2Checked = range2.isChecked();
*
* var range3 = SpreadsheetApp.getActive().getRange('A3');
* range3.setValue('random');
* // Sets the value of isRange3Checked as null, as it contains an invalid checkbox value.
* var isRange3Checked = range3.isChecked();
* true, if all cells in the range are checked, false if all cells in the
* range are unchecked, or null if any of the cells are unchecked or do not have
* checkbox data validation.
*/
isChecked(): Boolean
/**
* Determines whether the end of the range is bound to a particular column. For example, for the
* ranges A1:B10 or B:B, which are bound to columns at the end of the range, this
* method returns true; for the ranges 3:7 or A1:5, which are bound only
* to particular rows at the end of the range, this method returns false.
*
* @returns true if the end of the range is bound to a particular column; false
* otherwise.
*/
isEndColumnBounded(): Boolean
/**
* Determines whether the end of the range is bound to a particular row. For example, for the
* ranges A1:B10 or 3:7, which are bound to rows at the end of the range, this
* method returns true; for the ranges B:B or A1:C, which are bound only
* to particular columns at the end of the range, this method returns false.
*
* @returns true if the end of the range is bound to a particular row; false
* otherwise.
*/
isEndRowBounded(): Boolean
/**
* Returns true if the cells in the current range overlap any merged cells.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:B3");
*
* // True if any of the cells in A1:B3 is included in a merge.
* var isPartOfMerge = range.isPartOfMerge();
* true if the range overlaps any merged cells, otherwise returns false.
*/
isPartOfMerge(): Boolean
/**
* Determines whether the start of the range is bound to a particular column. For example, for the
* ranges A1:B10 or B:B, which are bound to columns at the start of the range,
* this method returns true; for the range 3:7, which is bound only to a row at
* the start of the range, this method returns false.
*
* @returns true if the start of the range is bound to a particular column; false
* otherwise.
*/
isStartColumnBounded(): Boolean
/**
* Determines whether the start of the range is bound to a particular row. For example, for the
* ranges A1:B10 or 3:7, which are bound to rows at the start of the range, this
* method returns true; for the range B:B, which is bound only to a particular
* column at the start of the range, this method returns false.
*
* @returns true if the start of the range is bound to a particular row; false
* otherwise.
*/
isStartRowBounded(): Boolean
/**
* Merges the cells in the range together into a single block.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
*
* // The code below 2-dimensionally merges the cells in A1 to B3
* sheet.getRange('A1:B3').merge();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The code below merges cells C5:E5 into one cell
* var range1 = sheet.getRange("C5:E5");
* range1.mergeAcross();
*
* // The code below creates 2 horizontal cells, F5:H5 and F6:H6
* var range2 = sheet.getRange("F5:H6");
* range2.mergeAcross();
*
* var sheet = SpreadsheetApp.getActiveSheet();
*
* // The code below vertically merges the cells in A1 to A10
* sheet.getRange('A1:A10').mergeVertically();
*
* // The code below creates 3 merged columns: B1 to B10, C1 to C10, and D1 to D10
* sheet.getRange('B1:D10').mergeVertically();
*
* // The code below moves the first 5 columns over to the 6th column
* var sheet = SpreadsheetApp.getActiveSheet()
* sheet.getRange("A1:E").moveTo(sheet.getRange("F1"));
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("A1");
*
* // newCell references B2
* var newCell = cell.offset(1, 1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("A1");
*
* // newCell references B2:B3
* var newRange = cell.offset(1, 1, 2);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("A1");
*
* // newCell references B2:C3
* var newRange = cell.offset(1, 1, 2, 2);
* Protection.removeEditor(emailAddress), Protection.removeEditor(user), Protection.removeEditors(emailAddresses), Protection.addEditor(emailAddress), Protection.addEditor(user), Protection.addEditors(emailAddresses), or setting a new
* value for Protection.setDomainEdit(editable)), the permissions mirror those of the
* spreadsheet itself, which effectively means that the range remains unprotected. If the range is
* already protected, this method creates a new protected range that overlaps the existing one. If
* a cell is protected by multiple protected ranges and any of them prevent a particular user from
* editing the cell, then that user is not permitted to edit the cell.
*
*
* // Protect range A1:B10, then remove all other users from the list of editors.
* var ss = SpreadsheetApp.getActive();
* var range = ss.getRange('A1:B10');
* var protection = range.protect().setDescription('Sample protected range');
*
* // Ensure the current user is an editor before removing others. Otherwise, if the user's edit
* // permission comes from a group, the script throws an exception upon removing the group.
* var me = Session.getEffectiveUser();
* protection.addEditor(me);
* protection.removeEditors(protection.getEditors());
* if (protection.canDomainEdit()) {
* protection.setDomainEdit(false);
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("A1:C7");
*
* // Randomizes the range
* range.randomize();
*
* var range = SpreadsheetApp.getActive().getRange('A1:B10');
*
* // Inserts checkboxes and sets each cell value to 'no' in the range A1:B10.
* range.insertCheckboxes('yes', 'no');
*
* var range1 = SpreadsheetApp.getActive().getRange('A1');
* range1.setValue('yes');
* // Removes the checkbox data validation in cell A1 and clears its value.
* range1.removeCheckboxes();
*
* var range2 = SpreadsheetApp.getActive().getRange('A2');
* range2.setValue('random');
* // Removes the checkbox data validation in cell A2 but does not clear its value.
* range2.removeCheckboxes();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B1:D7");
*
* // Remove duplicate rows in the range.
* range.removeDuplicates();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("B1:D7");
*
* // Remove rows which have duplicate values in column B.
* range.removeDuplicates([2]);
*
* // Remove rows which have duplicate values in both columns B and D.
* range.removeDuplicates([2,4]);
* '#ffffff'
* or 'white').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("B2:D5");
* range.setBackground("red");
* '#ffffff' or 'white'); a
* null value resets the color.
*
* @returns This range, for chaining.
*/
setBackground(
color: string
): SpreadsheetApp.Range
/**
* Sets the background color of all cells in the range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var bgColor = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.BACKGROUND)
* .build();
*
* var range = sheet.getRange("B2:D5");
* range.setBackgroundObject(bgColor);
* null value resets the background color.
*
* @returns This range, for chaining.
*/
setBackgroundObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.Range
/**
* Sets a rectangular grid of background colors (must match dimensions of this range).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var colorAccent1 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
* .build();
* var colorAccent2 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
* .build();
* var colorAccent3 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
* .build();
* var colorAccent4 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4)
* .build();
*
* var colors = [
* [colorAccent1, colorAccent2],
* [colorAccent3, colorAccent4]
* ];
*
* var cell = sheet.getRange("B5:C6");
* cell.setBackgroundObjects(colors);
* null values reset the color.
*
* @returns This range, for chaining.
*/
setBackgroundObjects(
color: SpreadsheetApp.Color[][]
): SpreadsheetApp.Range
/**
* Sets the background to the given color using RGB values (integers between 0 and 255 inclusive).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
*
* // Sets the background to white
* cell.setBackgroundRGB(255, 255, 255);
*
* // Sets the background to red
* cell.setBackgroundRGB(255, 0, 0);
* '#ffffff' or 'white').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var colors = [
* ["red", "white", "blue"],
* ["#FF0000", "#FFFFFF", "#0000FF"] // These are the hex equivalents
* ];
*
* var cell = sheet.getRange("B5:D6");
* cell.setBackgrounds(colors);
* '#ffffff' or
* 'white'); null values reset the color.
*
* @returns This range, for chaining.
*/
setBackgrounds(
color: string[][]
): SpreadsheetApp.Range
/**
* Sets the border property. Valid values are true (on), false (off) and null (no change).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* // Sets borders on the top and bottom, but leaves the left and right unchanged
* cell.setBorder(true, null, true, null, false, false);
* true for border, false for none, null for no change.
* @param left - true for border, false for none, null for no change.
* @param bottom - true for border, false for none, null for no change.
* @param right - true for border, false for none, null for no change.
* @param vertical - true for internal vertical borders, false for none, null for no change.
* @param horizontal - true for internal horizontal borders, false for none, null for no change.
*
* @returns This range, for chaining.
*/
setBorder(
top: Boolean,
left: Boolean,
bottom: Boolean,
right: Boolean,
vertical: Boolean,
horizontal: Boolean
): SpreadsheetApp.Range
/**
* Sets the border property with color and/or style. Valid values are true (on), false (off) and null (no change). For color, use Color in CSS notation (such as '#ffffff' or 'white').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* // Sets borders on the top and bottom, but leaves the left and right unchanged
* // Also sets the color to "red", and the border to "DASHED".
* cell.setBorder(true, null, true, null, false, false, "red", SpreadsheetApp.BorderStyle.DASHED);
* true for border, false for none, null for no change.
* @param left - true for border, false for none, null for no change.
* @param bottom - true for border, false for none, null for no change.
* @param right - true for border, false for none, null for no change.
* @param vertical - true for internal vertical borders, false for none, null for no change.
* @param horizontal - true for internal horizontal borders, false for none, null for no change.
* @param color - A color in CSS notation (such as '#ffffff' or 'white'), null for default color (black).
* @param style - A style for the borders, null for default style (solid).
*
* @returns This range, for chaining.
*/
setBorder(
top: Boolean,
left: Boolean,
bottom: Boolean,
right: Boolean,
vertical: Boolean,
horizontal: Boolean,
color: string,
style: SpreadsheetApp.BorderStyle
): SpreadsheetApp.Range
/**
* Sets one data validation rule for all cells in the range.
*
*
* // Set the data validation rule for cell A1 to require a value from B1:B10.
* var cell = SpreadsheetApp.getActive().getRange('A1');
* var range = SpreadsheetApp.getActive().getRange('B1:B10');
* var rule = SpreadsheetApp.newDataValidation().requireValueInRange(range).build();
* cell.setDataValidation(rule);
* null to remove data validation.
*
* @returns This range, for chaining.
*/
setDataValidation(
rule: SpreadsheetApp.DataValidation
): SpreadsheetApp.Range
/**
* Sets the data validation rules for all cells in the range. This method takes a two-dimensional
* array of data validations, indexed by row then by column. The array dimensions must correspond
* to the range dimensions.
*
*
* // Set the data validation rules for Sheet1!A1:B5 to require a value from Sheet2!A1:A10.
* var destinationRange = SpreadsheetApp.getActive().getSheetByName('Sheet1').getRange('A1:B5');
* var sourceRange = SpreadsheetApp.getActive().getSheetByName('Sheet2').getRange('A1:A10');
* var rule = SpreadsheetApp.newDataValidation().requireValueInRange(sourceRange).build();
* var rules = destinationRange.getDataValidations();
* for (var i = 0; i < rules.length; i++) {
* for (var j = 0; j < rules[i].length; j++) {
* rules[i][j] = rule;
* }
* }
* destinationRange.setDataValidations(rules);
* null values
* remove data validation.
*
* @returns This range, for chaining.
*/
setDataValidations(
rules: SpreadsheetApp.DataValidation[][]
): SpreadsheetApp.Range
/**
* Sets the font color in CSS notation (such as '#ffffff' or 'white').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* cell.setFontColor("red");
* '#ffffff' or 'white'); a
* null value resets the color.
*
* @returns This range, for chaining.
*/
setFontColor(
color: string
): SpreadsheetApp.Range
/**
* Sets the font color of the given range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var color = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.TEXT)
* .build();
*
* var cell = sheet.getRange("B2");
* cell.setFontColor(color);
* null value resets the color.
*
* @returns This range, for chaining.
*/
setFontColorObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.Range
/**
* Sets a rectangular grid of font colors (must match dimensions of this range).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var colorAccent1 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
* .build();
* var colorAccent2 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
* .build();
* var colorAccent3 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
* .build();
* var colorAccent4 = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4)
* .build();
*
* var colors = [
* [colorAccent1, colorAccent2],
* [colorAccent3, colorAccent4]
* ];
*
* var cell = sheet.getRange("B5:C6");
* cell.setFontColorObjects(colors);
* null values reset the font color.
*
* @returns This range, for chaining.
*/
setFontColorObjects(
colors: SpreadsheetApp.Color[][]
): SpreadsheetApp.Range
/**
* Sets a rectangular grid of font colors (must match dimensions of this range). The colors are in
* CSS notation (such as '#ffffff' or 'white').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var colors = [
* ["red", "white", "blue"],
* ["#FF0000", "#FFFFFF", "#0000FF"] // These are the hex equivalents
* ];
*
* var cell = sheet.getRange("B5:D6");
* cell.setFontColors(colors);
* '#ffffff' or
* 'white'); null values reset the color.
*
* @returns This range, for chaining.
*/
setFontColors(
colors: object[][]
): SpreadsheetApp.Range
/**
* Sets a rectangular grid of font families (must match dimensions of this range). Examples of
* font families are "Arial" or "Helvetica".
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var fonts = [
* ["Arial", "Helvetica", "Verdana"],
* ["Courier New", "Arial", "Helvetica]
* ];
*
* var cell = sheet.getRange("B2:D3");
* cell.setFontFamilies(fonts);
* null values reset the
* font family.
*
* @returns This range, for chaining.
*/
setFontFamilies(
fontFamilies: object[][]
): SpreadsheetApp.Range
/**
* Sets the font family, such as "Arial" or "Helvetica".
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* cell.setFontFamily("Helvetica");
* null value resets the font family.
*
* @returns This range, for chaining.
*/
setFontFamily(
fontFamily: string
): SpreadsheetApp.Range
/**
* Sets the font line style of the given range ('underline', 'line-through', or
* 'none').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* cell.setFontLine("line-through");
* 'underline', 'line-through', or
* 'none'; a null value resets the font line style.
*
* @returns This range, for chaining.
*/
setFontLine(
fontLine: string
): SpreadsheetApp.Range
/**
* Sets a rectangular grid of line styles (must match dimensions of this range).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The size of the two-dimensional array must match the size of the range.
* var fontLines = [
* ["underline", "line-through", "none"]
* ];
*
* var range = sheet.getRange("B2:D2");
* range.setFontLines(fontLines);
* 'underline', 'line-through', or 'none'); null values reset the font line style.
*
* @returns This range, for chaining.
*/
setFontLines(
fontLines: object[][]
): SpreadsheetApp.Range
/**
* Sets the font size, with the size being the point size to use.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* cell.setFontSize(20);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The size of the two-dimensional array must match the size of the range.
* var fontSizes = [
* [16, 20, 24]
* ];
*
* var range = sheet.getRange("B2:D2");
* range.setFontSizes(fontSizes);
* 'italic' or 'normal').
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* cell.setFontStyle("italic");
* 'italic' or 'normal'; a null
* value resets the font style.
*
* @returns This range, for chaining.
*/
setFontStyle(
fontStyle: string
): SpreadsheetApp.Range
/**
* Sets a rectangular grid of font styles (must match dimensions of this range).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The size of the two-dimensional array must match the size of the range.
* var fontStyles = [
* ["italic", "normal"]
* ];
*
* var range = sheet.getRange("B2:C2");
* range.setFontStyles(fontStyles);
* 'italic' or 'normal'; null values reset the font style.
*
* @returns This range, for chaining.
*/
setFontStyles(
fontStyles: object[][]
): SpreadsheetApp.Range
/**
* Set the font weight for the given range (normal/bold).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* cell.setFontWeight("bold");
* 'bold' or 'normal'; a null
* value resets the font weight.
*
* @returns This range, for chaining.
*/
setFontWeight(
fontWeight: string
): SpreadsheetApp.Range
/**
* Sets a rectangular grid of font weights (must match dimensions of this range). An example of a
* font weight is "bold".
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The size of the two-dimensional array must match the size of the range.
* var fontStyles = [
* [ "bold", "bold", "normal" ]
* ];
*
* var range = sheet.getRange("B2:D2");
* range.setFontWeights(fontStyles);
* 'bold' or 'normal'; null values reset the font weight.
*
* @returns This range, for chaining.
*/
setFontWeights(
fontWeights: object[][]
): SpreadsheetApp.Range
/**
* Updates the formula for this range. The given formula must be in A1 notation.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B5");
* cell.setFormula("=SUM(B3:B4)");
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B5");
* // This sets the formula to be the sum of the 3 rows above B5
* cell.setFormulaR1C1("=SUM(R[-3]C[0]:R[-1]C[0])");
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This sets the formulas to be a row of sums, followed by a row of averages right below.
* // The size of the two-dimensional array must match the size of the range.
* var formulas = [
* ["=SUM(B2:B4)", "=SUM(C2:C4)", "=SUM(D2:D4)"],
* ["=AVERAGE(B2:B4)", "=AVERAGE(C2:C4)", "=AVERAGE(D2:D4)"]
* ];
*
* var cell = sheet.getRange("B5:D6");
* cell.setFormulas(formulas);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This creates formulas for a row of sums, followed by a row of averages.
* var sumOfRowsAbove = "=SUM(R[-3]C[0]:R[-1]C[0])";
* var averageOfRowsAbove = "=AVERAGE(R[-4]C[0]:R[-2]C[0])";
*
* // The size of the two-dimensional array must match the size of the range.
* var formulas = [
* [sumOfRowsAbove, sumOfRowsAbove, sumOfRowsAbove],
* [averageOfRowsAbove, averageOfRowsAbove, averageOfRowsAbove]
* ];
*
* var cell = sheet.getRange("B5:D6");
* // This sets the formula to be the sum of the 3 rows above B5.
* cell.setFormulasR1C1(formulas);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* cell.setHorizontalAlignment("center");
* 'left', 'center' or 'normal'; a
* null value resets the alignment.
*
* @returns This range, for chaining.
*/
setHorizontalAlignment(
alignment: string
): SpreadsheetApp.Range
/**
* Sets a rectangular grid of horizontal alignments. see setHorizontalAlignment(alignment)
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The size of the two-dimensional array must match the size of the range.
* var horizontalAlignments = [
* [ "left", "right", "center" ]
* ];
*
* var range = sheet.getRange("B2:D2");
* range.setHorizontalAlignments(horizontalAlignments);
* 'left', 'center' or 'normal'; a null value resets the alignment.
*
* @returns This range, for chaining.
*/
setHorizontalAlignments(
alignments: object[][]
): SpreadsheetApp.Range
/**
* Sets the note to the given value.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* cell.setNote("This is a note");
* null value removes the note.
*
* @returns This range, for chaining.
*/
setNote(
note: string
): SpreadsheetApp.Range
/**
* Sets a rectangular grid of notes (must match dimensions of this range).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The size of the two-dimensional array must match the size of the range.
* var notes = [
* ["it goes", "like this", "the fourth, the fifth"],
* ["the minor fall", "and the", "major lift"]
* ];
*
* var cell = sheet.getRange("B2:D3");
* cell.setNotes(notes)
* null values remove the note.
*
* @returns This range, for chaining.
*/
setNotes(
notes: object[][]
): SpreadsheetApp.Range
/**
* Sets the number or date format to the given formatting string. The accepted format patterns are
* described in the Sheets API documentation.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* // Always show 3 decimal points
* cell.setNumberFormat("0.000");
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The size of the two-dimensional array must match the size of the range.
* var formats = [
* [ "0.000", "0,000,000", "$0.00" ]
* ];
*
* var range = sheet.getRange("B2:D2");
* range.setNumberFormats(formats);
*
* // Sets all cells in range B2:D4 to have the text "Hello world", with "Hello" bolded.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("B2:D4");
* var bold = SpreadsheetApp.newTextStyle()
* .setBold(true)
* .build();
* var richText = SpreadsheetApp.newRichTextValue()
* .setText("Hello world")
* .setTextStyle(0, 5, bold)
* .build();
* range.setRichTextValue(richText);
*
* // Sets the cells in range A1:A2 to have Rich Text values.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:A2");
* var bold = SpreadsheetApp.newTextStyle()
* .setBold(true)
* .build();
* var italic = SpreadsheetApp.newTextStyle()
* .setItalic(true)
* .build();
* var richTextA1 = SpreadsheetApp.newRichTextValue()
* .setText("This cell is bold")
* .setTextStyle(bold)
* .build();
* var richTextA2 = SpreadsheetApp.newRichTextValue()
* .setText("bold words, italic words")
* .setTextStyle(0, 11, bold)
* .setTextStyle(12, 24, italic)
* .build();
* range.setRichTextValues([[richTextA1], [richTextA2]]);
* null,
* the direction is inferred and then set.
*
*
* // Sets right-to-left text direction for the range.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("B5:C6");
* range.setTextDirection(SpreadsheetApp.TextDirection.RIGHT_TO_LEFT);
* null the direction is inferred before
* setting.
*
* @returns This range, for chaining.
*/
setTextDirection(
direction: SpreadsheetApp.TextDirection
): SpreadsheetApp.Range
/**
* Sets a rectangular grid of text directions. If a specified direction is null, the
* direction is inferred and then set.
*
*
* // Copies all of the text directions from range A1:B2 over to range C5:D6.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range1 = sheet.getRange("A1:B2");
* var range2 = sheet.getRange("C5:D6");
*
* range2.setTextRotations(range1.getTextDirections());
* null it is
* inferred before setting.
*
* @returns This range, for chaining.
*/
setTextDirections(
directions: SpreadsheetApp.TextDirection[][]
): SpreadsheetApp.Range
/**
* Sets the text rotation settings for the cells in the range. The input corresponds to the angle
* between the standard text orientation and the desired orientation. An input of zero indicates
* that the text is set to the standard orientation.
*
* For left to right text direction, positive angles are in the counterclockwise direction, * whereas for right to left they are in the clockwise direction. * *
* // Sets all cell's in range B2:D4 to have text rotated up 45 degrees.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("B2:D4");
*
* range.setTextRotation(45);
*
* // Sets all cell's in range B2:D4 to have the same text rotation settings as cell A1.
* var sheet = SpreadsheetApp.getActiveSheet();
*
* var rotation = sheet.getRange("A1").getTextRotation();
*
* sheet.getRange("B2:D4").setTextRotation(rotation);
*
*
* // Copies all of the text rotations from range A1:B2 over to range C5:D6.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range1 = sheet.getRange("A1:B2");
* var range2 = sheet.getRange("C5:D6");
*
* range2.setTextRotations(range1.getTextRotations());
*
* // Sets the cells in range C5:D6 to have underlined size 15 font.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("C5:D6");
* var style = SpreadsheetApp.newTextStyle()
* .setFontSize(15)
* .setUnderline(true)
* .build();
* range.setTextStyle(style);
*
* // Sets text styles for cells in range A1:B2
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B2");
* var bold = SpreadsheetApp.newTextStyle()
* .setBold(true)
* .build();
* var otherStyle = SpreadsheetApp.newTextStyle()
* .setBold(true)
* .setUnderline(true)
* .setItalic(true)
* .setForegroundColor("#335522")
* .setFontSize(44)
* .build();
* range.setTextStyles([[bold, otherStyle], [otherStyle, bold]]);
* '=' it is interpreted as a formula.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* cell.setValue(100);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The size of the two-dimensional array must match the size of the range.
* var values = [
* [ "2.000", "1,000,000", "$2.99" ]
* ];
*
* var range = sheet.getRange("B2:D2");
* range.setValues(values);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* cell.setVerticalAlignment("middle");
* 'top', 'middle' or 'bottom'; a
* null value resets the alignment.
*
* @returns This range, for chaining.
*/
setVerticalAlignment(
alignment: string
): SpreadsheetApp.Range
/**
* Sets a rectangular grid of vertical alignments (must match dimensions of this range).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The size of the two-dimensional array must match the size of the range.
* var alignments = [
* [ "top", "middle", "bottom" ]
* ];
*
* var range = sheet.getRange("B2:D2");
* range.setVerticalAlignments(alignments);
* 'top', 'middle'
* or 'bottom'; a null value resets the alignment.
*
* @returns This range, for chaining.
*/
setVerticalAlignments(
alignments: object[][]
): SpreadsheetApp.Range
/**
* Sets whether or not to stack the text for the cells in the range. If the text is stacked
* vertically, the degree text rotation setting is ignored.
*
*
* // Sets all cell's in range B2:D4 to have vertically stacked text.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("B2:D4");
*
* range.setVerticalText(true);
* Cells with wrap enabled (the default) resize to display their full content. Cells with wrap * disabled display as much as possible in the cell without resizing or running to multiple lines. * *
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var cell = sheet.getRange("B2");
* cell.setWrap(true);
*
* // Copies all of the wrap strategies from range A1:B2 over to range C5:D6.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range1 = sheet.getRange("A1:B2");
* var range2 = sheet.getRange("C5:D6");
*
* range2.setWrapStrategies(range1.getWrapStrategies());
*
* // Sets all cells in range B2:D4 to use the clip wrap strategy.
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("B2:D4");
*
* range.setWrapStrategy(SpreadsheetApp.WrapStrategy.CLIP);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The size of the two-dimensional array must match the size of the range.
* var wraps = [
* [ true, true, false ]
* ];
*
* var range = sheet.getRange("B2:D2");
* range.setWraps(wraps);
* This has the effect of creating, modifying, or deleting groups that intersect with the * range. For positive deltas, groups are created and/or modified; for negative deltas, groups are * destroyed and/or modified. * *
This has no effect when decreasing the group depth below zero or above eight. * *
If the column group control position is
* BEFORE, this throws an error when attempting to shift
* the depth of the first row.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getActiveRange();
*
* // The column grouping depth is increased by 1.
* range.shiftColumnGroupDepth(1);
*
* // The column grouping depth is decreased by 1.
* range.shiftColumnGroupDepth(-1);
* This has the effect of creating, modifying, or deleting groups that intersect with the * range. For positive deltas, groups are created and/or modified; for negative deltas, groups are * destroyed and/or modified. * *
This has no effect when decreasing the group depth below zero or above eight. * *
If the row group control position is BEFORE, this throws an error when attempting to shift the
* depth of the first row.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getActiveRange();
*
* // The row grouping depth is increased by 1.
* range.shiftRowGroupDepth(1);
*
* // The row grouping depth is decreased by 1.
* range.shiftRowGroupDepth(-1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange("A1:C7");
*
* // Sorts by the values in the first column (A)
* range.sort(1);
*
* // Sorts by the values in the second column (B)
* range.sort(2);
*
* // Sorts descending by column B
* range.sort({column: 2, ascending: false});
*
* // Sorts descending by column B, then ascending by column A
* // Note the use of an array
* range.sort([{column: 2, ascending: false}, {column: 1, ascending: true}]);
*
* // For rows that are sorted in ascending order, the "ascending" parameter is
* // optional, and just an integer with the column can be used instead. Note that
* // in general, keeping the sort specification consistent results in more readable
* // code. You can express the earlier sort as:
* range.sort([{column: 2, ascending: false}, 1]);
*
* // Alternatively, if you want all columns to be in ascending order, you can use
* // the following (this makes column 2 ascending)
* range.sort([2, 1]);
* // ... which is equivalent to
* range.sort([{column: 2, ascending: true}, {column: 1, ascending: true}]);
*
* // A1:A3 has the following values:
* // A B C
* // 1 |one,one,one | | |
* // 2 |two,two,two | | |
* // 3 |three,three,three| | |
*
* var range = SpreadsheetApp.getActiveSheet().getRange("A1:A3");
* range.splitTextToColumns();
*
* // Result after spliting the text to columns:
* // A B C
* // 1 |one |one |one |
* // 2 |two |two |two |
* // 3 |three |three |three |
*
* // A1:A3 has the following values:
* // A B C
* // 1 |one;one;one | | |
* // 2 |two;two;two | | |
* // 3 |three;three;three| | |
*
* var range = SpreadsheetApp.getActiveSheet().getRange("A1:A3");
* range.splitTextToColumns(SpreadsheetApp.TextToColumnsDelimiter.SEMICOLON);
*
* // Result after spliting the text to columns:
* // A B C
* // 1 |one |one |one |
* // 2 |two |two |two |
* // 3 |three |three |three |
*
* // A1:A3 has the following values:
* // A B C
* // 1 |one#one#one | | |
* // 2 |two#two#two | | |
* // 3 |three#three#three| | |
*
* var range = SpreadsheetApp.getActiveSheet().getRange("A1:A3");
* range.splitTextToColumns('#');
*
* // Result after spliting the text to columns:
* // A B C
* // 1 |one |one |one |
* // 2 |two |two |two |
* // 3 |three |three |three |
* * *
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getRange('A1:A4');
* range.activate();
* range.setValues(
* [' preceding space', 'following space ', 'two middle spaces', ' =SUM(1,2)'])
*
* range.trimWhitespace();
*
* var values = range.getValues();
* // Values are ['preceding space', 'following space', 'two middle spaces', '=SUM(1,2)']
*
* // Changes the state of cells which currently contain either the checked or unchecked value
* // configured in the range A1:B10 to 'unchecked'.
* var range = SpreadsheetApp.getActive().getRange('A1:B10');
* range.uncheck();
* Range instances. The last range in the list is set as the active range.
*
* Note: This provides a way to multi-select a number of ranges. * *
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['D4', 'B2:C4']);
* rangeList.activate();
*
* var selection = sheet.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();
* Calling this function on a range list is equivalent to selecting a set of ranges and * selecting the Format > Merge > Unmerge Sheets menu item. * *
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.breakApart();
*
* // Changes the state of cells which currently contain either the checked or unchecked value
* // configured in the ranges D4 and E6 to 'checked'.
* var rangeList = SpreadsheetApp.getActive().getRangeList(['D4', 'E6']);
* rangeList.check();
* Range in
* the range list.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.clear();
*
* // The code below clears the contents of the following ranges A:A and C:C in the active sheet,
* // but preserves the format, data validation rules, and comments.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.clear({contentsOnly: true});
* Range in the range list, leaving the formatting intact.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.clearContent();
* Range in the range list.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.clearDataValidations();
* Range in the range list.
*
* This clears text formatting for each range, but does not reset any number formatting rules. * *
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.clearFormat();
* Range in the range list.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.clearNote();
* Range instances in the same sheet.
*
* @returns The list of ranges.
*/
getRanges(): SpreadsheetApp.Range[]
/**
* Inserts checkboxes into each cell in the range, configured with true for checked and
* false for unchecked. Sets the value of all cells in the range to false.
*
*
* var rangeList = SpreadsheetApp.getActive().getRangeList(['D4', 'E6']);
*
* // Inserts checkboxes into each cell in the ranges D4 and E6 configured with 'true' for checked
* // and 'false' for unchecked. Also, sets the value of each cell in the ranges D4 and E6 to
* // 'false'.
* rangeList.insertCheckboxes();
*
* var rangeList = SpreadsheetApp.getActive().getRangeList(['D4', 'E6']);
*
* // Inserts checkboxes into each cell in the ranges D4 and E6 configured with 'yes' for checked
* // and the empty string for unchecked. Also, sets the value of each cell in the ranges D4 and
* // E6 to the empty string.
* rangeList.insertCheckboxes('yes');
*
* var rangeList = SpreadsheetApp.getActive().getRangeList(['D4', 'E6']);
*
* // Inserts checkboxes into each cell in the ranges D4 and E6 configured with 'yes' for checked
* // and 'no' for unchecked. Also, sets the value of each cell in the ranges D4 and E6 to 'no'.
* rangeList.insertCheckboxes('yes', 'no');
*
* var range = SpreadsheetApp.getActive().getRange('A1:B10');
*
* // Inserts checkboxes and sets each cell value to 'no' in the range A1:B10.
* range.insertCheckboxes('yes', 'no');
*
* var rangeList1 = SpreadsheetApp.getActive().getRangeList(['A1', 'A3']);
* rangeList1.setValue('yes');
* // Removes the checkbox data validation in cells A1 and A3 and clears their value.
* rangeList1.removeCheckboxes();
*
* var rangeList2 = SpreadsheetApp.getActive().getRangeList(['A5', 'A7']);
* rangeList2.setValue('random');
* // Removes the checkbox data validation in cells A5 and A7 but does not clear their value.
* rangeList2.removeCheckboxes();
* Range in the range list. Color is represented in
* in CSS notation; for example, '#ffffff' or 'white'.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.setBackground('red');
* '#ffffff' or 'white'; a null value resets the color.
*
* @returns This range list, for chaining.
*/
setBackground(
color: string
): SpreadsheetApp.RangeList
/**
* Sets the background to the given RGB color. This is a convenience wrapper around a setBackground(color) call.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* // Sets the background to red for each range in the range list.
* rangeList.setBackgroundRGB(255, 0, 0);
* Range in the range list. The valid values are
* true (on), false (off) and null (no change).
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A2:B4', 'C1:D4']);
* // Sets borders on the top and bottom of the ranges A2:B4 and C1:D4, but leaves the left and
* // right unchanged.
* rangeList.setBorder(true, null, true, null, false, false);
* true for border, false for none, null for no change.
* @param left - true for border, false for none, null for no change.
* @param bottom - true for border, false for none, null for no change.
* @param right - true for border, false for none, null for no change.
* @param vertical - true for internal vertical borders, false for none, null for no change.
* @param horizontal - true for internal horizontal borders, false for none, null for no change.
*
* @returns This range list, for chaining.
*/
setBorder(
top: Boolean,
left: Boolean,
bottom: Boolean,
right: Boolean,
vertical: Boolean,
horizontal: Boolean
): SpreadsheetApp.RangeList
/**
* Sets the border property with color and/or style for each Range in the range list.
* Valid values are true (on), false (off) and null (no change). Color is
* represented in in CSS notation; for example, '#ffffff' or 'white'.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A2:B4', 'C1:D4']);
* // Sets borders on the top and bottom, but leaves the left and right unchanged of the ranges
* // A2:B4 and C1:D4. Also sets the color to 'red', and the border to 'DASHED'.
* rangeList.setBorder(
* true, null, true, null, false, false, 'red', SpreadsheetApp.BorderStyle.DASHED);
* true for border, false for none, null for no change.
* @param left - true for border, false for none, null for no change.
* @param bottom - true for border, false for none, null for no change.
* @param right - true for border, false for none, null for no change.
* @param vertical - true for internal vertical borders, false for none, null for no change.
* @param horizontal - true for internal horizontal borders, false for none, null for no change.
* @param color - The border color in CSS notation like '#ffffff' or 'white', null for default color (black).
* @param style - The style for the borders, null for default style (solid).
*
* @returns This range list, for chaining.
*/
setBorder(
top: Boolean,
left: Boolean,
bottom: Boolean,
right: Boolean,
vertical: Boolean,
horizontal: Boolean,
color: string,
style: SpreadsheetApp.BorderStyle
): SpreadsheetApp.RangeList
/**
* Sets the font color for each Range in the range list. Color is represented in in CSS
* notation; for example, '#ffffff' or 'white'.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.setFontColor('red');
* '#ffffff' or 'white'; a
* null value resets the color.
*
* @returns This range list, for chaining.
*/
setFontColor(
color: string
): SpreadsheetApp.RangeList
/**
* Sets the font family for each Range in the range list. The font family is described
* by a string identifier such as Arial or Roboto.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.setFontFamily('Roboto');
* null value resets the font family.
*
* @returns This range list, for chaining.
*/
setFontFamily(
fontFamily: string
): SpreadsheetApp.RangeList
/**
* Sets the font line style for each Range in the range list. The line styles options
* are 'underline', 'line-through', or 'none'.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.setFontLine('line-through');
* 'underline', 'line-through', or
* 'none'; a null value resets the font line style.
*
* @returns This range list, for chaining.
*/
setFontLine(
fontLine: string
): SpreadsheetApp.RangeList
/**
* Sets the font size (in points) for each Range in the range list.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.setFontSize(20);
* Range in the range list. The font style options are
* 'italic' or 'normal'.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.setFontStyle("italic");
* 'italic' or 'normal'; a null
* value resets the font style.
*
* @returns This range list, for chaining.
*/
setFontStyle(
fontStyle: string
): SpreadsheetApp.RangeList
/**
* Set the font weight for each Range in the range list. The font weight options are
* 'normal' or 'bold'.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.setFontWeight('bold');
* 'bold' or 'normal'; a null
* value resets the font weight.
*
* @returns This range list, for chaining.
*/
setFontWeight(
fontWeight: string
): SpreadsheetApp.RangeList
/**
* Updates the formula for each Range in the range list. The given formula must be in
* A1 notation.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A11', 'C11']);
* rangeList.setFormula('=SUM(B1:B10)');
* Range in the range list. The given formula must be in
* R1C1 notation.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A11', 'C11']);
* // This sets the formula to be the sum of the 3 rows above B5
* rangeList.setFormulaR1C1('=SUM(R[-3]C[0]:R[-1]C[0])');
* Range in the range list. The alignment options
* are 'left', 'center', or 'right'.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.setHorizontalAlignment("center");
* 'left', 'center' or 'normal'; a
* null value resets the alignment.
*
* @returns This range list, for chaining.
*/
setHorizontalAlignment(
alignment: string
): SpreadsheetApp.RangeList
/**
* Sets the note text for each Range in the range list.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.setNote('This is a note');
* null value removes the note.
*
* @returns This range list, for chaining.
*/
setNote(
note: string
): SpreadsheetApp.RangeList
/**
* Sets the number or date format for each Range in the range list.
*
* The accepted formatting patterns are described in the Sheets API date and number formatting guide. * *
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A1:A10', 'C1:C10']);
* // Always show 3 decimal points for the specified ranges.
* rangeList.setNumberFormat('0.000');
* Range in the range list should show hyperlinks.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A1:A10', 'C1:C10']);
* // Show hyperlinks for all the ranges.
* rangeList.setShowHyperlink(true);
* Range in the range list. If a
* specified direction is null, the direction is inferred and then set.
*
*
* // Sets right-to-left text direction each range in the range list.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A1:A10', 'C1:C10']);
* rangeList.setTextDirection(SpreadsheetApp.TextDirection.RIGHT_TO_LEFT);
* null the direction is inferred before
* setting.
*
* @returns This range list, for chaining.
*/
setTextDirection(
direction: SpreadsheetApp.TextDirection
): SpreadsheetApp.RangeList
/**
* Sets the text rotation settings for the cells in each Range in the range list. The
* input corresponds to the angle between the standard text orientation and the desired
* orientation. An input of zero indicates that the text is set to the standard orientation.
*
* For left to right text direction, positive angles are in the counterclockwise direction, * whereas for right to left they are in the clockwise direction. * *
* // Sets the cells in the ranges A1:A10 and C1:C10 to have text rotated up 45 degrees.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['A1:A10', 'C1:C10']);
* rangeList.setTextRotation(45);
* Range in the range list. The value can be numeric, string,
* boolean or date. If it begins with '=' it is interpreted as a formula.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* // Set value of 100 to each range in the range list.
* var rangeList = sheet.getRangeList(['A:A', 'C:C']);
* rangeList.setValue(100);
* Range in the range list. The alignment options
* are 'top', 'middle' or 'bottom'.
*
*
* // Sets the vertical alignment to middle for the list of ranges.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['D4', 'B2:C4']);
* rangeList.setVerticalAlignment("middle");
* 'top', 'middle' or 'bottom'; a
* null value resets the alignment.
*
* @returns This range list, for chaining.
*/
setVerticalAlignment(
alignment: string
): SpreadsheetApp.RangeList
/**
* Sets whether or not to stack the text for the cells for each Range in the range
* list. If the text is stacked vertically, the degree text rotation setting is ignored.
*
*
* // Sets all cell's in ranges D4 and B2:D4 to have vertically stacked text.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['D4', 'B2:C4']);
* rangeList.setVerticalText(true);
* Range in the range list. Cells with wrap enabled resize
* to display their full content. Cells with wrap disabled display as much as possible in the cell
* without resizing or running to multiple lines.
*
*
* // Enable text wrap for the list of ranges.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['D4', 'B2:C4']);
* rangeList.setWrap(true);
* Range in the range list.
*
*
* // Sets the list of ranges to use the clip wrap strategy.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['D4', 'B2:C4']);
* rangeList.setWrapStrategy(SpreadsheetApp.WrapStrategy.CLIP);
* * *
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* var range = sheet.getRange('A1:A4');
* range.activate();
* range.setValues(
* [' preceding space', 'following space ', 'two middle spaces', ' =SUM(1,2)']);
*
* var rangeList = sheet.getRangeList(['A1', 'A2', 'A3', 'A4']);
* rangeList.trimWhitespace();
*
* var values = range.getValues();
* // Values are ['preceding space', 'following space', 'two middle spaces', '=SUM(1,2)']
*
* // Changes the state of cells which currently contain either the checked or unchecked value
* // configured in the ranges D4 and E6 to 'unchecked'.
* var rangeList = SpreadsheetApp.getActive().getRangeList(['D4', 'E6']);
* rangeList.uncheck();
* null if there is no link or if there are
* multiple different links.
*/
getLinkUrl(): string
/**
* Returns the link URL for the text from startOffset to endOffset. Offsets are 0
* based and relative to the cell's text, with the start offset being inclusive and the end offset
* being exclusive.
*
* @param startOffset - The start offset.
* @param endOffset - The end offset.
*
* @returns The link URL for this value, or null if there is no link or if multiple
* different links are in the given range.
*/
getLinkUrl(
startOffset: number,
endOffset: number
): string
/**
* Returns the Rich Text string split into an array of runs, wherein each run is the longest
* possible substring having a consistent text style.
*
* @returns An array of runs.
*/
getRuns(): SpreadsheetApp.RichTextValue[]
/**
* Gets the start index of this value in the cell.
*
* @returns The start index of this value in the cell.
*/
getStartIndex(): number
/**
* Returns the text of this value.
*
* @returns The text of this value.
*/
getText(): string
/**
* Returns the text style of this value.
*
* @returns The text style of this value.
*/
getTextStyle(): SpreadsheetApp.TextStyle
/**
* Returns the text style of the text from startOffset to endOffset. Offsets are 0
* based and relative to the cell's text, with the start offset being inclusive and the end offset
* being exclusive.
*
* @param startOffset - The start offset.
* @param endOffset - The end offset.
*
* @returns The text style of the given substring of this value.
*/
getTextStyle(
startOffset: number,
endOffset: number
): SpreadsheetApp.TextStyle
}
class RichTextValueBuilder {
private constructor();
/**
* Creates a Rich Text value from this builder.
*
* @returns A Rich Text value created from this builder.
*/
build(): SpreadsheetApp.RichTextValue
/**
* Sets the link URL for the given substring of this value, or clears it if linkUrl is
* null.
*
*
* // Creates a Rich Text value for the text "foo no baz" with "foo" pointing to
* // "https://bar.foo" and "baz" to "https://abc.xyz".
* // "foo" is underlined with the default link color, whereas "baz" has its text style
* // overridden by a call to `setTextStyle`, and is therefore black and bold with no underlining.
* const boldStyle = SpreadsheetApp.newTextStyle()
* .setUnderline(false)
* .setBold(true)
* .setForegroundColor("#000000")
* .build();
* const value = SpreadsheetApp.newRichTextValue()
* .setText("foo no baz")
* .setLinkUrl(0, 3, "https://bar.foo")
* .setLinkUrl(7, 10, "https://abc.xyz")
* .setTextStyle(7, 10, boldStyle)
* .build();
* linkUrl is null.
*
*
* // Creates a Rich Text value for the text "Foo" which points to "https://bar.foo".
* const value = SpreadsheetApp.newRichTextValue()
* .setText("Foo")
* .setLinkUrl("https://bar.foo")
* .build();
* setTextStyle(startOffset, endOffset, textStyle).
*
* @param text - The text for this value.
*
* @returns This builder, for chaining.
*/
setText(
text: string
): SpreadsheetApp.RichTextValueBuilder
/**
* Applies a text style to the given substring of this value. Offsets are 0 based and are relative
* to the cell's text value. Does nothing if textStyle is null.
*
*
* // Creates a Rich Text value for the text "HelloWorld", with "Hello" bolded, and "World"
* // italicized.
* var bold = SpreadsheetApp.newTextStyle().setBold(true).build();
* var italic = SpreadsheetApp.newTextStyle().setItalic(true).build();
* var value = SpreadsheetApp.newRichTextValue()
* .setText("HelloWorld")
* .setTextStyle(0, 5, bold)
* .setTextStyle(5, 10, italic)
* .build();
* textStyle. Does nothing if textStyle
* is null.
*
*
* // Creates a Rich Text value for the text "HelloWorld" with "Hello" bolded and italicized,
* // and "World" only italicized.
* var bold = SpreadsheetApp.newTextStyle().setBold(true).build();
* var italic = SpreadsheetApp.newTextStyle().setItalic(true).build();
* var value = SpreadsheetApp.newRichTextValue()
* .setText("HelloWorld")
* .setTextStyle(0, 5, bold)
* .setTextStyle(italic)
* .build();
* null if there is no active range. If
* multiple ranges are selected this method returns only the last selected range.
*
*
* var selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
* var activeRange = selection.getActiveRange();
* null if there are no active
* ranges.
*
* If there is a single range selected, this behaves as a getActiveRange() call.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* // Returns the list of active ranges.
* var activeRangeList = sheet.getActiveRangeList();
*
* var selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
* var activeSheet = selection.getActiveSheet();
* null if there is no current cell.
*
*
* var selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
* // Returns the current highlighted cell in the one of the active ranges.
* var currentCell = selection.getCurrentCell();
* current cell and active range
* and moving in the given direction, returns an adjusted range where the appropriate edge of the
* range has been shifted to cover the next data cell while still
* covering the current cell. If the active range is unbounded along the dimension of the direction, the original active range is returned. If there is no current cell
* or active range, null is returned. This is equivalent to selecting a range in the
* editor and hitting Ctrl+Shift+[arrow key].
*
*
* // Assume the active spreadsheet is blank.
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Makes C3 the current cell and C3:E5 the active range.
* sheet.getRange("C3:E5").activate();
* // Logs "C1:E3"
* Logger.log(SpreadsheetApp.getSelection().getNextDataRange(Direction.UP).getA1Notation());
* null if there is no
* selection
*/
getNextDataRange(
direction: SpreadsheetApp.Direction
): SpreadsheetApp.Range
}
class Sheet {
private constructor();
/**
* Activates this sheet. Does not alter the sheet itself, only the parent's notion of the active
* sheet.
*
*
* // This example assumes there is a sheet named "first"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var first = ss.getSheetByName("first");
* first.activate();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Appends a new row with 3 columns to the bottom of the
* // spreadsheet containing the values in the array
* sheet.appendRow(["a man", "a plan", "panama"]);
* DataSourceSheet if the sheet is of type SheetType.DATASOURCE, or null otherwise.
*
* @returns A data source sheet.
*/
asDataSourceSheet(): SpreadsheetApp.DataSourceSheet
/**
* Sets the width of the given column to fit its contents.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* sheet.getRange('a1').setValue('Whenever it is a damp, drizzly November in my soul...');
*
* // Sets the first column to a width which fits the text
* sheet.autoResizeColumn(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Sets the first 15 columns to a width that fits their text.
* sheet.autoResizeColumns(1, 15);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Sets the first 15 rows to a height that fits their text.
* sheet.autoResizeRows(1, 15);
*
* // This example assumes there is a sheet named "first"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var first = ss.getSheetByName("first");
* first.clear();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* sheet.clear({ formatOnly: true, contentsOnly: true });
* setConditionalFormatRules(rules) with an empty array as input.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* sheet.clearConditionalFormatRules();
*
* // This example assumes there is a sheet named "first"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var first = ss.getSheetByName("first");
* first.clearContents();
* Formatting refers to how data is formatted as allowed by choices under the "Format" menu * (ex: bold, italics, conditional formatting) and not width or height of cells. * *
* // This example assumes there is a sheet named "first"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var first = ss.getSheetByName("first");
* first.clearFormats();
*
* // This example assumes there is a sheet named "first"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var first = ss.getSheetByName("first");
* first.clearNotes();
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // All column groups on the sheet are collapsed.
* sheet.collapseAllColumnGroups();
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // All row groups on the sheet are collapsed.
* sheet.collapseAllRowGroups();
*
* var source = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = source.getSheets()[0];
*
* var destination = SpreadsheetApp.openById('ID_GOES HERE');
* sheet.copyTo(destination);
* DeveloperMetadataFinder for finding developer metadata within the scope of
* this sheet. Metadata is in the scope of a particular sheet if it is either associated with the
* sheet itself, or associated with a row, column, or range on that sheet.
*
* @returns A developer metadata finder to search for metadata in the scope of this sheet.
*/
createDeveloperMetadataFinder(): SpreadsheetApp.DeveloperMetadataFinder
/**
* Creates a text finder for the sheet, which can find and replace text within the sheet.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // Creates a text finder.
* var textFinder = sheet.createTextFinder('dog');
*
* // Returns the first occurrence of 'dog' in the sheet.
* var firstOccurrence = textFinder.findNext();
*
* // Replaces the last found occurrence of 'dog' with 'cat' and returns the number
* // of occurrences replaced.
* var numOccurrencesReplaced = findOccurrence.replaceWith('cat');
* TextFinder for the sheet.
*/
createTextFinder(
findText: string
): SpreadsheetApp.TextFinder
/**
* Deletes the column at the given column position.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Columns start at "1" - this deletes the first column
* sheet.deleteColumn(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Columns start at "1" - this deletes the first two columns
* sheet.deleteColumns(1, 2);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Rows start at "1" - this deletes the first row
* sheet.deleteRow(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Rows start at "1" - this deletes the first two rows
* sheet.deleteRows(1, 2);
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // All column groups on the sheet are expanded.
* sheet.expandAllColumnGroups();
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // All row groups on the sheet are expanded.
* sheet.expandAllRowGroups();
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // All column groups of depth 2 and lower are expanded, and groups with depth
* // 3 and higher are collapsed.
* sheet.expandColumnGroupsUpToDepth(2);
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // All row groups of depth 2 and lower are expanded, and groups with depth
* // 3 and higher are collapsed.
* sheet.expandRowGroupsUpToDepth(2);
* Note: It's preferrable to use getCurrentCell(), which the returns the current
* highlighted cell.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Returns the active cell
* var cell = sheet.getActiveCell();
* null if there is no active range. If
* multiple ranges are selected this method returns only the last selected range.
*
* The term "active range" refers to the range that a user has selected in the active sheet, * but in a custom function it refers to the cell being actively recalculated. * *
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
* var activeRange = sheet.getActiveRange();
* null if there are no active
* ranges.
*
* If there is a single range selected, this behaves as a getActiveRange() call.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* // Returns the list of active ranges.
* var activeRangeList = sheet.getActiveRangeList();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var charts = sheet.getCharts();
*
* for (var i in charts) {
* var chart = charts[i];
* // Do something with the chart
* }
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // Returns the group whose control index is at column 2 and has a depth of 1, or
* // null if the group doesn’t exist.
* var columnGroup = sheet.getColumnGroup(2, 1);
* null if the group doesn’t
* exist.
*/
getColumnGroup(
columnIndex: number,
groupDepth: number
): SpreadsheetApp.Group
/**
* Returns the GroupControlTogglePosition for all column groups on the sheet.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // GroupControlTogglePosition.AFTER if the column grouping control toggle is shown after the
* // group.
* var columnGroupControlPosition = sheet.getColumnGroupControlPosition();
* true if the column grouping control toggle is shown after the group on this
* sheet and false otherwise.
*/
getColumnGroupControlPosition(): SpreadsheetApp.GroupControlTogglePosition
/**
* Returns the group depth of the column at the given index.
*
* The group depth indicates how many groups overlap with the column. This can range between * zero and eight. * *
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // 1 if there is a group over columns 1 through 3
* var groupDepth = sheet.getColumnGroupDepth(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Columns start at 1
* Logger.log(sheet.getColumnWidth(1));
*
* // Logs the conditional format rules in a sheet.
* var rules = SpreadsheetApp.getActiveSheet().getConditionalFormatRules();
* for (var i = 0; i < rules.length; i++) {
* var rule = rules[i];
* Logger.log(rule);
* }
* null if there is no current cell. The
* current cell is the cell that has focus in the Google Sheets UI, and is highlighted by a dark
* border. There is never more than one current cell. When a user selects one or more cell ranges,
* one of the cells in the selection is the current cell.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
* // Returns the current highlighted cell in the one of the active ranges.
* var currentCell = sheet.getCurrentCell();
* Range corresponding to the dimensions in which data is present.
*
* This is functionally equivalent to creating a Range bounded by A1 and * (Range.getLastColumn(), Range.getLastRow()). * *
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This represents ALL the data
* var range = sheet.getDataRange();
* var values = range.getValues();
*
* // This logs the spreadsheet in CSV format with a trailing comma
* for (var i = 0; i < values.length; i++) {
* var row = "";
* for (var j = 0; j < values[i].length; j++) {
* if (values[i][j]) {
* row = row + values[i][j];
* }
* row = row + ",";
* }
* Logger.log(row);
* }
* null if there is no filter.
*
* @returns The filter.
*/
getFilter(): SpreadsheetApp.Filter
/**
* Returns the URL for the form that sends its responses to this sheet, or null if this
* sheet has no associated form.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var url = sheet.getFormUrl();
* null if this
* sheet doesn't have an associated form.
*/
getFormUrl(): string
/**
* Returns the number of frozen columns.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* Logger.log("Number of frozen columns: %s", sheet.getFrozenColumns());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* Logger.log("Number of frozen rows: %s", sheet.getFrozenRows());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* // Note that the JavaScript index is 0, but this logs 1
* var sheet = ss.getSheets()[0];
* // ... because spreadsheets are 1-indexed
* Logger.log(sheet.getIndex());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This logs the value in the very last cell of this sheet
* var lastRow = sheet.getLastRow();
* var lastColumn = sheet.getLastColumn();
* var lastCell = sheet.getRange(lastRow, lastColumn);
* Logger.log(lastCell.getValue());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This logs the value in the very last cell of this sheet
* var lastRow = sheet.getLastRow();
* var lastColumn = sheet.getLastColumn();
* var lastCell = sheet.getRange(lastRow, lastColumn);
* Logger.log(lastCell.getValue());
*
* // This example assumes there is a sheet named "first"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var first = ss.getSheetByName("first");
* Logger.log(first.getMaxColumns());
*
* // This example assumes there is a sheet named "first"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var first = ss.getSheetByName("first");
* Logger.log(first.getMaxRows());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* Logger.log(sheet.getName());
*
* // The code below logs the name of the first named range.
* var namedRanges = SpreadsheetApp.getActiveSheet().getNamedRanges();
* if (namedRanges.length > 1) {
* Logger.log(namedRanges[0].getName());
* }
* Spreadsheet that contains this sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // parent is identical to ss
* var parent = sheet.getParent();
*
* // Remove all range protections in the spreadsheet that the user has permission to edit.
* var sheet = SpreadsheetApp.getActiveSheet();
* var protections = sheet.getProtections(SpreadsheetApp.ProtectionType.RANGE);
* for (var i = 0; i < protections.length; i++) {
* var protection = protections[i];
* if (protection.canEdit()) {
* protection.remove();
* }
* }
*
* // Remove sheet protection from the active sheet, if the user has permission to edit it.
* var sheet = SpreadsheetApp.getActiveSheet();
* var protection = sheet.getProtections(SpreadsheetApp.ProtectionType.SHEET)[0];
* if (protection && protection.canEdit()) {
* protection.remove();
* }
* SpreadsheetApp.ProtectionType.RANGE or
* SpreadsheetApp.ProtectionType.SHEET.
*
* @returns An array of objects representing all protected ranges in the sheet, or a single-element
* array representing the protection on the sheet itself.
*/
getProtections(
type: SpreadsheetApp.ProtectionType
): SpreadsheetApp.Protection[]
/**
* Returns the range with the top left cell at the given coordinates.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Passing only two arguments returns a "range" with a single cell.
* var range = sheet.getRange(1, 1);
* var values = range.getValues();
* Logger.log(values[0][0]);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // When the "numRows" argument is used, only a single column of data is returned.
* var range = sheet.getRange(1, 1, 3);
* var values = range.getValues();
*
* // Prints 3 values from the first column, starting from row 1.
* for (var row in values) {
* for (var col in values[row]) {
* Logger.log(values[row][col]);
* }
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* var range = sheet.getRange(1, 1, 3, 3);
* var values = range.getValues();
*
* // Print values from a 3x3 box.
* for (var row in values) {
* for (var col in values[row]) {
* Logger.log(values[row][col]);
* }
* }
*
* // Get a range A1:D4 on sheet titled "Invoices"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var range = ss.getRange("Invoices!A1:D4");
*
* // Get cell A1 on the first sheet
* var sheet = ss.getSheets()[0];
* var cell = sheet.getRange("A1");
* RangeList collection representing the ranges in the same sheet specified
* by a non-empty list of A1 notations or R1C1 notations.
*
*
* // Get a list of ranges A1:D4, F1:H4.
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
* var rangeList = sheet.getRangeList(['A1:D4', 'F1:H4']);
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // Returns the group whose control index is at row 2 and has a depth of 1, or
* // null if the group doesn’t exist.
* var rowGroup = sheet.getRowGroup(2, 1);
* null if the group doesn’t
* exist.
*/
getRowGroup(
rowIndex: number,
groupDepth: number
): SpreadsheetApp.Group
/**
* Returns the GroupControlTogglePosition for all row groups on the sheet.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // GroupControlTogglePosition.AFTER if the row grouping control toggle is shown after the
* // group.
* var rowGroupControlPosition = sheet.getRowGroupControlPosition();
* true if the row grouping control toggle is shown after the group on this sheet
* and false otherwise.
*/
getRowGroupControlPosition(): SpreadsheetApp.GroupControlTogglePosition
/**
* Returns the group depth of the row at the given index.
*
* The group depth indicates how many groups overlap with the row. This can range between zero * and eight. * *
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
*
* // 1 if there is a group over rows 1 through 3
* var groupDepth = sheet.getRowGroupDepth(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Rows start at 1
* Logger.log(sheet.getRowHeight(1));
* Selection in the spreadsheet.
*
*
* var selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
* var currentCell = selection.getCurrentCell();
* This is an ID for the sheet that is unique to the spreadsheet. The ID is a monotonically
* increasing integer assigned at sheet creation time that is independent of sheet position. This
* is useful in conjunction with methods such as Range.copyFormatToRange(gridId, column, columnEnd, row, rowEnd) that take a gridId parameter rather than a Sheet instance.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* Logger.log(sheet.getSheetId());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* Logger.log(sheet.getSheetName());
* PageProtection
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var permissions = sheet.getSheetProtection();
*
* permissions.setProtected(true);
* permissions.addUser("user@example.com");
*
* // Logs the users that have access to edit this sheet. Note that this
* // is different from access to the entire spreadsheet - getUsers()
* // only returns users if permissions.isProtected() is set to true.
* var users = permissions.getUsers();
* Logger.log(users);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The two samples below produce the same output
* var values = sheet.getSheetValues(1, 1, 3, 3);
* Logger.log(values);
*
* var range = sheet.getRange(1, 1, 3, 3);
* values = range.getValues();
* Logger.log(values);
* null if the sheet tab has no color.
*
*
* // This example assumes there is a sheet named "first"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var first = ss.getSheetByName("first");
* var color = first.getTabColor();
* '#ffffff').
*/
getTabColor(): string
/**
* Gets the sheet tab color, or null if the sheet tab has no color.
*
*
* // This example assumes there is a sheet named "Sheet1"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var first = ss.getSheetByName("Sheet1");
* var color = first.getTabColorObject();
* null if the sheet tab has no color.
*/
getTabColorObject(): SpreadsheetApp.Color
/**
* Returns the type of the sheet.
*
* The default type of sheet is SheetType.GRID. A sheet that contains a single embedded
* object such as an EmbeddedChart is an SheetType.OBJECT sheet.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* Logger.log(sheet.getType());
* true if the sheet's gridlines are hidden; otherwise returns false.
* Gridlines are visible by default.
*
* @returns true if gridlines are hidden; false otherwise.
*/
hasHiddenGridlines(): Boolean
/**
* Hides the columns in the given range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This hides the first column
* var range = sheet.getRange("A1");
* sheet.hideColumn(range);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Hides the first column
* sheet.hideColumns(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Hides the first three columns
* sheet.hideColumns(1, 3);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This hides the first row
* var range = sheet.getRange("A1");
* sheet.hideRow(range);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Hides the first row
* sheet.hideRows(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Hides the first three rows
* sheet.hideRows(1, 3);
*
* var sheet = SpreadsheetApp.getActiveSheet();
* sheet.hideSheet();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This creates a simple bar chart from the first three rows
* // of the first two columns of the spreadsheet
* var chart = sheet.newChart()
* .setChartType(Charts.ChartType.BAR)
* .addRange(sheet.getRange("A1:B4"))
* .setPosition(5, 5, 0, 0)
* .setOption("title", "Dynamic Chart")
* .build();
* sheet.insertChart(chart);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts a column after the first column position
* sheet.insertColumnAfter(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts a column in the first column position
* sheet.insertColumnBefore(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Shifts all columns by one
* sheet.insertColumns(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Shifts all columns by three
* sheet.insertColumns(1, 3);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts a column in the second column position
* sheet.insertColumnsAfter(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts five columns before the first column
* sheet.insertColumnsBefore(1, 5);
* BlobSource as an image in the document at a given row and column. The image
* size is retrieved from the blob contents.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var blob = Utilities.newBlob(binaryData, 'image/png', 'MyImageName');
* sheet.insertImage(blob, 1, 1);
* BlobSource as an image in the document at a given row and column, with a
* pixel offset. The image size is retrieved from the blob contents.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var blob = Utilities.newBlob(binaryData, 'image/png', 'MyImageName');
* sheet.insertImage(blob, 1, 1, 10, 10);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* sheet.insertImage("https://www.google.com/images/srpr/logo3w.png", 1, 1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* sheet.insertImage("https://www.google.com/images/srpr/logo3w.png", 1, 1, 10, 10);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts a row after the first row position
* sheet.insertRowAfter(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts a row before the first row position
* sheet.insertRowBefore(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Shifts all rows down by one
* sheet.insertRows(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Shifts all rows down by three
* sheet.insertRows(1, 3);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts five rows after the first row
* sheet.insertRowsAfter(1, 5);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts five rows before the first row
* sheet.insertRowsBefore(1, 5);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Columns start at 1
* Logger.log(sheet.isColumnHiddenByUser(1));
* true if the column is hidden, false otherwise.
*/
isColumnHiddenByUser(
columnPosition: number
): Boolean
/**
* Returns true if this sheet layout is right-to-left. Returns false if the sheet
* uses the default left-to-right layout.
*
* @returns true if right-to-left; false otherwise.
*/
isRightToLeft(): Boolean
/**
* Returns whether the given row is hidden by a filter (not a filter view).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Rows start at 1
* Logger.log(sheet.isRowHiddenByFilter(1));
* true if the row is hidden, false otherwise.
*/
isRowHiddenByFilter(
rowPosition: number
): Boolean
/**
* Returns whether the given row is hidden by the user.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Rows start at 1
* Logger.log(sheet.isRowHiddenByUser(1));
* true if the row is hidden, false otherwise.
*/
isRowHiddenByUser(
rowPosition: number
): Boolean
/**
* Returns true if the sheet is currently hidden.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* if (sheet.isSheetHidden()) {
* // do something...
* }
* true if the sheet is hidden, false otherwise.
*/
isSheetHidden(): Boolean
/**
* Moves the columns selected by the given range to the position indicated by the destinationIndex. The columnSpec itself does not have to exactly represent an entire
* column or group of columns to move—it selects all columns that the range spans.
*
*
* // The code below moves rows A-B to destination index 5.
* // This results in those columns becoming columns C-D.
* var sheet = SpreadsheetApp.getActiveSheet();
* // Selects column A and column B to be moved.
* var columnSpec = sheet.getRange("A1:B1");
* sheet.moveColumns(columnSpec, 5);
* destinationIndex. The rowSpec itself does not have to exactly represent an entire row
* or group of rows to move—it selects all rows that the range spans.
*
*
* // The code below moves rows 1-2 to destination index 5.
* // This results in those rows becoming rows 3-4.
* var sheet = SpreadsheetApp.getActiveSheet();
* // Selects row 1 and row 2 to be moved.
* var rowSpec = sheet.getRange("A1:A2");
* sheet.moveRows(rowSpec, 5);
* This example shows how to create a new chart: * *
* var sheet = SpreadsheetApp.getActiveSheet();
* var range = sheet.getRange("A1:B8");
* var chartBuilder = sheet.newChart();
* chartBuilder.addRange(range)
* .setChartType(Charts.ChartType.LINE)
* .setPosition(2, 2, 0, 0)
* .setOption('title', 'My Line Chart!');
* sheet.insertChart(chartBuilder.build());
* Protection.removeEditor(emailAddress), Protection.removeEditor(user), Protection.removeEditors(emailAddresses), Protection.addEditor(emailAddress), Protection.addEditor(user), Protection.addEditors(emailAddresses), or setting a new
* value for Protection.setDomainEdit(editable)), the permissions mirror those of the
* spreadsheet itself, which effectively means that the sheet remains unprotected. If the sheet is
* already protected, this method returns an object representing its existing protection settings.
* A protected sheet may include unprotected regions.
*
*
* // Protect the active sheet, then remove all other users from the list of editors.
* var sheet = SpreadsheetApp.getActiveSheet();
* var protection = sheet.protect().setDescription('Sample protected sheet');
*
* // Ensure the current user is an editor before removing others. Otherwise, if the user's edit
* // permission comes from a group, the script throws an exception upon removing the group.
* var me = Session.getEffectiveUser();
* protection.addEditor(me);
* protection.removeEditors(protection.getEditors());
* if (protection.canDomainEdit()) {
* protection.setDomainEdit(false);
* }
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This removes all the embedded charts from the spreadsheet
* var charts = sheet.getCharts();
* for (var i in charts) {
* sheet.removeChart(charts[i]);
* }
* active range in the active sheet, with
* the top left cell in the range as the current cell.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
* var range = sheet.getRange('A1:D4');
* sheet.setActiveRange(range);
*
* var selection = sheet.getSelection();
* // Current cell: A1
* var currentCell = selection.getCurrentCell();
* // Active Range: A1:D4
* var activeRange = selection.getActiveRange();
* active ranges in the
* active sheet. The last range in the list is set as the active range.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['D4', 'B2:C4']);
* sheet.setActiveRangeList(rangeList);
*
* var selection = sheet.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();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:D4");
* sheet.setActiveSelection(range);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* sheet.setActiveSelection("A1:D4");
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* sheet.setColumnGroupControlPosition(SpreadsheetApp.GroupControlTogglePosition.AFTER);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Sets the first column to a width of 200 pixels
* sheet.setColumnWidth(1, 200);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Sets the first three columns to a width of 200 pixels
* sheet.setColumnWidths(1, 3, 200);
*
* // Remove one of the existing conditional format rules.
* var sheet = SpreadsheetApp.getActiveSheet();
* var rules = sheet.getConditionalFormatRules();
* rules.splice(1, 1); // Deletes the 2nd format rule.
* sheet.setConditionalFormatRules(rules);
* current cell.
*
* If the specified cell is present in an already selected range, then that range becomes the * active range with the cell as the current cell. * *
If the specified cell is not present in any selected range, then any existing selection is * removed and the cell becomes the current cell and the active range. * *
Note:The specified Range must consist of one cell, otherwise it throws an
* exception.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
* var cell = sheet.getRange('B5');
* sheet.setCurrentCell(cell);
*
* var selection = sheet.getSelection();
* // Current cell: B5
* var currentCell = selection.getCurrentCell();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Freezes the first column
* sheet.setFrozenColumns(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Freezes the first row
* sheet.setFrozenRows(1);
* true, hide gridlines in this sheet; otherwise show the
* gridlines.
*
* @returns This sheet, for chaining.
*/
setHiddenGridlines(
hideGridlines: Boolean
): SpreadsheetApp.Sheet
/**
* Sets the sheet name.
*
*
* // This example assumes there is a sheet named "first"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var first = ss.getSheetByName("first");
* first.setName("not first anymore");
* true, the sheet layout is set to right-to-left, with cell A1 at
* the top right corner. If false, the sheet layout is set to the default
* left-to-right, with cell A1 at the top left.
*
* @returns This sheet, for chaining.
*/
setRightToLeft(
rightToLeft: Boolean
): SpreadsheetApp.Sheet
/**
* Sets the position of the row group control toggle on the sheet.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
* sheet.setRowGroupControlPosition(SpreadsheetApp.GroupControlTogglePosition.AFTER);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Sets the first row to a height of 200 pixels
* sheet.setRowHeight(1, 200);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Sets the first three rows to a height of 20 pixels
* sheet.setRowHeights(1, 3, 20);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var permissions = sheet.getSheetProtection();
*
* // This copies the permissions on the first sheet to the second sheet
* var sheetToClonePermissionsTo = ss.getSheets()[1];
* sheetToClonePermissionsTo.setSheetProtection(permissions);
*
* // This example assumes there is a sheet named "first"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var first = ss.getSheetByName("first");
* first.setTabColor("ff0000"); // Set the color to red.
* first.setTabColor(null); // Unset the color.
* '#ffffff' or 'white'), or
* null to reset the tab color.
*
* @returns This sheet, for chaining.
*/
setTabColor(
color: string
): SpreadsheetApp.Sheet
/**
* Sets the sheet tab color.
*
*
* // This example assumes there is a sheet named "Sheet1"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var first = ss.getSheetByName("Sheet1");
* var color = SpreadsheetApp.newColor()
* .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
* .build();
* first.setTabColorObject(color); // Set the color to theme accent 1.
* first.setTabColorObject(null); // Unset the color.
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Unhides the first column
* sheet.showColumns(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Unhides the first three columns
* sheet.showColumns(1, 3);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Unhides the first row
* sheet.showRows(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Unhides the first three rows
* sheet.showRows(1, 3);
*
* var sheet = SpreadsheetApp.getActiveSheet();
* sheet.showSheet();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Sorts the sheet by the first column, ascending
* sheet.sort(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Sorts the sheet by the first column, descending
* sheet.sort(1, false);
* true for ascending sorts, false for descending.
*
* @returns the sheet, useful for method chaining
*/
sort(
columnPosition: number,
ascending: Boolean
): SpreadsheetApp.Sheet
/**
* Unhides the column in the given range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This unhides the first column if it was previously hidden
* var range = sheet.getRange("A1");
* sheet.unhideColumn(range);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This unhides the first row if it was previously hidden
* var range = sheet.getRange("A1");
* sheet.unhideRow(range);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This code is going to loop through all the charts and change them to
* // column charts
* var charts = sheet.getCharts();
* for (var i in charts) {
* var chart = charts[i];
* var newChart = chart
* .modify()
* .setChartType(Charts.ChartType.COLUMN)
* .build();
* sheet.updateChart(newChart);
* }
* DataSource.
*/
DATASOURCE = "DATASOURCE",
/**
* A sheet containing a grid. This is the default type.
*/
GRID = "GRID",
/**
* A sheet containing a single embedded object such as an EmbeddedChart.
*/
OBJECT = "OBJECT",
}
class Slicer {
private constructor();
/**
* Returns the background color of the slicer in CSS notation (such as '#ffffff').
*
* @returns The background color of this slicer. Returns null if no color is set.
*/
getBackgroundColor(): string
/**
* Return the background Color of the slicer.
*
* @returns The background color of this slicer. Returns null if no color is set.
*/
getBackgroundColorObject(): SpreadsheetApp.Color
/**
* Returns the column position (relative to the data range of the slicer) on which the filter is
* applied in the slicer, or null if the column position is not set. This should be
* 1-indexed position of the column similar to filter.
*
* @returns The column position of this slicer.
*/
getColumnPosition(): number
/**
* Gets information about where the slicer is positioned in the sheet.
*
* @returns An object containing the slicer's container position.
*/
getContainerInfo(): SpreadsheetApp.ContainerInfo
/**
* Returns the filter criteria of the slicer, or null if the filter criteria is not set.
*
* @returns The filter criteria of this slicer.
*/
getFilterCriteria(): SpreadsheetApp.FilterCriteria
/**
* Gets the data range on which the slicer is applied to.
*
* @returns The slicer range.
*/
getRange(): SpreadsheetApp.Range
/**
* Returns the title of the slicer.
*
* @returns This slicer, for chaining.
*/
getTitle(): string
/**
* Gets the horizontal alignment of the title.
*
* @returns The horizontal alignment of this slicer's title.
*/
getTitleHorizontalAlignment(): string
/**
* Returns the text style of the slicer's title.
*
* @returns The text style of this slicer's title.
*/
getTitleTextStyle(): SpreadsheetApp.TextStyle
/**
* Returns whether the given slicer is applied to pivot tables.
*
* @returns true if this slicer is applied to pivot tables, otherwise false.
*/
isAppliedToPivotTables(): Boolean
/**
* Deletes the slicer.
*/
remove(): void
/**
* Sets if the given slicer should be applied to pivot tables in the worksheet.
*
* @param applyToPivotTables - Specifies whether this slicer should apply to pivot tables.
*
* @returns This slicer, for chaining.
*/
setApplyToPivotTables(
applyToPivotTables: Boolean
): SpreadsheetApp.Slicer
/**
* Sets the background color of the slicer. A null value resets the background color.
*
* @param color - The new background color of this slicer in CSS notation (such as '#ffffff').
*
* @returns This slicer, for chaining.
*/
setBackgroundColor(
color: string
): SpreadsheetApp.Slicer
/**
* Sets the background Color of the slicer. A null value resets the background
* color.
*
* @param color - The new background color of this slicer.
*
* @returns This slicer, for chaining.
*/
setBackgroundColorObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.Slicer
/**
* Sets the column index and filtering criteria of the slicer. A null value resets the
* slicer filter.
*
* @param columnPosition - The new column position of this slicer.
* @param filterCriteria - The new filter criteria of this slicer.
*
* @returns This slicer, for chaining.
*/
setColumnFilterCriteria(
columnPosition: number,
filterCriteria: SpreadsheetApp.FilterCriteria
): SpreadsheetApp.Slicer
/**
* Sets the position where the slicer appears on the sheet. The anchor row and column position
* indices are 1-indexed.
*
* @param anchorRowPos - The slicer's top side is anchored in this row.
* @param anchorColPos - The slicer's top side is anchored in this col.
* @param offsetX - The horizontal offset from cell corner in pixels.
* @param offsetY - The vertical offset from cell corner in pixels.
*
* @returns This slicer, for chaining.
*/
setPosition(
anchorRowPos: number,
anchorColPos: number,
offsetX: number,
offsetY: number
): SpreadsheetApp.Slicer
/**
* Sets the data range on which the slicer is applied.
*
* @param rangeApi - The new range for this slicer.
*
* @returns This slicer, for chaining.
*/
setRange(
rangeApi: SpreadsheetApp.Range
): SpreadsheetApp.Slicer
/**
* Sets the title of the slicer. An empty title resets the title to default value.
*
* @param title - The new title of this slicer.
*
* @returns This slicer, for chaining.
*/
setTitle(
title: string
): SpreadsheetApp.Slicer
/**
* Sets the horizontal alignment of the title in the slicer. A null value resets the
* alignment.
*
* @param horizontalAlignment - The new horizontal alignment of this slicer's title.
*
* @returns This slicer, for chaining.
*/
setTitleHorizontalAlignment(
horizontalAlignment: string
): SpreadsheetApp.Slicer
/**
* Sets the text style of the slicer.
*
* @param textStyle - The new text style of the slicer's title.
*
* @returns This slicer, for chaining.
*/
setTitleTextStyle(
textStyle: SpreadsheetApp.TextStyle
): SpreadsheetApp.Slicer
}
enum SortOrder {
/**
* Ascending sort order.
*/
ASCENDING = "ASCENDING",
/**
* Descending sort order.
*/
DESCENDING = "DESCENDING",
}
class SortSpec {
private constructor();
/**
* Returns the background color used for sorting, or null if absent.
*
* @returns The background color.
*/
getBackgroundColor(): SpreadsheetApp.Color
/**
* Gets the data source column the sort spec acts on. Returns null if this sort spec is
* not acting on a data source column.
*
* @returns The data source column the sort spec acts on.
*/
getDataSourceColumn(): SpreadsheetApp.DataSourceColumn
/**
* Returns the dimension index or null if not linked to a local filter.
*
* @returns The dimension index.
*/
getDimensionIndex(): number
/**
* Returns the foreground color used for sorting, or null if absent.
*
* @returns The foreground color.
*/
getForegroundColor(): SpreadsheetApp.Color
/**
* Returns the sort order.
*
* @returns The sort order.
*/
getSortOrder(): SpreadsheetApp.SortOrder
/**
* Returns whether the sort order is ascending.
*
* @returns true if the sort order is ascending, or false otherwise.
*/
isAscending(): Boolean
}
class Spreadsheet {
private constructor();
/**
* Adds developer metadata with the specified key to the top-level spreadsheet.
*
* @param key - The key for the new developer metadata.
*
* @returns This spreadsheet, for chaining.
*/
addDeveloperMetadata(
key: string
): SpreadsheetApp.Spreadsheet
/**
* Adds developer metadata with the specified key and visibility to the spreadsheet.
*
* @param key - The key for the new developer metadata.
* @param visibility - The visibility of the new developer metadata.
*
* @returns This spreadsheet, for chaining.
*/
addDeveloperMetadata(
key: string,
visibility: SpreadsheetApp.DeveloperMetadataVisibility
): SpreadsheetApp.Spreadsheet
/**
* Adds developer metadata with the specified key and value to the spreadsheet.
*
* @param key - The key for the new developer metadata.
* @param value - The value for the new developer metadata.
*
* @returns This spreadsheet, for chaining.
*/
addDeveloperMetadata(
key: string,
value: string
): SpreadsheetApp.Spreadsheet
/**
* Adds developer metadata with the specified key, value, and visibility to the spreadsheet.
*
* @param key - The key for the new developer metadata.
* @param value - The value for the new developer metadata.
* @param visibility - The visibility of the new developer metadata.
*
* @returns This spreadsheet, for chaining.
*/
addDeveloperMetadata(
key: string,
value: string,
visibility: SpreadsheetApp.DeveloperMetadataVisibility
): SpreadsheetApp.Spreadsheet
/**
* Adds the given user to the list of editors for the Spreadsheet. If the user was already
* on the list of viewers, this method promotes the user out of the list of viewers.
*
* @param emailAddress - The email address of the user to add.
*
* @returns This Spreadsheet, for chaining.
*/
addEditor(
emailAddress: string
): SpreadsheetApp.Spreadsheet
/**
* Adds the given user to the list of editors for the Spreadsheet. If the user was already
* on the list of viewers, this method promotes the user out of the list of viewers.
*
* @param user - A representation of the user to add.
*
* @returns This Spreadsheet, for chaining.
*/
addEditor(
user: User
): SpreadsheetApp.Spreadsheet
/**
* Adds the given array of users to the list of editors for the Spreadsheet. If any of the
* users were already on the list of viewers, this method promotes them out of the list of
* viewers.
*
* @param emailAddresses - An array of email addresses of the users to add.
*
* @returns This Spreadsheet, for chaining.
*/
addEditors(
emailAddresses: string[]
): SpreadsheetApp.Spreadsheet
/**
* Creates a new menu in the Spreadsheet UI.
*
* Each menu entry runs a user-defined function. Usually, you want to call it from the onOpen() function so that the menu is automatically created when the spreadsheet is loaded.
*
*
* // The onOpen function is executed automatically every time a Spreadsheet is loaded
* function onOpen() {
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var menuEntries = [];
* // When the user clicks on "addMenuExample" then "Menu Entry 1", the function function1 is
* // executed.
* menuEntries.push({name: "Menu Entry 1", functionName: "function1"});
* menuEntries.push(null); // line separator
* menuEntries.push({name: "Menu Entry 2", functionName: "function2"});
*
* ss.addMenu("addMenuExample", menuEntries);
* }
* name and functionName
* parameters. You can use functions from included libraries, such as
* Library.libFunction1.
*/
addMenu(
name: string,
subMenus: object[]
): void
/**
* Adds the given user to the list of viewers for the Spreadsheet. If the user was already
* on the list of editors, this method has no effect.
*
* @param emailAddress - The email address of the user to add.
*
* @returns This Spreadsheet, for chaining.
*/
addViewer(
emailAddress: string
): SpreadsheetApp.Spreadsheet
/**
* Adds the given user to the list of viewers for the Spreadsheet. If the user was already
* on the list of editors, this method has no effect.
*
* @param user - A representation of the user to add.
*
* @returns This Spreadsheet, for chaining.
*/
addViewer(
user: User
): SpreadsheetApp.Spreadsheet
/**
* Adds the given array of users to the list of viewers for the Spreadsheet. If any of the
* users were already on the list of editors, this method has no effect for them.
*
* @param emailAddresses - An array of email addresses of the users to add.
*
* @returns This Spreadsheet, for chaining.
*/
addViewers(
emailAddresses: string[]
): SpreadsheetApp.Spreadsheet
/**
* Appends a row to the spreadsheet. This operation is atomic; it prevents issues where a user
* asks for the last row, and then writes to that row, and an intervening mutation occurs between
* getting the last row and writing to it.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Appends a new row with 3 columns to the bottom of the
* // spreadsheet containing the values in the array
* sheet.appendRow(["a man", "a plan", "panama"]);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* sheet.getRange('a1').setValue('Whenever it is a damp, drizzly November in my soul...');
*
* // Sets the first column to a width which fits the text
* sheet.autoResizeColumn(1);
*
* // This code makes a copy of the current spreadsheet and names it appropriately
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* ss.copy("Copy of " + ss.getName());
* DeveloperMetadataFinder for finding developer metadata within the scope of
* this spreadsheet. By default this considers all metadata associated with the spreadsheet,
* sheets, rows, and columns.
*
* @returns A developer metadata finder to search for metadata in the scope of this spreadsheet.
*/
createDeveloperMetadataFinder(): SpreadsheetApp.DeveloperMetadataFinder
/**
* Creates a text finder for the spreadsheet, which can be used to find and replace text within
* the spreadsheet. The search starts from the first sheet of the spreadsheet.
*
*
* var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
*
* // Creates a text finder.
* var textFinder = spreadsheet.createTextFinder('dog');
*
* // Returns the first occurrence of 'dog' in the spreadsheet.
* var firstOccurrence = textFinder.findNext();
*
* // Replaces the last found occurrence of 'dog' with 'cat' and returns the number
* // of occurrences replaced.
* var numOccurrencesReplaced = findOccurrence.replaceWith('cat');
* TextFinder for the spreadsheet.
*/
createTextFinder(
findText: string
): SpreadsheetApp.TextFinder
/**
* Deletes the currently active sheet.
*
*
* // The code below deletes the currently active sheet and stores the new active sheet in a
* // variable
* var newSheet = SpreadsheetApp.getActiveSpreadsheet().deleteActiveSheet();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Columns start at "1" - this deletes the first column
* sheet.deleteColumn(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Columns start at "1" - this deletes the first two columns
* sheet.deleteColumns(1, 2);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Rows start at "1" - this deletes the first row
* sheet.deleteRow(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Rows start at "1" - this deletes the first two rows
* sheet.deleteRows(1, 2);
*
* // The code below deletes the specified sheet.
* var ss = SpreadsheetApp.getActive();
* var sheet = ss.getSheetByName('My Sheet');
* ss.deleteSheet(sheet);
*
* // The code below makes a duplicate of the active sheet
* SpreadsheetApp.getActiveSpreadsheet().duplicateActiveSheet();
* Note: It's preferrable to use getCurrentCell(), which the returns the current
* highlighted cell.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
* // Returns the active cell
* var cell = sheet.getActiveCell();
* null if there is no active range. If
* multiple ranges are selected this method returns only the last selected range.
*
* The term "active range" refers to the range that a user has selected in the active sheet, * but in a custom function it refers to the cell being actively recalculated. * *
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
* var activeRange = sheet.getActiveRange();
* null if there are no active
* ranges.
*
* If there is a single range selected, this behaves as a getActiveRange() call.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* // Returns the list of active ranges.
* var activeRangeList = sheet.getActiveRangeList();
* The active sheet in a spreadsheet is the sheet that is being displayed in the spreadsheet * UI. * *
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
* To view the daily quotas for conversions, see Quotas for Google
* Services. Newly created G Suite domains might be temporarily subject to stricter quotas.
*
* @param contentType - The MIME type to convert to. For most blobs, 'application/pdf' is
* the only valid option. For images in BMP, GIF, JPEG, or PNG format, any of 'image/bmp', 'image/gif', 'image/jpeg', or 'image/png' are also
* valid.
*
* @returns The data as a blob.
*/
getAs(
contentType: string
): Blob
/**
* Returns all the bandings in this spreadsheet.
*
* @returns The bandings in this spreadsheet.
*/
getBandings(): SpreadsheetApp.Banding[]
/**
* Return the data inside this object as a blob.
*
* @returns The data as a blob.
*/
getBlob(): Blob
/**
* Gets the width in pixels of the given column.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Columns start at 1
* Logger.log(sheet.getColumnWidth(1));
* null if there is no current cell. The
* current cell is the cell that has focus in the Google Sheets UI, and is highlighted by a dark
* border. There is never more than one current cell. When a user selects one or more cell ranges,
* one of the cells in the selection is the current cell.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
* // Returns the current highlighted cell in the one of the active ranges.
* var currentCell = sheet.getCurrentCell();
* Range corresponding to the dimensions in which data is present.
*
* This is functionally equivalent to creating a Range bounded by A1 and * (Range.getLastColumn(), Range.getLastRow()). * *
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This represents ALL the data
* var range = sheet.getDataRange();
* var values = range.getValues();
*
* // This logs the spreadsheet in CSV format with a trailing comma
* for (var i = 0; i < values.length; i++) {
* var row = "";
* for (var j = 0; j < values[i].length; j++) {
* if (values[i][j]) {
* row = row + values[i][j];
* }
* row = row + ",";
* }
* Logger.log(row);
* }
* Spreadsheet.
*
* @returns An array of users with edit permission.
*/
getEditors(): User[]
/**
* Returns the URL for the form that sends its responses to this spreadsheet, or null if
* this spreadsheet has no associated form. If multiple forms send responses to this spreadsheet,
* the form URL returned is indeterminate. As an alternative, per sheet form URL associations can
* be retrieved through the Sheet.getFormUrl() method.
*
* @returns The URL for the form that places its responses in this spreadsheet, or null if
* this spreadsheet doesn't have an associated form.
*/
getFormUrl(): string
/**
* Returns the number of frozen columns.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* Logger.log("Number of frozen columns: %s", sheet.getFrozenColumns());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* Logger.log("Number of frozen rows: %s", sheet.getFrozenRows());
*
* // The code below logs the ID for the active spreadsheet.
* Logger.log(SpreadsheetApp.getActiveSpreadsheet().getId());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This logs the value in the very last cell of this sheet
* var lastRow = sheet.getLastRow();
* var lastColumn = sheet.getLastColumn();
* var lastCell = sheet.getRange(lastRow, lastColumn);
* Logger.log(lastCell.getValue());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This logs the value in the very last cell of this sheet
* var lastRow = sheet.getLastRow();
* var lastColumn = sheet.getLastColumn();
* var lastCell = sheet.getRange(lastRow, lastColumn);
* Logger.log(lastCell.getValue());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* Logger.log(ss.getName());
*
* // The code below logs the name of the first named range.
* var namedRanges = SpreadsheetApp.getActiveSpreadsheet().getNamedRanges();
* if (namedRanges.length > 1) {
* Logger.log(namedRanges[0].getName());
* }
*
* // The code below logs the number of sheets in the active spreadsheet.
* Logger.log(SpreadsheetApp.getActiveSpreadsheet().getNumSheets());
* null for a document in a shared drive.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var owner = ss.getOwner();
* Logger.log(owner.getEmail());
* null if the document is in a shared drive.
*/
getOwner(): User
/**
* Returns the list of predefined themes.
*
*
* // The code below returns the list of predefined themes.
* var predefinedThemesList = SpreadsheetApp.getPredefinedSpreadsheetThemes();
*
* // Remove all range protections in the spreadsheet that the user has permission to edit.
* var ss = SpreadsheetApp.getActive();
* var protections = ss.getProtections(SpreadsheetApp.ProtectionType.RANGE);
* for (var i = 0; i < protections.length; i++) {
* var protection = protections[i];
* if (protection.canEdit()) {
* protection.remove();
* }
* }
*
* // Remove all sheet protections in the spreadsheet that the user has permission to edit.
* var ss = SpreadsheetApp.getActive();
* var protections = ss.getProtections(SpreadsheetApp.ProtectionType.SHEET);
* for (var i = 0; i < protections.length; i++) {
* var protection = protections[i];
* if (protection.canEdit()) {
* protection.remove();
* }
* }
* SpreadsheetApp.ProtectionType.RANGE or
* SpreadsheetApp.ProtectionType.SHEET.
*
* @returns An array of objects representing all protected ranges or sheets in the spreadsheet.
*/
getProtections(
type: SpreadsheetApp.ProtectionType
): SpreadsheetApp.Protection[]
/**
* Returns the range as specified in A1 notation or R1C1 notation.
*
*
* // Get a range A1:D4 on sheet titled "Invoices"
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var range = ss.getRange("Invoices!A1:D4");
*
* // Get cell A1 on the first sheet
* var sheet = ss.getSheets()[0];
* var cell = sheet.getRange("A1");
* null if no range with the given name is found. If multiple
* sheets of the spreadsheet use the same range name, specify the sheet name without additional
* quotation marks — for example, getRangeByName('TaxRates') or getRangeByName('Sheet Name!TaxRates'), but not getRangeByName('"Sheet
* Name"!TaxRates').
*
*
* // Log the number of columns for the range named 'TaxRates' in the active spreadsheet.
* var range = SpreadsheetApp.getActiveSpreadsheet().getRangeByName('TaxRates');
* if (range != null) {
* Logger.log(range.getNumColumns());
* }
* RangeList collection representing the ranges in the same sheet specified
* by a non-empty list of A1 notations or R1C1 notations.
*
*
* // Get a list of ranges A1:D4, F1:H4.
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
* var rangeList = sheet.getRangeList(['A1:D4', 'F1:H4']);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Rows start at 1
* Logger.log(sheet.getRowHeight(1));
* Selection in the spreadsheet.
*
*
* var selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
* var currentCell = selection.getCurrentCell();
* If multiple sheets have the same name, the leftmost one is returned. Returns null if
* there is no sheet with the given name.
*
*
* // The code below logs the index of a sheet named "Expenses"
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Expenses");
* if (sheet != null) {
* Logger.log(sheet.getIndex());
* }
* This is an ID for the sheet that is unique to the spreadsheet. The ID is a monotonically
* increasing integer assigned at sheet creation time that is independent of sheet position. This
* is useful in conjunction with methods such as Range.copyFormatToRange(gridId, column, columnEnd, row, rowEnd) that take a gridId parameter rather than a Sheet instance.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* Logger.log(sheet.getSheetId());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* Logger.log(sheet.getSheetName());
* PageProtection
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var permissions = sheet.getSheetProtection();
*
* permissions.setProtected(true);
* permissions.addUser("user@example.com");
*
* // Logs the users that have access to edit this sheet. Note that this
* // is different from access to the entire spreadsheet - getUsers()
* // only returns users if permissions.isProtected() is set to true.
* var users = permissions.getUsers();
* Logger.log(users);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // The two samples below produce the same output
* var values = sheet.getSheetValues(1, 1, 3, 3);
* Logger.log(values);
*
* var range = sheet.getRange(1, 1, 3, 3);
* values = range.getValues();
* Logger.log(values);
*
* // The code below logs the name of the second sheet
* var sheets = SpreadsheetApp.getActiveSpreadsheet().getSheets();
* if (sheets.length > 1) {
* Logger.log(sheets[1].getName());
* }
* null if no theme is applied.
*
*
* // The code below returns the current theme of the spreadsheet.
* var currentTheme = SpreadsheetApp.getSpreadsheetTheme();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* Logger.log(ss.getUrl());
* Spreadsheet.
*
* @returns An array of users with view or comment permission.
*/
getViewers(): User[]
/**
* Hides the columns in the given range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This hides the first column
* var range = sheet.getRange("A1");
* sheet.hideColumn(range);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This hides the first row
* var range = sheet.getRange("A1");
* sheet.hideRow(range);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts a column after the first column position
* sheet.insertColumnAfter(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts a column in the first column position
* sheet.insertColumnBefore(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts a column in the second column position
* sheet.insertColumnsAfter(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts five columns before the first column
* sheet.insertColumnsBefore(1, 5);
* DataSourceSheet in the spreadsheet and starts data execution. As a
* side effect, this also makes the new sheet the active sheet.
*
* Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for specific data source
* type.
*
* @param spec - The data source specification to insert with.
*
* @returns The new data source sheet.
*/
insertDataSourceSheet(
spec: SpreadsheetApp.DataSourceSpec
): SpreadsheetApp.DataSourceSheet
/**
* Inserts a Spreadsheet as an image in the document at a given row and column. The image
* size is retrieved from the blob contents.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var blob = Utilities.newBlob(binaryData, 'image/png', 'MyImageName');
* sheet.insertImage(blob, 1, 1);
* Spreadsheet as an image in the document at a given row and column, with a
* pixel offset. The image size is retrieved from the blob contents.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var blob = Utilities.newBlob(binaryData, 'image/png', 'MyImageName');
* sheet.insertImage(blob, 1, 1, 10, 10);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* sheet.insertImage("https://www.google.com/images/srpr/logo3w.png", 1, 1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* sheet.insertImage("https://www.google.com/images/srpr/logo3w.png", 1, 1, 10, 10);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts a row after the first row position
* sheet.insertRowAfter(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts a row before the first row position
* sheet.insertRowBefore(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts five rows after the first row
* sheet.insertRowsAfter(1, 5);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This inserts five rows before the first row
* sheet.insertRowsBefore(1, 5);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* ss.insertSheet();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* ss.insertSheet(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var templateSheet = ss.getSheetByName('Sales');
* ss.insertSheet(1, {template: templateSheet});
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var templateSheet = ss.getSheetByName('Sales');
* ss.insertSheet({template: templateSheet});
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* ss.insertSheet('My New Sheet');
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* ss.insertSheet('My New Sheet', 1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var templateSheet = ss.getSheetByName('Sales');
* ss.insertSheet('My New Sheet', 1, {template: templateSheet});
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var templateSheet = ss.getSheetByName('Sales');
* ss.insertSheet('My New Sheet', {template: templateSheet});
* DataSourceTable spanning the
* entire sheet with the given data source specification, and starts data execution. As a side
* effect, makes the new sheet the active sheet.
*
* Throws an exception if the data source type is not enabled. Use SpreadsheetApp#enable...Execution() methods to enable data execution for specific data source
* type.
*
* @param spec - The data source specification to insert with.
*
* @returns The new sheet.
*/
insertSheetWithDataSourceTable(
spec: SpreadsheetApp.DataSourceSpec
): SpreadsheetApp.Sheet
/**
* Indicates whether the document allows anonymous viewing. As this is no longer supported in the
* new version of Google Sheets, use
* File.getSharingAccess() and File.getSharingPermission() instead.
*
*
* // Determine if the document allows anonymous viewing via the Drive API.
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var file = DriveApp.getFileById(ss.getId());
* var access = file.getSharingAccess();
* var permission = file.getSharingPermission();
* var isAnonymousAccess =
* access == DriveApp.Access.ANYONE || access == DriveApp.Access.ANYONE_WITH_LINK;
* var isAnonymousEdit = isAnonymousAccess && permission != DriveApp.Permission.NONE;
* true if the document allows anonymous viewing, false otherwise.
*/
isAnonymousView(): Boolean
/**
* Indicates whether the document allows edits from anonymous users. As this is no longer
* supported in the new version of
* Google Sheets, use File.getSharingAccess() and File.getSharingPermission() instead.
*
*
* // Determine if the document allow anonymous edits via the Drive API.
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var file = DriveApp.getFileById(ss.getId());
* var access = file.getSharingAccess();
* var permission = file.getSharingPermission();
* var isAnonymousAccess =
* access == DriveApp.Access.ANYONE || access == DriveApp.Access.ANYONE_WITH_LINK;
* var isAnonymousEdit = isAnonymousAccess && permission == DriveApp.Permission.EDIT;
* true if the document allows anonymous editing, false otherwise.
*/
isAnonymousWrite(): Boolean
/**
* Returns whether the given column is hidden by the user.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Columns start at 1
* Logger.log(sheet.isColumnHiddenByUser(1));
* true if the column is hidden, false otherwise.
*/
isColumnHiddenByUser(
columnPosition: number
): Boolean
/**
* Returns whether iterative calculation is enabled in this spreadsheet.
*
* @returns true if iterative calculation is enabled, false otherwise.
*/
isIterativeCalculationEnabled(): Boolean
/**
* Returns whether the given row is hidden by a filter (not a filter view).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Rows start at 1
* Logger.log(sheet.isRowHiddenByFilter(1));
* true if the row is hidden, false otherwise.
*/
isRowHiddenByFilter(
rowPosition: number
): Boolean
/**
* Returns whether the given row is hidden by the user.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Rows start at 1
* Logger.log(sheet.isRowHiddenByUser(1));
* true if the row is hidden, false otherwise.
*/
isRowHiddenByUser(
rowPosition: number
): Boolean
/**
* Moves the active sheet to the given position in the list of sheets. Throws an exception if the
* position is negative or greater than the number of sheets.
*
*
* // This example assumes there are two sheets in the current
* // active spreadsheet: one named "first", and another named "second",
* // and that the current active sheet (first) is in position 1
* var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = spreadsheet.getSheetByName("first");
*
* // This should output 'Current index of sheet: 1'
* Logger.log("Current index of sheet: %s", sheet.getIndex());
*
* spreadsheet.moveActiveSheet(2);
*
* // This should output 'New index of sheet: 2'
* Logger.log("New index of sheet: %s", sheet.getIndex());
* SheetType.OBJECT sheet and moves the provided chart to it. If the chart
* is already on its own sheet, that sheet is returned without creating a new one.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var chart = sheet.newChart().setPosition(1, 1, 0, 0).build();
* sheet.insertChart(chart);
* var objectSheet = SpreadsheetApp.getActive().moveChartToObjectSheet(chart);
* Use SpreadsheetApp#enable...Execution() methods to enable data execution for
* specific data source type.
*/
refreshAllDataSources(): void
/**
* Removes the given user from the list of editors for the Spreadsheet. This method doesn't
* block users from accessing the Spreadsheet if they belong to a class of users who have
* general access—for example, if the Spreadsheet is shared with the user's entire
* domain, or if the Spreadsheet is in a shared drive that the user can access.
*
*
For Drive files, this also removes the user from the list of viewers.
*
* @param emailAddress - The email address of the user to remove.
*
* @returns This Spreadsheet, for chaining.
*/
removeEditor(
emailAddress: string
): SpreadsheetApp.Spreadsheet
/**
* Removes the given user from the list of editors for the Spreadsheet. This method doesn't
* block users from accessing the Spreadsheet if they belong to a class of users who have
* general access—for example, if the Spreadsheet is shared with the user's entire
* domain, or if the Spreadsheet is in a shared drive that the user can access.
*
*
For Drive files, this also removes the user from the list of viewers.
*
* @param user - A representation of the user to remove.
*
* @returns This Spreadsheet, for chaining.
*/
removeEditor(
user: User
): SpreadsheetApp.Spreadsheet
/**
* Removes a menu that was added by addMenu(name, subMenus). The name argument
* should have the same value as the corresponding call to addMenu(name, subMenus).
*
*
* // The onOpen function is executed automatically every time a Spreadsheet is loaded
* function onOpen() {
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* ss.addMenu("badMenu", [{name: "remove bad menu", functionName: "removeBadMenu"},
* {name: "foo", functionName: "foo"}]);
* }
* function removeBadMenu() {
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* ss.removeMenu("badMenu"); // name must match the name used when added the menu
* }
* function foo(){
* //do nothing
* }
*
* // The code below creates a new named range "foo", and then remove it.
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* ss.setNamedRange("foo", ss.getActiveRange());
* ss.removeNamedRange("foo");
* Spreadsheet. This
* method has no effect if the user is an editor, not a viewer or commenter. This method also
* doesn't block users from accessing the Spreadsheet if they belong to a class of users who
* have general access—for example, if the Spreadsheet is shared with the user's
* entire domain, or if the Spreadsheet is in a shared drive that the user can access.
*
* For Drive files, this also removes the user from the list of editors.
*
* @param emailAddress - The email address of the user to remove.
*
* @returns This Spreadsheet for chaining.
*/
removeViewer(
emailAddress: string
): SpreadsheetApp.Spreadsheet
/**
* Removes the given user from the list of viewers and commenters for the Spreadsheet. This
* method has no effect if the user is an editor, not a viewer. This method also doesn't block
* users from accessing the Spreadsheet if they belong to a class of users who have general
* access—for example, if the Spreadsheet is shared with the user's entire domain, or
* if the Spreadsheet is in a shared drive that the user can access.
*
*
For Drive files, this also removes the user from the list of editors.
*
* @param user - A representation of the user to remove.
*
* @returns This Spreadsheet for chaining.
*/
removeViewer(
user: User
): SpreadsheetApp.Spreadsheet
/**
* Renames the document.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* ss.rename("This is the new name");
*
* // The code below renames the active sheet to "Hello world"
* SpreadsheetApp.getActiveSpreadsheet().renameActiveSheet("Hello world");
*
* // The code below applies default theme on the spreadsheet.
* SpreadsheetApp.resetSpreadsheetTheme();
* active range in the active sheet, with
* the top left cell in the range as the current cell.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
* var range = sheet.getRange('A1:D4');
* sheet.setActiveRange(range);
*
* var selection = sheet.getSelection();
* // Current cell: A1
* var currentCell = selection.getCurrentCell();
* // Active Range: A1:D4
* var activeRange = selection.getActiveRange();
* active ranges in the
* active sheet. The last range in the list is set as the active range.
*
*
* var sheet = SpreadsheetApp.getActiveSheet();
* var rangeList = sheet.getRangeList(['D4', 'B2:C4']);
* sheet.setActiveRangeList(rangeList);
*
* var selection = sheet.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();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var range = sheet.getRange("A1:D4");
* sheet.setActiveSelection(range);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* sheet.setActiveSelection("A1:D4");
*
* // The code below makes the first sheet active in the active spreadsheet.
* var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
* spreadsheet.setActiveSheet(spreadsheet.getSheets()[0]);
*
* 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());
* true, the most recent selection of the new active sheet
* becomes selected again as the new sheet becomes active; if false, the new sheet
* becomes active without changing the current selection.
*
* @returns The new active sheet.
*/
setActiveSheet(
sheet: SpreadsheetApp.Sheet,
restoreSelection: Boolean
): SpreadsheetApp.Sheet
/**
* Sets the document's policy on anonymous reading and writing. As this is no longer supported in
* the new version of Google Sheets,
* use File.setSharing(accessType, permissionType) as an alternative.
*
*
* // Set the document's policy on anonymous reading and writing via the Drive API.
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var file = DriveApp.getFileById(ss.getId());
*
* // Set anonymous read.
* file.setSharing(DriveApi.Access.ANYONE, DriveApi.Permission.VIEW);
*
* // Set anonymous write.
* file.setSharing(DriveApi.Access.ANYONE, DriveApi.Permission.EDIT);
*
* // Disable anonymous access.
* file.setSharing(DriveApi.Access.PRIVATE, file.getSharingPermission());
* true to allow anonymous reads; false otherwise.
* @param anonymousWriteAllowed - true to allow anonymous reads; false otherwise.
*/
setAnonymousAccess(
anonymousReadAllowed: Boolean,
anonymousWriteAllowed: Boolean
): void
/**
* Sets the width of the given column in pixels.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Sets the first column to a width of 200 pixels
* sheet.setColumnWidth(1, 200);
* current cell.
*
* If the specified cell is present in an already selected range, then that range becomes the * active range with the cell as the current cell. * *
If the specified cell is not present in any selected range, then any existing selection is * removed and the cell becomes the current cell and the active range. * *
Note:The specified Range must consist of one cell, otherwise it throws an
* exception.
*
*
* var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
* var cell = sheet.getRange('B5');
* sheet.setCurrentCell(cell);
*
* var selection = sheet.getSelection();
* // Current cell: B5
* var currentCell = selection.getCurrentCell();
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Freezes the first column
* sheet.setFrozenColumns(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Freezes the first row
* sheet.setFrozenRows(1);
* true if iterative calculation should be enabled; false
* otherwise.
*
* @returns This spreadsheet, for chaining.
*/
setIterativeCalculationEnabled(
isEnabled: Boolean
): SpreadsheetApp.Spreadsheet
/**
* Sets the maximum number of calculation iterations that should be performed during iterative
* calculation. This value must be between 1 and 10,000 (inclusive), and defaults to 50.
*
* @param maxIterations - The maximum number of calculation iterations (between 1 and 10,000).
*
* @returns This spreadsheet, for chaining.
*/
setMaxIterativeCalculationCycles(
maxIterations: number
): SpreadsheetApp.Spreadsheet
/**
* Names a range.
*
*
* // The code below creates a new named range "TaxRates" in the active spreadsheet
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* ss.setNamedRange("TaxRates", SpreadsheetApp.getActiveRange());
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Sets the first row to a height of 200 pixels
* sheet.setRowHeight(1, 200);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* var permissions = sheet.getSheetProtection();
*
* // This copies the permissions on the first sheet to the second sheet
* var sheetToClonePermissionsTo = ss.getSheets()[1];
* sheetToClonePermissionsTo.setSheetProtection(permissions);
*
* // The code below sets the second predefined theme as the current theme of the spreadsheet.
* var predefinedThemesList = SpreadsheetApp.getPredefinedSpreadsheetThemes();
* SpreadsheetApp.setSpreadsheetTheme(predefinedThemesList[1]);
* If the server-side script previously displayed a dialog that has not yet been dismissed, * then the existing dialog is replaced with the newly requested dialog's user interface. * *
The following code snippet displays a simple HtmlService application in a dialog with the
* specified title, height, and width:
*
*
* var htmlApp = HtmlService
* .createHtmlOutput('<p>A change of speed, a change of style...</p>')
* .setTitle('My HtmlService Application')
* .setWidth(250)
* .setHeight(300);
*
* SpreadsheetApp.getActiveSpreadsheet().show(htmlApp);
*
* // The script resumes execution immediately after showing the dialog.
* HtmlOutput.
*/
show(
userInterface: object
): void
/**
* Sorts a sheet by column, ascending.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Sorts the sheet by the first column, ascending
* sheet.sort(1);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // Sorts the sheet by the first column, descending
* sheet.sort(1, false);
* true for ascending sorts, false for descending.
*
* @returns the sheet, useful for method chaining
*/
sort(
columnPosition: number,
ascending: Boolean
): SpreadsheetApp.Sheet
/**
* Shows a popup window in the lower right corner of the spreadsheet with the given message.
*
*
* // Show a popup with the message "Task started".
* SpreadsheetApp.getActiveSpreadsheet().toast('Task started');
*
* // Show a popup with the title "Status" and the message "Task started".
* SpreadsheetApp.getActiveSpreadsheet().toast('Task started', 'Status');
*
* // Show a 3-second popup with the title "Status" and the message "Task started".
* SpreadsheetApp.getActiveSpreadsheet().toast('Task started', 'Status', 3);
* null, the toast defaults to 5 seconds;
* if negative, the toast remains until dismissed.
*/
toast(
msg: string,
title: string,
timeoutSeconds: Number
): void
/**
* Unhides the column in the given range.
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This unhides the first column if it was previously hidden
* var range = sheet.getRange("A1");
* sheet.unhideColumn(range);
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var sheet = ss.getSheets()[0];
*
* // This unhides the first row if it was previously hidden
* var range = sheet.getRange("A1");
* sheet.unhideRow(range);
* addMenu(name, subMenus). Works exactly like addMenu(name, subMenus).
*
*
* var ss = SpreadsheetApp.getActiveSpreadsheet();
* var menuEntries = [];
* menuEntries.push({name: "Lone Menu Entry", functionName: "function1"});
* ss.updateMenu("addMenuExample", menuEntries);
* name and functionName
* parameters. You can use functions from included libraries, such as
* Library.libFunction1.
*/
updateMenu(
name: string,
subMenus: object[]
): void
/**
* Waits until all the current executions in the spreadsheet complete, timing out after the
* provided number of seconds. Throws an exception if the executions are not completed when timing
* out, but does not cancel the data executions.
*
* @param timeoutInSeconds - The time to wait for data executions, in seconds. The maximum is 300
* seconds.
*/
waitForAllDataExecutionsCompletion(
timeoutInSeconds: number
): void
}
class SpreadsheetTheme {
private constructor();
/**
* Returns the concrete Color for a valid theme color type. Throws exception if the theme
* color type is not set in the current theme.
*
* @param themeColorType - Theme color type.
*
* @returns Concrete color.
*/
getConcreteColor(
themeColorType: SpreadsheetApp.ThemeColorType
): SpreadsheetApp.Color
/**
* Returns the font family of the theme, or null if it's a null theme.
*
* @returns The theme font family.
*/
getFontFamily(): string
/**
* Returns a list of all possible theme color types for the current theme.
*
* @returns A list of theme colors.
*/
getThemeColors(): SpreadsheetApp.ThemeColorType[]
/**
* Sets the concrete color associated with the ThemeColorType in this color scheme to the
* given color in RGB format.
*
* @param themeColorType - The theme color type.
* @param red - The value of red channel.
* @param green - The value of green channel.
* @param blue - The value of blue channel.
*
* @returns The theme, for chaining.
*/
setConcreteColor(
themeColorType: SpreadsheetApp.ThemeColorType,
red: number,
green: number,
blue: number
): SpreadsheetApp.SpreadsheetTheme
/**
* Sets the concrete color associated with the ThemeColorType in this color scheme to the
* given color.
*
* @param themeColorType - The theme color type.
* @param color - The color.
*
* @returns The theme, for chaining.
*/
setConcreteColor(
themeColorType: SpreadsheetApp.ThemeColorType,
color: SpreadsheetApp.Color
): SpreadsheetApp.SpreadsheetTheme
/**
* Sets the font family for the theme.
*
* @param fontFamily - The new theme font family.
*
* @returns This theme, for chaining.
*/
setFontFamily(
fontFamily: string
): SpreadsheetApp.SpreadsheetTheme
}
enum TextDirection {
/**
* Left-to-right text direction.
*/
LEFT_TO_RIGHT = "LEFT_TO_RIGHT",
/**
* Right-to-left text direction.
*/
RIGHT_TO_LEFT = "RIGHT_TO_LEFT",
}
class TextFinder {
private constructor();
/**
* Returns all cells matching the search criteria.
*
* @returns all the matching cells
*/
findAll(): SpreadsheetApp.Range[]
/**
* Returns the next cell matching the search criteria.
*
* @returns the next matching cell, or {code null} if there are no previous matches
*/
findNext(): SpreadsheetApp.Range
/**
* Returns the previous cell matching the search criteria.
*
* @returns the previous matching cell, or {code null} if there are no previous matches
*/
findPrevious(): SpreadsheetApp.Range
/**
* Returns the current cell matching the search criteria.
*
* @returns the current matching cell, or {code null} if there are no further matches
*/
getCurrentMatch(): SpreadsheetApp.Range
/**
* If true, configures the search to ignore diacritics while matching; otherwise the
* search matches diacritics. A diacritic is a sign, such as an accent or cedilla, which when
* written above or below a letter indicates a difference in pronunciation from the same letter
* when unmarked or differently marked.
*
* @param ignoreDiacritics - Whether the search considers diacritics.
*
* @returns this text finder, for chaining
*/
ignoreDiacritics(
ignoreDiacritics: Boolean
): SpreadsheetApp.TextFinder
/**
* If true, configures the search to match the search text's case exactly, otherwise the
* search defaults to case-insensitive matching.
*
* @param matchCase - Whether the matching is case-sensitive.
*
* @returns this text finder, for chaining
*/
matchCase(
matchCase: Boolean
): SpreadsheetApp.TextFinder
/**
* If true, configures the search to match the entire contents of a cell; otherwise, the
* search defaults to partial matching.
*
* @param matchEntireCell - Whether the entire cell is matched.
*
* @returns this text finder, for chaining
*/
matchEntireCell(
matchEntireCell: Boolean
): SpreadsheetApp.TextFinder
/**
* If true, configures the search to return matches that appear within formula text;
* otherwise cells with formulas are considered based on their displayed value.
*
* @param matchFormulaText - Whether the search examines formula text.
*
* @returns this text finder, for chaining
*/
matchFormulaText(
matchFormulaText: Boolean
): SpreadsheetApp.TextFinder
/**
* Replaces all matches with the specified text. Returns the number of occurrences replaced, which
* may be different from the number of matched cells.
*
* @param replaceText - The text that replaces the text in the matched cells.
*
* @returns the number of occurrences replaced
*/
replaceAllWith(
replaceText: string
): number
/**
* Replaces the search text in the currently matched cell with the specified text and returns the
* number of occurrences replaced.
*
* @param replaceText - The text that replaces the content in the currently matched cell.
*
* @returns the number of occurrences replaced
*/
replaceWith(
replaceText: string
): number
/**
* Configures the search to start searching immediately after the specified cell range.
*
* @param startRange - The cell range after which the search should start.
*
* @returns this text finder, for chaining
*/
startFrom(
startRange: SpreadsheetApp.Range
): SpreadsheetApp.TextFinder
/**
* If true, configures the search to interpret the search string as a regular expression;
* otherwise the search interprets the search string as normal text. For more details on how to
* use regular expressions, refer to the
* Find and replace support page.
*
* @param useRegEx - Whether to interpret the search string as a regular expression.
*
* @returns this text finder, for chaining
*/
useRegularExpression(
useRegEx: Boolean
): SpreadsheetApp.TextFinder
}
class TextRotation {
private constructor();
/**
* Gets the angle between standard text orientation and the current text orientation. For
* left-to-right text, positive angles are in the counterclockwise direction. If the text is set
* to stack vertically, this method returns 0.
*
* @returns The degrees between standard text rotation and the current text rotation.
*/
getDegrees(): number
/**
* Returns true if the text is stacked vertically; returns false otherwise.
*
* @returns Whether or not the text is stacked vertically.
*/
isVertical(): Boolean
}
class TextStyle {
private constructor();
/**
* Creates a text style builder initialized with the values of this text style.
*
* @returns A builder from this text style.
*/
copy(): SpreadsheetApp.TextStyleBuilder
/**
* Gets the font family of the text. Returns null if the font family isn't set or the
* corresponding RichTextValue has multiple runs with different font
* families.
*
* @returns The font family of the text (for example, "Arial") or null.
*/
getFontFamily(): string
/**
* Gets the font size of the text in points. Returns null if the font size isn't set or
* the corresponding RichTextValue has multiple runs with different font
* sizes.
*
* @returns The font size of the text or null.
*/
getFontSize(): number
/**
* Gets the font color of the text. Returns null if the font color isn't set or the
* corresponding RichTextValue has multiple runs with different font
* colors.
*
* @returns The font color of the text as a hex CSS value (for example, "#ff0000") or null.
*/
getForegroundColor(): string
/**
* Gets the font color of the text. Returns null if the font color isn't set or the
* corresponding RichTextValue has multiple runs with different font
* colors.
*
* @returns The font color of the text or null.
*/
getForegroundColorObject(): SpreadsheetApp.Color
/**
* Gets whether or not the text is bold. Returns null if bold isn't set or the
* corresponding RichTextValue has multiple runs with different bold
* settings.
*
* @returns Whether or not the cell is bold, or null.
*/
isBold(): Boolean
/**
* Gets whether or not the cell is italic. Returns null if italic isn't set or the
* corresponding RichTextValue has multiple runs with different italic
* settings.
*
* @returns Whether or not the cell is italic, or null.
*/
isItalic(): Boolean
/**
* Gets whether or not the cell has strikethrough. Returns null if strikethrough isn't set
* or the corresponding RichTextValue has multiple runs with different
* strikethrough settings.
*
* @returns Whether or not the cell has strikethrough, or null.
*/
isStrikethrough(): Boolean
/**
* Gets whether or not the cell is underlined. Returns null if underline isn't set or the
* corresponding RichTextValue has multiple runs with different underline
* settings.
*
* @returns Whether or not the cell is underlined, or null.
*/
isUnderline(): Boolean
}
class TextStyleBuilder {
private constructor();
/**
* Creates a text style from this builder.
*
* @returns A text style created from this builder.
*/
build(): SpreadsheetApp.TextStyle
/**
* Sets whether or not the text is bold.
*
* @param bold - Whether or not the text is bold.
*
* @returns The builder for chaining.
*/
setBold(
bold: Boolean
): SpreadsheetApp.TextStyleBuilder
/**
* Sets the text font family, such as "Arial".
*
* @param fontFamily - The desired font family.
*
* @returns The builder for chaining.
*/
setFontFamily(
fontFamily: string
): SpreadsheetApp.TextStyleBuilder
/**
* Sets the text font size in points.
*
* @param fontSize - The desired font size.
*
* @returns The builder for chaining.
*/
setFontSize(
fontSize: number
): SpreadsheetApp.TextStyleBuilder
/**
* Sets the text font color.
*
* @param cssString - The desired font color in CSS notation (such as '#ffffff' or 'white').
*
* @returns The builder for chaining.
*/
setForegroundColor(
cssString: string
): SpreadsheetApp.TextStyleBuilder
/**
* Sets the text font color.
*
* @param color - The desired font color.
*
* @returns The builder for chaining.
*/
setForegroundColorObject(
color: SpreadsheetApp.Color
): SpreadsheetApp.TextStyleBuilder
/**
* Sets whether or not the text is italic.
*
* @param italic - Whether or not the text is italic.
*
* @returns The builder for chaining.
*/
setItalic(
italic: Boolean
): SpreadsheetApp.TextStyleBuilder
/**
* Sets whether or not the text has strikethrough.
*
* @param strikethrough - Whether or not the text has strikethrough.
*
* @returns The builder for chaining.
*/
setStrikethrough(
strikethrough: Boolean
): SpreadsheetApp.TextStyleBuilder
/**
* Sets whether or not the text is underlined.
*
* @param underline - Whether or not the text is underlined.
*
* @returns The builder for chaining.
*/
setUnderline(
underline: Boolean
): SpreadsheetApp.TextStyleBuilder
}
enum TextToColumnsDelimiter {
/**
* "," delimiter.
*/
COMMA = "COMMA",
/**
* "." delimiter.
*/
PERIOD = "PERIOD",
/**
* ";" delimiter.
*/
SEMICOLON = "SEMICOLON",
/**
* " " delimiter.
*/
SPACE = "SPACE",
}
class ThemeColor {
private constructor();
/**
* Get the type of this color.
*
* @returns The color type.
*/
getColorType(): ColorType
/**
* Gets the theme color type of this color.
*
* @returns The theme color type.
*/
getThemeColorType(): SpreadsheetApp.ThemeColorType
}
enum ThemeColorType {
/**
* Represents the first accent color.
*/
ACCENT1 = "ACCENT1",
/**
* Represents the second accent color.
*/
ACCENT2 = "ACCENT2",
/**
* Represents the third accent color.
*/
ACCENT3 = "ACCENT3",
/**
* Represents the fourth accent color.
*/
ACCENT4 = "ACCENT4",
/**
* Represents the fifth accent color.
*/
ACCENT5 = "ACCENT5",
/**
* Represents the sixth accent color.
*/
ACCENT6 = "ACCENT6",
/**
* Represents the color to use for chart's background.
*/
BACKGROUND = "BACKGROUND",
/**
* Represents the color to use for hyperlinks.
*/
HYPERLINK = "HYPERLINK",
/**
* Represents the text color.
*/
TEXT = "TEXT",
/**
* Represents a theme color that is not supported.
*/
UNSUPPORTED = "UNSUPPORTED",
}
enum WrapStrategy {
/**
* Clip lines that are longer than the cell width.
*/
CLIP = "CLIP",
/**
* Overflow lines into the next cell, so long as that cell is empty. If the next cell over is
* non-empty, this behaves the same as CLIP.
*/
OVERFLOW = "OVERFLOW",
/**
* Wrap lines that are longer than the cell width onto a new line. Single words that are longer
* than a line are wrapped at the character level.
*/
WRAP = "WRAP",
}
class Border {
private constructor();
/**
* Returns the style of this border or null if the border does not contains a border
* style.
*
* @returns The border style.
*/
getBorderStyle(): SpreadsheetApp.BorderStyle
/**
* Returns the color of this border or null if the color is not specified in this border.
*
* @returns The border color.
*/
getColor(): SpreadsheetApp.Color
}
class Borders {
private constructor();
/**
* Returns the bottom border.
*
* @returns The bottom border.
*/
getBottom(): SpreadsheetApp.Border
/**
* Returns the left border.
*
* @returns The left border.
*/
getLeft(): SpreadsheetApp.Border
/**
* Returns the right border.
*
* @returns The right border.
*/
getRight(): SpreadsheetApp.Border
/**
* Returns the top border.
*
* @returns The top border.
*/
getTop(): SpreadsheetApp.Border
}
}