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。
getActiveRangeList()RangeList傳回有效工作表中有效範圍的清單，如果沒有有效範圍，則傳回 null。
getActiveSheet()Sheet傳回試算表中的目前工作表。
getCurrentCell()Range傳回在其中一個有效範圍中選取的目前 (醒目顯示) 儲存格，如果沒有目前儲存格，則傳回 null。
getNextDataRange(direction)Range從 current cell 和 active range 開始，並朝指定方向移動，傳回經過調整的範圍，其中範圍的適當邊緣已移至涵蓋 next data cell，同時仍涵蓋目前的儲存格。

內容詳盡的說明文件

getActiveRange()

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

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

回攻員

Range：有效範圍。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

  • 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：有效範圍清單。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

  • 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：目前的儲存格。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

  • 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。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

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