Class Sheet

試算表

存取及修改試算表工作表。常見作業包括重新命名工作表,以及從工作表存取範圍物件。

方法

方法傳回類型簡短說明
activate()Sheet啟用這個工作表。
addDeveloperMetadata(key)Sheet將具有指定鍵的開發人員中繼資料新增至工作表。
addDeveloperMetadata(key, visibility)Sheet將具有指定鍵和瀏覽權限的開發人員中繼資料新增至試算表。
addDeveloperMetadata(key, value)Sheet將指定鍵和值的開發人員中繼資料新增至試算表。
addDeveloperMetadata(key, value, visibility)Sheet將具有指定鍵、值和瀏覽權限的開發人員中繼資料新增至工作表。
appendRow(rowContents)Sheet在試算表目前資料區域的底部附加資料列。
asDataSourceSheet()DataSourceSheet|null如果工作表類型為 SheetType.DATASOURCE,則會以 DataSourceSheet 形式傳回工作表,否則會以 null 形式傳回。
autoResizeColumn(columnPosition)Sheet將指定資料欄的寬度設為符合內容。
autoResizeColumns(startColumn, numColumns)Sheet將指定欄位置起的所有欄寬設為符合內容大小。
autoResizeRows(startRow, numRows)Sheet設定從指定列位置開始的所有列高度,以配合內容。
clear()Sheet清除工作表中的內容和格式資訊。
clear(options)Sheet根據指定進階選項,清除工作表內容和/或格式。
clearConditionalFormatRules()void移除工作表中的所有條件式格式規則。
clearContents()Sheet清除工作表內容,但保留格式資訊。
clearFormats()Sheet清除工作表中的格式,但保留內容。
clearNotes()Sheet清除所有附註的試算表。
collapseAllColumnGroups()Sheet收合工作表中的所有欄群組。
collapseAllRowGroups()Sheet收合工作表中的所有列群組。
copyTo(spreadsheet)Sheet將工作表複製到指定試算表,該試算表可以與來源相同。
createDeveloperMetadataFinder()DeveloperMetadataFinder傳回 DeveloperMetadataFinder,用於在這個工作表範圍內尋找開發人員中繼資料。
createTextFinder(findText)TextFinder為試算表建立文字搜尋器,可在試算表中尋找及取代文字。
deleteColumn(columnPosition)Sheet刪除指定欄位置的欄。
deleteColumns(columnPosition, howMany)void從指定欄位置開始刪除多個欄。
deleteRow(rowPosition)Sheet刪除指定資料列位置的資料列。
deleteRows(rowPosition, howMany)void從指定資料列位置開始刪除多個資料列。
expandAllColumnGroups()Sheet展開工作表中的所有欄群組。
expandAllRowGroups()Sheet展開工作表中的所有列群組。
expandColumnGroupsUpToDepth(groupDepth)Sheet展開所有欄群組,直到指定深度為止,並收合所有其他欄群組。
expandRowGroupsUpToDepth(groupDepth)Sheet將所有列群組展開至指定深度,並收合所有其他列群組。
getActiveCell()Range傳回這份工作表中的作用中儲存格。
getActiveRange()Range傳回有效工作表中的所選範圍,如果沒有有效範圍,則傳回「null」。
getActiveRangeList()RangeList|null傳回有效工作表中的有效範圍清單,或如果沒有有效範圍,則傳回 null
getBandings()Banding[]傳回這個工作表中的所有帶狀。
getCharts()EmbeddedChart[]傳回這個工作表上的圖表陣列。
getColumnGroup(columnIndex, groupDepth)Group|null傳回指定索引和群組深度的欄群組。
getColumnGroupControlPosition()GroupControlTogglePosition傳回工作表上所有欄群組的 GroupControlTogglePosition
getColumnGroupDepth(columnIndex)Integer傳回指定索引處資料欄的群組深度。
getColumnWidth(columnPosition)Integer取得指定資料欄的寬度 (以像素為單位)。
getConditionalFormatRules()ConditionalFormatRule[]取得這個工作表中的所有條件式格式規則。
getCurrentCell()Range|null傳回有效工作表中的目前儲存格,或 null (如果沒有目前儲存格)。
getDataRange()Range傳回與資料所在維度對應的 Range
getDataSourceFormulas()DataSourceFormula[]取得所有資料來源公式。
getDataSourcePivotTables()DataSourcePivotTable[]取得所有資料來源資料透視表。
getDataSourceTables()DataSourceTable[]取得所有資料來源資料表。
getDeveloperMetadata()DeveloperMetadata[]取得與這份試算表相關的所有開發人員中繼資料。
getDrawings()Drawing[]傳回工作表上的繪圖陣列。
getFilter()Filter|null傳回這個工作表中的篩選器,如果沒有篩選器,則傳回 null
getFormUrl()String|null傳送回覆至這個工作表的表單網址,如果這個工作表沒有相關聯的表單,則傳回 null
getFrozenColumns()Integer傳回凍結的欄數。
getFrozenRows()Integer傳回凍結的列數。
getImages()OverGridImage[]傳回工作表上所有超出格線的圖片。
getIndex()Integer取得工作表在上層試算表中的位置。
getLastColumn()Integer傳回含有內容的最後一欄位置。
getLastRow()Integer傳回含有內容的最後一列位置。
getMaxColumns()Integer傳回工作表目前的欄數,不論內容為何。
getMaxRows()Integer傳回工作表目前的列數,不論內容為何。
getName()String傳回工作表名稱。
getNamedRanges()NamedRange[]取得這個工作表中的所有已命名範圍。
getParent()Spreadsheet傳回包含這個工作表的 Spreadsheet
getPivotTables()PivotTable[]傳回這張工作表上的所有資料透視表。
getProtections(type)Protection[]取得代表工作表中所有受保護範圍的物件陣列,或是代表工作表本身保護機制的單一元素陣列。
getRange(row, column)Range傳回左上角儲存格位於指定座標的範圍。
getRange(row, column, numRows)Range傳回範圍,左上角儲存格位於指定座標,且具有指定列數。
getRange(row, column, numRows, numColumns)Range傳回範圍,左上角儲存格位於指定座標,且具有指定列數和欄數。
getRange(a1Notation)Range以 A1 或 R1C1 標記法傳回指定範圍。
getRangeList(a1Notations)RangeList傳回 RangeList 集合,代表同一工作表中以非空白的 A1 標記或 R1C1 標記清單指定的範圍。
getRowGroup(rowIndex, groupDepth)Group|null傳回指定索引和群組深度的列群組。
getRowGroupControlPosition()GroupControlTogglePosition傳回工作表上所有列群組的 GroupControlTogglePosition
getRowGroupDepth(rowIndex)Integer傳回指定索引處資料列的群組深度。
getRowHeight(rowPosition)Integer取得指定列的高度 (以像素為單位)。
getSelection()Selection傳回試算表中的目前 Selection
getSheetId()Integer傳回這個物件代表的試算表 ID。
getSheetName()String傳回工作表名稱。
getSheetValues(startRow, startColumn, numRows, numColumns)Object[][]傳回這個範圍的值矩形格線,從指定座標開始。
getSlicers()Slicer[]傳回工作表上的篩選器陣列。
getTabColorObject()Color|null取得工作表分頁顏色,如果工作表分頁沒有顏色,則為 null
getType()SheetType傳回工作表的類型。
hasHiddenGridlines()Boolean如果工作表的格線已隱藏,則傳回 true;否則傳回 false
hideColumn(column)void隱藏指定範圍中的欄。
hideColumns(columnIndex)void隱藏指定索引處的單一資料欄。
hideColumns(columnIndex, numColumns)void隱藏從指定索引開始的一或多個連續資料欄。
hideRow(row)void隱藏指定範圍內的資料列。
hideRows(rowIndex)void隱藏指定索引的資料列。
hideRows(rowIndex, numRows)void從指定索引開始,隱藏一或多個連續資料列。
hideSheet()Sheet隱藏這份工作表。
insertChart(chart)void在工作表中新增圖表。
insertColumnAfter(afterPosition)Sheet在指定資料欄位置後方插入資料欄。
insertColumnBefore(beforePosition)Sheet在指定資料欄位置的前方插入資料欄。
insertColumns(columnIndex)void在工作表的指定位置插入空白欄。
insertColumns(columnIndex, numColumns)void在工作表中指定位置插入一或多個連續空白欄。
insertColumnsAfter(afterPosition, howMany)Sheet在指定欄位置後插入指定數量的欄。
insertColumnsBefore(beforePosition, howMany)Sheet在指定欄位置之前插入多個欄。
insertImage(blobSource, column, row)OverGridImage在文件的指定資料列和資料欄中,以圖片形式插入 BlobSource
insertImage(blobSource, column, row, offsetX, offsetY)OverGridImage在文件的指定列和欄中插入 BlobSource 做為圖片,並設定像素偏移量。
insertImage(url, column, row)OverGridImage在文件的指定列和欄插入圖片。
insertImage(url, column, row, offsetX, offsetY)OverGridImage在文件的指定列和欄中插入圖片,並設定像素偏移量。
insertRowAfter(afterPosition)Sheet在指定資料列位置後方插入資料列。
insertRowBefore(beforePosition)Sheet在指定資料列位置之前插入資料列。
insertRows(rowIndex)void在工作表的指定位置插入空白列。
insertRows(rowIndex, numRows)void在工作表中的指定位置插入一或多個連續空白列。
insertRowsAfter(afterPosition, howMany)Sheet在指定資料列位置後插入多列。
insertRowsBefore(beforePosition, howMany)Sheet在指定資料列位置之前插入多個資料列。
insertSlicer(range, anchorRowPos, anchorColPos)Slicer在這個工作表中新增篩選器。
insertSlicer(range, anchorRowPos, anchorColPos, offsetX, offsetY)Slicer在這個工作表中新增篩選器。
isColumnHiddenByUser(columnPosition)Boolean傳回指定資料欄是否遭使用者隱藏。
isRightToLeft()Boolean如果這個工作表版面配置是從右至左,則傳回 true
isRowHiddenByFilter(rowPosition)Boolean傳回指定資料列是否因篩選器 (而非篩選器檢視畫面) 而隱藏。
isRowHiddenByUser(rowPosition)Boolean傳回指定資料列是否遭使用者隱藏。
isSheetHidden()Boolean如果目前隱藏工作表,則傳回 true
moveColumns(columnSpec, destinationIndex)void將指定範圍選取的資料欄移至 destinationIndex 指示的位置。
moveRows(rowSpec, destinationIndex)void將指定範圍選取的資料列移至 destinationIndex 指示的位置。
newChart()EmbeddedChartBuilder傳回用於為這個工作表建立新圖表的建構工具。
protect()Protection建立物件,保護工作表不遭編輯,但具備權限的使用者除外。
removeChart(chart)void從上層工作表移除圖表。
setActiveRange(range)Range將指定範圍設為作用中工作表中的 active range,並將範圍中左上角的儲存格設為 current cell
setActiveRangeList(rangeList)RangeList將指定範圍清單設為作用中工作表中的 active ranges
setActiveSelection(range)Range為這個工作表設定有效選取區域。
setActiveSelection(a1Notation)Range設定以 A1 標記法或 R1C1 標記法指定的作用中選取範圍。
setColumnGroupControlPosition(position)Sheet設定工作表上欄群組控制項切換按鈕的位置。
setColumnWidth(columnPosition, width)Sheet以像素為單位設定指定資料欄的寬度。
setColumnWidths(startColumn, numColumns, width)Sheet以像素為單位設定指定資料欄的寬度。
setConditionalFormatRules(rules)void以輸入規則取代工作表中目前的所有條件式格式規則。
setCurrentCell(cell)Range將指定儲存格設為 current cell
setFrozenColumns(columns)void凍結指定欄數。
setFrozenRows(rows)void凍結指定列數。
setHiddenGridlines(hideGridlines)Sheet隱藏或顯示工作表格線。
setName(name)Sheet設定工作表名稱。
setRightToLeft(rightToLeft)Sheet將工作表版面配置設為由右至左,或取消設定。
setRowGroupControlPosition(position)Sheet設定工作表上列群組控制項切換按鈕的位置。
setRowHeight(rowPosition, height)Sheet以像素為單位,設定指定資料列的高度。
setRowHeights(startRow, numRows, height)Sheet以像素為單位設定指定列的高度。
setRowHeightsForced(startRow, numRows, height)Sheet以像素為單位設定指定列的高度。
setTabColor(color)Sheet設定工作表分頁標籤顏色。
setTabColorObject(color)Sheet設定工作表分頁標籤顏色。
showColumns(columnIndex)void取消隱藏指定索引處的資料欄。
showColumns(columnIndex, numColumns)void從指定索引開始,取消隱藏一或多個連續資料欄。
showRows(rowIndex)void取消隱藏指定索引處的資料列。
showRows(rowIndex, numRows)void從指定索引開始,取消隱藏一或多個連續資料列。
showSheet()Sheet顯示工作表。
sort(columnPosition)Sheet依遞增順序依欄排序工作表。
sort(columnPosition, ascending)Sheet依資料欄排序工作表。
unhideColumn(column)void取消隱藏指定範圍內的資料欄。
unhideRow(row)void取消隱藏指定範圍內的資料列。
updateChart(chart)void更新這個工作表中的圖表。

內容詳盡的說明文件

activate()

啟用這個工作表。不會變更工作表本身,只會變更父項對有效工作表的概念。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.activate();

回攻員

Sheet:新啟用的工作表。


addDeveloperMetadata(key)

在工作表中新增具有指定鍵的開發人員中繼資料。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Adds the key 'NAME' to the developer metadata for the sheet.
sheet.addDeveloperMetadata('NAME');

// Gets the updated metadata info and logs it to the console.
console.log(sheet.getDeveloperMetadata()[0].getKey());

參數

名稱類型說明
keyString新開發人員中繼資料的鍵。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

addDeveloperMetadata(key, visibility)

將具有指定鍵和瀏覽權限的開發人員中繼資料新增至試算表。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Adds the key 'NAME' and sets the developer metadata visibility to PROJECT
// for the sheet.
sheet.addDeveloperMetadata(
    'NAME',
    SpreadsheetApp.DeveloperMetadataVisibility.PROJECT,
);

// Gets the updated metadata info and logs it to the console.
const developerMetaData = sheet.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getVisibility().toString());

參數

名稱類型說明
keyString新開發人員中繼資料的鍵。
visibilityDeveloperMetadataVisibility新開發人員中繼資料的瀏覽權限。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

addDeveloperMetadata(key, value)

將指定鍵和值的開發人員中繼資料新增至試算表。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Adds the key 'COMPANY' with the value 'TECH' to the developer metadata for
// the sheet.
sheet.addDeveloperMetadata('COMPANY', 'TECH');

// Gets the updated metadata info and logs it to the console.
const developerMetaData = sheet.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getValue());

參數

名稱類型說明
keyString新開發人員中繼資料的鍵。
valueString新開發人員中繼資料的值。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

addDeveloperMetadata(key, value, visibility)

將指定鍵、值和瀏覽權限的開發人員中繼資料新增至試算表。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Adds the key 'COMPANY' with the value 'TECH' to the developer metadata and
// sets the visibility to DOCUMENT for the sheet.
sheet.addDeveloperMetadata(
    'COMPANY',
    'TECH',
    SpreadsheetApp.DeveloperMetadataVisibility.DOCUMENT,
);

// Gets the updated metadata info and logs it to the console.
const developerMetaData = sheet.getDeveloperMetadata()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getValue());
console.log(developerMetaData.getVisibility().toString());

參數

名稱類型說明
keyString新開發人員中繼資料的鍵。
valueString新開發人員中繼資料的值。
visibilityDeveloperMetadataVisibility新開發人員中繼資料的瀏覽權限。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

appendRow(rowContents)

在試算表目前資料區域的底部附加資料列。如果儲存格內容以 = 開頭,系統會將其解讀為公式。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Appends a new row with 3 columns to the bottom of the current
// data region in the sheet containing the values in the array.
sheet.appendRow(['a man', 'a plan', 'panama']);

參數

名稱類型說明
rowContentsObject[]要在工作表最後一列後方插入的值陣列。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

asDataSourceSheet()

如果工作表類型為 SheetType.DATASOURCE,則會以 DataSourceSheet 形式傳回工作表,否則會以 null 形式傳回。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can useSpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the data source sheet value if the sheet is of type
// SpreadsheetApp.SheetType.DATASOURCE, otherwise this returns a null value.
const dataSourceSheet = sheet.asDataSourceSheet();

// Gets the data source sheet value and logs it to the console.
console.log(dataSourceSheet);
console.log(sheet.getType().toString());

回攻員

DataSourceSheet|null:資料來源工作表。

授權

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

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

autoResizeColumn(columnPosition)

將指定資料欄的寬度設為符合內容。

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

參數

名稱類型說明
columnPositionInteger要調整大小的資料欄位置。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

autoResizeColumns(startColumn, numColumns)

從指定欄位置開始,將所有欄的寬度設為符合內容。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Sets the first 15 columns to a width that fits their text.
sheet.autoResizeColumns(1, 15);

參數

名稱類型說明
startColumnInteger要自動調整大小的起始欄。
numColumnsInteger要自動調整大小的欄數。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

autoResizeRows(startRow, numRows)

設定從指定列位置開始的所有列高度,以配合內容。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Sets the first 15 rows to a height that fits their text.
sheet.autoResizeRows(1, 15);

參數

名稱類型說明
startRowInteger要自動調整大小的起始列。
numRowsInteger要自動調整大小的列數。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

clear()

清除工作表中的內容和格式資訊。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.clear();

回攻員

Sheet:已清除的工作表。

授權

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

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

clear(options)

清除工作表的內容和/或格式,具體視指定進階選項而定。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
sheet.clear({formatOnly: true, contentsOnly: true});

參數

名稱類型說明
optionsObject包含進階選項的 JavaScript 地圖,如下所示。

進階參數

名稱類型說明
contentsOnlyBoolean是否要清除內容。
formatOnlyBoolean是否清除格式。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

clearConditionalFormatRules()

移除工作表中的所有條件式格式規則。等同於呼叫 setConditionalFormatRules(rules),並將空陣列做為輸入內容。

const sheet = SpreadsheetApp.getActiveSheet();
sheet.clearConditionalFormatRules();

授權

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

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

clearContents()

清除工作表內容,但保留格式資訊。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.clearContents();

回攻員

Sheet - This sheet, for chaining.

授權

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

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

clearFormats()

清除工作表格式,但保留內容。

格式是指「格式」選單中允許的資料格式 (例如粗體、斜體、條件式格式),而非儲存格的寬度或高度。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.clearFormats();

回攻員

Sheet - This sheet, for chaining.

授權

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

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

clearNotes()

清除所有附註。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.clearNotes();

回攻員

Sheet - This sheet, for chaining.

授權

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

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

collapseAllColumnGroups()

收合工作表中的所有欄群組。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// All column groups on the sheet are collapsed.
sheet.collapseAllColumnGroups();

回攻員

Sheet - This sheet, for chaining.

授權

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

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

collapseAllRowGroups()

收合工作表中的所有列群組。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// All row groups on the sheet are collapsed.
sheet.collapseAllRowGroups();

回攻員

Sheet - This sheet, for chaining.

授權

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

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

copyTo(spreadsheet)

將工作表複製到指定試算表,該試算表可以與來源試算表相同。複製的工作表會命名為「[原始名稱] 的副本」。

const source = SpreadsheetApp.getActiveSpreadsheet();
const sheet = source.getSheets()[0];

const destination = SpreadsheetApp.openById('ID_GOES HERE');
sheet.copyTo(destination);

參數

名稱類型說明
spreadsheetSpreadsheet要將這份工作表複製到的試算表,可以與來源試算表相同。

回攻員

Sheet:新工作表,用於串連。

授權

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

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

createDeveloperMetadataFinder()

傳回 DeveloperMetadataFinder,用於在這個工作表範圍內尋找開發人員中繼資料。如果中繼資料與工作表本身相關聯,或是與該工作表中的列、欄或範圍相關聯,則屬於特定工作表的範圍。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Adds developer metadata for testing.
sheet.addDeveloperMetadata('CITY', 'PARIS');

// Creates the developer metadata finder.
const metadatafinder = sheet.createDeveloperMetadataFinder();

// Finds the metadata with value 'PARIS' and displays its key in the console.
console.log(metadatafinder.withValue('PARIS').find()[0].getKey());

回攻員

DeveloperMetadataFinder:開發人員中繼資料搜尋器,可搜尋這個工作表範圍內的中繼資料。


createTextFinder(findText)

為試算表建立文字搜尋器,可在試算表中尋找及取代文字。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// Creates  a text finder.
const textFinder = sheet.createTextFinder('dog');

// Returns the first occurrence of 'dog' in the sheet.
const firstOccurrence = textFinder.findNext();

// Replaces the last found occurrence of 'dog' with 'cat' and returns the number
// of occurrences replaced.
const numOccurrencesReplaced = firstOccurrence.replaceWith('cat');

參數

名稱類型說明
findTextString要搜尋的文字。

回攻員

TextFinder:工作表的 TextFinder


deleteColumn(columnPosition)

刪除指定欄位置的欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Columns start at "1" - this deletes the first column
sheet.deleteColumn(1);

參數

名稱類型說明
columnPositionInteger資料欄位置,第一個資料欄從 1 開始。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

deleteColumns(columnPosition, howMany)

從指定欄位置開始刪除多個欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Columns start at "1" - this deletes the first two columns
sheet.deleteColumns(1, 2);

參數

名稱類型說明
columnPositionInteger要刪除的第一欄位置。
howManyInteger要刪除的欄數。

授權

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

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

deleteRow(rowPosition)

刪除指定資料列位置的資料列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Rows start at "1" - this deletes the first row
sheet.deleteRow(1);

參數

名稱類型說明
rowPositionInteger資料列的位置,第一列從 1 開始。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

deleteRows(rowPosition, howMany)

從指定資料列位置開始刪除多個資料列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Rows start at "1" - this deletes the first two rows
sheet.deleteRows(1, 2);

參數

名稱類型說明
rowPositionInteger要刪除的第一列位置。
howManyInteger要刪除的列數。

授權

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

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

expandAllColumnGroups()

展開工作表中的所有欄群組。這個方法至少需要一個資料欄群組。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// All column groups on the sheet are expanded.
sheet.expandAllColumnGroups();

回攻員

Sheet - This sheet, for chaining.

授權

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

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

expandAllRowGroups()

展開工作表中的所有列群組。這個方法至少需要一個資料列群組。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// All row groups on the sheet are expanded.
sheet.expandAllRowGroups();

回攻員

Sheet - This sheet, for chaining.

授權

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

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

expandColumnGroupsUpToDepth(groupDepth)

展開所有欄群組,直到指定深度為止,並收合所有其他欄群組。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// All column groups of depth 2 and lower are expanded, and groups with depth
// 3 and higher are collapsed.
sheet.expandColumnGroupsUpToDepth(2);

參數

名稱類型說明
groupDepthInteger要展開欄群組的群組深度。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

expandRowGroupsUpToDepth(groupDepth)

將所有列群組展開至指定深度,並收合所有其他列群組。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// All row groups of depth 2 and lower are expanded, and groups with depth
// 3 and higher are collapsed.
sheet.expandRowGroupsUpToDepth(2);

參數

名稱類型說明
groupDepthInteger要展開列群組的群組深度。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

getActiveCell()

傳回這個工作表中的作用中儲存格。

注意:建議使用 getCurrentCell(),這個項目會傳回目前醒目顯示的儲存格。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Returns the active cell
const cell = sheet.getActiveCell();

回攻員

Range:目前編輯中的儲存格。

授權

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

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

getActiveRange()

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

「有效範圍」一詞是指使用者在有效工作表中選取的範圍, 但在自訂函式中,是指正在重新計算的儲存格。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
const activeRange = sheet.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|null - 有效範圍清單。

授權

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

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

另請參閱


getBandings()

傳回這個工作表中的所有帶狀。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the banding info for the sheet.
const bandings = sheet.getBandings();

// Gets info on the bandings' second row color and logs it to the console.
for (const banding of bandings) {
  console.log(banding.getSecondRowColor());
}

回攻員

Banding[]:這個工作表中的所有帶狀。

授權

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

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

getCharts()

傳回這個工作表上的圖表陣列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const charts = sheet.getCharts();

for (const i in charts) {
  const chart = charts[i];
  // Do something with the chart
}

回攻員

EmbeddedChart[] - 圖表陣列。

授權

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

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

getColumnGroup(columnIndex, groupDepth)

傳回指定索引和群組深度的欄群組。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// Returns the group whose control index is at column 2 and has a depth of 1, or
// null if the group doesn’t exist.
const columnGroup = sheet.getColumnGroup(2, 1);

參數

名稱類型說明
columnIndexInteger群組控制項切換開關的欄索引,或群組內的索引。
groupDepthInteger群組的深度。

回攻員

Group|null - 控制索引和深度的欄群組,或在群組不存在時擲回例外狀況。

授權

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

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

getColumnGroupControlPosition()

傳回工作表上所有欄群組的 GroupControlTogglePosition

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// GroupControlTogglePosition.AFTER if the column grouping control toggle is
// shown after the group.
const columnGroupControlPosition = sheet.getColumnGroupControlPosition();

回攻員

GroupControlTogglePosition:如果這個工作表上的群組後方顯示欄群組控制項切換按鈕,則為 true,否則為 false

授權

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

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

getColumnGroupDepth(columnIndex)

傳回指定索引處資料欄的群組深度。

群組深度是指與資料欄重疊的群組數量。範圍介於零到八之間。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// 1 if there is a group over columns 1 through 3
const groupDepth = sheet.getColumnGroupDepth(1);

參數

名稱類型說明
columnIndexInteger資料欄的索引。

回攻員

Integer:指定索引處的資料欄群組深度。

授權

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

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

getColumnWidth(columnPosition)

取得指定資料欄的寬度 (以像素為單位)。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Columns start at 1
Logger.log(sheet.getColumnWidth(1));

參數

名稱類型說明
columnPositionInteger要檢查的資料欄位置。

回攻員

Integer:欄寬 (以像素為單位)。

授權

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

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

getConditionalFormatRules()

取得這個工作表中的所有條件式格式規則。

// Logs the conditional format rules in a sheet.
const rules = SpreadsheetApp.getActiveSheet().getConditionalFormatRules();
for (let i = 0; i < rules.length; i++) {
  const rule = rules[i];
  Logger.log(rule);
}

回攻員

ConditionalFormatRule[]:工作表中的所有規則陣列。

授權

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

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

getCurrentCell()

傳回有效工作表中的目前儲存格,或 null (如果沒有目前儲存格)。目前儲存格是指 Google 試算表 UI 中具有焦點的儲存格,並以深色邊框醒目顯示。目前最多只會有一個儲存格。使用者選取一或多個儲存格範圍時,所選範圍中的其中一個儲存格就是目前的儲存格。

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

回攻員

Range|null:目前的儲存格。

授權

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

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

getDataRange()

傳回與資料所在維度對應的 Range

這在功能上等同於建立以 A1 和 (Sheet.getLastColumn()、Sheet.getLastRow()) 為界的範圍。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This represents ALL the data
const range = sheet.getDataRange();
const values = range.getValues();

// This logs the spreadsheet in CSV format with a trailing comma
for (let i = 0; i < values.length; i++) {
  let row = '';
  for (let j = 0; j < values[i].length; j++) {
    if (values[i][j]) {
      row = row + values[i][j];
    }
    row = `${row},`;
  }
  Logger.log(row);
}

回攻員

Range:包含試算表中所有資料的範圍。

授權

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

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

getDataSourceFormulas()

取得所有資料來源公式。

// Opens the spreadsheet by its ID. If you created your script from within a
// Google Sheets file, use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets an array of the data source formulas on Sheet1.
// To get an array of data source formulas for the entire spreadsheet,
// replace 'sheet' with 'ss'.
const dataSourceFormulas = sheet.getDataSourceFormulas();

// Logs the first data source formula in the array.
console.log(dataSourceFormulas[0].getFormula());

回攻員

DataSourceFormula[]:資料來源公式清單。

授權

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

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

getDataSourcePivotTables()

取得所有資料來源資料透視表。

// Opens the spreadsheet file by its ID. If you created your script from a
// Google Sheets file, use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets an array of the data source pivot tables on Sheet1.
// To get an array of data source pivot tables for the entire
// spreadsheet, replace 'sheet' with 'ss'.
const dataSourcePivotTables = sheet.getDataSourcePivotTables();

// Logs the last time that the first pivot table in the array was refreshed.
console.log(dataSourcePivotTables[0].getStatus().getLastRefreshedTime());

回攻員

DataSourcePivotTable[] - 資料來源資料透視表清單。

授權

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

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

getDataSourceTables()

取得所有資料來源資料表。

// Opens the spreadsheet file by its ID. If you created your script from a
// Google Sheets file, use SpreadsheetApp.getActiveSpreadsheet().
// TODO(developer): Replace the ID with your own.
const ss = SpreadsheetApp.openById('abc123456');

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets an array of data source tables on Sheet1.
// To get an array of data source tables for the entire spreadsheet,
// replace 'sheet' with 'ss'.
const dataSourceTables = sheet.getDataSourceTables();

// Logs the last completed data execution time on the first data source table.
console.log(dataSourceTables[0].getStatus().getLastExecutionTime());

回攻員

DataSourceTable[]:資料來源表格清單。

授權

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

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

getDeveloperMetadata()

取得與這個工作表相關聯的所有開發人員中繼資料。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Adds developer metadata for testing.
sheet.addDeveloperMetadata('CITY', 'PARIS');

// Gets all the developer metadata for the sheet.
const developerMetaDataList = sheet.getDeveloperMetadata();

// Logs the developer metadata to the console.
for (const developerMetaData of developerMetaDataList) {
  console.log(developerMetaData.getKey());
}

回攻員

DeveloperMetadata[]:與這個工作表相關聯的開發人員中繼資料。

授權

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

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

getDrawings()

傳回工作表上的繪圖陣列。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets all the drawings from the sheet.
const allDrawings = sheet.getDrawings();

// Logs the number of drawings present on the sheet.
console.log(allDrawings.length);

回攻員

Drawing[]:這張工作表上的繪圖清單。

授權

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

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

getFilter()

傳回這個工作表中的篩選器,如果沒有篩選器,則傳回 null

// Gets the filter on the active sheet.
const ss = SpreadsheetApp.getActiveSheet();
const filter = ss.getFilter();

回攻員

Filter|null:篩選器。

授權

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

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

getFormUrl()

傳回將回覆傳送至這個工作表的表單網址,如果這個工作表沒有相關聯的表單,則傳回 null。如果使用者沒有編輯試算表的權限,系統會擲回例外狀況。

const sheet = SpreadsheetApp.getActiveSheet();
const url = sheet.getFormUrl();

回攻員

String|null - 將回覆內容放在這個工作表中的表單網址,或 null (如果這個工作表沒有相關聯的表單)。

授權

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

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

getFrozenColumns()

傳回凍結的欄數。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

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

回攻員

Integer:凍結的欄數。

授權

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

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

getFrozenRows()

傳回凍結的列數。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

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

回攻員

Integer:凍結的列數。

授權

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

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

getImages()

傳回工作表上所有超出格線的圖片。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets spreadsheet, you can use
// SpreadsheetApp.getActiveSpreadsheet() instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the over-the-grid images from Sheet1.
// To get the over-the-grid images from the entire spreadsheet, use
// ss.getImages() instead.
const images = sheet.getImages();

// For each image, logs the anchor cell in A1 notation.
for (const image of images) {
  console.log(image.getAnchorCell().getA1Notation());
}

回攻員

OverGridImage[]:格線上方圖片的陣列。

授權

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

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

getIndex()

取得工作表在上層試算表中的位置。從 1 開始。

const ss = SpreadsheetApp.getActiveSpreadsheet();
// Note that the JavaScript index is 0, but this logs 1
const sheet = ss.getSheets()[0];
// ... because spreadsheets are 1-indexed
Logger.log(sheet.getIndex());

回攻員

Integer:工作表在父項試算表中的位置。

授權

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

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

getLastColumn()

傳回含有內容的最後一欄位置。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This logs the value in the very last cell of this sheet
const lastRow = sheet.getLastRow();
const lastColumn = sheet.getLastColumn();
const lastCell = sheet.getRange(lastRow, lastColumn);
Logger.log(lastCell.getValue());

回攻員

Integer:包含內容的試算表最後一欄。

授權

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

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

getLastRow()

傳回含有內容的最後一列位置。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This logs the value in the very last cell of this sheet
const lastRow = sheet.getLastRow();
const lastColumn = sheet.getLastColumn();
const lastCell = sheet.getRange(lastRow, lastColumn);
Logger.log(lastCell.getValue());

回攻員

Integer:包含內容的試算表最後一列。

授權

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

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

getMaxColumns()

傳回工作表目前的欄數,不論內容為何。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
Logger.log(first.getMaxColumns());

回攻員

Integer:工作表的最大寬度。

授權

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

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

getMaxRows()

傳回工作表目前的列數,不論內容為何。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
Logger.log(first.getMaxRows());

回攻員

Integer:功能表的高度上限。

授權

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

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

getName()

傳回工作表的名稱。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
Logger.log(sheet.getName());

回攻員

String:工作表的名稱。

授權

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

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

getNamedRanges()

取得這個工作表中的所有已命名範圍。

// The code below logs the name of the first named range.
const namedRanges = SpreadsheetApp.getActiveSheet().getNamedRanges();
if (namedRanges.length > 1) {
  Logger.log(namedRanges[0].getName());
}

回攻員

NamedRange[]:工作表中所有已命名範圍的陣列。

授權

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

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

getParent()

傳回包含這個工作表的 Spreadsheet

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// parent is identical to ss
const parent = sheet.getParent();

回攻員

Spreadsheet:上層試算表。

授權

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

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

getPivotTables()

傳回這張工作表上的所有資料透視表。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets all the pivot table info for the sheet.
const pivotTables = sheet.getPivotTables();

// Logs the pivot tables to the console.
for (const pivotTable of pivotTables) {
  console.log(pivotTable.getSourceDataRange().getValues());
}

回攻員

PivotTable[]:這個工作表中的資料透視表。

授權

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

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

getProtections(type)

取得代表工作表中所有受保護範圍的物件陣列,或代表工作表本身保護機制的單一元素陣列。

// Remove all range protections in the spreadsheet that the user has permission
// to edit.
const sheet = SpreadsheetApp.getActiveSheet();
const protections = sheet.getProtections(SpreadsheetApp.ProtectionType.RANGE);
for (let i = 0; i < protections.length; i++) {
  const protection = protections[i];
  if (protection.canEdit()) {
    protection.remove();
  }
}
// Remove sheet protection from the active sheet, if the user has permission to
// edit it.
const sheet = SpreadsheetApp.getActiveSheet();
const protection = sheet.getProtections(SpreadsheetApp.ProtectionType.SHEET)[0];
if (protection?.canEdit()) {
  protection.remove();
}

參數

名稱類型說明
typeProtectionType受保護區域的類型,可能是 SpreadsheetApp.ProtectionType.RANGESpreadsheetApp.ProtectionType.SHEET

回攻員

Protection[]:物件陣列,代表工作表中的所有受保護範圍,或是代表工作表本身保護機制的單一元素陣列。

授權

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

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

getRange(row, column)

傳回左上角儲存格位於指定座標的範圍。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Passing only two arguments returns a "range" with a single cell.
const range = sheet.getRange(1, 1);
const values = range.getValues();
Logger.log(values[0][0]);

參數

名稱類型說明
rowInteger要傳回的儲存格列索引,列索引從 1 開始。
columnInteger要傳回的儲存格欄索引,欄索引從 1 開始。

回攻員

Range:只包含這個儲存格的範圍。

授權

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

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

getRange(row, column, numRows)

傳回範圍,左上角儲存格位於指定座標,且具有指定列數。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// When the "numRows" argument is used, only a single column of data is
// returned.
const range = sheet.getRange(1, 1, 3);
const values = range.getValues();

// Prints 3 values from the first column, starting from row 1.
for (const row in values) {
  for (const col in values[row]) {
    Logger.log(values[row][col]);
  }
}

參數

名稱類型說明
rowInteger範圍的起始列索引;列索引從 1 開始。
columnInteger範圍的欄索引,欄索引從 1 開始。
numRowsInteger要傳回的列數。

回攻員

Range:包含單一資料欄的範圍,且列數已指定。

授權

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

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

getRange(row, column, numRows, numColumns)

傳回範圍,左上角儲存格位於指定座標,且具有指定列數和欄數。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
const range = sheet.getRange(1, 1, 3, 3);
const values = range.getValues();

// Print values from a 3x3 box.
for (const row in values) {
  for (const col in values[row]) {
    Logger.log(values[row][col]);
  }
}

參數

名稱類型說明
rowInteger範圍的起始列索引;列索引從 1 開始。
columnInteger範圍的起始欄索引,欄索引從 1 開始。
numRowsInteger要傳回的列數。
numColumnsInteger要傳回的欄數。

回攻員

Range:與指定區域對應的範圍。

授權

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

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

getRange(a1Notation)

以 A1 或 R1C1 標記法傳回指定範圍。

// Get a range A1:D4 on sheet titled "Invoices"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const range = ss.getRange('Invoices!A1:D4');

// Get cell A1 on the first sheet
const sheet = ss.getSheets()[0];
const cell = sheet.getRange('A1');

參數

名稱類型說明
a1NotationString要傳回的範圍,以 A1 標記法或 R1C1 標記法指定。

回攻員

Range:指定地點的範圍。

授權

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

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

getRangeList(a1Notations)

傳回 RangeList 集合,代表同一工作表中以非空白 A1 標記或 R1C1 標記清單指定的範圍。

// Get a list of ranges A1:D4, F1:H4.
const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
const rangeList = sheet.getRangeList(['A1:D4', 'F1:H4']);

參數

名稱類型說明
a1NotationsString[]要傳回的範圍清單,以 A1 標記法或 R1C1 標記法指定。

回攻員

RangeList - 指定位置的範圍清單。

授權

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

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

getRowGroup(rowIndex, groupDepth)

傳回指定索引和群組深度的列群組。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// Returns the group whose control index is at row 2 and has a depth of 1, or
// null if the group doesn’t exist.
const rowGroup = sheet.getRowGroup(2, 1);

參數

名稱類型說明
rowIndexInteger群組控制項切換開關的列索引,或群組內的索引。
groupDepthInteger群組的深度。

回攻員

Group|null - 控制索引和深度的列群組,或在群組不存在時擲回例外狀況。

授權

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

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

getRowGroupControlPosition()

傳回工作表上所有列群組的 GroupControlTogglePosition

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// GroupControlTogglePosition.AFTER if the row grouping control toggle is shown
// after the group.
const rowGroupControlPosition = sheet.getRowGroupControlPosition();

回攻員

GroupControlTogglePosition - true:如果工作表上的群組後方顯示列群組控制項切換按鈕,則為 false

授權

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

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

getRowGroupDepth(rowIndex)

傳回指定索引處資料列的群組深度。

群組深度是指與資料列重疊的群組數量。範圍介於零到八之間。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// 1 if there is a group over rows 1 through 3
const groupDepth = sheet.getRowGroupDepth(1);

參數

名稱類型說明
rowIndexInteger資料列的索引。

回攻員

Integer:指定索引處的列群組深度。

授權

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

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

getRowHeight(rowPosition)

取得指定列的高度 (以像素為單位)。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Rows start at 1
Logger.log(sheet.getRowHeight(1));

參數

名稱類型說明
rowPositionInteger要檢查的資料列位置。

回攻員

Integer:列高 (以像素為單位)。

授權

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

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

getSelection()

傳回試算表中的目前 Selection

const selection = SpreadsheetApp.getActiveSpreadsheet().getSelection();
const currentCell = selection.getCurrentCell();

回攻員

Selection:目前選取的項目。

授權

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

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

getSheetId()

傳回這個物件代表的試算表 ID。

這是試算表的專屬工作表 ID。這個 ID 是在建立工作表時指派的單調遞增整數,與工作表位置無關。這與 Range.copyFormatToRange(gridId, column, columnEnd, row, rowEnd) 等方法搭配使用時非常實用,因為這些方法會採用 gridId 參數,而非 Sheet 例項。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

Logger.log(sheet.getSheetId());

回攻員

Integer:試算表專屬的工作表 ID。

授權

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

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

getSheetName()

傳回工作表名稱。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

Logger.log(sheet.getSheetName());

回攻員

String:工作表的名稱。

授權

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

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

getSheetValues(startRow, startColumn, numRows, numColumns)

傳回這個範圍的值矩形格線,從指定座標開始。如果列或欄位置的值為 -1,就相當於取得工作表中含有資料的最後一列或最後一欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// The two samples below produce the same output
let values = sheet.getSheetValues(1, 1, 3, 3);
Logger.log(values);

const range = sheet.getRange(1, 1, 3, 3);
values = range.getValues();
Logger.log(values);

參數

名稱類型說明
startRowInteger起始列的位置。
startColumnInteger起始資料欄的位置。
numRowsInteger要傳回值的列數。
numColumnsInteger要傳回值的欄數。

回攻員

Object[][]:值的二維陣列。

授權

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

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

getSlicers()

傳回工作表上的篩選器陣列。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets all slicers in the spreadsheet.
const slicers = sheet.getSlicers();

// Logs the slicer titles to the console.
for (const slicer of slicers) {
  console.log(slicer.getTitle());
}

回攻員

Slicer[]:這份工作表中的篩選器清單。

授權

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

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

getTabColorObject()

取得工作表分頁標籤顏色,如果工作表分頁標籤沒有顏色,則為 null

// This example assumes there is a sheet named "Sheet1"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('Sheet1');
const color = first.getTabColorObject();

回攻員

Color|null - 工作表分頁標籤的顏色,或 null (如果工作表分頁標籤沒有顏色)。

授權

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

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

getType()

傳回工作表類型。

預設的試算表類型為 SheetType.GRID。如果工作表只包含單一嵌入物件 (例如 EmbeddedChart),則為 SheetType.OBJECT 工作表。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
Logger.log(sheet.getType());

回攻員

SheetType:工作表類型。

授權

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

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

hasHiddenGridlines()

如果工作表的格線已隱藏,則會傳回 true;否則會傳回 false。格線預設為顯示狀態。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Checks if the spreadsheet has hidden gridelines and logs the result to the
// console.
console.log(sheet.hasHiddenGridlines());

回攻員

Boolean - true (如果格線已隱藏);否則為 false

授權

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

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

hideColumn(column)

隱藏指定範圍中的欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This hides the first column
let range = sheet.getRange('A1');
sheet.hideColumn(range);

// This hides the first 3 columns
range = sheet.getRange('A:C');
sheet.hideColumn(range);

參數

名稱類型說明
columnRange要隱藏的欄範圍。

授權

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

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

hideColumns(columnIndex)

隱藏指定索引處的單一資料欄。這個方法使用 1 索引。

如要使用索引隱藏多個資料欄,請使用 hideColumns(columnIndex, numColumns)

如要使用範圍隱藏多個資料欄,請使用 hideColumn()

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Hides the first column
sheet.hideColumns(1);

參數

名稱類型說明
columnIndexInteger要隱藏的資料欄索引。

授權

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

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

hideColumns(columnIndex, numColumns)

隱藏從指定索引開始的一或多個連續資料欄。這個方法使用 1 索引。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Hides the first three columns
sheet.hideColumns(1, 3);

參數

名稱類型說明
columnIndexInteger要隱藏的資料欄起始索引。
numColumnsInteger要隱藏的欄數。

授權

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

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

hideRow(row)

隱藏指定範圍內的資料列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This hides the first row
const range = sheet.getRange('A1');
sheet.hideRow(range);

參數

名稱類型說明
rowRange要隱藏的資料列範圍。

授權

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

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

hideRows(rowIndex)

隱藏指定索引處的資料列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Hides the first row
sheet.hideRows(1);

參數

名稱類型說明
rowIndexInteger要隱藏的資料列索引。

授權

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

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

hideRows(rowIndex, numRows)

隱藏從指定索引開始的一或多個連續資料列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Hides the first three rows
sheet.hideRows(1, 3);

參數

名稱類型說明
rowIndexInteger要隱藏的資料列起始索引。
numRowsInteger要隱藏的列數。

授權

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

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

hideSheet()

隱藏這份工作表。如果工作表已隱藏,這個指令就不會產生任何作用。如果對唯一顯示的表單呼叫這個方法,系統會擲回例外狀況。

const sheet = SpreadsheetApp.getActiveSheet();
sheet.hideSheet();

回攻員

Sheet - 目前的工作表。

授權

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

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

insertChart(chart)

在這個工作表中新增圖表。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This creates a simple bar chart from the first three rows
// of the first two columns of the spreadsheet
const 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);

參數

名稱類型說明
chartEmbeddedChart要插入的圖表。

授權

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

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

insertColumnAfter(afterPosition)

在指定資料欄位置後插入資料欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This inserts a column after the first column position
sheet.insertColumnAfter(1);

參數

名稱類型說明
afterPositionInteger要在其後方新增資料欄的資料欄。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

insertColumnBefore(beforePosition)

在指定資料欄位置之前插入資料欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This inserts a column in the first column position
sheet.insertColumnBefore(1);

參數

名稱類型說明
beforePositionInteger新資料欄應新增至哪個資料欄的前方。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

insertColumns(columnIndex)

在工作表的指定位置插入空白欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Shifts all columns by one
sheet.insertColumns(1);

參數

名稱類型說明
columnIndexInteger指出要插入資料欄的索引。

授權

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

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

insertColumns(columnIndex, numColumns)

在工作表中指定的位置插入一或多個連續空白欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Shifts all columns by three
sheet.insertColumns(1, 3);

參數

名稱類型說明
columnIndexInteger指出要插入資料欄的索引。
numColumnsInteger要插入的欄數。

授權

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

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

insertColumnsAfter(afterPosition, howMany)

在指定欄位置後插入指定數量的欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Inserts two columns after the first column on the first sheet of the
// spreadsheet.
sheet.insertColumnsAfter(1, 2);

參數

名稱類型說明
afterPositionInteger要在其後方新增資料欄的資料欄。
howManyInteger要插入的欄數。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

insertColumnsBefore(beforePosition, howMany)

在指定欄位置之前插入多個欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This inserts five columns before the first column
sheet.insertColumnsBefore(1, 5);

參數

名稱類型說明
beforePositionInteger新資料欄應新增至哪個資料欄的前方。
howManyInteger要插入的欄數。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

insertImage(blobSource, column, row)

在文件的指定資料列和資料欄中,以圖片形式插入 BlobSource。系統會從 Blob 內容擷取圖片大小。支援的 blob 大小上限為 2 MB。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

const binaryData = [];  // TODO(developer): Replace with your binary data.
const blob = Utilities.newBlob(binaryData, 'image/png', 'MyImageName');
sheet.insertImage(blob, 1, 1);

參數

名稱類型說明
blobSourceBlobSource包含圖片內容、MIME 類型和 (選填) 名稱的 Blob。
columnInteger資料欄位置。
rowInteger資料列位置。

回攻員

OverGridImage:插入的圖片。

授權

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

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

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

在文件的指定列和欄中插入 BlobSource 做為圖片,並設定像素偏移量。系統會從 Blob 內容擷取圖片大小。支援的 blob 大小上限為 2 MB。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

const binaryData = [];  // TODO(developer): Replace with your binary data.
const blob = Utilities.newBlob(binaryData, 'image/png', 'MyImageName');
sheet.insertImage(blob, 1, 1, 10, 10);

參數

名稱類型說明
blobSourceBlobSource包含圖片內容、MIME 類型和 (選填) 名稱的 Blob。
columnInteger資料欄位置。
rowInteger資料列位置。
offsetXInteger以像素為單位的儲存格角落水平偏移。
offsetYInteger以像素為單位的儲存格角落垂直偏移。

回攻員

OverGridImage:插入的圖片。

授權

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

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

insertImage(url, column, row)

在文件的指定列和欄中插入圖片。

提供的網址必須可供公開存取。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

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

參數

名稱類型說明
urlString圖片的網址。
columnInteger格線欄位置。
rowInteger格線列位置。

回攻員

OverGridImage:插入的圖片。

授權

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

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

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

在指定列和欄中插入圖片,並設定像素偏移量。

提供的網址必須可供公開存取。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

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

參數

名稱類型說明
urlString圖片的網址。
columnInteger資料欄位置。
rowInteger資料列位置。
offsetXInteger以像素為單位的儲存格角落水平偏移。
offsetYInteger以像素為單位的儲存格角落垂直偏移。

回攻員

OverGridImage - 插入的圖片。

授權

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

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

insertRowAfter(afterPosition)

在指定資料列位置後插入資料列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This inserts a row after the first row position
sheet.insertRowAfter(1);

參數

名稱類型說明
afterPositionInteger要新增資料列的後方資料列。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

insertRowBefore(beforePosition)

在指定資料列位置之前插入資料列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This inserts a row before the first row position
sheet.insertRowBefore(1);

參數

名稱類型說明
beforePositionInteger要新增資料列的資料列。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

insertRows(rowIndex)

在工作表的指定位置插入空白列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Shifts all rows down by one
sheet.insertRows(1);

參數

名稱類型說明
rowIndexInteger指出要插入資料列的索引。

授權

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

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

insertRows(rowIndex, numRows)

在工作表中的指定位置插入一或多個連續空白列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Shifts all rows down by three
sheet.insertRows(1, 3);

參數

名稱類型說明
rowIndexInteger指出要插入資料列的索引。
numRowsInteger要插入的列數。

授權

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

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

insertRowsAfter(afterPosition, howMany)

在指定資料列位置後插入多列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This inserts five rows after the first row
sheet.insertRowsAfter(1, 5);

參數

名稱類型說明
afterPositionInteger新資料列應加入的資料列後方。
howManyInteger要插入的列數。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

insertRowsBefore(beforePosition, howMany)

在指定資料列位置之前插入多個資料列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This inserts five rows before the first row
sheet.insertRowsBefore(1, 5);

參數

名稱類型說明
beforePositionInteger新資料列應新增至此資料列之前。
howManyInteger要插入的列數。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

insertSlicer(range, anchorRowPos, anchorColPos)

在這個工作表中新增篩選器。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range of the sheet.
const range = sheet.getRange('A1:D10');

// Inserts the slicer with a random range into the sheet.
const insertSlicers = sheet.insertSlicer(range.randomize(), 1, 10);

// Logs the insert slicer result to the console.
console.log(insertSlicers);

參數

名稱類型說明
rangeRange建立篩選器的範圍。
anchorRowPosInteger這個資料列會固定為篩選器的頂端。
anchorColPosInteger這個 col 會錨定 Slicer 的頂端。

回攻員

Slicer:新插入的篩選器。

授權

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

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

insertSlicer(range, anchorRowPos, anchorColPos, offsetX, offsetY)

在這個工作表中新增篩選器。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets the range.
const range = sheet.getRange('A1:D10');

// Inserts a slicer using the random range function.
const insertSlicers = sheet.insertSlicer(range.randomize(), 1, 10, 0, 0);

// Logs the insert slicer result to the console.
console.log(insertSlicers);

參數

名稱類型說明
rangeRange建立篩選器的範圍。
anchorRowPosInteger這個資料列會固定為篩選器的頂端。
anchorColPosInteger這個 col 會錨定 Slicer 的頂端。
offsetXInteger以像素為單位的儲存格角落水平偏移。
offsetYInteger以像素為單位的儲存格角落垂直偏移。

回攻員

Slicer:新插入的篩選器。

授權

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

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

isColumnHiddenByUser(columnPosition)

傳回指定資料欄是否遭使用者隱藏。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Columns start at 1
Logger.log(sheet.isColumnHiddenByUser(1));

參數

名稱類型說明
columnPositionInteger要檢查的資料欄位置。

回攻員

Boolean:如果資料欄已隱藏,則為 true,否則為 false

授權

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

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

isRightToLeft()

如果這個工作表版面配置是從右至左,則傳回 true。如果工作表使用預設的從左到右版面配置,則會傳回 false

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Checks if a spreadsheet is ordered from right to left and logs the result to
// the console.
console.log(sheet.isRightToLeft());

回攻員

Boolean:如果是從右到左,則為 true;否則為 false

授權

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

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

isRowHiddenByFilter(rowPosition)

傳回指定資料列是否因篩選器 (而非篩選器檢視畫面) 而隱藏。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Rows start at 1
Logger.log(sheet.isRowHiddenByFilter(1));

參數

名稱類型說明
rowPositionInteger要檢查的資料列位置。

回攻員

Boolean:如果資料列已隱藏,則為 true,否則為 false

授權

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

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

isRowHiddenByUser(rowPosition)

傳回使用者是否隱藏指定列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Rows start at 1
Logger.log(sheet.isRowHiddenByUser(1));

參數

名稱類型說明
rowPositionInteger要檢查的資料列位置。

回攻員

Boolean:如果資料列已隱藏,則為 true,否則為 false

授權

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

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

isSheetHidden()

如果目前隱藏工作表,則傳回 true

const sheet = SpreadsheetApp.getActiveSheet();
if (sheet.isSheetHidden()) {
  // do something...
}

回攻員

Boolean:如果工作表已隱藏,則為 true,否則為 false

授權

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

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

moveColumns(columnSpec, destinationIndex)

將指定範圍選取的資料欄移至 destinationIndex 指示的位置。columnSpec 不必完全代表要移動的整欄或欄群組,因為它會選取範圍涵蓋的所有欄。

// The code below moves rows A-B to destination index 5.
// This results in those columns becoming columns C-D.
const sheet = SpreadsheetApp.getActiveSheet();
// Selects column A and column B to be moved.
const columnSpec = sheet.getRange('A1:B1');
sheet.moveColumns(columnSpec, 5);

參數

名稱類型說明
columnSpecRange要移動的資料欄所跨越的範圍。
destinationIndexInteger資料欄應移至的索引。請注意,這個索引是根據欄移動前的座標而定。現有資料會向右移動,為移動的資料欄騰出空間,來源資料欄則會從格線中移除。因此資料可能會進入與原先指定不同的索引。

授權

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

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

moveRows(rowSpec, destinationIndex)

將指定範圍選取的資料列移至 destinationIndex 指示的位置。rowSpec 本身不必完全代表要移動的整列或整組資料列,只要選取範圍涵蓋的所有資料列即可。

// The code below moves rows 1-2 to destination index 5.
// This results in those rows becoming rows 3-4.
const sheet = SpreadsheetApp.getActiveSheet();
// Selects row 1 and row 2 to be moved.
const rowSpec = sheet.getRange('A1:A2');
sheet.moveRows(rowSpec, 5);

參數

名稱類型說明
rowSpecRange要移動的資料列範圍。
destinationIndexInteger資料列應移至的索引。請注意,這個索引是根據移動列之前的座標。現有資料會向下移動,為移動的資料列騰出空間,而來源資料列則會從格線中移除。因此,資料可能會存放在與原始指定不同的索引中。

授權

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

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

newChart()

傳回建立這個工作表新圖表的建構工具。

這個範例說明如何建立新圖表:

const sheet = SpreadsheetApp.getActiveSheet();
const range = sheet.getRange('A1:B8');
const chartBuilder = sheet.newChart();
chartBuilder.addRange(range)
    .setChartType(Charts.ChartType.LINE)
    .setPosition(2, 2, 0, 0)
    .setOption('title', 'My Line Chart!');
sheet.insertChart(chartBuilder.build());

回攻員

EmbeddedChartBuilder:用於建立新圖表的建構工具。


protect()

建立物件,保護工作表不遭編輯,但具備權限的使用者除外。在指令碼實際變更試算表的編輯者清單之前 (透過呼叫 Protection.removeEditor(emailAddress)Protection.removeEditor(user)Protection.removeEditors(emailAddresses)Protection.addEditor(emailAddress)Protection.addEditor(user)Protection.addEditors(emailAddresses),或為 Protection.setDomainEdit(editable) 設定新值),權限會與試算表本身相同,這表示工作表實際上仍未受到保護。如果工作表已受保護,這個方法會傳回代表現有保護設定的物件。受保護的工作表可能包含未受保護的區域。

// Protect the active sheet, then remove all other users from the list of
// editors.
const sheet = SpreadsheetApp.getActiveSheet();
const 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.
const me = Session.getEffectiveUser();
protection.addEditor(me);
protection.removeEditors(protection.getEditors());
if (protection.canDomainEdit()) {
  protection.setDomainEdit(false);
}

回攻員

Protection:代表保護設定的物件。

授權

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

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

removeChart(chart)

從上層工作表移除圖表。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This removes all the embedded charts from the spreadsheet
const charts = sheet.getCharts();
for (const i in charts) {
  sheet.removeChart(charts[i]);
}

參數

名稱類型說明
chartEmbeddedChart要移除的圖表。

授權

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

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

setActiveRange(range)

將指定範圍設為作用中工作表中的 active range,且範圍左上角的儲存格為 current cell

const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
const range = sheet.getRange('A1:D4');
sheet.setActiveRange(range);

const selection = sheet.getSelection();
// Current cell: A1
const currentCell = selection.getCurrentCell();
// Active Range: A1:D4
const activeRange = selection.getActiveRange();

參數

名稱類型說明
rangeRange要設為有效範圍的範圍。

回攻員

Range:新啟用的範圍。

授權

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

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

setActiveRangeList(rangeList)

將指定範圍清單設為作用中工作表中的 active ranges。清單中的最後一個範圍會設為 active range

const sheet = SpreadsheetApp.getActiveSheet();
const rangeList = sheet.getRangeList(['D4', 'B2:C4']);
sheet.setActiveRangeList(rangeList);

const selection = sheet.getSelection();
// Current cell: B2
const currentCell = selection.getCurrentCell();
// Active range: B2:C4
const activeRange = selection.getActiveRange();
// Active range list: [D4, B2:C4]
const activeRangeList = selection.getActiveRangeList();

參數

名稱類型說明
rangeListRangeList可選取的範圍清單。

回攻員

RangeList:新選取的範圍清單。

授權

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

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

setActiveSelection(range)

為這個工作表設定有效選取區域。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

const range = sheet.getRange('A1:D4');
sheet.setActiveSelection(range);

參數

名稱類型說明
rangeRange要設為有效選取範圍的範圍。

回攻員

Range:新啟用的範圍。

授權

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

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

setActiveSelection(a1Notation)

設定以 A1 標記法或 R1C1 標記法指定的作用中選取範圍。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

sheet.setActiveSelection('A1:D4');

參數

名稱類型說明
a1NotationString要設為作用中的範圍,以 A1 標記法或 R1C1 標記法指定。

回攻員

Range:新啟用的範圍。

授權

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

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

setColumnGroupControlPosition(position)

設定工作表上欄群組控制項切換按鈕的位置。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
sheet.setColumnGroupControlPosition(
    SpreadsheetApp.GroupControlTogglePosition.AFTER,
);

參數

名稱類型說明
positionGroupControlTogglePosition欄群組控制項切換鈕的位置。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

setColumnWidth(columnPosition, width)

以像素為單位設定指定資料欄的寬度。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Sets the first column to a width of 200 pixels
sheet.setColumnWidth(1, 200);

參數

名稱類型說明
columnPositionInteger要設定的指定資料欄位置。
widthInteger要設定的寬度 (以像素為單位)。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

setColumnWidths(startColumn, numColumns, width)

以像素為單位設定指定資料欄的寬度。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Sets the first three columns to a width of 200 pixels
sheet.setColumnWidths(1, 3, 200);

參數

名稱類型說明
startColumnInteger要變更的起始欄位置。
numColumnsInteger要變更的欄數。
widthInteger要設定的寬度 (以像素為單位)。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

setConditionalFormatRules(rules)

以輸入規則取代工作表中目前的所有條件式格式規則。 系統會依輸入順序評估規則。

// Remove one of the existing conditional format rules.
const sheet = SpreadsheetApp.getActiveSheet();
const rules = sheet.getConditionalFormatRules();
rules.splice(1, 1);  // Deletes the 2nd format rule.
sheet.setConditionalFormatRules(rules);

參數

名稱類型說明
rulesConditionalFormatRule[]新的條件式格式規則。

授權

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

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

setCurrentCell(cell)

將指定儲存格設為 current cell

如果指定儲存格位於已選取的範圍中,該範圍就會成為有效範圍,且該儲存格會成為目前儲存格。

如果指定儲存格不在任何選取範圍內,系統會移除所有現有選取項目,並將該儲存格設為目前儲存格和有效範圍。

注意:指定的 Range 必須由一個儲存格組成,否則會擲回例外狀況。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
const cell = sheet.getRange('B5');
sheet.setCurrentCell(cell);

const selection = sheet.getSelection();
// Current cell: B5
const currentCell = selection.getCurrentCell();

參數

名稱類型說明
cellRange要設為目前儲存格的儲存格。

回攻員

Range:新設定的目前儲存格。

授權

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

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

setFrozenColumns(columns)

凍結指定欄數。如果為零,則不會凍結任何資料欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Freezes the first column
sheet.setFrozenColumns(1);

參數

名稱類型說明
columnsInteger要凍結的欄數。

授權

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

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

setFrozenRows(rows)

凍結指定列數。如果為零,則不會凍結任何資料列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Freezes the first row
sheet.setFrozenRows(1);

參數

名稱類型說明
rowsInteger要凍結的列數。

授權

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

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

setHiddenGridlines(hideGridlines)

隱藏或顯示工作表格線。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can us eSpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Hides the gridlines in the sheet.
sheet.setHiddenGridlines(true);

參數

名稱類型說明
hideGridlinesBoolean如果 true,則隱藏這個工作表中的格線;否則顯示格線。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

setName(name)

設定工作表名稱。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.setName('not first anymore');

參數

名稱類型說明
nameString工作表的新名稱。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

setRightToLeft(rightToLeft)

將工作表版面配置設為由右至左,或取消設定。

// Opens the spreadsheet file by its URL. If you created your script from within
// a Google Sheets file, you can use SpreadsheetApp.getActiveSpreadsheet()
// instead.
// TODO(developer): Replace the URL with your own.
const ss = SpreadsheetApp.openByUrl(
    'https://docs.google.com/spreadsheets/d/abc123456/edit',
);

// Gets a sheet by its name.
const sheet = ss.getSheetByName('Sheet1');

// Sets the sheet layout, so that the sheet is ordered from right to left.
sheet.setRightToLeft(true);

參數

名稱類型說明
rightToLeftBoolean如果為 true,工作表版面配置會設為從右到左,且儲存格 A1 位於右上角。如果設為 false,工作表版面配置會設為預設的從左到右,且儲存格 A1 位於左上角。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

setRowGroupControlPosition(position)

設定工作表上列群組控制項切換按鈕的位置。

const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
sheet.setRowGroupControlPosition(
    SpreadsheetApp.GroupControlTogglePosition.AFTER,
);

參數

名稱類型說明
positionGroupControlTogglePosition列群組控制項切換按鈕的位置。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

setRowHeight(rowPosition, height)

以像素為單位,設定指定資料列的高度。根據預設,系統會配合儲存格內容調整列的大小。如要強制將資料列設為特定高度,請使用 setRowHeightsForced(startRow, numRows, height)

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Sets the first row to a height of 200 pixels
sheet.setRowHeight(1, 200);

參數

名稱類型說明
rowPositionInteger要變更的列位置。
heightInteger要設定的高度 (以像素為單位)。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

setRowHeights(startRow, numRows, height)

以像素為單位設定指定列的高度。根據預設,系統會配合儲存格內容調整列的大小。如要強制將資料列設為特定高度,請使用 setRowHeightsForced(startRow, numRows, height)

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Sets the first three rows to a height of 20 pixels
sheet.setRowHeights(1, 3, 20);

參數

名稱類型說明
startRowInteger要變更的起始列位置。
numRowsInteger要變更的列數。
heightInteger要設定的高度 (以像素為單位)。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

setRowHeightsForced(startRow, numRows, height)

以像素為單位設定指定列的高度。根據預設,系統會配合儲存格內容調整列的大小。使用 setRowHeightsForced 時,即使儲存格內容高於列高,系統仍會強制將列高設為指定高度。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Sets the first three rows to a height of 5 pixels.
sheet.setRowHeightsForced(1, 3, 5);

參數

名稱類型說明
startRowInteger要變更的起始列位置。
numRowsInteger要變更的列數。
heightInteger要設定的高度 (以像素為單位)。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

setTabColor(color)

設定工作表分頁標籤顏色。

// This example assumes there is a sheet named "first"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('first');
first.setTabColor('ff0000');  // Set the color to red.
first.setTabColor(null);      // Unset the color.

參數

名稱類型說明
colorStringCSS 標記中的顏色代碼 (例如 '#ffffff''white'),或是 null,用來重設分頁顏色。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

setTabColorObject(color)

設定工作表分頁標籤顏色。

// This example assumes there is a sheet named "Sheet1"
const ss = SpreadsheetApp.getActiveSpreadsheet();
const first = ss.getSheetByName('Sheet1');
const color = SpreadsheetApp.newColor()
                  .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
                  .build();
first.setTabColorObject(color);  // Set the color to theme accent 1.
first.setTabColorObject(null);   // Unset the color.

參數

名稱類型說明
colorColor要設定的工作表分頁顏色。

回攻員

Sheet - This sheet, for chaining.

授權

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

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

showColumns(columnIndex)

取消隱藏指定索引處的資料欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Unhides the first column
sheet.showColumns(1);

參數

名稱類型說明
columnIndexInteger要取消隱藏的資料欄索引。

授權

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

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

showColumns(columnIndex, numColumns)

從指定索引開始,取消隱藏一或多個連續資料欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Unhides the first three columns
sheet.showColumns(1, 3);

參數

名稱類型說明
columnIndexInteger要取消隱藏的欄的起始索引。
numColumnsInteger要取消隱藏的欄數。

授權

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

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

showRows(rowIndex)

取消隱藏指定索引處的資料列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Unhides the first row
sheet.showRows(1);

參數

名稱類型說明
rowIndexInteger要取消隱藏的資料列索引。

授權

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

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

showRows(rowIndex, numRows)

從指定索引開始,取消隱藏一或多個連續資料列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];
// Unhides the first three rows
sheet.showRows(1, 3);

參數

名稱類型說明
rowIndexInteger要取消隱藏的資料列起始索引。
numRowsInteger要取消隱藏的列數。

授權

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

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

showSheet()

顯示工作表。如果工作表已顯示,這個指令就不會產生任何作用。

const sheet = SpreadsheetApp.getActiveSheet();
sheet.showSheet();

回攻員

Sheet - 目前的工作表。

授權

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

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

sort(columnPosition)

依欄遞增排序工作表。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Sorts the sheet by the first column, ascending
sheet.sort(1);

參數

名稱類型說明
columnPositionInteger做為排序依據的資料欄。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

sort(columnPosition, ascending)

依資料欄排序工作表。這個函式會採用參數來指定遞增或遞減。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// Sorts the sheet by the first column, descending
sheet.sort(1, false);

參數

名稱類型說明
columnPositionInteger做為排序依據的資料欄。
ascendingBooleantrue 代表遞增排序,false 代表遞減排序。

回攻員

Sheet:工作表,適用於方法鏈結。

授權

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

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

unhideColumn(column)

取消隱藏指定範圍內的資料欄。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This unhides the first column if it was previously hidden
const range = sheet.getRange('A1');
sheet.unhideColumn(range);

參數

名稱類型說明
columnRange要取消隱藏的範圍 (如有隱藏)。

授權

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

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

unhideRow(row)

取消隱藏指定範圍內的資料列。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This unhides the first row if it was previously hidden
const range = sheet.getRange('A1');
sheet.unhideRow(range);

參數

名稱類型說明
rowRange要取消隱藏的範圍 (如有隱藏)。

授權

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

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

updateChart(chart)

更新這個工作表中的圖表。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheets()[0];

// This code is going to loop through all the charts and change them to
// column charts
const charts = sheet.getCharts();
for (const i in charts) {
  const chart = charts[i];
  const newChart = chart.modify().setChartType(Charts.ChartType.COLUMN).build();
  sheet.updateChart(newChart);
}

參數

名稱類型說明
chartEmbeddedChart要更新的圖表。

授權

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

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

已淘汰的方法