Class Selection

選取

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

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

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

方法

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

內容詳盡的說明文件

getActiveRange()

傳回有效工作表中的所選範圍，如果沒有有效範圍，則傳回「null」。如果選取多個範圍，這個方法只會傳回最後選取的範圍。

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

回攻員

Range|null：有效範圍。

授權

使用這個方法的指令碼需要一或多個下列範圍的授權：

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

getActiveRangeList()

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

如果只選取單一範圍，這項操作的行為與 getActiveRange() 呼叫相同。 

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

回攻員

RangeList|null - 有效範圍清單。

授權

使用這個方法的指令碼需要一或多個下列範圍的授權：

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

getActiveSheet()

傳回試算表中的現用工作表。 

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

回攻員

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

授權

使用這個方法的指令碼需要一或多個下列範圍的授權：

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

getCurrentCell()

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

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

回攻員

Range|null：目前的儲存格。

授權

使用這個方法的指令碼需要一或多個下列範圍的授權：

  • 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.
const ss = SpreadsheetApp.getActiveSpreadsheet();
const 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(),
);

參數

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

回攻員

Range|null：包含資料儲存格的調整後範圍，或 null (如果沒有選取範圍)。

授權

使用這個方法的指令碼需要一或多個下列範圍的授權：

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