Class Selection

  • A selection is the set of cells the user has highlighted in the sheet, which can include non-adjacent ranges.

  • The current cell within a selection is where the user's focus is, highlighted with a darker border in the Google Sheets UI.

  • The Selection object provides methods to access the active range, list of active ranges, the active sheet, and the current cell.

  • Methods like getActiveRange(), getActiveRangeList(), getActiveSheet(), and getCurrentCell() allow programmatic interaction with the user's selection.

  • The getNextDataRange() method helps find the next data region edge based on the current cell and active range.
Selection

Access the current active selection in the active sheet. A selection is the set of cells the user has highlighted in the sheet, which can be non-adjacent ranges. One cell in the selection is the current cell, where the user's current focus is. The current cell is highlighted with a darker border in the Google Sheets UI. 

constactiveSheet=SpreadsheetApp.getActiveSheet();
constrangeList=activeSheet.getRangeList(['A1:B4','D1:E4']);
rangeList.activate();
constselection=activeSheet.getSelection();
// Current Cell: D1
console.log(`Current Cell: ${selection.getCurrentCell().getA1Notation()}`);
// Active Range: D1:E4
console.log(`Active Range: ${selection.getActiveRange().getA1Notation()}`);
// Active Ranges: A1:B4, D1:E4
constranges=selection.getActiveRangeList().getRanges();
for(leti=0;i < ranges.length;i++){
console.log(`Active Ranges: ${ranges[i].getA1Notation()}`);
}
console.log(`Active Sheet: ${selection.getActiveSheet().getName()}`);

Methods

MethodReturn typeBrief description
getActiveRange() Range Returns the selected range in the active sheet, or null if there is no active range.
getActiveRangeList() RangeList Returns the list of active ranges in the active sheet or null if there are no active ranges.
getActiveSheet() Sheet Returns the active sheet in the spreadsheet.
getCurrentCell() Range Returns the current (highlighted) cell that is selected in one of the active ranges or null if there is no current cell.
getNextDataRange(direction) Range Starting from the 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.

Detailed documentation

getActiveRange()

Returns the selected range in the active sheet, or null if there is no active range. If multiple ranges are selected this method returns only the last selected range. 

constselection=SpreadsheetApp.getActiveSpreadsheet().getSelection();
constactiveRange=selection.getActiveRange();

Return

Range — The active range.

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

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

getActiveRangeList()

Returns the list of active ranges in the active sheet or null if there are no active ranges.

If there is a single range selected, this behaves as a getActiveRange() call. 

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

Return

RangeList — The list of active ranges.

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

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

getActiveSheet()

Returns the active sheet in the spreadsheet. 

constselection=SpreadsheetApp.getActiveSpreadsheet().getSelection();
constactiveSheet=selection.getActiveSheet();

Return

Sheet — The active sheet in the spreadsheet.

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

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

getCurrentCell()

Returns the current (highlighted) cell that is selected in one of the active ranges or null if there is no current cell. 

constselection=SpreadsheetApp.getActiveSpreadsheet().getSelection();
// Returns the current highlighted cell in the one of the active ranges.
constcurrentCell=selection.getCurrentCell();

Return

Range — The current cell.

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

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

getNextDataRange(direction)

Starting from the 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.
constss=SpreadsheetApp.getActiveSpreadsheet();
constsheet=ss.getSheets()[0];
// Makes C3 the current cell and C3:E5 the active range.
sheet.getRange('C3:E5').activate();
// Logs 'C1:E3'
console.log(
SpreadsheetApp.getSelection()
.getNextDataRange(SpreadsheetApp.Direction.UP)
.getA1Notation(),
);

Parameters

NameTypeDescription
directionDirection The direction in which to find the next data region edge cell.

Return

Range — The adjusted range that includes the data cell, or null if there is no selection.

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

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

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

Last updated 2024年12月02日 UTC.