Class Range

範圍

存取及修改試算表範圍。範圍可以是工作表中的單一儲存格,或試算表中相鄰的儲存格群組。

方法

方法傳回類型簡短說明
activate()Range將指定範圍設為 active range,範圍中的左上方的儲存格為 current cell
activateAsCurrentCell()Range將指定的儲存格設為 current cell
addDeveloperMetadata(key)Range將具有指定金鑰的開發人員中繼資料新增至範圍。
addDeveloperMetadata(key, visibility)Range將具有指定金鑰和瀏覽權限的開發人員中繼資料新增至範圍。
addDeveloperMetadata(key, value)Range將具有指定鍵和值的開發人員中繼資料新增至範圍。
addDeveloperMetadata(key, value, visibility)Range針對範圍新增具有指定鍵、值和瀏覽權限的開發人員中繼資料。
applyColumnBanding()Banding為範圍套用預設的資料欄色帶主題。
applyColumnBanding(bandingTheme)Banding將指定的欄帶化主題套用至範圍。
applyColumnBanding(bandingTheme, showHeader, showFooter)Banding將指定的資料欄色帶主題套用至包含指定標頭和頁尾設定的範圍。
applyRowBanding()Banding為範圍套用預設的列帶色主題。
applyRowBanding(bandingTheme)Banding將指定列的帶狀主題套用至範圍。
applyRowBanding(bandingTheme, showHeader, showFooter)Banding將指定列帶區主題套用至包含指定頁首和頁尾設定的範圍。
autoFill(destination, series)void根據這個範圍內的資料,在 destinationRange 中填入資料。
autoFillToNeighbor(series)void根據鄰近儲存格計算新資料的範圍,並根據這個範圍內包含的資料自動填入新值的範圍。
breakApart()Range再次將範圍中的任何多欄儲存格分割成個別儲存格。
canEdit()Boolean決定使用者是否有權編輯範圍內的所有儲存格。
check()Range將範圍中的核取方塊狀態變更為「已勾選」。
clear()Range清除內容和格式範圍。
clear(options)Range依照指定的進階選項,清除內容、格式、資料驗證規則和/或留言的範圍。
clearContent()Range清除範圍的內容,保留格式。
clearDataValidations()Range清除範圍的資料驗證規則。
clearFormat()Range清除這個範圍的格式設定。
clearNote()Range清除指定儲存格或儲存格中的附註。
collapseGroups()Range收合該範圍內的所有群組。
copyFormatToRange(gridId, column, columnEnd, row, rowEnd)void將範圍的格式複製到指定位置。
copyFormatToRange(sheet, column, columnEnd, row, rowEnd)void將範圍的格式複製到指定位置。
copyTo(destination)void將特定儲存格範圍的資料複製到其他儲存格範圍。
copyTo(destination, copyPasteType, transposed)void將特定儲存格範圍的資料複製到其他儲存格範圍。
copyTo(destination, options)void將特定儲存格範圍的資料複製到其他儲存格範圍。
copyValuesToRange(gridId, column, columnEnd, row, rowEnd)void將範圍的內容複製到指定位置。
copyValuesToRange(sheet, column, columnEnd, row, rowEnd)void將範圍的內容複製到指定位置。
createDataSourcePivotTable(dataSource)DataSourcePivotTable從資料來源建立空白資料來源資料透視表,並錨定於這個範圍的第一個儲存格。
createDataSourceTable(dataSource)DataSourceTable從資料來源建立空白資料來源資料表,固定於此範圍的第一個儲存格。
createDeveloperMetadataFinder()DeveloperMetadataFinder傳回 DeveloperMetadataFinderApi,尋找此範圍範圍內的開發人員中繼資料。
createFilter()Filter建立篩選器,並將其套用至工作表中的指定範圍。
createPivotTable(sourceData)PivotTable根據這個範圍內的第一個儲存格,以指定的 sourceData 建立空白資料透視表。
createTextFinder(findText)TextFinder為範圍建立文字搜尋器,以便找出並取代這個範圍中的文字。
deleteCells(shiftDimension)void刪除這個儲存格範圍。
expandGroups()Range展開收合的群組。
getA1Notation()String以 A1 標記法傳回範圍的字串說明。
getBackground()String傳回範圍中左上角儲存格的背景顏色 (例如 '#ffffff')。
getBackgroundObject()Color傳回範圍中左上角儲存格的背景顏色。
getBackgroundObjects()Color[][]傳回範圍內儲存格的背景顏色。
getBackgrounds()String[][]傳回範圍內儲存格的背景顏色 (例如 '#ffffff')。
getBandings()Banding[]傳回套用至這個範圍內任何儲存格的所有色帶。
getCell(row, column)Range傳回特定範圍內的指定儲存格。
getColumn()Integer傳回這個範圍的起始欄位置。
getDataRegion()Range傳回在四個基數 Direction 中展開的範圍副本,以涵蓋所有相鄰的儲存格含有資料。
getDataRegion(dimension)Range如果指定維度為 Dimension.ROWS,則傳回範圍展開 Direction.UPDirection.DOWN 的副本,如果維度是 Dimension.COLUMNS,則傳回 Direction.NEXTDirection.PREVIOUS
getDataSourceFormula()DataSourceFormula傳回範圍內第一個儲存格的 DataSourceFormula;如果儲存格不含資料來源公式,則傳回 null
getDataSourceFormulas()DataSourceFormula[]傳回範圍內儲存格的 DataSourceFormula
getDataSourcePivotTables()DataSourcePivotTable[]取得與指定範圍重疊的所有資料來源資料透視表。
getDataSourceTables()DataSourceTable[]取得與範圍重疊的所有資料來源資料表。
getDataSourceUrl()String傳回這個範圍內的資料網址,可用於建立圖表和查詢。
getDataTable()DataTable傳回這個物件內的資料做為 DataTable。
getDataTable(firstRowIsHeader)DataTable以 DataTable 的形式傳回這個範圍內的資料。
getDataValidation()DataValidation傳回範圍內左上方儲存格的資料驗證規則。
getDataValidations()DataValidation[][]傳回範圍內所有儲存格的資料驗證規則。
getDeveloperMetadata()DeveloperMetadata[]取得與這個範圍相關聯的開發人員中繼資料。
getDisplayValue()String傳回範圍中左上角儲存格的顯示值。
getDisplayValues()String[][]傳回這個範圍的值矩形格線。
getFilter()Filter傳回這個範圍所屬的工作表上篩選器;如果工作表上沒有篩選器,則傳回 null
getFontColorObject()Color傳回範圍左上角的儲存格字型顏色。
getFontColorObjects()Color[][]傳回範圍內儲存格的字型顏色。
getFontFamilies()String[][]傳回範圍內儲存格的字型系列。
getFontFamily()String傳回範圍左上角的儲存格字型系列。
getFontLine()String取得範圍左上角的儲存格線條樣式 ('underline''line-through''none')。
getFontLines()String[][]取得範圍中儲存格的線條樣式 ('underline''line-through''none')。
getFontSize()Integer傳回範圍左上角的儲存格點大小。
getFontSizes()Integer[][]傳回範圍內儲存格的字型大小。
getFontStyle()String傳回範圍左上角的儲存格字型樣式 ('italic''normal')。
getFontStyles()String[][]傳回範圍內儲存格的字型樣式。
getFontWeight()String傳回範圍左上角的儲存格字型粗細 (一般/粗體)。
getFontWeights()String[][]傳回範圍內儲存格的字型粗細。
getFormula()String傳回範圍左上方儲存格的公式 (A1 標記法);如果儲存格是空白或不含公式,則傳回空字串。
getFormulaR1C1()String傳回指定儲存格的公式 (R1C1 標記法);如果無,則傳回 null
getFormulas()String[][]傳回範圍內儲存格的公式 (A1 標記法)。
getFormulasR1C1()String[][]傳回範圍內儲存格的公式 (R1C1 標記法)。
getGridId()Integer傳回範圍父項工作表的格線 ID。
getHeight()Integer傳回範圍的高度。
getHorizontalAlignment()String傳回儲存格左上方角落的儲存格文字水平對齊方式 (左側/中間/右側)。
getHorizontalAlignments()String[][]傳回範圍內儲存格的水平對齊方式。
getLastColumn()Integer傳回結尾欄的位置。
getLastRow()Integer傳回結束列位置。
getMergedRanges()Range[]傳回 Range 物件陣列,這些物件代表的合併儲存格位於目前範圍內,或目前範圍中至少有一個儲存格。
getNextDataCell(direction)Range從範圍第一欄和範圍列的儲存格開始,以指定的方向傳回下一個儲存格,方向為指定方向的連續儲存格範圍,其中含有資料的儲存格範圍,或試算表邊緣的儲存格。
getNote()String傳回與指定範圍相關聯的附註。
getNotes()String[][]傳回與範圍內儲存格相關聯的附註。
getNumColumns()Integer傳回這個範圍中的欄數。
getNumRows()Integer傳回這個範圍中的列數。
getNumberFormat()String取得指定範圍的左上角儲存格的數字或日期格式。
getNumberFormats()String[][]傳回範圍內儲存格的數字或日期格式。
getRichTextValue()RichTextValue傳回範圍左上方儲存格的 RTF 值;如果儲存格值不是文字,則傳回 null
getRichTextValues()RichTextValue[][]傳回範圍內儲存格的 RTF 格式值。
getRow()Integer傳回這個範圍的列位置。
getRowIndex()Integer傳回這個範圍的列位置。
getSheet()Sheet傳回這個範圍所屬的工作表。
getTextDirection()TextDirection傳回範圍左上方儲存格的文字方向。
getTextDirections()TextDirection[][]傳回範圍內儲存格的文字方向。
getTextRotation()TextRotation傳回範圍左上方儲存格的文字旋轉設定。
getTextRotations()TextRotation[][]傳回範圍內儲存格的文字旋轉設定。
getTextStyle()TextStyle傳回範圍左上方儲存格的文字樣式。
getTextStyles()TextStyle[][]傳回範圍內儲存格的文字樣式。
getValue()Object傳回範圍中左上方的儲存格的值。
getValues()Object[][]傳回這個範圍的值矩形格線。
getVerticalAlignment()String傳回範圍左上角的儲存格垂直對齊 (頂部/中間/底部)。
getVerticalAlignments()String[][]傳回範圍內儲存格的垂直對齊方式。
getWidth()Integer傳回資料欄中範圍的寬度。
getWrap()Boolean傳回儲存格文字是否換行。
getWrapStrategies()WrapStrategy[][]傳回範圍內儲存格的文字換行策略。
getWrapStrategy()WrapStrategy傳回範圍左上方儲存格的文字換行策略。
getWraps()Boolean[][]傳回儲存格內的文字是否換行。
insertCells(shiftDimension)Range在這個範圍內插入空白儲存格。
insertCheckboxes()Range將核取方塊插入範圍中的每個儲存格,並將 true 設為已勾選,而 false 代表未勾選。
insertCheckboxes(checkedValue)Range將核取方塊插入範圍中的每個儲存格,已設定勾選的自訂值,以及未勾選的空字串。
insertCheckboxes(checkedValue, uncheckedValue)Range在範圍中的每個儲存格中插入核取方塊,並使用已勾選和未勾選狀態的自訂值進行設定。
isBlank()Boolean如果範圍完全空白,則傳回 true
isChecked()Boolean傳回範圍內所有儲存格的核取方塊狀態是否為「已勾選」。
isEndColumnBounded()Boolean決定範圍結尾是否繫結至特定資料欄。
isEndRowBounded()Boolean決定範圍結尾是否繫結至特定資料列。
isPartOfMerge()Boolean如果目前範圍內的儲存格與任何合併的儲存格重疊,則傳回 true
isStartColumnBounded()Boolean決定範圍的開頭是否受到特定欄約束。
isStartRowBounded()Boolean決定範圍的開頭是否繫結至特定資料列。
merge()Range將範圍內的儲存格合併成一個區塊。
mergeAcross()Range合併指定範圍中資料欄內的儲存格範圍。
mergeVertically()Range將範圍中的儲存格合併在一起。
moveTo(target)void剪下並貼上這個範圍 (格式和值) 到目標範圍。
offset(rowOffset, columnOffset)Range傳回從指定資料列數和欄數 (可以是負數) 與這個範圍之間偏移的新範圍 (可以是負數)。
offset(rowOffset, columnOffset, numRows)Range傳回相對於目前範圍的新範圍,其左上點會與指定的資料列與資料欄從目前範圍偏移,並在儲存格中指定高度。
offset(rowOffset, columnOffset, numRows, numColumns)Range傳回相對於目前範圍的新範圍,其左上點會與指定的資料列與資料欄偏移,從目前範圍偏移,以及在儲存格中指定高度和寬度。
protect()Protection建立可保護範圍,使其無法編輯範圍的物件,唯具備權限的使用者除外。
randomize()Range在指定範圍內隨機排序資料列。
removeCheckboxes()Range移除範圍內的所有核取方塊。
removeDuplicates()Range如果該範圍內的值與任何前一個資料列的值重複,系統會移除這個值。
removeDuplicates(columnsToCompare)Range在指定資料欄中,假如指定資料欄中包含與任何前列值重複的值,則該範圍會將其移除。
setBackground(color)Range設定 CSS 標記法 (例如 '#ffffff''white') 範圍內所有儲存格的背景顏色。
setBackgroundObject(color)Range設定範圍內所有儲存格的背景顏色。
setBackgroundObjects(color)Range設定背景顏色的矩形格線 (必須與這個範圍的尺寸相符)。
setBackgroundRGB(red, green, blue)Range使用 RGB 值將背景設為指定顏色 (含 0 到 255 之間的整數)。
setBackgrounds(color)Range設定背景顏色的矩形格線 (必須與這個範圍的尺寸相符)。
setBorder(top, left, bottom, right, vertical, horizontal)Range設定邊框屬性。
setBorder(top, left, bottom, right, vertical, horizontal, color, style)Range使用顏色和/或樣式設定邊框屬性。
setDataValidation(rule)Range為範圍內的所有儲存格設定一項資料驗證規則。
setDataValidations(rules)Range為範圍內的所有儲存格設定資料驗證規則。
setFontColor(color)Range設定 CSS 標記法 (例如 '#ffffff''white') 的字型顏色。
setFontColorObject(color)Range設定指定範圍的字型顏色。
setFontColorObjects(colors)Range設定字型顏色的矩形格線 (必須與此範圍的尺寸相符)。
setFontColors(colors)Range設定字型顏色的矩形格線 (必須與此範圍的尺寸相符)。
setFontFamilies(fontFamilies)Range設定字型系列的矩形格線 (必須與這個範圍的尺寸相符)。
setFontFamily(fontFamily)Range設定字型系列,例如「 相簿」或「Helvetica」。
setFontLine(fontLine)Range設定指定範圍的字型行樣式 ('underline''line-through''none')。
setFontLines(fontLines)Range設定線條樣式的矩形格線 (必須與這個範圍的尺寸相符)。
setFontSize(size)Range設定字型大小,也就是要使用的點大小。
setFontSizes(sizes)Range設定字型大小的矩形格線 (必須與此範圍的尺寸相符)。
setFontStyle(fontStyle)Range設定指定範圍 ('italic''normal') 的字型樣式。
setFontStyles(fontStyles)Range設定字型樣式的矩形格線 (必須與這個範圍的尺寸相符)。
setFontWeight(fontWeight)Range設定指定範圍的字型粗細 (一般/粗體)。
setFontWeights(fontWeights)Range設定字型粗細的矩形格線 (必須與這個範圍的尺寸相符)。
setFormula(formula)Range更新這個範圍的公式。
setFormulaR1C1(formula)Range更新這個範圍的公式。
setFormulas(formulas)Range設定公式的矩形格線 (必須與這個範圍的尺寸相符)。
setFormulasR1C1(formulas)Range設定公式的矩形格線 (必須與這個範圍的尺寸相符)。
setHorizontalAlignment(alignment)Range為指定範圍 (左/中間/右側) 設定水平 (由左至右) 對齊方式。
setHorizontalAlignments(alignments)Range設定水平對齊的矩形格線。
setNote(note)Range將附註設為指定值。
setNotes(notes)Range設定記事的矩形格線 (必須與這個範圍的尺寸相符)。
setNumberFormat(numberFormat)Range將數字或日期格式設為指定的格式字串。
setNumberFormats(numberFormats)Range設定數字或日期格式的矩形格線 (必須與此範圍的尺寸相符)。
setRichTextValue(value)Range設定範圍內儲存格的 RTF 格式值。
setRichTextValues(values)Range設定 RTF 值的矩形格線。
setShowHyperlink(showHyperlink)Range設定範圍是否應顯示超連結。
setTextDirection(direction)Range設定範圍中的儲存格文字方向。
setTextDirections(directions)Range設定文字路線的矩形格線。
setTextRotation(degrees)Range設定範圍中儲存格的文字旋轉設定。
setTextRotation(rotation)Range設定範圍中儲存格的文字旋轉設定。
setTextRotations(rotations)Range設定文字旋轉的矩形格線。
setTextStyle(style)Range設定範圍內儲存格的文字樣式。
setTextStyles(styles)Range設定文字樣式的矩形格線。
setValue(value)Range設定範圍的值。
setValues(values)Range設定值的矩形格線 (必須與這個範圍的尺寸相符)。
setVerticalAlignment(alignment)Range設定指定範圍 (頂端/中間/底部) 的垂直 (由上至下) 對齊方式。
setVerticalAlignments(alignments)Range設定垂直對齊的矩形格線 (必須與這個範圍的尺寸相符)。
setVerticalText(isVertical)Range設定是否要堆疊範圍內儲存格的文字堆疊。
setWrap(isWrapEnabled)Range設定指定範圍的儲存格換行。
setWrapStrategies(strategies)Range設定包裝策略的矩形格線。
setWrapStrategy(strategy)Range設定範圍中的儲存格文字換行策略。
setWraps(isWrapEnabled)Range設定字詞包裝政策的矩形格線 (尺寸必須符合這個範圍的尺寸)。
shiftColumnGroupDepth(delta)Range以指定的金額變更範圍的資料欄分組深度。
shiftRowGroupDepth(delta)Range以指定的金額變更範圍的資料列分組深度。
sort(sortSpecObj)Range依欄和指定順序排序指定範圍內的儲存格。
splitTextToColumns()void根據自動偵測的分隔符號將文字欄分割成多個資料欄。
splitTextToColumns(delimiter)void使用指定字串做為自訂分隔符號,將文字資料欄分割成多個資料欄。
splitTextToColumns(delimiter)void根據指定的分隔符號將文字欄分割成多個資料欄。
trimWhitespace()Range刪除這個範圍中所有儲存格中的空白字元 (例如空格、定位點或換行符號)。
uncheck()Range將範圍中的核取方塊狀態變更為「未勾選」。

內容詳盡的說明文件

activate()

將指定範圍設為 active range,範圍中的左上方的儲存格為 current cell

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var range = sheet.getRange('A1:D10');
range.activate();

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

回攻員

Range — 這個範圍,用於鏈結。


activateAsCurrentCell()

將指定的儲存格設為 current cell

如果指定儲存格出現在現有範圍中,則該範圍會成為有效範圍,並以儲存格做為目前儲存格。

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

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

// Gets the first sheet of the spreadsheet.
var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];

// Gets the cell B5 and sets it as the active cell.
var range = sheet.getRange('B5');
var currentCell = range.activateAsCurrentCell();

// Logs the activated cell.
console.log(currentCell.getA1Notation());

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');

// Adds the key 'NAME' to the developer metadata for row 2.
range.addDeveloperMetadata('NAME');

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

參數

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

回攻員

Range — 這個範圍,用於鏈結。

授權

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

  • 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on Sheet1.
const range = sheet.getRange('2:2');

// Adds the key 'NAME' and sets the developer metadata visibility to 'DOCUMENT'
// for row 2 on Sheet1.
range.addDeveloperMetadata('NAME', SpreadsheetApp.DeveloperMetadataVisibility.DOCUMENT);

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

參數

名稱類型說明
keyString新開發人員中繼資料的金鑰。
visibilityDeveloperMetadataVisibility新開發人員中繼資料的顯示設定。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

  • 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 of Sheet1.
const range = sheet.getRange('2:2');

// Adds the key 'NAME' and sets the value to 'GOOGLE' for the metadata of row 2.
range.addDeveloperMetadata('NAME', 'GOOGLE');

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

參數

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

回攻員

Range — 這個範圍,用於鏈結。

授權

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

  • 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');

// Adds the key 'NAME', sets the value to 'GOOGLE', and sets the visibility
// to PROJECT for row 2 on the sheet.
range.addDeveloperMetadata(
  'NAME',
  'GOOGLE',
  SpreadsheetApp.DeveloperMetadataVisibility.PROJECT);

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

參數

名稱類型說明
keyString新開發人員中繼資料的金鑰。
valueString新開發人員中繼資料的值。
visibilityDeveloperMetadataVisibility新開發人員中繼資料的顯示設定。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

applyColumnBanding()

為範圍套用預設的資料欄色帶主題。根據預設,色帶具有標題,且沒有頁尾顏色。

// 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');

// Applies column banding to row 2.
const colBanding = range.applyColumnBanding();

// Gets the first banding on the sheet and logs the color of the header column.
console.log(sheet.getBandings()[0].getHeaderColumnColorObject().asRgbColor().asHexString());

// Gets the first banding on the sheet and logs the color of the second column.
console.log(sheet.getBandings()[0].getSecondColumnColorObject().asRgbColor().asHexString());

回攻員

Banding — 全新色帶。

授權

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

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

applyColumnBanding(bandingTheme)

將指定的欄帶化主題套用至範圍。根據預設,色帶為標頭,且沒有頁尾顏色。

// 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on the sheet.
const range = sheet.getRange('2:2');

// Applies the INDIGO color banding theme to the columns in row 2.
const colBanding = range.applyColumnBanding(SpreadsheetApp.BandingTheme.INDIGO);

// Gets the first banding on the sheet and logs the color of the second column.
console.log(sheet.getBandings()[0].getSecondColumnColorObject().asRgbColor().asHexString());

參數

名稱類型說明
bandingThemeBandingTheme要套用至範圍中資料欄的顏色主題。

回攻員

Banding — 全新色帶。

授權

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

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

applyColumnBanding(bandingTheme, showHeader, showFooter)

將指定資料欄的色帶主題套用至包含指定標頭和頁尾設定的範圍。

// 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets rows 12-22 on the sheet.
const range = sheet.getRange('12:22');

// Applies the BLUE color banding theme to rows 12-22.
// Sets the header visibility to false and the footer visibility to true.
const colBanding = range.applyColumnBanding(SpreadsheetApp.BandingTheme.BLUE, false, true);

// Gets the banding color and logs it to the console.
console.log(sheet.getBandings()[0].getSecondColumnColorObject().asRgbColor().asHexString());

// Gets the header color object and logs it to the console. Returns null because the header
// visibility is set to false.
console.log(sheet.getBandings()[0].getHeaderColumnColorObject());

// Gets the footer color and logs it to the console.
console.log(sheet.getBandings()[0].getFooterColumnColorObject().asRgbColor().asHexString());

參數

名稱類型說明
bandingThemeBandingTheme要套用至範圍中資料欄的顏色主題。
showHeaderBoolean如果是 true,系統會將色帶主題標頭顏色套用至第一欄。
showFooterBoolean如果是 true,系統會將色帶主題的頁尾顏色套用至最後一欄。

回攻員

Banding — 全新色帶。

授權

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

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

applyRowBanding()

為範圍套用預設的列帶色主題。根據預設,色帶具有標題,且沒有頁尾顏色。

// Opens the spreadsheet 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 rows 1-30 on Sheet1.
const range = sheet.getRange('1:30');

// Applies row banding to rows 1-30.
range.applyRowBanding();

// Gets the hex color of the second banded row.
const secondRowColor = range.getBandings()[0]
                            .getSecondRowColorObject()
                            .asRgbColor()
                            .asHexString();

// Logs the hex color to console.
console.log(secondRowColor);

回攻員

Banding — 色帶。

授權

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

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

applyRowBanding(bandingTheme)

將指定列的帶狀主題套用至範圍。根據預設,色帶具有標題,且沒有頁尾顏色。

// Opens the spreadsheet 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 rows 1-30 on Sheet1.
const range = sheet.getRange('1:30');

// Applies the INDIGO row banding theme to rows 1-30.
range.applyRowBanding(SpreadsheetApp.BandingTheme.INDIGO);

// Gets the hex color of the second banded row.
const secondRowColor = range.getBandings()[0]
                            .getSecondRowColorObject()
                            .asRgbColor()
                            .asHexString();

// Logs the hex color to console.
console.log(secondRowColor);

參數

名稱類型說明
bandingThemeBandingTheme要套用至範圍內資料列的顏色主題。

回攻員

Banding — 全新色帶。

授權

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

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

applyRowBanding(bandingTheme, showHeader, showFooter)

將指定列帶區主題套用至包含指定標頭和頁尾設定的範圍。

// Opens the spreadsheet 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 rows 1-30 on Sheet1.
const range = sheet.getRange('1:30');

// Applies the INDIGO row banding to rows 1-30 and
// specifies to hide the header and show the footer.
range.applyRowBanding(SpreadsheetApp.BandingTheme.INDIGO, false, true);

參數

名稱類型說明
bandingThemeBandingTheme要套用至範圍內資料列的顏色主題。
showHeaderBoolean如果是 true,系統會將色條主題的標頭顏色套用至第一列。
showFooterBoolean如果是 true,系統會將色條主題的頁尾顏色套用至最後一列。

回攻員

Banding — 全新色帶。

授權

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

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

autoFill(destination, series)

根據這個範圍內的資料,在 destinationRange 中填入資料。新值也會由指定的 series 類型決定。目的地範圍必須包含這個範圍,且只能從一個方向延伸。舉例來說,下列函式會根據 A1:A4 中目前的值,將 A1:A20 填入一連串遞增的數字:

var sheet = SpreadsheetApp.getActiveSheet();

// Has values [1, 2, 3, 4].
var sourceRange = sheet.getRange("A1:A4");
// The range to fill with values.
var destination = sheet.getRange("A1:A20");

// Inserts new values in A5:A20, continuing the pattern expressed in A1:A4
sourceRange.autoFill(destination, SpreadsheetApp.AutoFillSeries.DEFAULT_SERIES);

參數

名稱類型說明
destinationRange要自動填入值的範圍。目的地範圍應包含這個範圍,且只能從一個方向延伸 (向上、向下、向左或向右)。
seriesAutoFillSeries用於計算新值的自動填入系列類型。本系列的效果會因來源資料的類型和數量而有所不同。

授權

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

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

autoFillToNeighbor(series)

根據鄰近儲存格計算新資料的範圍,並根據這個範圍內包含的資料自動填入新值的範圍。這些新值也會由指定的 series 類型決定。

計算出的目的地範圍會考量周遭資料以決定新值的插入位置:如果資料自動填入的資料欄左側或右側,新值只會延伸至相鄰的資料。

舉例來說,如果 A1:A20 填入一系列遞增的數字,且在包含一系列日期的 B1:B4 範圍呼叫此方法,則新值只會插入 B5:B20 中。如此一來,這些新值會「固定」到含有 A 欄值的儲存格。

var sheet = SpreadsheetApp.getActiveSheet();

// A1:A20 has values [1, 2, 3, ... 20].
// B1:B4 has values [1/1/2017, 1/2/2017, ...]
var sourceRange = sheet.getRange("B1:B4");

// Results in B5:B20 having values [1/5/2017, ... 1/20/2017]
sourceRange.autoFillToNeighbor(SpreadsheetApp.AutoFillSeries.DEFAULT_SERIES);

參數

名稱類型說明
seriesAutoFillSeries用於計算新值的自動填入系列類型。本系列的效果會因來源資料的類型和數量而有所不同。

授權

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

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

breakApart()

再次將範圍中的任何多欄儲存格分割成個別儲存格。

在範圍上呼叫這個函式,等同於選取範圍,然後依序點選「格式」>「合併儲存格」>「取消合併」

// Opens the spreadsheet 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 range A1:C6 on Sheet1.
const range = sheet.getRange('A1:C6');

// Unmerges the range A1:C6 into individual cells.
range.breakApart();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

canEdit()

決定使用者是否有權編輯範圍內的所有儲存格。試算表擁有者隨時可以編輯受保護的範圍和工作表。

// Opens the spreadsheet 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 range A1:C6 on Sheet1.
const range = sheet.getRange('A1:C6');

// Logs whether the user has permission to edit every cell in the range.
console.log(range.canEdit());

回攻員

Boolean:如果使用者有權編輯範圍內所有儲存格,則為 true;否則為 false

授權

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

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

check()

將範圍中的核取方塊狀態變更為「已勾選」。忽略目前範圍中不包含已勾選或未勾選值的儲存格。

// Changes the state of cells which currently contain either the checked or unchecked value
// configured in the range A1:B10 to 'checked'.
var range = SpreadsheetApp.getActive().getRange('A1:B10');
range.check();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

clear()

清除內容和格式範圍。

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

var range = sheet.getRange("A1:D10");
range.clear();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

clear(options)

依照指定的進階選項,清除內容、格式、資料驗證規則和/或留言的範圍。根據預設,系統會清除所有資料。

// The code below clears range C2:G7 in the active sheet, but preserves the format,
// data validation rules, and comments.
SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 5).clear({contentsOnly: true});

參數

名稱類型說明
optionsObject指定進階參數的 JavaScript 物件,如下所示。

進階參數

名稱類型說明
commentsOnlyBoolean是否只清除留言。
contentsOnlyBoolean是否只要清除內容。
formatOnlyBoolean是否要僅清除格式;請注意,清除格式會一併清除資料驗證規則。
validationsOnlyBoolean是否僅清除資料驗證規則。
skipFilteredRowsBoolean是否要清除已篩選的資料列。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

clearContent()

清除範圍中的內容,保留格式。

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

var range = sheet.getRange("A1:D10");
range.clearContent();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

clearDataValidations()

清除範圍的資料驗證規則。

// Clear the data validation rules for cells A1:B5.
var range = SpreadsheetApp.getActive().getRange('A1:B5');
range.clearDataValidations();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

clearFormat()

清除這個範圍的格式設定。

這會清除範圍內儲存格或儲存格的文字格式設定,但不會重設任何數字格式設定規則。

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

var range = sheet.getRange("A1:D10");
range.clearFormat();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

clearNote()

清除指定儲存格或儲存格中的附註。

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

var range = sheet.getRange("A1:D10");
range.clearNote();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

collapseGroups()

收合該範圍內的所有群組。如果沒有群組完全在範圍內,系統會收合該範圍內最深的展開群組。

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var range = sheet.getActiveRange();

// All row and column groups within the range are collapsed.
range.collapseGroups();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

copyFormatToRange(gridId, column, columnEnd, row, rowEnd)

將範圍的格式複製到指定位置。如果目的地大於或小於來源範圍,來源將會重複或由其截斷。請注意,這個方法只會複製格式。

如需 GRId 參數的詳細說明,請參閱 getGridId()

var ss = SpreadsheetApp.getActiveSpreadsheet();
var source = ss.getSheets()[0];

var range = source.getRange("B2:D4");

// This copies the formatting in B2:D4 in the source sheet to
// D4:F6 in the sheet with gridId 1555299895. Note that you can get the gridId
// of a sheet by calling sheet.getSheetId() or range.getGridId().
range.copyFormatToRange(1555299895, 4, 6, 4, 6);

參數

名稱類型說明
gridIdInteger試算表內工作表的專屬 ID (不限位置)。
columnInteger目標範圍的第一欄。
columnEndInteger目標範圍的結束資料欄。
rowInteger目標範圍的起始列。
rowEndInteger目標範圍的結束列。

授權

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

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

另請參閱


copyFormatToRange(sheet, column, columnEnd, row, rowEnd)

將範圍的格式複製到指定位置。如果目的地大於或小於來源範圍,來源將會重複或由其截斷。請注意,這個方法只會複製格式。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var source = ss.getSheets()[0];
var destination = ss.getSheets()[1];

var range = source.getRange("B2:D4");

// This copies the formatting in B2:D4 in the source sheet to
// D4:F6 in the second sheet
range.copyFormatToRange(destination, 4, 6, 4, 6);

參數

名稱類型說明
sheetSheet目標工作表。
columnInteger目標範圍的第一欄。
columnEndInteger目標範圍的結束資料欄。
rowInteger目標範圍的起始列。
rowEndInteger目標範圍的結束列。

授權

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

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

copyTo(destination)

將特定儲存格範圍的資料複製到其他儲存格範圍。系統會複製值和格式設定。

// The code below copies the first 5 columns over to the 6th column.
var sheet = SpreadsheetApp.getActiveSheet();
var rangeToCopy = sheet.getRange(1, 1, sheet.getMaxRows(), 5);
rangeToCopy.copyTo(sheet.getRange(1, 6));

參數

名稱類型說明
destinationRange要複製到的目的地範圍;只有左上角的儲存格位置才有關聯。

授權

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

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

copyTo(destination, copyPasteType, transposed)

將特定儲存格範圍的資料複製到另一個儲存格範圍。

// The code below copies only the values of the first 5 columns over to the 6th column.
var sheet = SpreadsheetApp.getActiveSheet();
sheet.getRange("A:E").copyTo(sheet.getRange("F1"), SpreadsheetApp.CopyPasteType.PASTE_VALUES,
false);

參數

名稱類型說明
destinationRange要複製到的目的地範圍;只有左上角的儲存格位置才有關聯。
copyPasteTypeCopyPasteType這個類型會指定將範圍內容貼到目的地的方式。
transposedBoolean是否應貼上範圍轉置的方向設定範圍。

授權

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

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

copyTo(destination, options)

將特定儲存格範圍的資料複製到其他儲存格範圍。根據預設,系統會複製值和格式設定,但可以使用進階引數覆寫這項設定。

// The code below copies only the values of the first 5 columns over to the 6th column.
var sheet = SpreadsheetApp.getActiveSheet();
sheet.getRange("A:E").copyTo(sheet.getRange("F1"), {contentsOnly:true});

參數

名稱類型說明
destinationRange要複製到的目的地範圍;只有左上角的儲存格位置才有關聯。
optionsObject指定進階參數的 JavaScript 物件,如下所示。

進階參數

名稱類型說明
formatOnlyBoolean指定只複製這個格式
contentsOnlyBoolean指定系統僅會複製內容

授權

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

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

copyValuesToRange(gridId, column, columnEnd, row, rowEnd)

將範圍的內容複製到指定位置。如果目的地大於或小於來源範圍,來源就會重複或遭到截斷。

如需 GRId 參數的詳細說明,請參閱 getGridId()

var ss = SpreadsheetApp.getActiveSpreadsheet();
var source = ss.getSheets()[0];

var range = source.getRange("B2:D4");

// This copies the data in B2:D4 in the source sheet to
// D4:F6 in the sheet with gridId 0
range.copyValuesToRange(0, 4, 6, 4, 6);

參數

名稱類型說明
gridIdInteger試算表內工作表的專屬 ID (不限位置)。
columnInteger目標範圍的第一欄。
columnEndInteger目標範圍的結束資料欄。
rowInteger目標範圍的起始列。
rowEndInteger目標範圍的結束列。

授權

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

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

另請參閱


copyValuesToRange(sheet, column, columnEnd, row, rowEnd)

將範圍的內容複製到指定位置。如果目的地大於或小於來源範圍,來源就會重複或遭到截斷。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var source = ss.getSheets()[0];
var destination = ss.getSheets()[1];

var range = source.getRange("B2:D4");

// This copies the data in B2:D4 in the source sheet to
// D4:F6 in the second sheet
range.copyValuesToRange(destination, 4, 6, 4, 6);

參數

名稱類型說明
sheetSheet目標工作表。
columnInteger目標範圍的第一欄。
columnEndInteger目標範圍的結束資料欄。
rowInteger目標範圍的起始列。
rowEndInteger目標範圍的結束列。

授權

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

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

createDataSourcePivotTable(dataSource)

從資料來源建立空白資料來源資料透視表,並錨定於這個範圍的第一個儲存格。

這個範例說明如何建立及設定新的資料來源資料透視表。

var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
var anchorCell = spreadsheet.getSheets()[0].getRange('A1');
var dataSource = spreadsheet.getDataSources()[0];

var pivotTable = anchorCell.createDataSourcePivotTable(dataSource);
pivotTable.addRowGroup('dataColumnA');
pivotTable.addColumnGroup('dataColumnB');
pivotTable.addPivotValue('dataColumnC', SpreadsheetApp.PivotTableSummarizeFunction.SUM);
pivotTable.addFilter('dataColumnA',
                     SpreadsheetApp.newFilterCriteria().whenTextStartsWith('A').build());

參數

名稱類型說明
dataSourceDataSource用來建立資料透視表的資料來源。

回攻員

DataSourcePivotTable:新建立的資料來源資料透視表。

授權

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

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

createDataSourceTable(dataSource)

從資料來源建立空白資料來源資料表,固定於此範圍的第一個儲存格。

這個範例說明如何建立及設定新的資料來源資料表。

var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
var anchorCell = spreadsheet.getSheets()[0].getRange('A1');
var dataSource = spreadsheet.getDataSources()[0];

var dataSourceTable = anchorCell.createDataSourceTable(dataSource);
    .addColumns('dataColumnA', 'dataColumnB', 'dataColumnC')
    .addSortSpec('dataColumnA', /* ascending= *\/ true)
    .addSortSpec('dataColumnB', /* ascending= *\/ false);

參數

名稱類型說明
dataSourceDataSource用來建立資料透視表的資料來源。

回攻員

DataSourceTable:新建立的資料來源資料表。

授權

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

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

createDeveloperMetadataFinder()

傳回 DeveloperMetadataFinderApi,尋找此範圍範圍內的開發人員中繼資料。中繼資料必須完全涵蓋在該範圍內,才位於範圍範圍內。舉例來說,與第 3:3 列相關的中繼資料不在「A1:D5」範圍的範圍內,但位於「1:5」範圍。

// 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

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

// Creates a developer metadata finder to search for metadata in the scope of this range.
const developerMetaDataFinder = range.createDeveloperMetadataFinder();

// Logs information about the developer metadata finder to the console.
const developerMetaData = developerMetaDataFinder.find()[0];
console.log(developerMetaData.getKey());
console.log(developerMetaData.getValue());
console.log(developerMetaData.getVisibility().toString());

回攻員

DeveloperMetadataFinder:開發人員中繼資料搜尋工具,用於搜尋這個範圍內的中繼資料。


createFilter()

建立篩選器,並將其套用至工作表中的指定範圍。每張工作表只能建立一個篩選器。如要在建立篩選器後存取及修改篩選器,請使用 getFilter()Sheet.getFilter()

let ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");

// Creates a new filter and applies it to the range A1:C20 on the active sheet.
function createFilter() {
  range.createFilter();
}
// Gets the filter and applies criteria that only shows cells that aren't empty.
function getFilterAddCriteria() {
  let filter = range.getFilter();
  let criteria = SpreadsheetApp.newFilterCriteria()
    .whenCellNotEmpty()
    .build();
  filter.setColumnFilterCriteria(2, criteria);
}
請使用這個方法為 Grid 工作表 (預設工作表類型) 建立篩選器。 格狀工作表是未連線至資料庫的工作表。如要建立其他類型的篩選器,請參閱以下資源:

回攻員

Filter:新的篩選器。

授權

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

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

createPivotTable(sourceData)

以指定的 sourceData 建立空白資料透視表,並錨定在這個範圍中的第一個儲存格。

// 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets cell A1 as a range in order to place the pivot table.
const range = sheet.getRange('A1');

// Gets the range of the source data for the pivot table.
const dataRange = sheet.getRange('E12:G20');

// Creates an empty pivot table from the specified source data.
const pivotTable = range.createPivotTable(dataRange);

// Logs the values from the pivot table's source data to the console.
console.log(pivotTable.getSourceDataRange().getValues());

參數

名稱類型說明
sourceDataRange要用來建立資料透視表的資料。

回攻員

PivotTable:新建立的 PivotTable

授權

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

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

createTextFinder(findText)

為範圍建立文字搜尋器,以便找出並取代這個範圍中的文字。

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var range = sheet.getActiveRange();

// Creates  a text finder for the range.
var textFinder = range.createTextFinder('dog');

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

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

參數

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

回攻員

TextFinder:範圍的 TextFinder


deleteCells(shiftDimension)

刪除這個儲存格範圍。工作表中的現有資料 (與提供的維度一起) 會轉移至刪除的範圍。

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

var range = sheet.getRange("A1:D10");
range.deleteCells(SpreadsheetApp.Dimension.COLUMNS);

參數

名稱類型說明
shiftDimensionDimension要改變現有資料的維度。

授權

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

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

expandGroups()

展開收合的群組。控制切換位置是指控制項切換鈕顯示在群組之前或之後的索引,視設定而定。如果同一個位置有多個群組,系統就會擴充該群組。

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var range = sheet.getActiveRange();

// All row and column groups within the range are expanded.
range.expandGroups();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

getA1Notation()

以 A1 標記法傳回範圍的字串說明。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange(1, 1, 2, 5);

// Logs "A1:E2"
Logger.log(range.getA1Notation());

回攻員

String:以 A1 標記法表示範圍的字串說明。

授權

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

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

getBackground()

傳回範圍內左上方的儲存格的背景顏色 (例如 '#ffffff')。

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

var cell = sheet.getRange("B5");
Logger.log(cell.getBackground());

回攻員

String — 背景的顏色代碼。

授權

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

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

getBackgroundObject()

傳回範圍中左上角儲存格的背景顏色。

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

var cell = sheet.getRange("B5");
Logger.log(cell.getBackgroundObject().asRgbColor().asHexString());

回攻員

Color:範圍左上方儲存格的背景顏色。

授權

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

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

getBackgroundObjects()

傳回範圍內儲存格的背景顏色。

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

var range = sheet.getRange("B5:C6");
var bgColors = range.getBackgroundObjects();
for (var i in bgColors) {
  for (var j in bgColors[i]) {
    Logger.log(bgColors[i][j].asRgbColor().asHexString());
  }
}

回攻員

Color[][]:背景顏色的二維陣列。

授權

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

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

getBackgrounds()

傳回範圍內儲存格的背景顏色 (例如 '#ffffff')。

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

var range = sheet.getRange("B5:C6");
var bgColors = range.getBackgrounds();
for (var i in bgColors) {
  for (var j in bgColors[i]) {
    Logger.log(bgColors[i][j]);
  }
}

回攻員

String[][]:背景色彩代碼的二維陣列。

授權

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

  • 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Sets a range.
const range = sheet.getRange('A1:K50');

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

// Logs the second row color for each banding to the console.
for (let banding of bandings) {
  console.log(banding.getSecondRowColor());
}

回攻員

Banding[] — 套用至這個範圍內任何儲存格的所有色帶。

授權

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

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

getCell(row, column)

傳回特定範圍內的指定儲存格。

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

var range = sheet.getRange("B2:D4");

// The row and column here are relative to the range
// getCell(1,1) in this code returns the cell at B2
var cell = range.getCell(1, 1);
Logger.log(cell.getValue());

參數

名稱類型說明
rowInteger儲存格相對於範圍的列。
columnInteger儲存格相對於範圍的資料欄。

回攻員

Range:指定座標處含有單一儲存格的範圍。

授權

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

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

getColumn()

傳回這個範圍的起始欄位置。

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

var range = sheet.getRange("B2:D4");
// Logs "2.0"
Logger.log(range.getColumn());

回攻員

Integer:試算表中範圍的起始欄位置。

授權

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

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

getDataRegion()

傳回在四個基數 Direction 中展開的範圍副本,以涵蓋所有相鄰的儲存格含有資料。如果範圍周圍環繞空白儲存格,但不包括對角線,則會傳回該範圍本身。這與在編輯器中選取範圍及輸入 Ctrl+A 類似。

// Assume the active spreadsheet is blank.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
sheet.getRange("C2").setValue(100);
sheet.getRange("B3").setValue(100);
sheet.getRange("D3").setValue(100);
sheet.getRange("C4").setValue(100);
// Logs "B2:D4"
Logger.log(sheet.getRange("C3").getDataRegion().getA1Notation());

回攻員

Range:範圍的資料地區或整份試算表的範圍。

授權

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

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

getDataRegion(dimension)

如果指定維度為 Dimension.ROWS,則傳回範圍展開 Direction.UPDirection.DOWN 的副本,如果維度是 Dimension.COLUMNS,則傳回 Direction.NEXTDirection.PREVIOUS。範圍擴展是根據在以資料表整理的範圍旁邊偵測資料而定。展開範圍會涵蓋所有相鄰的儲存格,其中含有資料,且會沿著指定維度呈現,範圍也包括表格邊界。如果原始範圍沿著指定維度圍繞空白儲存格,會傳回範圍本身。這個方法類似選取範圍,並在編輯器中為資料欄輸入 Ctrl+Space,或在編輯器中為資料列輸入 Shift+Space

// Assume the active spreadsheet is blank.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
sheet.getRange("C2").setValue(100);
sheet.getRange("B3").setValue(100);
sheet.getRange("D3").setValue(100);
sheet.getRange("C4").setValue(100);
// Logs "C2:C4"
Logger.log(sheet.getRange("C3").getDataRegion(SpreadsheetApp.Dimension.ROWS).getA1Notation());
// Logs "B3:D3"
Logger.log(
    sheet.getRange("C3").getDataRegion(SpreadsheetApp.Dimension.COLUMNS).getA1Notation());

參數

名稱類型說明
dimensionDimension要擴大範圍的維度。

回攻員

Range:範圍的資料地區,或是涵蓋原始範圍的每一欄或每一列的範圍。

授權

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

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

getDataSourceFormula()

傳回範圍內第一個儲存格的 DataSourceFormula;如果儲存格不含資料來源公式,則傳回 null

// 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 the range A1 on Sheet1.
const range = sheet.getRange('A1');

// Gets the data source formula from cell A1.
const dataSourceFormula = range.getDataSourceFormula();

// Gets the formula.
const formula = dataSourceFormula.getFormula();

// Logs the formula.
console.log(formula);

回攻員

DataSourceFormula:儲存格的 DataSourceFormula

授權

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

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

getDataSourceFormulas()

傳回範圍內儲存格的 DataSourceFormula

// 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 the range A1:B5 on Sheet1.
const range = sheet.getRange('A1:B5');

// Gets an array of the data source formulas in the range A1:B5.
const dataSourceFormulas = range.getDataSourceFormulas();

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

回攻員

DataSourceFormula[]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 the range A1:G50 on Sheet1.
const range = sheet.getRange('A1:G50');

// Gets an array of the data source pivot tables in the range A1:G50.
const dataSourcePivotTables = range.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 the range A1:G50 on Sheet1.
const range = sheet.getRange('A1:G50');

// Gets the first data source table in the range A1:G50.
const dataSourceTable = range.getDataSourceTables()[0];

// Logs the time of the last completed data execution on the data source table.
console.log(dataSourceTable.getStatus().getLastExecutionTime());

回攻員

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

授權

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

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

getDataSourceUrl()

傳回這個範圍內的資料網址,可用來建立圖表和查詢。

Code.gs

function doGet() {
  var ss = SpreadsheetApp.openById('1khO6hBWTNNyvyyxvob7aoZTI9ZvlqqASNeq0e29Tw2c');
  var sheet = ss.getSheetByName('ContinentData');
  var range = sheet.getRange('A1:B8');

  var template = HtmlService.createTemplateFromFile('piechart');
  template.dataSourceUrl = range.getDataSourceUrl();
  return template.evaluate();
}

piechart.html

<!DOCTYPE html>
<html>
  <head>
    <!--Load the AJAX API-->
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript">
      // Load the Visualization API and the corechart package.
      google.charts.load('current', {'packages': ['corechart']});

      // Set a callback to run when the Google Visualization API is loaded.
      google.charts.setOnLoadCallback(queryData);

      function queryData() {
        var query = new google.visualization.Query('<?= dataSourceUrl ?>');
        query.send(drawChart);
      }

      // Callback that creates and populates a data table,
      // instantiates the pie chart, passes in the data and
      // draws it.
      function drawChart(response) {
        if (response.isError()) {
          alert('Error: ' + response.getMessage() + ' ' + response.getDetailedMessage());
          return;
        }
        var data = response.getDataTable();

        // Set chart options.
        var options = {
          title: 'Population by Continent',
          width: 400,
          height: 300
        };

        // Instantiate and draw the chart, passing in some options.
        var chart = new google.visualization.PieChart(document.getElementById('chart_div'));
        chart.draw(data, options);
      }
    </script>
  </head>
  <body>
    <!-- Div that holds the pie chart. -->
    <div id="chart_div"></div>
  </body>
</html>

回攻員

String:這個範圍的網址做為資料來源,可傳遞至其他 API,例如圖表。

授權

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

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

getDataTable()

以 DataTable 的形式傳回這個物件內的資料。

// 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 the range A1:B7 on Sheet1.
const range = sheet.getRange('A1:B7');

// Gets the range A1:B7 as a data table. The values in each column must be of the same type.
const datatable = range.getDataTable();

// Uses the Charts service to build a bar chart from the data table.
// This doesn't build an embedded chart. To do that, use sheet.newChart().addRange() instead.
const chart = Charts.newBarChart()
                  .setDataTable(datatable)
                  .setOption('title', 'Your Chart Title Here')
                  .build();

回攻員

DataTable:將資料做為資料表。


getDataTable(firstRowIsHeader)

以 DataTable 的形式傳回這個範圍內的資料。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("A1:B7");

// Calling this method with "true" sets the first line to be the title of the axes
var datatable = range.getDataTable(true);

// Note that this doesn't build an EmbeddedChart, so you can't just use
// Sheet#insertChart(). To do that, use sheet.newChart().addRange() instead.
var chart = Charts.newBarChart()
    .setDataTable(datatable)
    .setOption("title", "Your Title Here")
    .build();

參數

名稱類型說明
firstRowIsHeaderBoolean是否要將第一列視為標題。

回攻員

DataTable:將資料做為資料表。

授權

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

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

getDataValidation()

傳回範圍內左上方儲存格的資料驗證規則。如果儲存格尚未設定資料驗證,這個方法會傳回 null

// Log information about the data validation rule for cell A1.
var cell = SpreadsheetApp.getActive().getRange('A1');
var rule = cell.getDataValidation();
if (rule != null) {
  var criteria = rule.getCriteriaType();
  var args = rule.getCriteriaValues();
  Logger.log('The data validation rule is %s %s', criteria, args);
} else {
  Logger.log('The cell does not have a data validation rule.')
}

回攻員

DataValidation:範圍中左上角儲存格的資料驗證規則。

授權

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

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

getDataValidations()

傳回範圍內所有儲存格的資料驗證規則。如果尚未在特定儲存格上設定資料驗證,這個方法會針對該儲存格在陣列中的位置傳回 null

// Change existing data validation rules that require a date in 2013 to require a date in 2014.
var oldDates = [new Date('1/1/2013'), new Date('12/31/2013')];
var newDates = [new Date('1/1/2014'), new Date('12/31/2014')];
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange(1, 1, sheet.getMaxRows(), sheet.getMaxColumns());
var rules = range.getDataValidations();

for (var i = 0; i < rules.length; i++) {
  for (var j = 0; j < rules[i].length; j++) {
    var rule = rules[i][j];

    if (rule != null) {
      var criteria = rule.getCriteriaType();
      var args = rule.getCriteriaValues();

      if (criteria == SpreadsheetApp.DataValidationCriteria.DATE_BETWEEN
          && args[0].getTime() == oldDates[0].getTime()
          && args[1].getTime() == oldDates[1].getTime()) {
        // Create a builder from the existing rule, then change the dates.
        rules[i][j] = rule.copy().withCriteria(criteria, newDates).build();
      }
    }
  }
}
range.setDataValidations(rules);

回攻員

DataValidation[][]:與範圍內儲存格相關聯的資料驗證規則二維陣列。

授權

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

  • 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets row 2 on Sheet1.
const range = sheet.getRange('2:2');

// Adds metadata to row 2.
range.addDeveloperMetadata('NAME', 'GOOGLE');

// Logs the metadata to console.
for (const metadata of range.getDeveloperMetadata()) {
  console.log(`${metadata.getKey()}: ${metadata.getValue()}`);
}

回攻員

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

授權

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

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

getDisplayValue()

傳回範圍中左上角儲存格的顯示值。這個值是 String。顯示的值會考量日期、時間和貨幣格式設定,包括由試算表的語言代碼設定自動套用的格式。空白儲存格會傳回空字串。

// 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets cell A30 and sets its value to 'Test code.'
const cell = sheet.getRange('A30');
cell.setValue('Test code');

// Gets the value and logs it to the console.
console.log(cell.getDisplayValue());

回攻員

String:這個儲存格中顯示的值。

授權

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

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

getDisplayValues()

傳回這個範圍的值矩形格線。

傳回顯示值的二維陣列,請先依列和欄建立索引。這些值為 String 物件。顯示的值會考量日期、時間和貨幣格式設定,包括由試算表語言代碼設定自動套用的格式。空白儲存格會以陣列中的空字串表示。請注意,雖然範圍索引是從 1, 1 開始,但 JavaScript 陣列是從 [0][0] 建立索引。

// The code below gets the displayed values for the range C2:G8
// in the active spreadsheet.  Note that this is a JavaScript array.
var values = SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getDisplayValues();
Logger.log(values[0][0]);

回攻員

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

授權

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

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

getFilter()

傳回這個範圍所屬的工作表上篩選器;如果工作表上沒有篩選器,則傳回 null

let ss = SpreadsheetApp.getActiveSheet();
let range = ss.getRange("A1:C20");
// Gets the existing filter on the sheet that the given range belongs to.
let filter = range.getFilter();

回攻員

Filter:篩選器。

授權

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

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

getFontColorObject()

傳回範圍左上角的儲存格字型顏色。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getFontColorObject().asRgbColor().asHexString());

回攻員

Color:範圍左上方儲存格的字型顏色。

授權

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

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

getFontColorObjects()

傳回範圍內儲存格的字型顏色。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getFontColorObjects();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j].asRgbColor().asHexString());
  }
}

回攻員

Color[][]:與範圍內儲存格相關聯的 2D 字型顏色陣列。

授權

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

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

getFontFamilies()

傳回範圍內儲存格的字型系列。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getFontFamilies();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

回攻員

String[][]:與範圍內儲存格相關聯的 2D 字型系列陣列。

授權

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

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

getFontFamily()

傳回範圍左上角的儲存格字型系列。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getFontFamily());

回攻員

String — 儲存格的字型系列。

授權

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

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

getFontLine()

取得範圍左上角的儲存格線條樣式 ('underline''line-through''none')。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getFontLine());

回攻員

String — 字型行。

授權

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

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

getFontLines()

取得範圍中儲存格的線條樣式 ('underline''line-through''none')。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getFontLines();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

回攻員

String[][]:與範圍內儲存格相關聯的二維字型陣列。

授權

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

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

getFontSize()

傳回範圍左上角的儲存格點大小。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getFontSize());

回攻員

Integer:以點數表示的字型大小。

授權

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

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

getFontSizes()

傳回範圍內儲存格的字型大小。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getFontSizes();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

回攻員

Integer[][]:與範圍內儲存格相關聯的文字字型大小陣列。

授權

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

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

getFontStyle()

傳回範圍左上角的儲存格字型樣式 ('italic''normal')。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getFontStyle());

回攻員

String:儲存格文字的字型樣式。

授權

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

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

getFontStyles()

傳回範圍內儲存格的字型樣式。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getFontStyles();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

回攻員

String[][]:與範圍內儲存格相關聯的文字樣式的二維字型陣列。

授權

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

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

getFontWeight()

傳回範圍左上角的儲存格字型粗細 (一般/粗體)。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getFontWeight());

回攻員

String:儲存格文字的字型粗細。

授權

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

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

getFontWeights()

傳回範圍內儲存格的字型粗細。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getFontWeights();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

回攻員

String[][]:與範圍內儲存格相關聯的文字粗細的二維陣列。

授權

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

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

getFormula()

傳回範圍左上方儲存格的公式 (A1 標記法);如果儲存格是空白或不含公式,則傳回空字串。

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

// This assumes you have a function in B5 that sums up
// B2:B4
var range = sheet.getRange("B5");

// Logs the calculated value and the formula
Logger.log("Calculated value: %s Formula: %s",
           range.getValue(),
           range.getFormula());

回攻員

String:儲存格的公式。

授權

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

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

getFormulaR1C1()

傳回指定儲存格的公式 (R1C1 標記法);如果無,則傳回 null

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

var range = sheet.getRange("B5");
var formula = range.getFormulaR1C1();
Logger.log(formula);

回攻員

String:R1C1 標記法中的公式。

授權

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

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

getFormulas()

傳回範圍內儲存格的公式 (A1 標記法)。如果儲存格不含公式,則 2D 陣列中的項目會是空白字串。

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

var range = sheet.getRange("B5:C6");
var formulas = range.getFormulas();
for (var i in formulas) {
  for (var j in formulas[i]) {
    Logger.log(formulas[i][j]);
  }
}

回攻員

String[][]:字串格式的二維公式陣列。

授權

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

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

getFormulasR1C1()

傳回範圍內儲存格的公式 (R1C1 標記法)。如果儲存格沒有公式,則 2D 陣列中的項目為 null

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

var range = sheet.getRange("B5:C6");
var formulas = range.getFormulasR1C1();
for (var i in formulas) {
  for (var j in formulas[i]) {
    Logger.log(formulas[i][j]);
  }
}

回攻員

String[][]:R1C1 標記法的二維公式陣列。

授權

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

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

getGridId()

傳回範圍父項工作表的格線 ID。ID 是隨機非負數的整數值。

// Log the grid ID of the first sheet (by tab position) in the spreadsheet.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getGridId());

回攻員

Integer:父項工作表的格線 ID。

授權

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

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

getHeight()

傳回範圍的高度。

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

var range = sheet.getRange("B2:D4");
// logs 3.0
Logger.log(range.getHeight());

回攻員

Integer — 範圍的高度。

授權

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

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

getHorizontalAlignment()

傳回範圍左上方中儲存格文字的水平對齊方式 (左側/中間/右側)。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getHorizontalAlignment());

回攻員

String:儲存格文字的水平對齊方式。

授權

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

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

getHorizontalAlignments()

傳回範圍內儲存格的水平對齊方式。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getHorizontalAlignments();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

回攻員

String[][]:與範圍內儲存格相關聯的文字水平對齊陣列。

授權

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

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

getLastColumn()

傳回結尾欄的位置。

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

var range = sheet.getRange("B2:D4");
// Logs "4.0"
Logger.log(range.getLastColumn());

回攻員

Integer:試算表中範圍的結束欄位置。

授權

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

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

getLastRow()

傳回結束列位置。

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

var range = sheet.getRange("B2:D4");
// Logs "4.0"
Logger.log(range.getLastRow());

回攻員

Integer:試算表中範圍的結束列位置。

授權

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

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

getMergedRanges()

傳回 Range 物件陣列,這些物件代表的合併儲存格位於目前範圍內,或目前範圍中至少有一個儲存格。

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

var range = sheet.getRange("A1:B3");

var mergedRanges = range.getMergedRanges();
for (var i = 0; i < mergedRanges.length; i++) {
  Logger.log(mergedRanges[i].getA1Notation());
  Logger.log(mergedRanges[i].getDisplayValue());
}

回攻員

Range[]Range 物件的陣列,代表與範圍重疊的合併儲存格。


getNextDataCell(direction)

從範圍第一欄和範圍列的儲存格開始,以指定的方向傳回下一個儲存格,方向為指定方向的連續儲存格範圍,其中含有資料的儲存格範圍,或試算表邊緣的儲存格。這相當於在編輯器中輸入 Ctrl+[arrow key]

// Assume the active spreadsheet is blank.
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];

var range = sheet.getRange("C3:E5");
// Logs "C1"
Logger.log(range.getNextDataCell(SpreadsheetApp.Direction.UP).getA1Notation());

參數

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

回攻員

Range:資料區域邊緣儲存格或試算表邊緣的儲存格。

授權

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

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

getNote()

傳回與指定範圍相關聯的附註。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getNote());

回攻員

String:與指定儲存格相關聯的附註。

授權

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

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

getNotes()

傳回與範圍內儲存格相關聯的附註。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getNotes();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

回攻員

String[][]:與範圍內儲存格相關聯的二維陣列陣列。

授權

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

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

getNumColumns()

傳回這個範圍內的欄數。

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

var range = sheet.getRange("B2:D5");
Logger.log(range.getNumColumns());

回攻員

Integer:這個範圍中的欄數。

授權

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

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

getNumRows()

傳回這個範圍內的列數。

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

var range = sheet.getRange("B2:D5");
Logger.log(range.getNumRows());

回攻員

Integer:這個範圍中的列數。

授權

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

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

getNumberFormat()

取得指定範圍的左上角儲存格的數字或日期格式。如要瞭解傳回的格式模式,請參閱 Sheets API 說明文件

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

var cell = sheet.getRange("C4");
Logger.log(cell.getNumberFormat());

回攻員

String:範圍左上方儲存格的數字格式。

授權

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

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

getNumberFormats()

傳回範圍內儲存格的數字或日期格式。如需回傳的格式模式,請參閱 Sheets API 說明文件

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

var range = sheet.getRange("B5:C6");
var formats = range.getNumberFormats();
for (var i in formats) {
  for (var j in formats[i]) {
    Logger.log(formats[i][j]);
  }
}

回攻員

String[][]:數字格式的二維陣列。

授權

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

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

getRichTextValue()

傳回範圍左上方儲存格的 RTF 值;如果儲存格值不是文字,則傳回 null

// Gets the Rich Text value of cell D4.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("D4:F6");
var richText = range.getRichTextValue();
console.log(richText.getText());

回攻員

RichTextValue:範圍中左上角儲存格的 RTF 值,如果儲存格值不是文字,則為 null

授權

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

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

getRichTextValues()

傳回範圍內儲存格的 RTF 值。

// Gets the Rich Text values for all cells in range B5:C6
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
var values = range.getRichTextValues();

for (var i = 0; i < values.length; i++) {
  for (var j = 0; j < values[i].length; j++) {
    console.log(values[i][j].getText());
  }
}

回攻員

RichTextValue[][]:RTF 值的二維陣列。

授權

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

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

getRow()

傳回這個範圍的列位置。與 getRowIndex() 相同。

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

var range = sheet.getRange("B2");
Logger.log(range.getRow());

回攻員

Integer — 範圍的列位置。

授權

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

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

getRowIndex()

傳回這個範圍的列位置。與 getRow() 相同。

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

var range = sheet.getRange("B2");
Logger.log(range.getRowIndex());

回攻員

Integer — 範圍的列位置。

授權

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

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

另請參閱


getSheet()

傳回這個範圍所屬的工作表。

// 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

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

// Gets the sheet that the range belongs to.
const rangeSheet = range.getSheet();

// Gets the sheet name and logs it to the console.
console.log(rangeSheet.getName());

回攻員

Sheet:這個範圍所屬的工作表。

授權

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

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

getTextDirection()

傳回範圍左上方儲存格的文字方向。如果透過自動偵測功能判定儲存格文字方向,系統會傳回 null

// Get the text direction of cell B1.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B1:D4");
Logger.log(range.getTextDirection());

回攻員

TextDirection:範圍中左上角儲存格的文字方向。

授權

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

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

getTextDirections()

傳回範圍內儲存格的文字方向。對於採用自動偵測的儲存格,2D 陣列中的項目為 null

// Get the text directions for all cells in range B5:C6
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
var directions = range.getTextDirections();

for (var i = 0; i < directions.length; i++) {
  for (var j = 0; j < directions[i].length; j++) {
    Logger.log(directions[i][j]);
  }
}

回攻員

TextDirection[][]:文字路線的二維陣列。

授權

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

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

getTextRotation()

傳回範圍左上方儲存格的文字旋轉設定。

// Log the text rotation settings for a cell.
var sheet = SpreadsheetApp.getActiveSheet();

var cell = sheet.getRange("A1");
Logger.log(cell.getTextRotation());

回攻員

TextRotation:文字旋轉設定。

授權

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

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

getTextRotations()

傳回範圍內儲存格的文字旋轉設定。

var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B2:D4");

var results = range.getTextRotations();

for (var i in results) {
  for (var j in results[i]) {
    var rotation = results[i][j];
    Logger.log("Cell [%s, %s] has text rotation: %v", i, j, rotation);
  }
}

回攻員

TextRotation[][]:與範圍內儲存格相關聯的 2D 文字旋轉陣列。

授權

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

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

getTextStyle()

傳回範圍左上方儲存格的文字樣式。

// Get the text style of cell D4.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("D4:F6");
var style = range.getTextStyle();
Logger.log(style);

回攻員

TextStyle:範圍中左上角儲存格的文字樣式。

授權

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

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

getTextStyles()

傳回範圍內儲存格的文字樣式。

// Get the text styles for all cells in range B5:C6
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
var styles = range.getTextStyles();

for (var i = 0; i < styles.length; i++) {
  for (var j = 0; j < styles[i].length; j++) {
    Logger.log(styles[i][j]);
  }
}

回攻員

TextStyle[][]:文字樣式的二維陣列。

授權

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

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

getValue()

傳回範圍中左上方的儲存格的值。視儲存格的值而定,這個值可能是 NumberBooleanDateString 類型。空白儲存格會傳回空字串。

// 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

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

// Gets the value of the top-left cell in the range and logs it to the console.
console.log(range.getValue());

回攻員

Object:這個儲存格中的值。

授權

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

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

getValues()

傳回這個範圍的值矩形格線。

傳回值的二維陣列,請先依列和欄建立索引。視儲存格的值而定,值的類型可能是 NumberBooleanDateString。空白儲存格會以陣列中的空字串表示。請注意,雖然範圍索引是從 1, 1 開始,但 JavaScript 陣列是從 [0][0] 建立索引。

// The code below gets the values for the range C2:G8
// in the active spreadsheet.  Note that this is a JavaScript array.
var values = SpreadsheetApp.getActiveSheet().getRange(2, 3, 6, 4).getValues();
Logger.log(values[0][0]);
在網頁應用程式中,Date 值不是法律參數,如果範圍包含含有 Date 值的儲存格,getValues() 無法將資料傳回網頁應用程式。請改為將所有從工作表擷取到的值轉換為支援的 JavaScript 原始值,例如 NumberBooleanString

回攻員

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

授權

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

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

getVerticalAlignment()

傳回範圍左上角的儲存格垂直對齊 (頂部/中間/底部)。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getVerticalAlignment());

回攻員

String:儲存格文字的垂直對齊方式。

授權

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

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

getVerticalAlignments()

傳回範圍內儲存格的垂直對齊方式。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getVerticalAlignments();

for (var i in results) {
  for (var j in results[i]) {
    Logger.log(results[i][j]);
  }
}

回攻員

String[][]:與範圍內儲存格相關聯的文字垂直對齊的二維陣列。

授權

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

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

getWidth()

傳回資料欄中範圍的寬度。

// 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

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

// Gets the width of the range in number of columns and logs it to the console.
console.log(range.getWidth());

回攻員

Integer:範圍中的欄數。

授權

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

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

getWrap()

傳回儲存格文字是否換行。如要取得更精細的包裝策略,請使用 getWrapStrategy()

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.getWrap());

回攻員

Boolean:這個儲存格中的文字是否換行。

授權

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

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

getWrapStrategies()

傳回範圍內儲存格的文字換行策略。

// Get the text wrapping strategies for all cells in range B5:C6
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
var strategies = range.getWrapStrategies();

for (var i = 0; i < strategies.length; i++) {
  for (var j = 0; j < strategies[i].length; j++) {
    Logger.log(strategies[i][j]);
  }
}

回攻員

WrapStrategy[][]:文字包裝策略的二維陣列。

授權

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

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

getWrapStrategy()

傳回範圍左上方儲存格的文字換行策略。

// Get the text wrapping strategy of cell B1.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B1:D4");
Logger.log(range.getWrapStrategy());

回攻員

WrapStrategy:範圍中左上角儲存格的文字換行策略。

授權

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

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

getWraps()

傳回儲存格內的文字是否換行。如要取得更精細的包裝策略,請使用 getWrapStrategies()

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

var results = range.getVerticalAlignments();

for (var i in results) {
  for (var j in results[i]) {
    var isWrapped = results[i][j];
    if (isWrapped) {
       Logger.log("Cell [%s, %s] has wrapped text", i, j);
    }
  }
}

回攻員

Boolean[][]:與範圍內儲存格相關聯的文字垂直對齊的二維陣列。

授權

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

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

insertCells(shiftDimension)

在這個範圍內插入空白儲存格。新儲存格會保留先前佔用這個範圍的儲存格中的任何格式設定。工作表中現有資料會與提供的維度一起從插入的範圍移出。

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

var range = sheet.getRange("A1:D10");
range.insertCells(SpreadsheetApp.Dimension.COLUMNS);

參數

名稱類型說明
shiftDimensionDimension要改變現有資料的維度。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

insertCheckboxes()

將核取方塊插入範圍中的每個儲存格,並將 true 設為已勾選,而 false 代表未勾選。將範圍內所有儲存格的值設為 false

var range = SpreadsheetApp.getActive().getRange('A1:B10');

// Inserts checkboxes into each cell in the range A1:B10 configured with 'true' for checked
// and 'false' for unchecked. Also, sets the value of each cell in the range A1:B10 to 'false'.
range.insertCheckboxes();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

insertCheckboxes(checkedValue)

將核取方塊插入範圍中的每個儲存格,已設定勾選的自訂值,以及未勾選的空字串。將範圍內每個儲存格的值設為空字串。

var range = SpreadsheetApp.getActive().getRange('A1:B10');

// Inserts checkboxes into each cell in the range A1:B10 configured with 'yes' for checked
// and the empty string for unchecked. Also, sets the value of each cell in the range A1:B10 to
//  the empty string.
range.insertCheckboxes('yes');

參數

名稱類型說明
checkedValueObject核取方塊資料驗證勾選的值。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

insertCheckboxes(checkedValue, uncheckedValue)

在範圍中的每個儲存格中插入核取方塊,並使用已勾選和未勾選狀態的自訂值進行設定。將範圍內每個儲存格的值設為自訂的未檢查值。

var range = SpreadsheetApp.getActive().getRange('A1:B10');

// Inserts checkboxes into each cell in the range A1:B10 configured with 'yes' for checked
// and 'no' for unchecked. Also, sets the value of each cell in the range A1:B10 to 'no'.
range.insertCheckboxes('yes', 'no');

參數

名稱類型說明
checkedValueObject核取方塊資料驗證勾選的值。
uncheckedValueObject核取方塊資料驗證的未勾選值。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

isBlank()

如果範圍完全空白,系統會傳回 true

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B2:D4");

Logger.log(range.isBlank());

回攻員

Booleantrue 表示範圍空白,否則會傳回 false

授權

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

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

isChecked()

傳回範圍內所有儲存格的核取方塊狀態是否為「已勾選」。如果部分儲存格已勾選,而其餘部分未勾選,或者部分儲存格沒有核取方塊資料驗證,則會傳回 null

var range = SpreadsheetApp.getActive().getRange('A1:A3');

// Inserts checkboxes and sets each cell value to 'no' in the range A1:A3.
range.insertCheckboxes('yes', 'no');

var range1 = SpreadsheetApp.getActive().getRange('A1');
range1.setValue('yes');
// Sets the value of isRange1Checked as true as it contains the checked value.
var isRange1Checked = range1.isChecked();

var range2 = SpreadsheetApp.getActive().getRange('A2');
range2.setValue('no');
// Sets the value of isRange2Checked as false as it contains the unchecked value.
var isRange2Checked = range2.isChecked();

var range3 = SpreadsheetApp.getActive().getRange('A3');
range3.setValue('random');
// Sets the value of isRange3Checked as null, as it contains an invalid checkbox value.
var isRange3Checked = range3.isChecked();

回攻員

Booleantrue (如果已勾選範圍內的所有儲存格),如果已勾選範圍內的所有儲存格,則為 false;如果未勾選任何儲存格或未勾選核取方塊資料驗證,則為 null

授權

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

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

isEndColumnBounded()

決定範圍結尾是否繫結至特定資料欄。舉例來說,對於繫結至範圍末端資料欄的 A1:B10B:B,這個方法會傳回 true;如果範圍的 3:7A1:5,這個方法只會繫結至範圍結尾的特定資料列,這個方法會傳回 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

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

// Determines if the end of the range is bound to a particular column and logs it to the
// console.
console.log(range.isEndColumnBounded());

回攻員

Boolean:如果範圍的結尾繫結至特定資料欄,則為 true;否則為 false

授權

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

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

isEndRowBounded()

決定範圍結尾是否繫結至特定資料列。舉例來說,如果範圍是範圍末端的 A1:B103:7,這個方法會傳回 true;如果範圍是 B:BA1:C,且範圍僅繫結至範圍結尾的特定資料欄,這個方法會傳回 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

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

// Determines if the end of the range is bound to a particular row and logs it to the console.
console.log(range.isEndRowBounded());

回攻員

Boolean - 如果範圍的結尾是繫結至特定資料列,則為 true;否則為 false

授權

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

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

isPartOfMerge()

如果目前範圍內的儲存格與任何合併的儲存格重疊,則傳回 true

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

var range = sheet.getRange("A1:B3");

// True if any of the cells in A1:B3 is included in a merge.
var isPartOfMerge = range.isPartOfMerge();

回攻員

Boolean — 如果範圍與任何合併的儲存格重疊,則傳回 true,否則會傳回 false


isStartColumnBounded()

決定範圍的開頭是否受到特定欄約束。舉例來說,如果範圍是 A1:B10B:B,且繫結至範圍開頭的資料欄,這個方法會傳回 true;對於僅繫結至範圍開頭資料列的 3:7 範圍,這個方法會傳回 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

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

// Determines if the start of the range is bound to a particular column and logs it to the
// console.
console.log(range.isStartColumnBounded());

回攻員

Boolean:如果範圍的起始範圍繫結至特定資料欄,則為 true;否則為 false

授權

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

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

isStartRowBounded()

決定範圍的開頭是否繫結至特定資料列。舉例來說,對於範圍起始列的 A1:B103:7 範圍,這個方法會傳回 true;對於僅繫結至範圍起始特定資料欄的 B:B 範圍,這個方法會傳回 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

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

// Determines if the start of the range is bound to a particular row and logs it to the
// console.
console.log(range.isStartRowBounded());

回攻員

Boolean - 如果範圍開頭是繫結至特定資料列,則為 true,否則為 false

授權

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

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

merge()

將範圍內的儲存格合併成一個區塊。

var sheet = SpreadsheetApp.getActiveSheet();

// The code below 2-dimensionally merges the cells in A1 to B3
sheet.getRange('A1:B3').merge();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

mergeAcross()

合併指定範圍內資料欄指定範圍中的儲存格。

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

// The code below merges cells C5:E5 into one cell
var range1 = sheet.getRange("C5:E5");
range1.mergeAcross();

// The code below creates 2 horizontal cells, F5:H5 and F6:H6
var range2 = sheet.getRange("F5:H6");
range2.mergeAcross();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

mergeVertically()

將範圍中的儲存格合併在一起。

var sheet = SpreadsheetApp.getActiveSheet();

// The code below vertically merges the cells in A1 to A10
sheet.getRange('A1:A10').mergeVertically();

// The code below creates 3 merged columns: B1 to B10, C1 to C10, and D1 to D10
sheet.getRange('B1:D10').mergeVertically();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

moveTo(target)

剪下並貼上這個範圍 (格式和值) 到目標範圍。

// The code below moves the first 5 columns over to the 6th column
var sheet = SpreadsheetApp.getActiveSheet()
sheet.getRange("A1:E").moveTo(sheet.getRange("F1"));

參數

名稱類型說明
targetRange要複製這個範圍的目標範圍;只有左上角的儲存格位置才有關聯。

授權

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

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

offset(rowOffset, columnOffset)

傳回從指定資料列數和欄數 (可以是負數) 與這個範圍之間偏移的新範圍 (可以是負數)。新範圍的大小與原始範圍相同。

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

var cell = sheet.getRange("A1");

// newCell references B2
var newCell = cell.offset(1, 1);

參數

名稱類型說明
rowOffsetInteger從範圍左上角儲存格算起的列數;負數則代表從左上角儲存格算起的列。
columnOffsetInteger從範圍左上角儲存格算起的欄數;負值代表從範圍左上角儲存格算起的欄數。

回攻員

Range — 這個範圍,用於鏈結。


offset(rowOffset, columnOffset, numRows)

傳回相對於目前範圍的新範圍,其左上點會與指定的列和欄從目前範圍偏移,以及在儲存格中指定高度。

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

var cell = sheet.getRange("A1");

// newCell references B2:B3
var newRange = cell.offset(1, 1, 2);

參數

名稱類型說明
rowOffsetInteger從範圍左上角儲存格算起的列數;負數則代表從左上角儲存格算起的列。
columnOffsetInteger從範圍左上角儲存格算起的欄數;負值代表從範圍左上角儲存格算起的欄數。
numRowsInteger新範圍的列高。

回攻員

Range — 這個範圍,用於鏈結。


offset(rowOffset, columnOffset, numRows, numColumns)

傳回相對於目前範圍的新範圍,其左上點會與指定列和欄從目前範圍偏移,以及在儲存格中指定高度和寬度。

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

var cell = sheet.getRange("A1");

// newCell references B2:C3
var newRange = cell.offset(1, 1, 2, 2);

參數

名稱類型說明
rowOffsetInteger從範圍左上角儲存格算起的列數;負數則代表從左上角儲存格算起的列。
columnOffsetInteger從範圍左上角儲存格算起的欄數;負值代表從範圍左上角儲存格算起的欄數。
numRowsInteger新範圍的列高。
numColumnsInteger新範圍的欄寬度。

回攻員

Range — 這個範圍,用於鏈結。


protect()

建立可保護範圍,使其無法編輯範圍的物件,唯具備權限的使用者除外。在指令碼實際變更範圍的編輯器清單 (透過呼叫 Protection.removeEditor(emailAddress)Protection.removeEditor(user)Protection.removeEditors(emailAddresses)Protection.addEditor(emailAddress)Protection.addEditor(user)Protection.addEditors(emailAddresses) 或為 Protection.setDomainEdit(editable) 設定新值) 之前,權限會反映試算表本身的權限,也就是說,這個範圍實際上不會受到保護。如果該範圍已經受到保護,此方法就會建立一個與現有範圍重疊的新保護範圍。如果儲存格受到多個保護範圍保護,而且任一範圍禁止特定使用者編輯儲存格,則使用者無法編輯該儲存格。

// Protect range A1:B10, then remove all other users from the list of editors.
var ss = SpreadsheetApp.getActive();
var range = ss.getRange('A1:B10');
var protection = range.protect().setDescription('Sample protected range');

// 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.
var 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

randomize()

針對指定範圍內的資料列順序隨機排序。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("A1:C7");

// Randomizes the range
range.randomize();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

removeCheckboxes()

移除範圍內的所有核取方塊。清除每個儲存格的資料驗證,如果儲存格含有勾選或未勾選的值,也會清除該儲存格的值。

var range = SpreadsheetApp.getActive().getRange('A1:B10');

// Inserts checkboxes and sets each cell value to 'no' in the range A1:B10.
range.insertCheckboxes('yes', 'no');

var range1 = SpreadsheetApp.getActive().getRange('A1');
range1.setValue('yes');
// Removes the checkbox data validation in cell A1 and clears its value.
range1.removeCheckboxes();

var range2 = SpreadsheetApp.getActive().getRange('A2');
range2.setValue('random');
// Removes the checkbox data validation in cell A2 but does not clear its value.
range2.removeCheckboxes();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

removeDuplicates()

如果該範圍內的值與任何前一個資料列的值重複,系統會移除這個值。只要資料列的值相同,但字母大小寫、格式或公式不同,就會視為重複資料列。這個方法也會移除在檢視畫面中隱藏的重複資料列 (例如因篩選器而隱藏的重複資料列)。不在這個範圍內的內容不會遭到移除。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B1:D7");

// Remove duplicate rows in the range.
range.removeDuplicates();

回攻員

Range:移除重複項目後的結果範圍。範圍大小會每移除一個資料列,縮減一個資料列。

授權

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

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

removeDuplicates(columnsToCompare)

在指定資料欄中,假如指定資料欄中包含與任何前列值重複的值,則該範圍會將其移除。只要資料列的值相同,但字母大小寫、格式或公式不同,系統就會視為重複資料列。這個方法也會移除在檢視畫面中隱藏的重複資料列 (例如因篩選器而隱藏的重複資料列)。不在這個範圍內的內容不會遭到移除。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("B1:D7");

// Remove rows which have duplicate values in column B.
range.removeDuplicates([2]);

// Remove rows which have duplicate values in both columns B and D.
range.removeDuplicates([2,4]);

參數

名稱類型說明
columnsToCompareInteger[]要分析重複值的資料欄。如果沒有提供任何資料欄,系統就會分析所有資料欄是否含有重複內容。

回攻員

Range:移除重複項目後的結果範圍。範圍大小會每移除一個資料列,縮減一個資料列。

授權

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

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

setBackground(color)

設定 CSS 標記法 (例如 '#ffffff''white') 範圍內所有儲存格的背景顏色。

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

var range = sheet.getRange("B2:D5");
range.setBackground("red");

參數

名稱類型說明
colorStringCSS 標記法 (例如 '#ffffff''white') 中的顏色代碼;null 值會重設顏色。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setBackgroundObject(color)

設定範圍內所有儲存格的背景顏色。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var bgColor = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.BACKGROUND)
    .build();

var range = sheet.getRange("B2:D5");
range.setBackgroundObject(bgColor);

參數

名稱類型說明
colorColor要設定的背景顏色;null 值會重設背景顏色。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setBackgroundObjects(color)

設定背景顏色的矩形格線 (必須與此範圍的尺寸相符)。

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

var colorAccent1 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
    .build();
var colorAccent2 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
    .build();
var colorAccent3 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
    .build();
var colorAccent4 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4)
    .build();

var colors = [
  [colorAccent1, colorAccent2],
  [colorAccent3, colorAccent4]
];

var cell = sheet.getRange("B5:C6");
cell.setBackgroundObjects(colors);

參數

名稱類型說明
colorColor[][]二維顏色陣列;null 值會重設顏色。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setBackgroundRGB(red, green, blue)

使用 RGB 值 (含 0 到 255 之間的整數) 將背景設為指定顏色。

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

var cell = sheet.getRange("B2");

// Sets the background to white
cell.setBackgroundRGB(255, 255, 255);

// Sets the background to red
cell.setBackgroundRGB(255, 0, 0);

參數

名稱類型說明
redIntegerRGB 標記法中的紅色值。
greenIntegerRGB 標記法中的綠色值。
blueIntegerRGB 標記法中的藍色值。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setBackgrounds(color)

設定背景顏色的矩形格線 (必須與這個範圍的尺寸相符)。顏色採用 CSS 標記法 (例如 '#ffffff''white')。

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

var colors = [
  ["red", "white", "blue"],
  ["#FF0000", "#FFFFFF", "#0000FF"] // These are the hex equivalents
];

var cell = sheet.getRange("B5:D6");
cell.setBackgrounds(colors);

參數

名稱類型說明
colorString[][]CSS 標記法 (例如 '#ffffff''white') 的二維顏色陣列;null 值會重設顏色。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setBorder(top, left, bottom, right, vertical, horizontal)

設定邊框屬性。有效值為 true (開啟)、false (關閉) 和 null (保持不變)。

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

var cell = sheet.getRange("B2");
// Sets borders on the top and bottom, but leaves the left and right unchanged
cell.setBorder(true, null, true, null, false, false);

參數

名稱類型說明
topBooleantrue 代表無框線,false 代表無,null 代表不變更。
leftBooleantrue 代表無框線,false 代表無,null 代表不變更。
bottomBooleantrue 代表無框線,false 代表無,null 代表不變更。
rightBooleantrue 代表無框線,false 代表無,null 代表不變更。
verticalBooleantrue 代表內部垂直框線,false 代表無,null 代表不變更。
horizontalBooleantrue 代表內部水平框線,false 表示無,null 代表不變更。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setBorder(top, left, bottom, right, vertical, horizontal, color, style)

使用顏色和/或樣式設定邊框屬性。有效值為 true (開啟)、false (關閉) 和 null (保持不變)。如果是顏色,請在 CSS 標記法 (例如 '#ffffff''white') 中使用「顏色」。

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

var cell = sheet.getRange("B2");
// Sets borders on the top and bottom, but leaves the left and right unchanged
// Also sets the color to "red", and the border to "DASHED".
cell.setBorder(true, null, true, null, false, false, "red", SpreadsheetApp.BorderStyle.DASHED);

參數

名稱類型說明
topBooleantrue 代表無框線,false 代表無,null 代表不變更。
leftBooleantrue 代表無框線,false 代表無,null 代表不變更。
bottomBooleantrue 代表無框線,false 代表無,null 代表不變更。
rightBooleantrue 代表無框線,false 代表無,null 代表不變更。
verticalBooleantrue 代表內部垂直框線,false 代表無,null 代表不變更。
horizontalBooleantrue 代表內部水平框線,false 表示無,null 代表不變更。
colorStringCSS 標記法中的顏色 (例如 '#ffffff''white'),null 代表預設顏色 (黑色)。
styleBorderStyle框線的樣式,null 代表預設樣式 (固定樣式)。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setDataValidation(rule)

為範圍內的所有儲存格設定一項資料驗證規則。

// Set the data validation rule for cell A1 to require a value from B1:B10.
var cell = SpreadsheetApp.getActive().getRange('A1');
var range = SpreadsheetApp.getActive().getRange('B1:B10');
var rule = SpreadsheetApp.newDataValidation().requireValueInRange(range).build();
cell.setDataValidation(rule);

參數

名稱類型說明
ruleDataValidation要設定的資料驗證規則,或 null 移除資料驗證。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setDataValidations(rules)

為範圍內的所有儲存格設定資料驗證規則。這個方法會採用資料驗證的二維陣列,並依照資料列和資料欄來建立索引。陣列維度必須與範圍維度對應。

// Set the data validation rules for Sheet1!A1:B5 to require a value from Sheet2!A1:A10.
var destinationRange = SpreadsheetApp.getActive().getSheetByName('Sheet1').getRange('A1:B5');
var sourceRange = SpreadsheetApp.getActive().getSheetByName('Sheet2').getRange('A1:A10');
var rule = SpreadsheetApp.newDataValidation().requireValueInRange(sourceRange).build();
var rules = destinationRange.getDataValidations();
for (var i = 0; i < rules.length; i++) {
  for (var j = 0; j < rules[i].length; j++) {
    rules[i][j] = rule;
  }
}
destinationRange.setDataValidations(rules);

參數

名稱類型說明
rulesDataValidation[][]要設定的資料驗證規則的二維陣列;null 值會移除資料驗證。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontColor(color)

設定 CSS 標記法 (例如 '#ffffff''white') 的字型顏色。

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

var cell = sheet.getRange("B2");
cell.setFontColor("red");

參數

名稱類型說明
colorStringCSS 標記法中的字型顏色 (例如 '#ffffff''white');null 值會重設顏色。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontColorObject(color)

設定指定範圍的字型顏色。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var color = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.TEXT)
    .build();

var cell = sheet.getRange("B2");
cell.setFontColor(color);

參數

名稱類型說明
colorColor要設定的字型顏色;null 值會重設顏色。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontColorObjects(colors)

設定字型顏色的矩形格線 (必須與此範圍的尺寸相符)。

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

var colorAccent1 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT1)
    .build();
var colorAccent2 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT2)
    .build();
var colorAccent3 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT3)
    .build();
var colorAccent4 = SpreadsheetApp.newColor()
    .setThemeColor(SpreadsheetApp.ThemeColorType.ACCENT4)
    .build();

var colors = [
  [colorAccent1, colorAccent2],
  [colorAccent3, colorAccent4]
];

var cell = sheet.getRange("B5:C6");
cell.setFontColorObjects(colors);

參數

名稱類型說明
colorsColor[][]二維色彩陣列;null 值會重設字型顏色。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontColors(colors)

設定字型顏色的矩形格線 (必須與此範圍的尺寸相符)。顏色採用 CSS 標記法 (例如 '#ffffff''white')。

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

var colors = [
  ["red", "white", "blue"],
  ["#FF0000", "#FFFFFF", "#0000FF"] // These are the hex equivalents
];

var cell = sheet.getRange("B5:D6");
cell.setFontColors(colors);

參數

名稱類型說明
colorsObject[][]CSS 標記法 (例如 '#ffffff''white') 的二維顏色陣列;null 值會重設顏色。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontFamilies(fontFamilies)

設定字型系列的矩形格線 (必須與這個範圍的尺寸相符)。字型系列範例包括「 相簿」或「Helvetica」。

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

var fonts = [
  ["Arial", "Helvetica", "Verdana"],
  ["Courier New", "Arial", "Helvetica]
];

var cell = sheet.getRange("B2:D3");
cell.setFontFamilies(fonts);

參數

名稱類型說明
fontFamiliesObject[][]字型系列的二維陣列;null 值會重設字型系列。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontFamily(fontFamily)

設定字型系列,例如「 相簿」或「Helvetica」。

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

var cell = sheet.getRange("B2");
cell.setFontFamily("Helvetica");

參數

名稱類型說明
fontFamilyString要設定的字型系列;null 值會重設字型系列。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontLine(fontLine)

設定指定範圍的字型行樣式 ('underline''line-through''none')。

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

var cell = sheet.getRange("B2");
cell.setFontLine("line-through");

參數

名稱類型說明
fontLineString字型行樣式為 'underline''line-through''none'null 值會重設字型行樣式。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontLines(fontLines)

設定線條樣式的矩形格線 (必須與這個範圍的尺寸相符)。

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

// The size of the two-dimensional array must match the size of the range.
var fontLines = [
  ["underline", "line-through", "none"]
];

var range = sheet.getRange("B2:D2");
range.setFontLines(fontLines);

參數

名稱類型說明
fontLinesObject[][]字型行樣式的二維陣列 ('underline''line-through''none');null 值會重設字型線條樣式。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontSize(size)

設定字型大小,做為要使用的資料點大小。

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

var cell = sheet.getRange("B2");
cell.setFontSize(20);

參數

名稱類型說明
sizeInteger以點數表示的字型大小。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontSizes(sizes)

設定字型大小的矩形格線 (必須與此範圍的尺寸相符)。尺寸是以點為單位。

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

// The size of the two-dimensional array must match the size of the range.
var fontSizes = [
  [16, 20, 24]
];

var range = sheet.getRange("B2:D2");
range.setFontSizes(fontSizes);

參數

名稱類型說明
sizesObject[][]大小的二維陣列。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontStyle(fontStyle)

設定指定範圍 ('italic''normal') 的字型樣式。

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

var cell = sheet.getRange("B2");
cell.setFontStyle("italic");

參數

名稱類型說明
fontStyleString字型樣式 'italic''normal'null 值會重設字型樣式。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontStyles(fontStyles)

設定字型樣式的矩形格線 (必須與此範圍的尺寸相符)。

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

// The size of the two-dimensional array must match the size of the range.
var fontStyles = [
  ["italic", "normal"]
];

var range = sheet.getRange("B2:C2");
range.setFontStyles(fontStyles);

參數

名稱類型說明
fontStylesObject[][]字型樣式的二維陣列 ('italic''normal');null 值會重設字型樣式。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontWeight(fontWeight)

設定指定範圍的字型粗細 (一般/粗體)。

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

var cell = sheet.getRange("B2");
cell.setFontWeight("bold");

參數

名稱類型說明
fontWeightString字型粗細 ('bold''normal');null 值會重設字型粗細。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFontWeights(fontWeights)

設定字型粗細的矩形格線 (必須與這個範圍的尺寸相符)。字型粗細的範例為「粗體」。

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

// The size of the two-dimensional array must match the size of the range.
var fontStyles = [
  [ "bold", "bold", "normal" ]
];

var range = sheet.getRange("B2:D2");
range.setFontWeights(fontStyles);

參數

名稱類型說明
fontWeightsObject[][]字型粗細的二維陣列 ('bold''normal');null 值會重設字型粗細。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFormula(formula)

更新這個範圍的公式。指定的公式必須採用 A1 標記法。

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

var cell = sheet.getRange("B5");
cell.setFormula("=SUM(B3:B4)");

參數

名稱類型說明
formulaString字串,代表要為儲存格設定的公式。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFormulaR1C1(formula)

更新這個範圍的公式。提供的公式必須採用 R1C1 標記法。

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

var cell = sheet.getRange("B5");
// This sets the formula to be the sum of the 3 rows above B5
cell.setFormulaR1C1("=SUM(R[-3]C[0]:R[-1]C[0])");

參數

名稱類型說明
formulaString字串公式。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFormulas(formulas)

設定公式的矩形格線 (必須與這個範圍的尺寸相符)。提供的公式必須採用 A1 標記法。這個方法會採用二維公式陣列,其中先依列建立索引,再依資料欄建立索引。陣列維度必須與範圍維度相符。

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

// This sets the formulas to be a row of sums, followed by a row of averages right below.
// The size of the two-dimensional array must match the size of the range.
var formulas = [
  ["=SUM(B2:B4)", "=SUM(C2:C4)", "=SUM(D2:D4)"],
  ["=AVERAGE(B2:B4)", "=AVERAGE(C2:C4)", "=AVERAGE(D2:D4)"]
];

var cell = sheet.getRange("B5:D6");
cell.setFormulas(formulas);

參數

名稱類型說明
formulasString[][]公式的二維字串陣列。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setFormulasR1C1(formulas)

設定公式的矩形格線 (必須與這個範圍的尺寸相符)。提供的公式必須是 R1C1 標記法。

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

// This creates formulas for a row of sums, followed by a row of averages.
var sumOfRowsAbove = "=SUM(R[-3]C[0]:R[-1]C[0])";
var averageOfRowsAbove = "=AVERAGE(R[-4]C[0]:R[-2]C[0])";

// The size of the two-dimensional array must match the size of the range.
var formulas = [
  [sumOfRowsAbove, sumOfRowsAbove, sumOfRowsAbove],
  [averageOfRowsAbove, averageOfRowsAbove, averageOfRowsAbove]
];

var cell = sheet.getRange("B5:D6");
// This sets the formula to be the sum of the 3 rows above B5.
cell.setFormulasR1C1(formulas);

參數

名稱類型說明
formulasString[][]R1C1 格式的二維公式陣列。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setHorizontalAlignment(alignment)

為指定範圍 (左側/中間/右側) 設定水平 (由左至右) 對齊方式。

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

var cell = sheet.getRange("B2");
cell.setHorizontalAlignment("center");

參數

名稱類型說明
alignmentString'left''center''normal' 對齊方式;null 值會重設對齊方式。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setHorizontalAlignments(alignments)

設定水平對齊的矩形格線。請參閱 setHorizontalAlignment(alignment)

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

// The size of the two-dimensional array must match the size of the range.
var horizontalAlignments = [
  [ "left", "right", "center" ]
];

var range = sheet.getRange("B2:D2");
range.setHorizontalAlignments(horizontalAlignments);

參數

名稱類型說明
alignmentsObject[][]二維對齊陣列,'left''center''normal'null 值會重設對齊方式。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

另請參閱


setNote(note)

將附註設為指定值。

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

var cell = sheet.getRange("B2");
cell.setNote("This is a note");

參數

名稱類型說明
noteString要針對範圍設定的附註值;null 值會移除附註。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setNotes(notes)

設定附註的矩形格線 (必須與這個範圍的尺寸相符)。

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

// The size of the two-dimensional array must match the size of the range.
var notes = [
  ["it goes", "like this", "the fourth, the fifth"],
  ["the minor fall", "and the", "major lift"]
];

var cell = sheet.getRange("B2:D3");
cell.setNotes(notes)

參數

名稱類型說明
notesObject[][]筆記的二維陣列;null 值會移除附註。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

另請參閱


setNumberFormat(numberFormat)

將數字或日期格式設為指定的格式字串。如需可接受的格式模式,請參閱 Sheets API 說明文件

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

var cell = sheet.getRange("B2");
// Always show 3 decimal points
cell.setNumberFormat("0.000");

參數

名稱類型說明
numberFormatString數字格式字串。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setNumberFormats(numberFormats)

設定數字或日期格式的矩形格線 (必須與此範圍的尺寸相符)。這些值是 Sheets API 說明文件中所述的格式模式字串。

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

// The size of the two-dimensional array must match the size of the range.
var formats = [
  [ "0.000", "0,000,000", "$0.00" ]
];

var range = sheet.getRange("B2:D2");
range.setNumberFormats(formats);

參數

名稱類型說明
numberFormatsObject[][]數字格式的二維陣列。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setRichTextValue(value)

設定範圍內儲存格的 RTF 格式值。

// Sets all cells in range B2:D4 to have the text "Hello world", with "Hello" bolded.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B2:D4");
var bold = SpreadsheetApp.newTextStyle()
    .setBold(true)
    .build();
var richText = SpreadsheetApp.newRichTextValue()
    .setText("Hello world")
    .setTextStyle(0, 5, bold)
    .build();
range.setRichTextValue(richText);

參數

名稱類型說明
valueRichTextValue所需的 RTF 格式值。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setRichTextValues(values)

設定 RTF 值的矩形格線。

// Sets the cells in range A1:A2 to have Rich Text values.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("A1:A2");
var bold = SpreadsheetApp.newTextStyle()
    .setBold(true)
    .build();
var italic = SpreadsheetApp.newTextStyle()
    .setItalic(true)
    .build();
var richTextA1 = SpreadsheetApp.newRichTextValue()
    .setText("This cell is bold")
    .setTextStyle(bold)
    .build();
var richTextA2 = SpreadsheetApp.newRichTextValue()
    .setText("bold words, italic words")
    .setTextStyle(0, 11, bold)
    .setTextStyle(12, 24, italic)
    .build();
range.setRichTextValues([[richTextA1], [richTextA2]]);

參數

名稱類型說明
valuesRichTextValue[][]所需的 RTF 格式值。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

設定範圍是否應顯示超連結。

// 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 Sheet1 by its name.
const sheet = ss.getSheetByName('Sheet1');

// Gets cell A30 and sets its hyperlink value.
const range = sheet.getRange('A30');
range.setValue('https://www.example.com');

// Sets cell A30 to show hyperlinks.
range.setShowHyperlink(true);

參數

名稱類型說明
showHyperlinkBoolean是否顯示超連結。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setTextDirection(direction)

設定範圍中的儲存格文字方向。如果指定方向為 null,系統會推論方向然後設定。

// Sets right-to-left text direction for the range.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B5:C6");
range.setTextDirection(SpreadsheetApp.TextDirection.RIGHT_TO_LEFT);

參數

名稱類型說明
directionTextDirection指定的文字方向;如果 null,系統會在設定前推斷方向。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setTextDirections(directions)

設定文字路線的矩形格線。如果指定方向為 null,系統會推論方向後再設定。

// Copies all of the text directions from range A1:B2 over to range C5:D6.
var sheet = SpreadsheetApp.getActiveSheet();
var range1 = sheet.getRange("A1:B2");
var range2 = sheet.getRange("C5:D6");

range2.setTextRotations(range1.getTextDirections());

參數

名稱類型說明
directionsTextDirection[][]所需文字方向;如果指定方向為 null,系統會在設定之前先推斷。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setTextRotation(degrees)

設定範圍中儲存格的文字旋轉設定。輸入內容對應標準文字方向與所需方向之間的角度。輸入 0 表示文字已設為標準方向。

如果是從左到右的文字方向,正角則是逆時針方向,由右到左則為順時針方向。

// Sets all cell's in range B2:D4 to have text rotated up 45 degrees.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B2:D4");

range.setTextRotation(45);

參數

名稱類型說明
degreesInteger標準螢幕方向與所需方向之間的所需角度。從左到右的文字中,正角是以逆時針方向呈現。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setTextRotation(rotation)

為範圍中的儲存格設定文字旋轉設定。

// Sets all cell's in range B2:D4 to have the same text rotation settings as cell A1.
var sheet = SpreadsheetApp.getActiveSheet();

var rotation = sheet.getRange("A1").getTextRotation();

sheet.getRange("B2:D4").setTextRotation(rotation);

參數

名稱類型說明
rotationTextRotation所需的文字旋轉設定。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setTextRotations(rotations)

設定文字旋轉的矩形格線。

// Copies all of the text rotations from range A1:B2 over to range C5:D6.
var sheet = SpreadsheetApp.getActiveSheet();
var range1 = sheet.getRange("A1:B2");
var range2 = sheet.getRange("C5:D6");

range2.setTextRotations(range1.getTextRotations());

參數

名稱類型說明
rotationsTextRotation[][]所需的文字旋轉設定。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setTextStyle(style)

設定範圍內儲存格的文字樣式。

// Sets the cells in range C5:D6 to have underlined size 15 font.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("C5:D6");
var style = SpreadsheetApp.newTextStyle()
    .setFontSize(15)
    .setUnderline(true)
    .build();
range.setTextStyle(style);

參數

名稱類型說明
styleTextStyle所需的文字樣式。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setTextStyles(styles)

設定文字樣式的矩形格線。

// Sets text styles for cells in range A1:B2
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("A1:B2");
var bold = SpreadsheetApp.newTextStyle()
    .setBold(true)
    .build();
var otherStyle = SpreadsheetApp.newTextStyle()
    .setBold(true)
    .setUnderline(true)
    .setItalic(true)
    .setForegroundColor("#335522")
    .setFontSize(44)
    .build();
range.setTextStyles([[bold, otherStyle], [otherStyle, bold]]);

參數

名稱類型說明
stylesTextStyle[][]所需的文字樣式。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setValue(value)

設定範圍的值。這個值可以是數字、字串、布林值或日期。如果開頭為 '=',則系統會解讀為公式。

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

var cell = sheet.getRange("B2");
cell.setValue(100);

參數

名稱類型說明
valueObject範圍的值。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setValues(values)

設定值的矩形格線 (必須與這個範圍的尺寸相符)。如果值開頭為 =,系統會將這個值解讀為公式。

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

// The size of the two-dimensional array must match the size of the range.
var values = [
  [ "2.000", "1,000,000", "$2.99" ]
];

var range = sheet.getRange("B2:D2");
range.setValues(values);

參數

名稱類型說明
valuesObject[][]二維值的陣列。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setVerticalAlignment(alignment)

設定指定範圍 (頂端/中間/底部) 的垂直 (由上至下) 對齊方式。

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

var cell = sheet.getRange("B2");
cell.setVerticalAlignment("middle");

參數

名稱類型說明
alignmentString'top''middle''bottom' 對齊方式;null 值會重設對齊方式。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setVerticalAlignments(alignments)

設定垂直對齊的矩形格線 (必須與這個範圍的尺寸相符)。

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

// The size of the two-dimensional array must match the size of the range.
var alignments = [
  [ "top", "middle", "bottom" ]
];

var range = sheet.getRange("B2:D2");
range.setVerticalAlignments(alignments);

參數

名稱類型說明
alignmentsObject[][]二維對齊陣列,'top''middle''bottom'null 值會重設對齊方式。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

另請參閱


setVerticalText(isVertical)

設定是否要堆疊範圍內儲存格的文字堆疊。如果文字垂直堆疊,系統會忽略文字旋轉角度設定。

// Sets all cell's in range B2:D4 to have vertically stacked text.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B2:D4");

range.setVerticalText(true);

參數

名稱類型說明
isVerticalBoolean是否堆疊文字。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setWrap(isWrapEnabled)

設定指定範圍的儲存格換行。

啟用換行功能的儲存格 (預設) 可以調整大小以顯示完整內容。停用換行功能的儲存格會在儲存格中盡可能顯示,且不調整大小或執行多行。

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

var cell = sheet.getRange("B2");
cell.setWrap(true);

參數

名稱類型說明
isWrapEnabledBoolean是否自動換行。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setWrapStrategies(strategies)

設定包裝策略的矩形格線。

// Copies all of the wrap strategies from range A1:B2 over to range C5:D6.
var sheet = SpreadsheetApp.getActiveSheet();
var range1 = sheet.getRange("A1:B2");
var range2 = sheet.getRange("C5:D6");

range2.setWrapStrategies(range1.getWrapStrategies());

參數

名稱類型說明
strategiesWrapStrategy[][]所需的包裝策略。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setWrapStrategy(strategy)

設定範圍中的儲存格文字換行策略。

// Sets all cells in range B2:D4 to use the clip wrap strategy.
var sheet = SpreadsheetApp.getActiveSheet();
var range = sheet.getRange("B2:D4");

range.setWrapStrategy(SpreadsheetApp.WrapStrategy.CLIP);

參數

名稱類型說明
strategyWrapStrategy所需的包裝策略。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

setWraps(isWrapEnabled)

設定字詞包裝政策的矩形格線 (尺寸必須符合這個範圍的尺寸)。啟用包裝功能的儲存格 (預設) 會調整大小以顯示完整內容。停用換行功能的儲存格會在儲存格中盡可能顯示,且不調整大小或執行多行。

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

// The size of the two-dimensional array must match the size of the range.
var wraps = [
  [ true, true, false ]
];

var range = sheet.getRange("B2:D2");
range.setWraps(wraps);

參數

名稱類型說明
isWrapEnabledObject[][]納入變數的二維陣列,用於判斷是否要納入儲存格中的文字。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

另請參閱


shiftColumnGroupDepth(delta)

以指定的金額變更範圍的資料欄分組深度。

這會影響建立、修改或刪除與該範圍交集的群組。針對正值差異,系統會建立和/或修改群組;如果是負差異,群組會遭到刪除和/或修改。

如果將群組深度降低至 0 以下或超過八個,則不會有任何影響。

如果 column group control positionBEFORE,在嘗試移動第一個資料列的深度時,就會擲回錯誤。

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var range = sheet.getActiveRange();

// The column grouping depth is increased by 1.
range.shiftColumnGroupDepth(1);

// The column grouping depth is decreased by 1.
range.shiftColumnGroupDepth(-1);

參數

名稱類型說明
deltaInteger要變更這個範圍的資料欄群組深度金額。

回攻員

Range — 這個範圍,用於鏈結。

擲回

Error:當控制位置為 GroupControlTogglePosition.BEFORE 時,嘗試移動第一欄的深度

授權

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

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

shiftRowGroupDepth(delta)

以指定的金額變更範圍的資料列分組深度。

這會影響建立、修改或刪除與該範圍交集的群組。針對正值差異,系統會建立和/或修改群組;如果是負差異,群組會遭到刪除和/或修改。

如果將群組深度降低至 0 以下或超過八個,則不會有任何影響。

如果 row group control positionBEFORE,在嘗試移動第一個資料列的深度時,就會擲回錯誤。

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var range = sheet.getActiveRange();

// The row grouping depth is increased by 1.
range.shiftRowGroupDepth(1);

// The row grouping depth is decreased by 1.
range.shiftRowGroupDepth(-1);

參數

名稱類型說明
deltaInteger要變更這個範圍的資料列群組深度的金額。

回攻員

Range — 這個範圍,用於鏈結。

擲回

Error:當控制位置為 GroupControlTogglePosition.BEFORE 時,嘗試調整第一列的深度

授權

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

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

sort(sortSpecObj)

依欄和指定順序排序指定範圍內的儲存格。

var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheets()[0];
var range = sheet.getRange("A1:C7");

// Sorts by the values in the first column (A)
range.sort(1);

// Sorts by the values in the second column (B)
range.sort(2);

// Sorts descending by column B
range.sort({column: 2, ascending: false});

// Sorts descending by column B, then ascending by column A
// Note the use of an array
range.sort([{column: 2, ascending: false}, {column: 1, ascending: true}]);

// For rows that are sorted in ascending order, the "ascending" parameter is
// optional, and just an integer with the column can be used instead. Note that
// in general, keeping the sort specification consistent results in more readable
// code. You can express the earlier sort as:
range.sort([{column: 2, ascending: false}, 1]);

// Alternatively, if you want all columns to be in ascending order, you can use
// the following (this makes column 2 ascending)
range.sort([2, 1]);
// ... which is equivalent to
range.sort([{column: 2, ascending: true}, {column: 1, ascending: true}]);

參數

名稱類型說明
sortSpecObjObject要排序的資料欄。

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

splitTextToColumns()

根據自動偵測的分隔符號將文字欄分割成多個資料欄。

// A1:A3 has the following values:
//           A                  B                 C
// 1 |one,one,one      |                 |                 |
// 2 |two,two,two      |                 |                 |
// 3 |three,three,three|                 |                 |

var range = SpreadsheetApp.getActiveSheet().getRange("A1:A3");
range.splitTextToColumns();

// Result after spliting the text to columns:
//           A                  B                 C
// 1 |one              |one              |one              |
// 2 |two              |two              |two              |
// 3 |three            |three            |three            |

授權

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

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

splitTextToColumns(delimiter)

使用指定字串做為自訂分隔符號,將文字資料欄分割成多個資料欄。

// A1:A3 has the following values:
//           A                  B                 C
// 1 |one#one#one      |                 |                 |
// 2 |two#two#two      |                 |                 |
// 3 |three#three#three|                 |                 |

var range = SpreadsheetApp.getActiveSheet().getRange("A1:A3");
range.splitTextToColumns('#');

// Result after spliting the text to columns:
//           A                  B                 C
// 1 |one              |one              |one              |
// 2 |two              |two              |two              |
// 3 |three            |three            |three            |

參數

名稱類型說明
delimiterString要分割的自訂分隔符號。

授權

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

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

splitTextToColumns(delimiter)

根據指定的分隔符號將文字欄分割成多個資料欄。

// A1:A3 has the following values:
//           A                  B                 C
// 1 |one;one;one      |                 |                 |
// 2 |two;two;two      |                 |                 |
// 3 |three;three;three|                 |                 |

var range = SpreadsheetApp.getActiveSheet().getRange("A1:A3");
range.splitTextToColumns(SpreadsheetApp.TextToColumnsDelimiter.SEMICOLON);

// Result after spliting the text to columns:
//           A                  B                 C
// 1 |one              |one              |one              |
// 2 |two              |two              |two              |
// 3 |three            |three            |three            |

參數

名稱類型說明
delimiterTextToColumnsDelimiter要分割的預設分隔符號。

授權

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

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

trimWhitespace()

刪除這個範圍中所有儲存格中的空白字元 (例如空格、定位點或換行符號)。移除每個儲存格文字開頭和結尾的所有空白字元,並將其餘空白字元的所有子序列縮減為單一空格。

var sheet = SpreadsheetApp.getActiveSpreadsheet().getSheets()[0];
var range = sheet.getRange('A1:A4');
range.activate();
range.setValues(
    [' preceding space', 'following space ', 'two  middle  spaces', '   =SUM(1,2)'])

range.trimWhitespace();

var values = range.getValues();
// Values are ['preceding space', 'following space', 'two middle spaces', '=SUM(1,2)']

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

uncheck()

將範圍中核取方塊的狀態變更為「未勾選」。忽略目前範圍中不包含勾選或未勾選值的範圍。

// Changes the state of cells which currently contain either the checked or unchecked value
// configured in the range A1:B10 to 'unchecked'.
var range = SpreadsheetApp.getActive().getRange('A1:B10');
range.uncheck();

回攻員

Range — 這個範圍,用於鏈結。

授權

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

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

已淘汰的方法