本頁面由 Cloud Translation API 翻譯而成。

Class Selection

在使用中的工作表中存取目前使用中的選項。選擇項目是指使用者在工作表中醒目顯示的一組儲存格，可以是不相鄰的範圍。所選儲存格中的一個儲存格，就是使用者目前焦點所在的儲存格。在 Google 試算表 UI 中，目前的儲存格會以較深的邊框醒目顯示。

var activeSheet = SpreadsheetApp.getActiveSheet();
var rangeList = activeSheet.getRangeList(['A1:B4', 'D1:E4']);
rangeList.activate();

var selection = 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
var ranges =  selection.getActiveRangeList().getRanges();
for (var i = 0; i < ranges.length; i++) {
  console.log('Active Ranges: ' + ranges[i].getA1Notation());
}
console.log('Active Sheet: ' + selection.getActiveSheet().getName());

方法

方法	傳回類型	簡短說明
`getActiveRange()`	`Range`	傳回使用中工作表中選取的範圍；如果沒有使用中的範圍，則傳回 `null`。
`getActiveRangeList()`	`RangeList`	傳回使用中工作表中的有效範圍清單；如果沒有有效範圍，則傳回 `null`。
`getActiveSheet()`	`Sheet`	傳回試算表中的有效工作表。
`getCurrentCell()`	`Range`	傳回目前在其中一個有效範圍中選取的 (已醒目顯示) 儲存格；如果目前沒有儲存格，則傳回 `null`。
`getNextDataRange(direction)`	`Range`	從 `current cell` 和 `active range` 開始，然後朝指定方向移動，傳回調整後的範圍，其中範圍的適當邊緣已移動至涵蓋 `next data cell`，同時涵蓋目前的儲存格。

內容詳盡的說明文件

`getActiveRange()`

傳回使用中工作表中選取的範圍；如果沒有使用中的範圍，則傳回 null。如果選取多個範圍，這個方法只會傳回最後一個選取的範圍。

var selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
var activeRange = selection.getActiveRange();

回攻員

Range：使用中的範圍。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

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

`getActiveRangeList()`

傳回使用中工作表中的有效範圍清單；如果沒有有效範圍，則傳回 null。

如果只選取單一範圍，這會視為 getActiveRange() 呼叫。

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

回攻員

RangeList：有效範圍的清單。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

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

`getActiveSheet()`

傳回試算表中的有效工作表。

var selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
var activeSheet = selection.getActiveSheet();

回攻員

Sheet：試算表的有效工作表。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

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

`getCurrentCell()`

傳回目前在其中一個有效範圍中選取的 (已醒目顯示) 儲存格；如果目前沒有儲存格，則傳回 null。

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

回攻員

Range：目前的儲存格。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

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

`getNextDataRange(direction)`

從 current cell 和 active range 開始，然後朝指定方向移動，傳回調整後的範圍，其中範圍的適當邊緣已移動至涵蓋 next data cell，同時涵蓋目前的儲存格。如果有效範圍沿著方向的 dimension 不界限，會傳回原本的有效範圍。如果沒有當前的儲存格或有效的範圍，會傳回 null。這相當於在編輯器中選取範圍，然後按下 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'
console.log(SpreadsheetApp.getSelection()
                          .getNextDataRange(SpreadsheetApp.Direction.UP)
                          .getA1Notation());

參數

名稱	類型	說明
`direction`	`Direction`	尋找下一個資料區域邊緣儲存格的方向。

回攻員

Range：含有資料儲存格的調整範圍；如果沒有選取項目，則選取 null。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

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