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返回展开的范围 Direction.UPDirection.DOWN 的副本,前提是 如果维度为 Dimension.COLUMNS,则为 Dimension.ROWSDirection.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设置字体系列,如“Arial”或“Helvetica”。
setFontLine(fontLine)Range设置给定范围('underline''line-through''none')。
setFontLines(fontLines)Range用于设置线条样式的矩形网格(必须匹配此范围的尺寸)。
setFontSize(size)Range设置字体大小,大小为要使用的点大小。
setFontSizes(sizes)Range用于设置字体大小的矩形网格(必须匹配此范围的尺寸)。
setFontStyle(fontStyle)Range设置给定范围('italic''normal')的字体样式。
setFontStyles(fontStyles)Range用于设置字体样式的矩形网格(必须匹配此范围的尺寸)。
setFontWeight(fontWeight)Range设置给定范围(正常/粗体)的字体粗细。
setFontWeights(fontWeights)Range用于设置字体粗细的矩形网格(必须匹配此范围的尺寸)。
setFormula(formula)Range更新此范围的公式。
setFormulaR1C1(formula)Range更新此范围的公式。
setFormulas(formulas)Range用于设置一个矩形的公式网格(必须匹配此范围的尺寸)。
setFormulasR1C1(formulas)Range用于设置一个矩形的公式网格(必须匹配此范围的尺寸)。
setHorizontalAlignment(alignment)Range为给定范围(左/中/右)设置水平(从左到右)对齐方式。
setHorizontalAlignments(alignments)Range用于设置一个水平对齐的矩形网格。
setNote(note)Range将备注设为指定值。
setNotes(notes)Range设置一个矩形备注网格(必须匹配此范围的尺寸)。
setNumberFormat(numberFormat)Range将数字或日期格式设置为给定的格式字符串。
setNumberFormats(numberFormats)Range用于设置一个数字或日期格式的矩形网格(必须匹配此范围的尺寸)。
setRichTextValue(value)Range为范围内的单元格设置 RTF 值。
setRichTextValues(values)Range用于设置富文本值的矩形网格。
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:A20A1:A4 中的当前值为基础,添加一系列递增数字:

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 个工作表(默认的工作表类型)创建过滤条件。 网格工作表是指未与数据库关联的工作表。要创建其他类型的过滤条件,请执行以下操作: 请参阅以下内容: <ph type="x-smartling-placeholder">

返回

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)

返回展开的范围 Direction.UPDirection.DOWN 的副本,前提是 如果维度为 Dimension.COLUMNS,则指定的维度为 Dimension.ROWS;如果维度为 Direction.NEXT,则为 Direction.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