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返回范围左上角单元格的富文本值,如果单元格值不是文本,则返回 null
getRichTextValues()RichTextValue[][]返回范围内单元格的富文本值。
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(含 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设置字体系列,例如“bigquery”或“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设置范围中单元格的富文本值。
setRichTextValues(values)Range设置富文本值的矩形网格。
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)

将该范围的格式复制到指定位置。如果目标范围大于或小于来源范围,则来源范围会相应地重复或截断。请注意,此方法仅复制格式设置。

如需详细了解 gridId 参数,请参阅 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)

将该范围中的内容复制到指定位置。如果目的地大于或小于来源范围,则来源范围会相应地重复或截断。

如需详细了解 gridId 参数,请参阅 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[][] - 与范围内的单元格相关联的字体颜色的二维数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权:

  • 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[][] - 与范围内的单元格相关联的二维字体系列数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权:

  • 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 表示法)。对于不含公式的单元格,二维数组中的条目是空字符串。

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 表示法)。对于不含公式的单元格,二维数组中的条目为 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()

返回范围左上角单元格的富文本值,如果单元格值不是文本,则返回 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 - 范围中左上角单元格的富文本值,如果单元格值不是文本,则返回 null

授权

使用此方法的脚本需要获得以下一个或多个范围的授权:

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

getRichTextValues()

返回范围内单元格的富文本值。

// 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[][] - 富文本值的二维数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权:

  • 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[][] - 与范围内的单元格关联的二维文本旋转数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权:

  • 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]);
在 Web 应用中,Date 值不是合法参数。如果该范围包含值为 Date 的单元格,则 getValues() 无法向 Web 应用返回数据。相反,请从工作表中检索到的所有值转换为受支持的 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());

弃踢回攻

Boolean - 如果范围为空,则为 true;否则为 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();

弃踢回攻

Boolean - true(如果范围中的所有单元格均勾选),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(含 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);

参数

名称类型说明
redInteger红色值,采用 RGB 表示法。
greenInteger绿色值,采用 RGB 表示法。
blueInteger蓝色值,采用 RGB 表示法。

弃踢回攻

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 表示无变化。
colorString一种采用 CSS 表示法的颜色(例如 '#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)

用于设置一个矩形网格,其中包含字体系列(必须与此范围的尺寸一致)。字体系列的示例包括“bigquery”或“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)

设置字体系列,如“bigquery”或“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)

为范围中的单元格设置富文本值。

// 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)

设置富文本值的矩形网格。

// 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)

为范围中的单元格设定文本旋转设置。输入对应于标准文本方向与所需方向之间的角度。如果输入值为零,则表示文本设置为标准方向。

对于从左到右的文本方向,正角度为逆时针方向,而正角为从右到左的顺时针方向。

// 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 以下或超过 8 之间,则此属性不会产生任何影响。

如果 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 以下或超过 8 之间,则此属性不会产生任何影响。

如果 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

已废弃的方法