class sheet

Google Apps Script

more_vert

Class Sheet

Access and modify spreadsheet sheets. Common operations are renaming a sheet and accessing range objects from the sheet.

Methods

MethodReturn typeBrief description

activate()

Sheet

Activates this sheet.

appendRow(rowContents)

Sheet

Appends a row to the spreadsheet.

autoResizeColumn(columnPosition)

Sheet

Sets the width of the given column to fit its contents

clear()

Sheet

Clears the sheet of content and formatting information.

clear(options)

Sheet

Clears the sheet of contents and/or format, as specified with the given advanced options.

clearContents()

Sheet

Clears the sheet of contents, while preserving formatting information.

clearFormats()

Sheet

Clears the sheet of formatting, while preserving contents.

clearNotes()

Sheet

Clears the sheet of all notes.

copyTo(spreadsheet)

Sheet

Copies the sheet to a given spreadsheet, which can be the same spreadsheet as the source.

deleteColumn(columnPosition)

Sheet

Deletes the column at the given column position.

deleteColumns(columnPosition,howMany)

void

Deletes a number of columns starting at the given column position.

deleteRow(rowPosition)

Sheet

Deletes the row at the given row position.

deleteRows(rowPosition,howMany)

void

Deletes a number of rows starting at the given row position.

getActiveCell()

Range

Returns the active cell in this sheet.

getActiveRange()

Range

Returns the active range for the active sheet.

getCharts()

EmbeddedChart[]

Returns an array of charts on this sheet.

getColumnWidth(columnPosition)

Integer

Gets the width in pixels of the given column.

getDataRange()

Range

Returns a Range corresponding to the dimensions in which data is present.

getFormUrl()

String

Returns the URL for the form that sends its responses to this sheet, or null if this sheet has no associated form.

getFrozenColumns()

Integer

Returns the number of frozen columns.

getFrozenRows()

Integer

Returns the number of frozen rows.

getIndex()

Integer

Gets the position of the sheet in its parent spreadsheet.

getLastColumn()

Integer

Returns the position of the last column that has content.

getLastRow()

Integer

Returns the position of the last row that has content.

getMaxColumns()

Integer

Returns the current number of columns in the sheet, regardless of content.

getMaxRows()

Integer

Returns the current number of rows in the sheet, regardless of content.

getName()

String

Returns the name of the sheet.

getNamedRanges()

NamedRange[]

Gets all the named ranges in this sheet.

getParent()

Spreadsheet

Returns the Spreadsheet that contains this sheet.

getProtections(type)

Protection[]

Gets an array of objects representing all protected ranges in the sheet, or a single-element array representing the protection on the sheet itself.

getRange(row, column)

Range

Returns the range with the top left cell at the given coordinates.

getRange(row, column, numRows)

Range

Returns the range with the top left cell at the given coordinates, and with the given number of rows.

getRange(row, column, numRows,numColumns)

Range

Returns the range with the top left cell at the given coordinates with the given number of rows and columns.

getRange(a1Notation)

Range

Returns the range as specified in A1 notation or R1C1 notation.

getRowHeight(rowPosition)

Integer

Gets the height in pixels of the given row.

getSheetId()

Integer

Returns the ID of the sheet represented by this object.

getSheetName()

String

Returns the sheet name.

getSheetValues(startRow,startColumn, numRows,numColumns)

Object[][]

Returns the rectangular grid of values for this range starting at the given coordinates.

getTabColor()

String

Gets the sheet tab color, or null if the sheet tab has no color.

hideColumn(column)

void

Hides the columns in the given range.

hideColumns(columnIndex)

void

Hides the column at the given index.

hideColumns(columnIndex,numColumns)

void

Hides one or more consecutive columns starting at the given index.

hideRow(row)

void

Hides the rows in the given range.

hideRows(rowIndex)

void

Hides the row at the given index.

hideRows(rowIndex, numRows)

void

Hides one or more consecutive rows starting at the given index.

hideSheet()

Sheet

Hides this sheet.

insertChart(chart)

void

Adds a new chart to this sheet.

insertColumnAfter(afterPosition)

Sheet

Inserts a column after the given column position.

insertColumnBefore(beforePosition)

Sheet

Inserts a column before the given column position.

insertColumns(columnIndex)

void

Inserts a blank column in a sheet at the specified location.

insertColumns(columnIndex,numColumns)

void

Inserts one or more consecutive blank columns in a sheet starting at the specified location.

insertColumnsAfter(afterPosition, howMany)

Sheet

Inserts a number of columns after the given column position.

insertColumnsBefore(beforePosition, howMany)

Sheet

Inserts a number of columns before the given column position.

insertImage(blob, column, row)

void

Inserts a Blob as an image in the document at a given row and column.

insertImage(blob, column, row,offsetX, offsetY)

void

Inserts a Blob as an image in the document at a given row and column, with a pixel offset.

insertImage(url, column, row)

void

Inserts an image in the document at a given row and column.

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

void

Inserts an image in the document at a given row and column, with a pixel offset.

insertRowAfter(afterPosition)

Sheet

Inserts a row after the given row position.

insertRowBefore(beforePosition)

Sheet

Inserts a row before the given row position.

insertRows(rowIndex)

void

Inserts a blank row in a sheet at the specified location.

insertRows(rowIndex, numRows)

void

Inserts one or more consecutive blank rows in a sheet starting at the specified location.

insertRowsAfter(afterPosition,howMany)

Sheet

Inserts a number of rows after the given row position.

insertRowsBefore(beforePosition, howMany)

Sheet

Inserts a number of rows before the given row position.

isSheetHidden()

Boolean

Returns true if the sheet is currently hidden.

moveColumns(columnSpec,destinationIndex)

void

Moves the columns selected by the given range to the position indicated by the destinationIndex.

moveRows(rowSpec,destinationIndex)

void

Moves the rows selected by the given range to the position indicated by the destinationIndex.

newChart()

EmbeddedChartBuilder

Returns a builder to create a new chart for this sheet.

protect()

Protection

Creates an object that can protect the sheet from being edited except by users who have permission.

removeChart(chart)

void

Removes a chart from the parent sheet.

setActiveRange(range)

Range

Sets the active range for the active sheet.

setActiveSelection(range)

Range

Sets the active selection region for this sheet.

setActiveSelection(a1Notation)

Range

Sets the active selection, as specified in A1 notation or R1C1 notation.

setColumnWidth(columnPosition,width)

Sheet

Sets the width of the given column in pixels.

setFrozenColumns(columns)

void

Freezes the given number of columns.

setFrozenRows(rows)

void

Freezes the given number of rows.

setName(name)

Sheet

Sets the sheet name.

setRowHeight(rowPosition,height)

Sheet

Sets the row height of the given row in pixels.

setTabColor(color)

Sheet

Sets the sheet tab color.

showColumns(columnIndex)

void

Unhides the column at the given index.

showColumns(columnIndex,numColumns)

void

Unhides one or more consecutive columns starting at the given index.

showRows(rowIndex)

void

Unhides the row at the given index.

showRows(rowIndex, numRows)

void

Unhides one or more consecutive rows starting at the given index.

showSheet()

Sheet

Makes the sheet visible.

sort(columnPosition)

Sheet

Sorts a sheet by column, ascending.

sort(columnPosition,ascending)

Sheet

Sorts a sheet by column.

unhideColumn(column)

void

Unhides the column in the given range.

unhideRow(row)

void

Unhides the row in the given range.

updateChart(chart)

void

Updates the chart on this sheet.

▸

Deprecated methods

Detailed documentation

activate()

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();

Return

Sheet — the newly active sheet

appendRow(rowContents)

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"]);

Parameters

NameTypeDescription

rowContents

Object[]

an array of values to insert after the last row in the sheet

Return

Sheet — the sheet, useful for method chaining

autoResizeColumn(columnPosition)

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

Parameters

NameTypeDescription

columnPosition

Integer

the position of the given column to resize

Return

Sheet — the sheet, useful for method chaining

clear()

Clears the sheet of content and formatting information.

 // This example assumes there is a sheet named "first"

 var ss = SpreadsheetApp.getActiveSpreadsheet();

 var first = ss.getSheetByName("first");

 first.clear();

Return

Sheet — the cleared sheet

clear(options)

Clears the sheet of contents and/or format, as specified with the given advanced options.

The advanced options are:

contentsOnly
formatOnly

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 sheet.clear({ formatOnly: true, contentsOnly: true });

Parameters

NameTypeDescription

options

Object

a JavaScript map containing advanced options

Return

Sheet — the sheet for chaining

clearContents()

Clears the sheet of contents, while preserving formatting information.

 // This example assumes there is a sheet named "first"

 var ss = SpreadsheetApp.getActiveSpreadsheet();

 var first = ss.getSheetByName("first");

 first.clearContents();

Return

Sheet — the sheet for chaining

clearFormats()

Clears the sheet of formatting, while preserving contents.

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();

Return

Sheet — the sheet for chaining

clearNotes()

Clears the sheet of all notes.

 // This example assumes there is a sheet named "first"

 var ss = SpreadsheetApp.getActiveSpreadsheet();

 var first = ss.getSheetByName("first");

 first.clearNotes();

Return

Sheet — the sheet for chaining

copyTo(spreadsheet)

Copies the sheet to a given spreadsheet, which can be the same spreadsheet as the source. The copied sheet is named "Copy of [original name]".

 var source = SpreadsheetApp.getActiveSpreadsheet();

 var sheet = source.getSheets()[0];

 var destination = SpreadsheetApp.openById('ID_GOES HERE');

 sheet.copyTo(destination);

Parameters

NameTypeDescription

spreadsheet

Spreadsheet

the spreadsheet to copy this sheet to, which can be the same spreadsheet as the source

Return

Sheet — the new sheet for chaining

deleteColumn(columnPosition)

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

Parameters

NameTypeDescription

columnPosition

Integer

the position of the column, starting at 1 for the first column

Return

Sheet — the sheet, useful for method chaining

deleteColumns(columnPosition, howMany)

Deletes a number of columns starting at the given column position.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Columns start at "1" - this deletes the first two columns

 sheet.deleteColumns(1, 2);

Parameters

NameTypeDescription

columnPosition

Integer

the position of the first column to delete

howMany

Integer

the number of columns to delete

deleteRow(rowPosition)

Deletes the row at the given row position.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Rows start at "1" - this deletes the first row

 sheet.deleteRow(1);

Parameters

NameTypeDescription

rowPosition

Integer

the position of the row, starting at 1 for the first row

Return

Sheet — the sheet, useful for method chaining

deleteRows(rowPosition, howMany)

Deletes a number of rows starting at the given row position.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Rows start at "1" - this deletes the first two rows

 sheet.deleteRows(1, 2);

Parameters

NameTypeDescription

rowPosition

Integer

the position of the first row to delete

howMany

Integer

the number of rows to delete

getActiveCell()

Returns the active cell in this sheet.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Returns the active cell

 var cell = sheet.getActiveCell();

Return

Range — the current active cell

getActiveRange()

Returns the active range for the active sheet.

Returns the range of cells that is currently considered active. 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.

Note that when called on a SpreadsheetApp it effectively calls getActiveSpreadsheet and then getActiveSheet to act on the active Sheet.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Returns the active range

 var range = sheet.getActiveRange();

Return

Range — the active range

getCharts()

Returns an array of charts on this sheet.

 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

Return

EmbeddedChart[] — an array of charts

getColumnWidth(columnPosition)

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

Parameters

NameTypeDescription

columnPosition

Integer

the position of the column to examine

Return

Integer — column width in pixels

getDataRange()

Returns a 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);

Return

Range — a range consisting of all the data in the spreadsheet

getFormUrl()

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();

Return

String — the URL for the form that places its responses in this sheet, or null if this sheet doesn't have an associated form.

getFrozenColumns()

Returns the number of frozen columns.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

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

Return

Integer — the number of frozen columns

getFrozenRows()

Returns the number of frozen rows.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

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

Return

Integer — the number of frozen rows

getIndex()

Gets the position of the sheet in its parent spreadsheet. Starts at 1.

 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());

Return

Integer — the position of the sheet in its parent spreadsheet

getLastColumn()

Returns the position of the last column that has content.

 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());

Return

Integer — the last column of the sheet that contains content

getLastRow()

Returns the position of the last row that has content.

 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());

Return

Integer — the last row of the sheet that contains content

getMaxColumns()

Returns the current number of columns in the sheet, regardless of content.

 // This example assumes there is a sheet named "first"

 var ss = SpreadsheetApp.getActiveSpreadsheet();

 var first = ss.getSheetByName("first");

 Logger.log(first.getMaxColumns());

Return

Integer — the maximum width of the sheet

getMaxRows()

Returns the current number of rows in the sheet, regardless of content.

 // This example assumes there is a sheet named "first"

 var ss = SpreadsheetApp.getActiveSpreadsheet();

 var first = ss.getSheetByName("first");

 Logger.log(first.getMaxRows());

Return

Integer — the maximum height of the sheet

getName()

Returns the name of the sheet.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 Logger.log(sheet.getName());

Return

String — the name of the sheet

getNamedRanges()

Gets all the named ranges in this sheet.

 // 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());

Return

NamedRange[] — an array of all the named ranges in the sheet

getParent()

Returns the Spreadsheet that contains this sheet.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // parent is identical to ss

 var parent = sheet.getParent();

Return

Spreadsheet — the parent spreadsheet

getProtections(type)

Gets an array of objects representing all protected ranges in the sheet, or a single-element array representing the protection on the sheet itself.

 // 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();

Parameters

NameTypeDescription

type

ProtectionType

the type of protected area, either SpreadsheetApp.ProtectionType.RANGE or SpreadsheetApp.ProtectionType.SHEET

Return

Protection[] — an array of objects representing all protected ranges in the sheet, or a single-element array representing the protection on the sheet itself

getRange(row, column)

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]);

Parameters

NameTypeDescription

row

Integer

the row of the cell to return

column

Integer

the column of the cell to return

Return

Range — a Range containing only this cell

getRange(row, column, numRows)

Returns the range with the top left cell at the given coordinates, and with the given number of rows.

 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]);

Parameters

NameTypeDescription

row

Integer

the starting row of the range

column

Integer

the column of the range

numRows

Integer

the number of rows to return

Return

Range — a Range containing a single column of data with the number of rows specified

getRange(row, column, numRows, numColumns)

Returns the range with the top left cell at the given coordinates with the given number of rows and columns.

 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]);

Parameters

NameTypeDescription

row

Integer

the starting row of the range

column

Integer

the starting column of the range

numRows

Integer

the number of rows to return

numColumns

Integer

the number of columns to return

Return

Range — a Range corresponding to the area specified

getRange(a1Notation)

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");

Parameters

NameTypeDescription

a1Notation

String

the range to return, as specified in A1 notation or R1C1 notation

Return

Range — the range at the location designated

getRowHeight(rowPosition)

Gets the height in pixels of the given row.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Rows start at 1

 Logger.log(sheet.getRowHeight(1));

Parameters

NameTypeDescription

rowPosition

Integer

the *position* of the row to examine

Return

Integer — row height in pixels

getSheetId()

Returns the ID of the sheet represented by this object.

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());

Return

Integer — an ID for the sheet unique to the spreadsheet

getSheetName()

Returns the sheet name.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 Logger.log(sheet.getSheetName());

Return

String — the name of the sheet

getSheetValues(startRow, startColumn, numRows, numColumns)

Returns the rectangular grid of values for this range starting at the given coordinates. A -1 value given as the row or column position is equivalent to getting the very last row or column that has data in the sheet.

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

Parameters

NameTypeDescription

startRow

Integer

the position of the starting row

startColumn

Integer

the position of the starting column

numRows

Integer

the number of rows to return values for

numColumns

Integer

the number of columns to return values for

Return

Object[][] — a two dimension array of values

getTabColor()

Gets the sheet tab color, or 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();

Return

String — color code in CSS notation (like '#ffffff')

hideColumn(column)

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

Parameters

NameTypeDescription

column

Range

the column range to hide

hideColumns(columnIndex)

Hides the column at the given index.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Hides the first column

 sheet.hideColumns(1);

Parameters

NameTypeDescription

columnIndex

Integer

the index of the column to hide

hideColumns(columnIndex, numColumns)

Hides one or more consecutive columns starting at the given index.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Hides the first three columns

 sheet.hideColumns(1, 3);

Parameters

NameTypeDescription

columnIndex

Integer

the starting index of the columns to hide

numColumns

Integer

the number of columns to hide

hideRow(row)

Hides the rows in the given range.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // This hides the first row

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

 sheet.hideRow(range);

Parameters

NameTypeDescription

row

Range

the row range to hide

hideRows(rowIndex)

Hides the row at the given index.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Hides the first row

 sheet.hideRows(1);

Parameters

NameTypeDescription

rowIndex

Integer

the index of the row to hide

hideRows(rowIndex, numRows)

Hides one or more consecutive rows starting at the given index.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Hides the first three rows

 sheet.hideRows(1, 3);

Parameters

NameTypeDescription

rowIndex

Integer

the starting index of the rows to hide

numRows

Integer

the number of rows to hide

hideSheet()

Hides this sheet. Has no effect if the sheet is already hidden. If this method is called on the only visible sheet, it throws an exception.

 var sheet = SpreadsheetApp.getActiveSheet();

 sheet.hideSheet();

Return

Sheet — the current sheet

insertChart(chart)

Adds a new chart to this sheet.

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

Parameters

NameTypeDescription

chart

EmbeddedChart

the chart to insert

insertColumnAfter(afterPosition)

Inserts a column after the given column position.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // This inserts a column after the first column position

 sheet.insertColumnAfter(1);

Parameters

NameTypeDescription

afterPosition

Integer

the column after which the new column should be added

Return

Sheet — the sheet, useful for method chaining

insertColumnBefore(beforePosition)

Inserts a column before the given column position.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // This inserts a column in the first column position

 sheet.insertColumnBefore(1);

Parameters

NameTypeDescription

beforePosition

Integer

the column before which the new column should be added

Return

Sheet — the sheet, useful for method chaining

insertColumns(columnIndex)

Inserts a blank column in a sheet at the specified location.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Shifts all columns by one

 sheet.insertColumns(1);

Parameters

NameTypeDescription

columnIndex

Integer

the index to insert a column

insertColumns(columnIndex, numColumns)

Inserts one or more consecutive blank columns in a sheet starting at the specified location.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Shifts all columns by three

 sheet.insertColumns(1, 3);

Parameters

NameTypeDescription

columnIndex

Integer

the index to insert a column

numColumns

Integer

the number of columns to insert

insertColumnsAfter(afterPosition, howMany)

Inserts a number of columns after the given column position.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // This inserts a column in the second column position

 sheet.insertColumnsAfter(1);

Parameters

NameTypeDescription

afterPosition

Integer

the column after which the new column should be added

howMany

Integer

the number of columns to insert

Return

Sheet — the sheet, useful for method chaining

insertColumnsBefore(beforePosition, howMany)

Inserts a number of columns before the given column position.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // This inserts five columns before the first column

 sheet.insertColumnsBefore(1, 5);

Parameters

NameTypeDescription

beforePosition

Integer

the column before which the new column should be added

howMany

Integer

the number of columns to insert

Return

Sheet — the sheet, useful for method chaining

insertImage(blob, column, row)

Inserts a Blob 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);

Parameters

NameTypeDescription

blob

Blob

blob containing the image contents, MIME type and, optionally, a name

column

Integer

the column position

row

Integer

the row position

insertImage(blob, column, row, offsetX, offsetY)

Inserts a Blob 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);

Parameters

NameTypeDescription

blob

Blob

blob containing the image contents, MIME type and, optionally, a name

column

Integer

the column position

row

Integer

the row position

offsetX

Integer

horizontal offset from cell corner in pixels

offsetY

Integer

vertical offset from cell corner in pixels

insertImage(url, column, row)

Inserts an image in the document at a given row and column.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

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

Parameters

NameTypeDescription

url

String

the url of the image

column

Integer

the grid column position

row

Integer

the grid row position

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

Inserts an image in the document at a given row and column, with a pixel offset.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

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

Parameters

NameTypeDescription

url

String

the url for the image

column

Integer

the column position

row

Integer

the row position

offsetX

Integer

horizontal offset from cell corner in pixels

offsetY

Integer

vertical offset from cell corner in pixels

insertRowAfter(afterPosition)

Inserts a row after the given row position.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // This inserts a row after the first row position

 sheet.insertRowAfter(1);

Parameters

NameTypeDescription

afterPosition

Integer

the row after which the new row should be added

Return

Sheet — the sheet, useful for method chaining

insertRowBefore(beforePosition)

Inserts a row before the given row position.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // This inserts a row before the first row position

 sheet.insertRowBefore(1);

Parameters

NameTypeDescription

beforePosition

Integer

the row before which the new row should be added

Return

Sheet — the sheet, useful for method chaining

insertRows(rowIndex)

Inserts a blank row in a sheet at the specified location.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Shifts all rows down by one

 sheet.insertRows(1);

Parameters

NameTypeDescription

rowIndex

Integer

the index to insert a row

insertRows(rowIndex, numRows)

Inserts one or more consecutive blank rows in a sheet starting at the specified location.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Shifts all rows down by three

 sheet.insertRows(1, 3);

Parameters

NameTypeDescription

rowIndex

Integer

the index to insert a row

numRows

Integer

the number of rows to insert

insertRowsAfter(afterPosition, howMany)

Inserts a number of rows after the given row position.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // This inserts five rows after the first row

 sheet.insertRowsAfter(1, 5);

Parameters

NameTypeDescription

afterPosition

Integer

the row after which the new rows should be added

howMany

Integer

the number of rows to insert

Return

Sheet — the sheet, useful for method chaining

insertRowsBefore(beforePosition, howMany)

Inserts a number of rows before the given row position.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // This inserts five rows before the first row

 sheet.insertRowsBefore(1, 5);

Parameters

NameTypeDescription

beforePosition

Integer

the row before which the new rows should be added

howMany

Integer

the number of rows to insert

Return

Sheet — the sheet, useful for method chaining

isSheetHidden()

Returns true if the sheet is currently hidden.

 var sheet = SpreadsheetApp.getActiveSheet();

 if (sheet.isSheetHidden()) {

   // do something...

Return

Boolean — true if the sheet is hidden, false otherwise

moveColumns(columnSpec, destinationIndex)

Moves the columns selected by the given range to the position indicated by the destinationIndex. The columnSpecitself 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);

Parameters

NameTypeDescription

columnSpec

Range

A range spanning the columns that should be moved.

destinationIndex

Integer

The index that the columns should be moved to. Note that this index is based on the coordinates before the columns are moved. Existing data is shifted right to make room for the moved columns while the source columns are removed from the grid. Therefore, the data may end up at a different index than originally specified.

moveRows(rowSpec, destinationIndex)

Moves the rows selected by the given range to the position indicated by the 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);

Parameters

NameTypeDescription

rowSpec

Range

A range spanning the rows that should be moved.

destinationIndex

Integer

The index that the rows should be moved to. Note that this index is based on the coordinates before the rows are moved. Existing data is shifted down to make room for the moved rows while the source rows are removed from the grid. Therefore, the data may end up at a different index than originally specified.

newChart()

Returns a builder to create a new chart for this sheet.

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());

Return

EmbeddedChartBuilder — a builder for create a new chart

protect()

Creates an object that can protect the sheet from being edited except by users who have permission. Until the script actually changes the list of editors for the sheet (by calling 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);

Return

Protection — an object representing the protection settings

removeChart(chart)

Removes a chart from the parent sheet.

 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]);

Parameters

NameTypeDescription

chart

EmbeddedChart

the chart to remove

setActiveRange(range)

Sets the active range for the active sheet.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

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

 sheet.setActiveRange(range);

Parameters

NameTypeDescription

range

Range

the range to set as the active range

Return

Range — the newly active range

setActiveSelection(range)

Sets the active selection region for this sheet.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

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

 sheet.setActiveSelection(range);

Parameters

NameTypeDescription

range

Range

the range to set as the active selection

Return

Range — the newly active range

setActiveSelection(a1Notation)

Sets the active selection, as specified in A1 notation or R1C1 notation.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 sheet.setActiveSelection("A1:D4");

Parameters

NameTypeDescription

a1Notation

String

the range to set as active, as specified in A1 notation or R1C1 notation

Return

Range — the newly active range

setColumnWidth(columnPosition, width)

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

Parameters

NameTypeDescription

columnPosition

Integer

the position of the given column to set

width

Integer

the width in pixels to set it to

Return

Sheet — the sheet, useful for method chaining

setFrozenColumns(columns)

Freezes the given number of columns. If zero, no columns are frozen.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Freezes the first column

 sheet.setFrozenColumns(1);

Parameters

NameTypeDescription

columns

Integer

the number of columns to freeze

setFrozenRows(rows)

Freezes the given number of rows. If zero, no rows are frozen.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Freezes the first row

 sheet.setFrozenRows(1);

Parameters

NameTypeDescription

rows

Integer

the number of rows to freeze

setName(name)

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");

Parameters

NameTypeDescription

name

String

the new name for the sheet

Return

Sheet — the sheet for chaining

setRowHeight(rowPosition, height)

Sets the row height of the given row in pixels.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Sets the first row to a height of 200 pixels

 sheet.setRowHeight(1, 200);

Parameters

NameTypeDescription

rowPosition

Integer

the row position to change

height

Integer

height in pixels to set it to

Return

Sheet — the sheet, useful for method chaining

setTabColor(color)

Sets the sheet tab color.

 // 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.

Parameters

NameTypeDescription

color

String

color code in CSS notation (like '#ffffff' or 'white'), or null to reset the tab color

Return

Sheet — the sheet for chaining

showColumns(columnIndex)

Unhides the column at the given index.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Unhides the first column

 sheet.showColumns(1);

Parameters

NameTypeDescription

columnIndex

Integer

the index of the column to unhide

showColumns(columnIndex, numColumns)

Unhides one or more consecutive columns starting at the given index.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Unhides the first three columns

 sheet.showColumns(1, 3);

Parameters

NameTypeDescription

columnIndex

Integer

the starting index of the columns to unhide

numColumns

Integer

the number of columns to unhide

showRows(rowIndex)

Unhides the row at the given index.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Unhides the first row

 sheet.showRows(1);

Parameters

NameTypeDescription

rowIndex

Integer

the index of the row to unhide

showRows(rowIndex, numRows)

Unhides one or more consecutive rows starting at the given index.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Unhides the first three rows

 sheet.showRows(1, 3);

Parameters

NameTypeDescription

rowIndex

Integer

the starting index of the rows to unhide

numRows

Integer

the number of rows to unhide

showSheet()

Makes the sheet visible. Has no effect if the sheet is already visible.

 var sheet = SpreadsheetApp.getActiveSheet();

 sheet.showSheet();

Return

Sheet — the current sheet

sort(columnPosition)

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

Parameters

NameTypeDescription

columnPosition

Integer

the column to sort by

Return

Sheet — the sheet, useful for method chaining

sort(columnPosition, ascending)

Sorts a sheet by column. Takes a parameter to specify ascending or descending.

 var ss = SpreadsheetApp.getActiveSpreadsheet();

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

 // Sorts the sheet by the first column, descending

 sheet.sort(1, false);

Parameters

NameTypeDescription

columnPosition

Integer

the column to sort by

ascending

Boolean

true for ascending, false for descending

Return

Sheet — the sheet, useful for method chaining

unhideColumn(column)

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

Parameters

NameTypeDescription

column

Range

the range to unhide, if hidden

unhideRow(row)

Unhides the row in the given 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);

Parameters

NameTypeDescription

row

Range

the range to unhide, if hidden

updateChart(chart)

Updates the chart on this sheet.

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

Parameters

NameTypeDescription

chart

EmbeddedChart

the chart to update

Deprecated methods

▸

getSheetProtection()

▸

setSheetProtection(permissions)

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

最終更新日: 10月 20, 2017

Blog
The latest news on the G Suite Developers blog

GitHub
Fork our samples and try them yourself

Issue Tracker
Something wrong? Send us a bug report!

Stack Overflow
Ask a question under the google-apps-script tag

Videos
Check out the Apps Script videos on YouTube
Tools
- Script Editor
- Service Health Dashboard
Connect
Product Info
- Terms of Service

Android

Bahasa Indonesia Deutsch English español français Português Brasileiro Русский 日本語简体中文 한국어