Excel.Range class

Range 表示一组或多个连续单元格,例如单元格、行、列或单元格块。 若要详细了解如何在整个 API 中使用区域,请从 Excel JavaScript API 中的范围开始。

扩展

注解

[ API 集:ExcelApi 1.1 ]

示例

// Get a Range object by its address.
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    const cell = range.getCell(0,0);
    cell.load('address');
    await context.sync();
    
    console.log(cell.address);
});

属性

address

指定 A1 样式中的区域引用。 地址值包含工作表引用 (例如“Sheet1!A1:B4“) 。

addressLocal

表示用户语言中指定范围的范围引用。

cellCount

指定区域中的单元格数。 如果单元格数超过 2^31-1 (2,147,483,647),此 API 返回 -1。

columnCount

指定区域中的列总数。

columnHidden

表示当前范围中的所有列是否处于隐藏状态。 true当一个区域中的所有列都隐藏时,值。 false当区域中没有列处于隐藏状态时,该值为 。 null当某个区域中的某些列处于隐藏状态且不隐藏同一范围中的其他列时,该值表示。

columnIndex

指定区域中第一个单元格的列号。 从零开始编制索引。

conditionalFormats

与范围相交的 的 集合 ConditionalFormats

context

与 对象关联的请求上下文。 这会将加载项的进程连接到 Office 主机应用程序的进程。

control

访问应用于此区域的单元格控件。 如果区域有多个单元格控件,则返回 EmptyCellControl

dataValidation

返回数据有效性对象。

format

返回一个格式对象,其中封装了区域的字体、填充、边框、对齐方式和其他属性。

formulas

表示采用 A1 表示法的公式。 如果单元格没有公式,则返回其值。

formulasLocal

表示采用 A1 样式表示法的公式,使用用户的语言和数字格式区域设置。 例如,英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。 如果单元格没有公式,则返回其值。

formulasR1C1

表示采用 R1C1 样式表示法的公式。 如果单元格没有公式,则返回其值。

hasSpill

表示所有单元格是否都具有溢出边框。 true如果所有单元格都有溢出边框,或者false所有单元格都没有溢出边框,则返回 。 null如果区域中有和没有溢出边框的单元格,则返回 。

height

返回从范围上边缘到范围下边缘的 100% 缩放的距离(以磅为单位)。

hidden

表示当前区域中的所有单元格是否处于隐藏状态。 值是 true 隐藏区域中的所有单元格时。 false当区域中没有单元格被隐藏时,值。 null当某个区域中的某些单元格处于隐藏状态,而同一区域中的其他单元格未隐藏时,值表示。

hyperlink

表示当前范围的超链接。

isEntireColumn

表示当前区域是否为整列。

isEntireRow

表示当前区域是否为整行。

left

返回从工作表左边缘到区域左边缘的 100% 缩放的距离(以磅为单位)。

linkedDataTypeState

表示每个单元格的数据类型状态。

numberFormat

表示给定区域的 Excel 数字格式代码。 有关 Excel 数字格式的详细信息,请参阅 数字格式代码

numberFormatCategories

表示每个单元格的数字格式的类别。

numberFormatLocal

表示基于用户语言设置的给定区域的 Excel 数字格式代码。 获取或设置 numberFormatLocal 属性时,Excel 不执行任何语言或格式强制。 任何返回的文本都根据系统设置中指定的语言使用本地格式的字符串。

rowCount

返回区域中的总行数。

rowHidden

表示当前范围中的所有行是否处于隐藏状态。 值是 true 隐藏范围中的所有行时。 false当区域中没有隐藏行时,值。 null当某个区域中的某些行处于隐藏状态且同一区域中的其他行未隐藏时,该值表示。

rowIndex

返回区域中第一个单元格的行编号。 从零开始编制索引。

savedAsArray

表示是否将所有单元格另存为数组公式。 true如果所有单元格都另存为数组公式,或者false所有单元格不另存为数组公式,则返回 。 null如果某些单元格将保存为数组公式,而有些单元格则不保存,则返回 。

sort

表示当前 range 的区域排序。

style

表示当前区域的样式。 如果单元格的样式不一致, null 将返回 。 对于自定义样式,将返回样式名称。 对于内置样式,将返回表示枚举中的 BuiltInStyle 值的字符串。

text

指定区域的文本值。 文本值与单元格宽度无关。 Excel UI 中发生的数字符号 (#) 替换不会影响 API 返回的文本值。

top

返回从工作表上边缘到区域上边缘的 100% 缩放的距离(以磅为单位)。

values

表示指定区域的原始值。 返回的数据可以是字符串、数字或布尔值。 包含错误的单元格将返回错误字符串。 如果返回的值以加号 (“+”) 、减 (“-”) 或等号 (“=”) 开头,Excel 会将此值解释为公式。

valuesAsJson

此区域中单元格中值的 JSON 表示形式。 与 不同 Range.valuesRange.valuesAsJson 支持可在单元格中的所有数据类型。 示例包括格式化的数字值和 Web 图像,以及标准布尔值、数字值和字符串值。 从此 API 返回的数据始终与 en-US 区域设置一致。 若要检索用户的显示区域设置中的数据,请使用 Range.valuesAsJsonLocal

valuesAsJsonLocal

此区域中单元格中值的 JSON 表示形式。 与 不同 Range.valuesRange.valuesAsJsonLocal 支持可在单元格中的所有数据类型。 示例包括格式化的数字值和 Web 图像,以及标准布尔值、数字值和字符串值。 从此 API 返回的数据始终与用户的显示区域设置保持一致。 若要检索独立于区域设置的数据,请使用 Range.valuesAsJson

valueTypes

指定每个单元格中的数据类型。

width

返回从范围的左边缘到范围右边缘的 100% 缩放的距离(以磅为单位)。

worksheet

包含当前区域的工作表。

方法

autoFill(destinationRange, autoFillType)

使用指定的自动填充逻辑填充从当前范围到目标范围的范围。 目标范围可以是 null 或可以水平或垂直扩展源范围。 不支持不连续的范围。

有关详细信息,请参阅 使用自动填充和快速填充

autoFill(destinationRange, autoFillTypeString)

使用指定的自动填充逻辑填充从当前范围到目标范围的范围。 目标范围可以是 null 或可以水平或垂直扩展源范围。 不支持不连续的范围。

有关详细信息,请参阅 使用自动填充和快速填充

calculate()

计算工作表上的单元格区域。

clear(applyTo)

清除范围值和格式设置,例如填充和边框。

clear(applyToString)

清除范围值和格式设置,例如填充和边框。

clearOrResetContents()

清除区域中单元格的值,并特别考虑包含控件的单元格。 如果区域仅包含空白值和设置为默认值的控件,则会删除值和控件格式。 否则,这会将包含控件的单元格设置为默认值,并清除区域中其他单元格的值。

convertDataTypeToText()

将数据类型为文本的区域单元格。

convertToLinkedDataType(serviceID, languageCulture)

在工作表中将区域单元格转换为链接数据类型。

copyFrom(sourceRange, copyType, skipBlanks, transpose)

将单元格数据或格式从源区域或 RangeAreas 复制到当前区域。 目标范围的大小可以不同于源范围或 RangeAreas。 如果目标小于源,则会自动扩展。 注意:与 Excel UI 中的复制功能一样,如果目标范围正好大于行或列中源范围的倍数,则会多次复制源内容。 例如,将 2x2 范围复制到 2x6 范围将导致原始 2x2 范围的 3 个副本。

copyFrom(sourceRange, copyTypeString, skipBlanks, transpose)

将单元格数据或格式从源区域或 RangeAreas 复制到当前区域。 目标范围的大小可以不同于源范围或 RangeAreas。 如果目标小于源,则会自动扩展。 注意:与 Excel UI 中的复制功能一样,如果目标范围正好大于行或列中源范围的倍数,则会多次复制源内容。 例如,将 2x2 范围复制到 2x6 范围将导致原始 2x2 范围的 3 个副本。

delete(shift)

删除与区域相关的单元格。

delete(shiftString)

删除与区域相关的单元格。

find(text, criteria)

根据指定的条件查找给定的字符串。 如果当前区域大于单个单元格,则搜索将限制为该范围,否则搜索将涵盖从该单元格之后开始的整个工作表。

findOrNullObject(text, criteria)

根据指定的条件查找给定的字符串。 如果当前区域大于单个单元格,则搜索将限制为该范围,否则搜索将涵盖从该单元格之后开始的整个工作表。 如果没有匹配项,则此方法返回对象的 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

flashFill()

对当前范围执行快速填充。 快速填充在感知模式时自动填充数据,因此范围必须是单个列范围,并且周围有数据才能找到模式。

getAbsoluteResizedRange(numRows, numColumns)

获取一个 Range 对象,该对象具有与当前 Range 对象相同的左上角单元格,但具有指定的行数和列数。

getBoundingRect(anotherRange)

获取包含指定区域的最小 range 对象。 例如, GetBoundingRect “B2:C5”和“D10:E15”的 为“B2:E15”。

getCell(row, column)

根据行和列编号获取包含单个单元格的 range 对象。 单元格可以位于其父区域的边界之外,只要它保留在工作表网格中。 返回的单元格位于相对于区域左上角的单元格的位置。

getCellProperties(cellPropertiesLoadOptions)

返回一个 2D 数组,其中封装了每个单元格的字体、填充、边框、对齐方式和其他属性数据。

getColumn(column)

获取范围中包含的列。

getColumnProperties(columnPropertiesLoadOptions)

返回一个一维数组,其中封装了每个列的字体、填充、边框、对齐方式和其他属性数据。 对于给定列中每个单元格不一致的属性,将返回 null。

getColumnsAfter(count)

获取当前 Range 对象右侧的一定数量的列。

getColumnsBefore(count)

获取当前 Range 对象左侧的一定数量的列。

getDependents()

返回一个 WorkbookRangeAreas 对象,该对象表示包含同一工作表中或多个工作表中指定区域的所有依赖单元格的区域。 注意:如果未找到依赖项,此 API 将返回错误 ItemNotFound

getDirectDependents()

返回一个 对象,该对象表示包含同一 WorkbookRangeAreas 工作表中或跨多个工作表的指定区域的所有直接依赖单元格的区域。 注意:如果未找到依赖项,此 API 将返回错误 ItemNotFound

getDirectPrecedents()

返回一个 WorkbookRangeAreas 对象,该对象表示包含同一工作表中或跨多个工作表的指定区域的所有直接引用单元格的区域。 注意:如果未找到任何先例,此 API 将返回错误 ItemNotFound

getEntireColumn()

获取一个 对象,该对象表示区域 (的整个列,例如,如果当前区域表示单元格“B4:E11”,则它是 getEntireColumn 表示列“B:E”) 的区域。

getEntireRow()

获取一个对象,该对象表示区域 (的整行,例如,如果当前区域表示单元格“B4:E11”,则它是 GetEntireRow 表示行“4:11”) 的区域。

getExtendedRange(direction, activeCell)

返回一个 range 对象,该对象包括当前范围以及范围边缘,具体取决于提供的方向。 这与 Windows 上的 Excel UI 中的 Ctrl+Shift+箭头键行为匹配。

getExtendedRange(directionString, activeCell)

返回一个 range 对象,该对象包括当前范围以及范围边缘,具体取决于提供的方向。 这与 Windows 上的 Excel UI 中的 Ctrl+Shift+箭头键行为匹配。

getImage()

将范围呈现为 Base64 编码的 png 图像。 重要说明*:Excel for Mac目前不支持此 API。 有关当前状态,请访问 OfficeDev/office-js 问题 #235

getIntersection(anotherRange)

获取表示指定区域的矩形交集的 range 对象。

getIntersectionOrNullObject(anotherRange)

获取表示指定区域的矩形交集的 range 对象。 如果未找到交集,则此方法返回一个 对象,其 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getLastCell()

获取区域内的最后一个单元格。 例如,“B2:D5”的最后一个单元格是“D5”。

getLastColumn()

获取区域内的最后一列。 例如,“B2:D5”的最后一列是“D2:D5”。

getLastRow()

获取区域内的最后一行。 例如,“B2:D5”的最后一行是“B5:D5”。

getMergedAreasOrNullObject()

返回一个 RangeAreas 对象,该对象代表此区域中的合并区域。 请注意,如果此范围内的合并区域计数超过 512,则此方法将无法返回结果。 RangeAreas如果该对象不存在,则此函数将返回一个对象,其isNullObject属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getOffsetRange(rowOffset, columnOffset)

获取表示与指定区域偏移的区域的对象。 返回的区域的尺寸将与此区域一致。 如果强制在工作表网格的边界之外生成区域,将引发错误。

getPivotTables(fullyContained)

获取与区域重叠的数据透视表的作用域集合。

getPrecedents()

返回一个 对象,该对象表示包含同一 WorkbookRangeAreas 工作表中或跨多个工作表的指定区域的所有前置单元格的区域。 注意:如果未找到任何先例,此 API 将返回错误 ItemNotFound

getRangeEdge(direction, activeCell)

返回一个 range 对象,该对象是与提供的方向对应的数据区域边缘单元格。 这与 Excel on Windows UI 中的 Ctrl+Arrow 键行为匹配。

getRangeEdge(directionString, activeCell)

返回一个 range 对象,该对象是与提供的方向对应的数据区域边缘单元格。 这与 Excel on Windows UI 中的 Ctrl+Arrow 键行为匹配。

getResizedRange(deltaRows, deltaColumns)

获取与 Range 当前 Range 对象类似的对象,但其右下角展开 (或按行和列数收缩) 。

getRow(row)

获取范围中包含的行。

getRowProperties(rowPropertiesLoadOptions)

返回一个一维数组,其中封装了每个行的字体、填充、边框、对齐方式和其他属性数据。 对于在给定行内每个单元格中不一致的属性, null 将返回 。

getRowsAbove(count)

获取当前 Range 对象上方的一定行数。

getRowsBelow(count)

获取当前 Range 对象下面的特定行数。

getSpecialCells(cellType, cellValueType)

RangeAreas获取对象,该对象包含一个或多个矩形区域,该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格, ItemNotFound 则会引发错误。

getSpecialCells(cellTypeString, cellValueTypeString)

RangeAreas获取对象,该对象包含一个或多个矩形区域,该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格, ItemNotFound 则会引发错误。

getSpecialCellsOrNullObject(cellType, cellValueType)

RangeAreas获取由一个或多个区域组成的 对象,该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格,则此方法返回一个 对象,其 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getSpecialCellsOrNullObject(cellTypeString, cellValueTypeString)

RangeAreas获取由一个或多个区域组成的 对象,该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格,则此方法返回一个 对象,其 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getSpillingToRange()

获取 Range 对象,它在调用定位单元格时包含溢出区域。 如果应用于具有多个单元格的区域,则会失败。

getSpillingToRangeOrNullObject()

获取 Range 对象,它在调用定位单元格时包含溢出区域。 如果区域不是定位点单元格或找不到溢出区域,则此方法返回对象,其 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getSpillParent()

获取 Range 对象,它包含要将某个单元格溢出到的定位单元格。 如果应用于具有多个单元格的区域,则会失败。

getSpillParentOrNullObject()

获取包含要溢出到的单元格的定位单元格的范围对象。 如果它不是溢出的单元格,或者提供了多个单元格,则此方法返回一个 对象,其 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getSurroundingRegion()

返回一个 Range 对象,该对象代表此区域中左上角单元格的周围区域。 周围区域是由相对于该区域的空白行和空白列的任何组合所限定的区域。

getTables(fullyContained)

获取与区域重叠的限定范围的表格集合。

getUsedRange(valuesOnly)

返回指定 range 对象的所用区域。 如果区域中没有使用的单元格,则此函数将引发错误 ItemNotFound

getUsedRangeOrNullObject(valuesOnly)

返回指定 range 对象的所用区域。 如果区域中没有已用单元格,则此方法返回一个 对象,其 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getVisibleView()

表示当前 range 对象的可见行。

group(groupOption)

组大纲的列和行。

group(groupOptionString)

组大纲的列和行。

hideGroupDetails(groupOption)

隐藏行或列组的详细信息。

hideGroupDetails(groupOptionString)

隐藏行或列组的详细信息。

insert(shift)

将单个单元格或一系列单元格插入到工作表中取代此区域,并移动其他单元格以留出空间。 返回现在空白处的新 Range 对象。

insert(shiftString)

将单个单元格或一系列单元格插入到工作表中取代此区域,并移动其他单元格以留出空间。 返回现在空白处的新 Range 对象。

load(options)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()

load(propertyNames)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()

load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()

merge(across)

将范围单元格合并到工作表的一个区域内。

moveTo(destinationRange)

将单元格值、格式和公式从当前区域移动到目标区域,替换这些单元格中的旧信息。 如果目标范围小于当前范围,则会自动扩展。 不会更改目标区域中超出原始区域区域的任何单元格。

removeDuplicates(columns, includesHeader)

从列指定的区域中删除重复值。

replaceAll(text, replacement, criteria)

根据当前区域内指定的条件查找并替换给定的字符串。

select()

在 Excel UI 中选择指定的区域。

set(properties, options)

同时设置对象的多个属性。 可以传递具有相应属性的纯对象,也可以传递同一类型的另一个 API 对象。

set(properties)

基于现有的已加载对象,同时对对象设置多个属性。

setCellProperties(cellPropertiesData)

基于单元格属性的 2D 数组汇报区域,封装字体、填充、边框和对齐等内容。

setColumnProperties(columnPropertiesData)

基于列属性的单维数组汇报范围,并封装字体、填充、边框和对齐方式等内容。

setDirty()

设置下一次重新计算发生时要重新计算的区域。

setRowProperties(rowPropertiesData)

基于行属性的一维数组汇报区域,并封装字体、填充、边框和对齐方式等内容。

showCard()

显示活动单元格的卡片(如果该单元格具有富值内容)。

showGroupDetails(groupOption)

显示行或列组的详细信息。

showGroupDetails(groupOptionString)

显示行或列组的详细信息。

toJSON()

重写 JavaScript toJSON() 方法,以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (,反过来又调用toJSON传递给它的 对象的 方法。) 而原始Excel.Range对象是 API 对象,toJSON该方法返回一个纯 JavaScript 对象, (类型为 Excel.Interfaces.RangeData) ,其中包含原始对象中任何已加载子属性的浅表副本。

track()

根据文档中的相应更改来跟踪对象,以便进行自动调整。 此调用是 context.trackedObjects.add (thisObject) 的简写。 如果跨 .sync 调用和“.run”批处理的顺序执行外部使用此对象,并在设置属性或调用对象方法时收到“InvalidObjectPath”错误,则需要在首次创建对象时将该对象添加到跟踪的对象集合。

ungroup(groupOption)

取消对大纲的列和行的分组。

ungroup(groupOptionString)

取消对大纲的列和行的分组。

unmerge()

将范围单元格取消合并为各个单元格。

untrack()

释放与此对象关联的内存(如果先前已跟踪过)。 此调用是 context.trackedObjects.remove (thisObject) 的简写。 拥有许多跟踪对象会降低主机应用程序的速度,因此请在使用完毕后释放所添加的任何对象。 在内存释放生效之前,需要调用 。context.sync()

属性详细信息

address

指定 A1 样式中的区域引用。 地址值包含工作表引用 (例如“Sheet1!A1:B4“) 。

readonly address: string;

属性值

string

注解

[ API 集:ExcelApi 1.1 ]

addressLocal

表示用户语言中指定范围的范围引用。

readonly addressLocal: string;

属性值

string

注解

[ API 集:ExcelApi 1.1 ]

cellCount

指定区域中的单元格数。 如果单元格数超过 2^31-1 (2,147,483,647),此 API 返回 -1。

readonly cellCount: number;

属性值

number

注解

[ API 集:ExcelApi 1.1 ]

columnCount

指定区域中的列总数。

readonly columnCount: number;

属性值

number

注解

[ API 集:ExcelApi 1.1 ]

columnHidden

表示当前范围中的所有列是否处于隐藏状态。 true当一个区域中的所有列都隐藏时,值。 false当区域中没有列处于隐藏状态时,该值为 。 null当某个区域中的某些列处于隐藏状态且不隐藏同一范围中的其他列时,该值表示。

columnHidden: boolean;

属性值

boolean

注解

[ API 集:ExcelApi 1.2 ]

columnIndex

指定区域中第一个单元格的列号。 从零开始编制索引。

readonly columnIndex: number;

属性值

number

注解

[ API 集:ExcelApi 1.1 ]

conditionalFormats

与范围相交的 的 集合 ConditionalFormats

readonly conditionalFormats: Excel.ConditionalFormatCollection;

属性值

注解

[ API 集:ExcelApi 1.6 ]

context

与 对象关联的请求上下文。 这会将加载项的进程连接到 Office 主机应用程序的进程。

context: RequestContext;

属性值

control

注意

此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

访问应用于此区域的单元格控件。 如果区域有多个单元格控件,则返回 EmptyCellControl

control: CellControl;

属性值

注解

[ API 集:ExcelApi BETA (仅预览版) ]

dataValidation

返回数据有效性对象。

readonly dataValidation: Excel.DataValidation;

属性值

注解

[ API 集:ExcelApi 1.8 ]

format

返回一个格式对象,其中封装了区域的字体、填充、边框、对齐方式和其他属性。

readonly format: Excel.RangeFormat;

属性值

注解

[ API 集:ExcelApi 1.1 ]

formulas

表示采用 A1 表示法的公式。 如果单元格没有公式,则返回其值。

formulas: any[][];

属性值

any[][]

注解

[ API 集:ExcelApi 1.1 ]

formulasLocal

表示采用 A1 样式表示法的公式,使用用户的语言和数字格式区域设置。 例如,英语中的公式 "=SUM(A1, 1.5)" 在德语中将变为 "=SUMME(A1; 1,5)"。 如果单元格没有公式,则返回其值。

formulasLocal: any[][];

属性值

any[][]

注解

[ API 集:ExcelApi 1.1 ]

formulasR1C1

表示采用 R1C1 样式表示法的公式。 如果单元格没有公式,则返回其值。

formulasR1C1: any[][];

属性值

any[][]

注解

[ API 集:ExcelApi 1.2 ]

hasSpill

表示所有单元格是否都具有溢出边框。 true如果所有单元格都有溢出边框,或者false所有单元格都没有溢出边框,则返回 。 null如果区域中有和没有溢出边框的单元格,则返回 。

readonly hasSpill: boolean;

属性值

boolean

注解

[ API 集:ExcelApi 1.12 ]

height

返回从范围上边缘到范围下边缘的 100% 缩放的距离(以磅为单位)。

readonly height: number;

属性值

number

注解

[ API 集:ExcelApi 1.10 ]

hidden

表示当前区域中的所有单元格是否处于隐藏状态。 值是 true 隐藏区域中的所有单元格时。 false当区域中没有单元格被隐藏时,值。 null当某个区域中的某些单元格处于隐藏状态,而同一区域中的其他单元格未隐藏时,值表示。

readonly hidden: boolean;

属性值

boolean

注解

[ API 集:ExcelApi 1.2 ]

表示当前范围的超链接。

hyperlink: Excel.RangeHyperlink;

属性值

注解

[ API 集:ExcelApi 1.7 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-hyperlink.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Orders");

    let productsRange = sheet.getRange("A3:A5");
    productsRange.load("values");

    await context.sync();

    // Create a hyperlink to a URL 
    // for each product name in the first table.
    for (let i = 0; i < productsRange.values.length; i++) {
        let cellRange = productsRange.getCell(i, 0);
        let cellText = productsRange.values[i][0];

        let hyperlink = {
            textToDisplay: cellText,
            screenTip: "Search Bing for '" + cellText + "'",
            address: "https://www.bing.com?q=" + cellText
        }
        cellRange.hyperlink = hyperlink;
    }

    await context.sync();
});

isEntireColumn

表示当前区域是否为整列。

readonly isEntireColumn: boolean;

属性值

boolean

注解

[ API 集:ExcelApi 1.7 ]

isEntireRow

表示当前区域是否为整行。

readonly isEntireRow: boolean;

属性值

boolean

注解

[ API 集:ExcelApi 1.7 ]

left

返回从工作表左边缘到区域左边缘的 100% 缩放的距离(以磅为单位)。

readonly left: number;

属性值

number

注解

[ API 集:ExcelApi 1.10 ]

linkedDataTypeState

表示每个单元格的数据类型状态。

readonly linkedDataTypeState: Excel.LinkedDataTypeState[][];

属性值

注解

[ API 集:ExcelApi 1.9 ]

numberFormat

表示给定区域的 Excel 数字格式代码。 有关 Excel 数字格式的详细信息,请参阅 数字格式代码

numberFormat: any[][];

属性值

any[][]

注解

[ API 集:ExcelApi 1.1 ]

示例

// Set the text of the chart title to "My Chart" and display it as an overlay on the chart.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "F5:G7";
    const numberFormat = [[null, "d-mmm"], [null, "d-mmm"], [null, null]]
    const values = [["Today", 42147], ["Tomorrow", "5/24"], ["Difference in days", null]];
    const formulas = [[null,null], [null,null], [null,"=G6-G5"]];
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.numberFormat = numberFormat;
    range.values = values;
    range.formulas= formulas;
    range.load('text');
    await context.sync();
    
    console.log(range.text);
});

numberFormatCategories

表示每个单元格的数字格式的类别。

readonly numberFormatCategories: Excel.NumberFormatCategory[][];

属性值

注解

[ API 集:ExcelApi 1.12 ]

numberFormatLocal

表示基于用户语言设置的给定区域的 Excel 数字格式代码。 获取或设置 numberFormatLocal 属性时,Excel 不执行任何语言或格式强制。 任何返回的文本都根据系统设置中指定的语言使用本地格式的字符串。

numberFormatLocal: any[][];

属性值

any[][]

注解

[ API 集:ExcelApi 1.7 ]

rowCount

返回区域中的总行数。

readonly rowCount: number;

属性值

number

注解

[ API 集:ExcelApi 1.1 ]

rowHidden

表示当前范围中的所有行是否处于隐藏状态。 值是 true 隐藏范围中的所有行时。 false当区域中没有隐藏行时,值。 null当某个区域中的某些行处于隐藏状态且同一区域中的其他行未隐藏时,该值表示。

rowHidden: boolean;

属性值

boolean

注解

[ API 集:ExcelApi 1.2 ]

rowIndex

返回区域中第一个单元格的行编号。 从零开始编制索引。

readonly rowIndex: number;

属性值

number

注解

[ API 集:ExcelApi 1.1 ]

savedAsArray

表示是否将所有单元格另存为数组公式。 true如果所有单元格都另存为数组公式,或者false所有单元格不另存为数组公式,则返回 。 null如果某些单元格将保存为数组公式,而有些单元格则不保存,则返回 。

readonly savedAsArray: boolean;

属性值

boolean

注解

[ API 集:ExcelApi 1.12 ]

sort

表示当前 range 的区域排序。

readonly sort: Excel.RangeSort;

属性值

注解

[ API 集:ExcelApi 1.2 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/event-column-and-row-sort.yaml

async function sortTopToBottom(criteria: string) {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1:E5");

        // Find the column header that provides the sort criteria.
        const header = range.find(criteria, {});
        header.load("columnIndex");
        await context.sync();

        range.sort.apply(
            [
                {
                    key: header.columnIndex,
                    sortOn: Excel.SortOn.value
                }
            ],
            false /*matchCase*/,
            true /*hasHeaders*/,
            Excel.SortOrientation.rows
        );
        await context.sync();
    });
}

style

表示当前区域的样式。 如果单元格的样式不一致, null 将返回 。 对于自定义样式,将返回样式名称。 对于内置样式,将返回表示枚举中的 BuiltInStyle 值的字符串。

style: string;

属性值

string

注解

[ API 集:ExcelApi 1.7 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/style.yaml

await Excel.run(async (context) => {
    let worksheet = context.workbook.worksheets.getItem("Sample");
    let range = worksheet.getRange("A1:E1");

    // Apply built-in style. 
    // Styles are in the Home tab ribbon.
    range.style = Excel.BuiltInStyle.neutral;
    range.format.horizontalAlignment = "Right";

    await context.sync();
});

text

指定区域的文本值。 文本值与单元格宽度无关。 Excel UI 中发生的数字符号 (#) 替换不会影响 API 返回的文本值。

readonly text: string[][];

属性值

string[][]

注解

[ API 集:ExcelApi 1.1 ]

top

返回从工作表上边缘到区域上边缘的 100% 缩放的距离(以磅为单位)。

readonly top: number;

属性值

number

注解

[ API 集:ExcelApi 1.10 ]

values

表示指定区域的原始值。 返回的数据可以是字符串、数字或布尔值。 包含错误的单元格将返回错误字符串。 如果返回的值以加号 (“+”) 、减 (“-”) 或等号 (“=”) 开头,Excel 会将此值解释为公式。

values: any[][];

属性值

any[][]

注解

[ API 集:ExcelApi 1.1 ]

valuesAsJson

此区域中单元格中值的 JSON 表示形式。 与 不同 Range.valuesRange.valuesAsJson 支持可在单元格中的所有数据类型。 示例包括格式化的数字值和 Web 图像,以及标准布尔值、数字值和字符串值。 从此 API 返回的数据始终与 en-US 区域设置一致。 若要检索用户的显示区域设置中的数据,请使用 Range.valuesAsJsonLocal

valuesAsJson: CellValue[][];

属性值

注解

[ API 集:ExcelApi 1.16 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/20-data-types/data-types-formatted-number.yaml

// This function creates a formatted number data type,
// and sets the format of this data type as a date.
await Excel.run(async (context) => {
  // Get the Sample worksheet and a range on that sheet.
  const sheet = context.workbook.worksheets.getItemOrNullObject("Sample");
  const dateRange = sheet.getRange("A1");

  // Write a number formatted as a date to cell A1.
  dateRange.valuesAsJson = [
    [
      {
        type: Excel.CellValueType.formattedNumber,
        basicValue: 32889.0,
        numberFormat: "m/d/yyyy"
      }
    ]
  ];
  await context.sync();
});

valuesAsJsonLocal

此区域中单元格中值的 JSON 表示形式。 与 不同 Range.valuesRange.valuesAsJsonLocal 支持可在单元格中的所有数据类型。 示例包括格式化的数字值和 Web 图像,以及标准布尔值、数字值和字符串值。 从此 API 返回的数据始终与用户的显示区域设置保持一致。 若要检索独立于区域设置的数据,请使用 Range.valuesAsJson

valuesAsJsonLocal: CellValue[][];

属性值

注解

[ API 集:ExcelApi 1.16 ]

valueTypes

指定每个单元格中的数据类型。

readonly valueTypes: Excel.RangeValueType[][];

属性值

注解

[ API 集:ExcelApi 1.1 ]

width

返回从范围的左边缘到范围右边缘的 100% 缩放的距离(以磅为单位)。

readonly width: number;

属性值

number

注解

[ API 集:ExcelApi 1.10 ]

worksheet

包含当前区域的工作表。

readonly worksheet: Excel.Worksheet;

属性值

注解

[ API 集:ExcelApi 1.1 ]

方法详细信息

autoFill(destinationRange, autoFillType)

使用指定的自动填充逻辑填充从当前范围到目标范围的范围。 目标范围可以是 null 或可以水平或垂直扩展源范围。 不支持不连续的范围。

有关详细信息,请参阅 使用自动填充和快速填充

autoFill(destinationRange?: Range | string, autoFillType?: Excel.AutoFillType): void;

参数

destinationRange

Excel.Range | string

要自动填充的目标范围。 如果目标区域为 null,则会根据周围的单元格填充数据 (这是双击 UI 的区域填充句柄) 时的行为。

autoFillType
Excel.AutoFillType

自动填充的类型。 根据当前范围的内容指定如何填充目标范围。 默认值为“FillDefault”。

返回

void

注解

[ API set: ExcelApi 1.9, ExcelApi Preview for null destinationRange ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-auto-fill.yaml

await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const sumCell = sheet.getRange("P4");
  
  // Copy everything. The formulas will be contextually updated based on their new locations.
  sumCell.autoFill("P4:P7", Excel.AutoFillType.fillCopy);
  sumCell.format.autofitColumns();
  await context.sync();
});

autoFill(destinationRange, autoFillTypeString)

使用指定的自动填充逻辑填充从当前范围到目标范围的范围。 目标范围可以是 null 或可以水平或垂直扩展源范围。 不支持不连续的范围。

有关详细信息,请参阅 使用自动填充和快速填充

autoFill(destinationRange?: Range | string, autoFillTypeString?: "FillDefault" | "FillCopy" | "FillSeries" | "FillFormats" | "FillValues" | "FillDays" | "FillWeekdays" | "FillMonths" | "FillYears" | "LinearTrend" | "GrowthTrend" | "FlashFill"): void;

参数

destinationRange

Excel.Range | string

要自动填充的目标范围。 如果目标区域为 null,则会根据周围的单元格填充数据 (这是双击 UI 的区域填充句柄) 时的行为。

autoFillTypeString

"FillDefault" | "FillCopy" | "FillSeries" | "FillFormats" | "FillValues" | "FillDays" | "FillWeekdays" | "FillMonths" | "FillYears" | "LinearTrend" | "GrowthTrend" | "FlashFill"

自动填充的类型。 根据当前范围的内容指定如何填充目标范围。 默认值为“FillDefault”。

返回

void

注解

[ API set: ExcelApi 1.9, ExcelApi Preview for null destinationRange ]

calculate()

计算工作表上的单元格区域。

calculate(): void;

返回

void

注解

[ API 集:ExcelApi 1.6 ]

clear(applyTo)

清除范围值和格式设置,例如填充和边框。

clear(applyTo?: Excel.ClearApplyTo): void;

参数

applyTo
Excel.ClearApplyTo

可选。 确定清除操作的类型。 有关详细信息,请参阅 Excel.ClearApplyTo

返回

void

注解

[ API 集:ExcelApi 1.1 ]

示例

// Clear the format and contents of the range.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.clear();
    await context.sync(); 
});

clear(applyToString)

清除范围值和格式设置,例如填充和边框。

clear(applyToString?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks" | "ResetContents"): void;

参数

applyToString

"All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks" | "ResetContents"

可选。 确定清除操作的类型。 有关详细信息,请参阅 Excel.ClearApplyTo

返回

void

注解

[ API 集:ExcelApi 1.1 ]

clearOrResetContents()

注意

此 API 以预览状态提供给开发者,可能根据我们收到的反馈更改。 请勿在生产环境中使用此 API。

清除区域中单元格的值,并特别考虑包含控件的单元格。 如果区域仅包含空白值和设置为默认值的控件,则会删除值和控件格式。 否则,这会将包含控件的单元格设置为默认值,并清除区域中其他单元格的值。

clearOrResetContents(): void;

返回

void

注解

[ API 集:ExcelApi BETA (仅预览版) ]

convertDataTypeToText()

将数据类型为文本的区域单元格。

convertDataTypeToText(): void;

返回

void

注解

[ API 集:ExcelApi 1.9 ]

convertToLinkedDataType(serviceID, languageCulture)

在工作表中将区域单元格转换为链接数据类型。

convertToLinkedDataType(serviceID: number, languageCulture: string): void;

参数

serviceID

number

用于查询数据的服务 ID。

languageCulture

string

要查询服务的语言区域性。

返回

void

注解

[ API 集:ExcelApi 1.9 ]

copyFrom(sourceRange, copyType, skipBlanks, transpose)

将单元格数据或格式从源区域或 RangeAreas 复制到当前区域。 目标范围的大小可以不同于源范围或 RangeAreas。 如果目标小于源,则会自动扩展。 注意:与 Excel UI 中的复制功能一样,如果目标范围正好大于行或列中源范围的倍数,则会多次复制源内容。 例如,将 2x2 范围复制到 2x6 范围将导致原始 2x2 范围的 3 个副本。

copyFrom(sourceRange: Range | RangeAreas | string, copyType?: Excel.RangeCopyType, skipBlanks?: boolean, transpose?: boolean): void;

参数

sourceRange

Excel.Range | Excel.RangeAreas | string

要从中复制的源范围或 RangeAreas 。 当源 RangeAreas 具有多个区域时,必须能够通过从矩形区域中删除完整的行或列来创建其窗体。

copyType
Excel.RangeCopyType

要复制的单元格数据或格式的类型。 默认值为“All”。

skipBlanks

boolean

如果跳过源区域中的空白单元格,则为 True。 默认为 false。

transpose

boolean

如此 如果转置目标区域中的单元格。 默认为 false。

返回

void

注解

[ API 集:ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-copyfrom.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    // Place a label in front of the copied data.
    sheet.getRange("F2").values = [["Copied Formula"]];

    // Copy a range preserving the formulas.
    // Note: non-formula values are copied over as is.
    sheet.getRange("G2").copyFrom("A1:E1", Excel.RangeCopyType.formulas);
    await context.sync();
});

copyFrom(sourceRange, copyTypeString, skipBlanks, transpose)

将单元格数据或格式从源区域或 RangeAreas 复制到当前区域。 目标范围的大小可以不同于源范围或 RangeAreas。 如果目标小于源,则会自动扩展。 注意:与 Excel UI 中的复制功能一样,如果目标范围正好大于行或列中源范围的倍数,则会多次复制源内容。 例如,将 2x2 范围复制到 2x6 范围将导致原始 2x2 范围的 3 个副本。

copyFrom(sourceRange: Range | RangeAreas | string, copyTypeString?: "All" | "Formulas" | "Values" | "Formats" | "Link" | "ColumnWidths", skipBlanks?: boolean, transpose?: boolean): void;

参数

sourceRange

Excel.Range | Excel.RangeAreas | string

要从中复制的源范围或 RangeAreas 。 当源 RangeAreas 具有多个区域时,必须能够通过从矩形区域中删除完整的行或列来创建其窗体。

copyTypeString

"All" | "Formulas" | "Values" | "Formats" | "Link" | "ColumnWidths"

要复制的单元格数据或格式的类型。 默认值为“All”。

skipBlanks

boolean

如果跳过源区域中的空白单元格,则为 True。 默认为 false。

transpose

boolean

如此 如果转置目标区域中的单元格。 默认为 false。

返回

void

注解

[ API 集:ExcelApi 1.9 ]

delete(shift)

删除与区域相关的单元格。

delete(shift: Excel.DeleteShiftDirection): void;

参数

shift
Excel.DeleteShiftDirection

指定移动单元格的方式。 有关详细信息,请参阅 Excel.DeleteShiftDirection

返回

void

注解

[ API 集:ExcelApi 1.1 ]

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.delete("Left");
    await context.sync(); 
});

delete(shiftString)

删除与区域相关的单元格。

delete(shiftString: "Up" | "Left"): void;

参数

shiftString

"Up" | "Left"

指定移动单元格的方式。 有关详细信息,请参阅 Excel.DeleteShiftDirection

返回

void

注解

[ API 集:ExcelApi 1.1 ]

find(text, criteria)

根据指定的条件查找给定的字符串。 如果当前区域大于单个单元格,则搜索将限制为该范围,否则搜索将涵盖从该单元格之后开始的整个工作表。

find(text: string, criteria: Excel.SearchCriteria): Excel.Range;

参数

text

string

要查找的字符串。

criteria
Excel.SearchCriteria

其他搜索条件,包括搜索方向以及搜索是否需要匹配整个单元格还是区分大小写。

返回

表示 Range 包含与搜索文本和条件匹配的值的第一个单元格的 对象。

注解

[ API 集:ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-find.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const table = sheet.tables.getItem("ExpensesTable");
    const searchRange = table.getRange();

    // NOTE: If no match is found, an ItemNotFound error
    // is thrown when Range.find is evaluated.
    const foundRange = searchRange.find($("#searchText").val().toString(), {
        completeMatch: isCompleteMatchToggle,
        matchCase: isMatchCaseToggle,
        searchDirection: searchDirectionToggle
    });
    
    foundRange.load("address");
    await context.sync();


    console.log(foundRange.address);
});

findOrNullObject(text, criteria)

根据指定的条件查找给定的字符串。 如果当前区域大于单个单元格,则搜索将限制为该范围,否则搜索将涵盖从该单元格之后开始的整个工作表。 如果没有匹配项,则此方法返回对象的 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

findOrNullObject(text: string, criteria: Excel.SearchCriteria): Excel.Range;

参数

text

string

要查找的字符串。

criteria
Excel.SearchCriteria

其他搜索条件,包括搜索方向以及搜索是否需要匹配整个单元格还是区分大小写。

返回

Range与搜索条件匹配的 。

注解

[ API 集:ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-find.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const table = sheet.tables.getItem("ExpensesTable");
    const searchRange = table.getRange();
    const foundRange = searchRange.findOrNullObject($("#searchText").val().toString(), {
        completeMatch: isCompleteMatchToggle,
        matchCase: isMatchCaseToggle,
        searchDirection: searchDirectionToggle
    });
    
    foundRange.load("address");
    await context.sync();

    if (foundRange.isNullObject) {
        console.log("Text not found");
    } else {
        console.log(foundRange.address);
    }
});

flashFill()

对当前范围执行快速填充。 快速填充在感知模式时自动填充数据,因此范围必须是单个列范围,并且周围有数据才能找到模式。

flashFill(): void;

返回

void

注解

[ API 集:ExcelApi 1.9 ]

getAbsoluteResizedRange(numRows, numColumns)

获取一个 Range 对象,该对象具有与当前 Range 对象相同的左上角单元格,但具有指定的行数和列数。

getAbsoluteResizedRange(numRows: number, numColumns: number): Excel.Range;

参数

numRows

number

新范围大小的行数。

numColumns

number

新范围大小的列数。

返回

注解

[ API 集:ExcelApi 1.7 ]

getBoundingRect(anotherRange)

获取包含指定区域的最小 range 对象。 例如, GetBoundingRect “B2:C5”和“D10:E15”的 为“B2:E15”。

getBoundingRect(anotherRange: Range | string): Excel.Range;

参数

anotherRange

Excel.Range | string

范围对象、地址或范围名称。

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D4:G6";
    let range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range = range.getBoundingRect("G4:H8");
    range.load('address');
    await context.sync();
    
    console.log(range.address); // Prints Sheet1!D4:H8
});

getCell(row, column)

根据行和列编号获取包含单个单元格的 range 对象。 单元格可以位于其父区域的边界之外,只要它保留在工作表网格中。 返回的单元格位于相对于区域左上角的单元格的位置。

getCell(row: number, column: number): Excel.Range;

参数

row

number

要检索的单元格的行号。 从零开始编制索引。

column

number

要检索的单元格的列号。 从零开始编制索引。

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    const cell = range.getCell(0,0);
    cell.load('address');
    await context.sync();
    
    console.log(cell.address);
});

getCellProperties(cellPropertiesLoadOptions)

返回一个 2D 数组,其中封装了每个单元格的字体、填充、边框、对齐方式和其他属性数据。

getCellProperties(cellPropertiesLoadOptions: CellPropertiesLoadOptions): OfficeExtension.ClientResult<CellProperties[][]>;

参数

cellPropertiesLoadOptions
Excel.CellPropertiesLoadOptions

一个 对象,表示要加载的单元格属性。

返回

一个 2D 数组,其中每个项表示相应单元格的请求属性。

注解

[ API 集:ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/cell-properties.yaml

await Excel.run(async (context) => {
    const cell = context.workbook.getActiveCell();

    // Define the cell properties to get by setting the matching LoadOptions to true.
    const propertiesToGet = cell.getCellProperties({
        address: true,
        format: {
            fill: {
                color: true
            },
            font: {
                color: true
            }
        },
        style: true
    });

    // Sync to get the data from the workbook.
    await context.sync();
    const cellProperties = propertiesToGet.value[0][0];
    console.log(
        `Address: ${cellProperties.address}\nStyle: ${cellProperties.style}\nFill Color: ${cellProperties.format.fill.color}\nFont Color: ${cellProperties.format.font.color}`);
});

getColumn(column)

获取范围中包含的列。

getColumn(column: number): Excel.Range;

参数

column

number

要检索的区域的列号。 从零开始编制索引。

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet19";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getColumn(1);
    range.load('address');
    await context.sync();

    console.log(range.address); // prints Sheet1!B1:B8
});

getColumnProperties(columnPropertiesLoadOptions)

返回一个一维数组,其中封装了每个列的字体、填充、边框、对齐方式和其他属性数据。 对于给定列中每个单元格不一致的属性,将返回 null。

getColumnProperties(columnPropertiesLoadOptions: ColumnPropertiesLoadOptions): OfficeExtension.ClientResult<ColumnProperties[]>;

参数

columnPropertiesLoadOptions
Excel.ColumnPropertiesLoadOptions

一个 对象,表示要加载的列属性。

返回

一个数组,其中每个项表示相应列的请求属性。

注解

[ API 集:ExcelApi 1.9 ]

getColumnsAfter(count)

获取当前 Range 对象右侧的一定数量的列。

getColumnsAfter(count?: number): Excel.Range;

参数

count

number

可选。 生成的范围中要包含的列数。 一般来说,使用正数可以在当前范围之外创建一个范围。 也可以使用负数在当前范围之内创建一个范围。 默认值为 1。

返回

注解

[ API 集:ExcelApi 1.2 ]

getColumnsBefore(count)

获取当前 Range 对象左侧的一定数量的列。

getColumnsBefore(count?: number): Excel.Range;

参数

count

number

可选。 生成的范围中要包含的列数。 一般来说,使用正数可以在当前范围之外创建一个范围。 也可以使用负数在当前范围之内创建一个范围。 默认值为 1。

返回

注解

[ API 集:ExcelApi 1.2 ]

getDependents()

返回一个 WorkbookRangeAreas 对象,该对象表示包含同一工作表中或多个工作表中指定区域的所有依赖单元格的区域。 注意:如果未找到依赖项,此 API 将返回错误 ItemNotFound

getDependents(): Excel.WorkbookRangeAreas;

返回

注解

[ API 集:ExcelApi 1.15 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-dependents.yaml

// This function highlights all the dependent cells of the active cell.
// Dependent cells contain formulas that refer to other cells.
await Excel.run(async (context) => {
  // Get addresses of the active cell's dependent cells.
  const range = context.workbook.getActiveCell();
  const dependents = range.getDependents();
  range.load("address");
  dependents.areas.load("address");
  await context.sync();

  console.log(`All dependent cells of ${range.address}:`);

  // Use the dependents API to loop through dependents of the active cell.
  for (let i = 0; i < dependents.areas.items.length; i++) {
    // Highlight and print out the address of each dependent cell.
    dependents.areas.items[i].format.fill.color = "Orange";
    console.log(`  ${dependents.areas.items[i].address}`);
  }
  await context.sync();
});

getDirectDependents()

返回一个 对象,该对象表示包含同一 WorkbookRangeAreas 工作表中或跨多个工作表的指定区域的所有直接依赖单元格的区域。 注意:如果未找到依赖项,此 API 将返回错误 ItemNotFound

getDirectDependents(): Excel.WorkbookRangeAreas;

返回

注解

[ API 集:ExcelApi 1.13 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-direct-dependents.yaml

await Excel.run(async (context) => {
  // Direct dependents are cells that contain formulas that refer to other cells.
  let range = context.workbook.getActiveCell();
  let directDependents = range.getDirectDependents();
  range.load("address");
  directDependents.areas.load("address");
  await context.sync();
  
  console.log(`Direct dependent cells of ${range.address}:`);
  
  // Use the direct dependents API to loop through direct dependents of the active cell.
  for (let i = 0; i < directDependents.areas.items.length; i++) {
    // Highlight and print the address of each dependent cell.
    directDependents.areas.items[i].format.fill.color = "Yellow";
    console.log(`  ${directDependents.areas.items[i].address}`);
  }
  await context.sync();
});

getDirectPrecedents()

返回一个 WorkbookRangeAreas 对象,该对象表示包含同一工作表中或跨多个工作表的指定区域的所有直接引用单元格的区域。 注意:如果未找到任何先例,此 API 将返回错误 ItemNotFound

getDirectPrecedents(): Excel.WorkbookRangeAreas;

返回

注解

[ API 集:ExcelApi 1.12 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/precedents.yaml

await Excel.run(async (context) => {
  // Precedents are cells referenced by the formula in a cell.
  // A "direct precedent" is a cell directly referenced by the selected formula.
  let range = context.workbook.getActiveCell();
  let directPrecedents = range.getDirectPrecedents();
  range.load("address");
  directPrecedents.areas.load("address");
  await context.sync();

  console.log(`Direct precedent cells of ${range.address}:`);

  // Use the direct precedents API to loop through precedents of the active cell.
  for (let i = 0; i < directPrecedents.areas.items.length; i++) {
    // Highlight and console the address of each precedent cell.
    directPrecedents.areas.items[i].format.fill.color = "Yellow";
    console.log(`  ${directPrecedents.areas.items[i].address}`);
  }
  await context.sync();
});

getEntireColumn()

获取一个 对象,该对象表示区域 (的整个列,例如,如果当前区域表示单元格“B4:E11”,则它是 getEntireColumn 表示列“B:E”) 的区域。

getEntireColumn(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

// Note: the grid properties of the Range (values, numberFormat, formulas) 
// contains null since the Range in question is unbounded.
await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D:F";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    const rangeEC = range.getEntireColumn();
    rangeEC.load('address');
    await context.sync();
    
    console.log(rangeEC.address);
});

getEntireRow()

获取一个对象,该对象表示区域 (的整行,例如,如果当前区域表示单元格“B4:E11”,则它是 GetEntireRow 表示行“4:11”) 的区域。

getEntireRow(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

// Gets an object that represents the entire row of the range 
// (for example, if the current range represents cells "B4:E11", 
// its GetEntireRow is a range that represents rows "4:11").
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "D:F"; 
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    const rangeER = range.getEntireRow();
    rangeER.load('address');
    await context.sync();
    
    console.log(rangeER.address);
});

getExtendedRange(direction, activeCell)

返回一个 range 对象,该对象包括当前范围以及范围边缘,具体取决于提供的方向。 这与 Windows 上的 Excel UI 中的 Ctrl+Shift+箭头键行为匹配。

getExtendedRange(direction: Excel.KeyboardDirection, activeCell?: Range | string): Excel.Range;

参数

direction
Excel.KeyboardDirection

活动单元格的方向。

activeCell

Excel.Range | string

此区域中的活动单元格。 默认情况下,活动单元格是区域的左上角单元格。 如果活动单元格不在此范围内,则会引发错误。

返回

注解

[ API 集:ExcelApi 1.13 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-get-range-edge.yaml

await Excel.run(async (context) => {
  // Get the selected range.
  const range = context.workbook.getSelectedRange();

  // Specify the direction with the `KeyboardDirection` enum.
  const direction = Excel.KeyboardDirection.down;

  // Get the active cell in the workbook.
  const activeCell = context.workbook.getActiveCell();

  // Get all the cells from the currently selected range to the bottom-most edge of the used range.
  // This method acts like the Ctrl+Shift+Arrow key keyboard shortcut while a range is selected.
  const extendedRange = range.getExtendedRange(
    direction,
    activeCell // If the selected range contains more than one cell, the active cell must be defined.
  );
  extendedRange.select();

  await context.sync();
});

getExtendedRange(directionString, activeCell)

返回一个 range 对象,该对象包括当前范围以及范围边缘,具体取决于提供的方向。 这与 Windows 上的 Excel UI 中的 Ctrl+Shift+箭头键行为匹配。

getExtendedRange(directionString: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;

参数

directionString

"Left" | "Right" | "Up" | "Down"

活动单元格的方向。

activeCell

Excel.Range | string

此区域中的活动单元格。 默认情况下,活动单元格是区域的左上角单元格。 如果活动单元格不在此范围内,则会引发错误。

返回

注解

[ API 集:ExcelApi 1.13 ]

getImage()

将范围呈现为 Base64 编码的 png 图像。 重要说明*:Excel for Mac目前不支持此 API。 有关当前状态,请访问 OfficeDev/office-js 问题 #235

getImage(): OfficeExtension.ClientResult<string>;

返回

注解

[ API 集:ExcelApi 1.7 ]

getIntersection(anotherRange)

获取表示指定区域的矩形交集的 range 对象。

getIntersection(anotherRange: Range | string): Excel.Range;

参数

anotherRange

Excel.Range | string

将用于确定区域交集的 range 对象或区域地址。

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = 
        context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getIntersection("D4:G6");
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!D4:F6
});

getIntersectionOrNullObject(anotherRange)

获取表示指定区域的矩形交集的 range 对象。 如果未找到交集,则此方法返回一个 对象,其 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getIntersectionOrNullObject(anotherRange: Range | string): Excel.Range;

参数

anotherRange

Excel.Range | string

将用于确定区域交集的 range 对象或区域地址。

返回

注解

[ API 集:ExcelApi 1.4 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-relationships.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // We want the most recent quarter that has data, so
    // exclude quarters without data and get the last of
    // the remaining columns.
    const usedDataRange = dataRange.getUsedRange(true /* valuesOnly */);
    const currentQuarterRange = usedDataRange.getLastColumn();

    // Asian and European teams have separate contests.
    const asianSalesRange = sheet.getRange("A2:E4");
    const europeanSalesRange = sheet.getRange("A5:E7");

    // The data for each chart is the intersection of the
    // current quarter column and the rows for the continent.
    const asianContestRange = asianSalesRange.getIntersectionOrNullObject(currentQuarterRange);
    const europeanContestRange = europeanSalesRange.getIntersectionOrNullObject(currentQuarterRange);

    // Must sync before you can test the output of *OrNullObject
    // method/property.
    await context.sync();

    if (asianContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("Asian");
    } else {
        createContinentChart(
            sheet,
            "Asian",
            asianContestRange,
            "A9",
            "F24"
        );
    }

    if (europeanContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("European");
    } else {
        createContinentChart(
            sheet,
            "European",
            europeanContestRange,
            "A25",
            "F40"
        );
    }

    await context.sync();
});

getLastCell()

获取区域内的最后一个单元格。 例如,“B2:D5”的最后一个单元格是“D5”。

getLastCell(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastCell();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!F8
});

getLastColumn()

获取区域内的最后一列。 例如,“B2:D5”的最后一列是“D2:D5”。

getLastColumn(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastColumn();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!F1:F8
});

getLastRow()

获取区域内的最后一行。 例如,“B2:D5”的最后一行是“B5:D5”。

getLastRow(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getLastRow();
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!A8:F8
});

getMergedAreasOrNullObject()

返回一个 RangeAreas 对象,该对象代表此区域中的合并区域。 请注意,如果此范围内的合并区域计数超过 512,则此方法将无法返回结果。 RangeAreas如果该对象不存在,则此函数将返回一个对象,其isNullObject属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getMergedAreasOrNullObject(): Excel.RangeAreas;

返回

注解

[ API 集:ExcelApi 1.13 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-merged-ranges.yaml

await Excel.run(async (context) => {
  // Retrieve the worksheet and the table in that worksheet.
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const tableRange = sheet.getRange("B2:E6");

  // Retrieve the merged range within the table and load its details.
  const mergedAreas = tableRange.getMergedAreasOrNullObject();
  mergedAreas.load("address");
  mergedAreas.load("cellCount");

  // Select the merged range.
  const range = mergedAreas.areas.getItemAt(0);
  range.select();
  await context.sync();

  // Print out the details of the `mergedAreas` range object.
  console.log(`Address of the merged range: ${mergedAreas.address}`);
  console.log(`Number of cells in the merged range: ${mergedAreas.cellCount}`);

  await context.sync();
});

getOffsetRange(rowOffset, columnOffset)

获取表示与指定区域偏移的区域的对象。 返回的区域的尺寸将与此区域一致。 如果强制在工作表网格的边界之外生成区域,将引发错误。

getOffsetRange(rowOffset: number, columnOffset: number): Excel.Range;

参数

rowOffset

number

区域偏移的行数(正数、负数或 0)。 正值表示向下偏移,负值表示向上偏移。

columnOffset

number

区域偏移的列数(正数、负数或 0)。 正值表示向右偏移,负值表示向左偏移。

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "D4:F6";
    const range = 
        context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getOffsetRange(-1,4);
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!H3:J5
});

getPivotTables(fullyContained)

获取与区域重叠的数据透视表的作用域集合。

getPivotTables(fullyContained?: boolean): Excel.PivotTableScopedCollection;

参数

fullyContained

boolean

如果 true为 ,则仅返回完全包含在范围边界中的数据透视表。 默认值 false为 。

返回

注解

[ API 集:ExcelApi 1.12 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-get-pivottables.yaml

await Excel.run(async (context) => {
  const activeRange = context.workbook.getSelectedRange();

  // Get all the PivotTables that intersect with this range.
  const partiallyContainedPivotTables = activeRange.getPivotTables();
  // Get all the PivotTables that are completely contained within this range.
  const fullyContainedPivotTables = activeRange.getPivotTables(true);

  partiallyContainedPivotTables.load("name");
  fullyContainedPivotTables.load("name");
  await context.sync();

  // Display the names in the console.
  console.log("PivotTables in the current range:")
  partiallyContainedPivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
  console.log("PivotTables completely contained in the current range:")
  fullyContainedPivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
});

getPrecedents()

返回一个 对象,该对象表示包含同一 WorkbookRangeAreas 工作表中或跨多个工作表的指定区域的所有前置单元格的区域。 注意:如果未找到任何先例,此 API 将返回错误 ItemNotFound

getPrecedents(): Excel.WorkbookRangeAreas;

返回

注解

[ API 集:ExcelApi 1.14 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/precedents.yaml

await Excel.run(async (context) => {
  // Precedents are cells referenced by the formula in a cell.
  let range = context.workbook.getActiveCell();
  let precedents = range.getPrecedents();
  range.load("address");
  precedents.areas.load("address");
  await context.sync();

  console.log(`All precedent cells of ${range.address}:`);

  // Use the precedents API to loop through precedents of the active cell.
  for (let i = 0; i < precedents.areas.items.length; i++) {
    // Highlight and console the address of each precedent cell.
    precedents.areas.items[i].format.fill.color = "Orange";
    console.log(`  ${precedents.areas.items[i].address}`);
  }
  await context.sync();
});

getRangeEdge(direction, activeCell)

返回一个 range 对象,该对象是与提供的方向对应的数据区域边缘单元格。 这与 Excel on Windows UI 中的 Ctrl+Arrow 键行为匹配。

getRangeEdge(direction: Excel.KeyboardDirection, activeCell?: Range | string): Excel.Range;

参数

direction
Excel.KeyboardDirection

活动单元格的方向。

activeCell

Excel.Range | string

此区域中的活动单元格。 默认情况下,活动单元格是区域的左上角单元格。 如果活动单元格不在此范围内,则会引发错误。

返回

注解

[ API 集:ExcelApi 1.13 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-get-range-edge.yaml

await Excel.run(async (context) => {
  // Get the selected range.
  const range = context.workbook.getSelectedRange();

  // Specify the direction with the `KeyboardDirection` enum.
  const direction = Excel.KeyboardDirection.up;

  // Get the active cell in the workbook.
  const activeCell = context.workbook.getActiveCell();

  // Get the top-most cell of the current used range.
  // This method acts like the Ctrl+Arrow key keyboard shortcut while a range is selected.
  const rangeEdge = range.getRangeEdge(
    direction,
    activeCell // If the selected range contains more than one cell, the active cell must be defined.
  );
  rangeEdge.select();

  await context.sync();
});

getRangeEdge(directionString, activeCell)

返回一个 range 对象,该对象是与提供的方向对应的数据区域边缘单元格。 这与 Excel on Windows UI 中的 Ctrl+Arrow 键行为匹配。

getRangeEdge(directionString: "Left" | "Right" | "Up" | "Down", activeCell?: Range | string): Excel.Range;

参数

directionString

"Left" | "Right" | "Up" | "Down"

活动单元格的方向。

activeCell

Excel.Range | string

此区域中的活动单元格。 默认情况下,活动单元格是区域的左上角单元格。 如果活动单元格不在此范围内,则会引发错误。

返回

注解

[ API 集:ExcelApi 1.13 ]

getResizedRange(deltaRows, deltaColumns)

获取与 Range 当前 Range 对象类似的对象,但其右下角展开 (或按行和列数收缩) 。

getResizedRange(deltaRows: number, deltaColumns: number): Excel.Range;

参数

deltaRows

number

相对于当前范围,展开右下角的行数。 使用正数可展开范围,使用负数可合拢范围。

deltaColumns

number

相对于当前范围展开右下角的列数。 使用正数可展开范围,使用负数可合拢范围。

返回

注解

[ API 集:ExcelApi 1.2 ]

getRow(row)

获取范围中包含的行。

getRow(row: number): Excel.Range;

参数

row

number

要检索的区域的行号。 从零开始编制索引。

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress).getRow(1);
    range.load('address');
    await context.sync();
    
    console.log(range.address); // prints Sheet1!A2:F2
});

getRowProperties(rowPropertiesLoadOptions)

返回一个一维数组,其中封装了每个行的字体、填充、边框、对齐方式和其他属性数据。 对于在给定行内每个单元格中不一致的属性, null 将返回 。

getRowProperties(rowPropertiesLoadOptions: RowPropertiesLoadOptions): OfficeExtension.ClientResult<RowProperties[]>;

参数

rowPropertiesLoadOptions
Excel.RowPropertiesLoadOptions

一个 对象,表示要加载的行属性。

返回

一个数组,其中每个项表示相应行的请求属性。

注解

[ API 集:ExcelApi 1.9 ]

getRowsAbove(count)

获取当前 Range 对象上方的一定行数。

getRowsAbove(count?: number): Excel.Range;

参数

count

number

可选。 生成的范围中要包含的行数。 一般来说,使用正数可以在当前范围之外创建一个范围。 也可以使用负数在当前范围之内创建一个范围。 默认值为 1。

返回

注解

[ API 集:ExcelApi 1.2 ]

getRowsBelow(count)

获取当前 Range 对象下面的特定行数。

getRowsBelow(count?: number): Excel.Range;

参数

count

number

可选。 生成的范围中要包含的行数。 一般来说,使用正数可以在当前范围之外创建一个范围。 也可以使用负数在当前范围之内创建一个范围。 默认值为 1。

返回

注解

[ API 集:ExcelApi 1.2 ]

getSpecialCells(cellType, cellValueType)

RangeAreas获取对象,该对象包含一个或多个矩形区域,该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格, ItemNotFound 则会引发错误。

getSpecialCells(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

参数

cellType
Excel.SpecialCellType

要包含的单元格类型。

cellValueType
Excel.SpecialCellValueType

如果 cellTypeconstantsformulas,则此参数用于确定结果中要包含的单元格类型。 这些值可以组合在一起以返回多个类型。 默认情况下,将选择所有常量或公式,无论类型如何。

返回

注解

[ API 集:ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-areas.yaml

await Excel.run(async (context) => {

    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const usedRange = sheet.getUsedRange();

    // Find the ranges with either text or logical (boolean) values.
    const formulaRanges = usedRange.getSpecialCells("Constants", "LogicalText");
    formulaRanges.format.fill.color = "orange";

    return context.sync();
});

getSpecialCells(cellTypeString, cellValueTypeString)

RangeAreas获取对象,该对象包含一个或多个矩形区域,该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格, ItemNotFound 则会引发错误。

getSpecialCells(cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible", cellValueTypeString?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;

参数

cellTypeString

"ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible"

要包含的单元格类型。

cellValueTypeString

"All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"

如果 cellTypeconstantsformulas,则此参数用于确定结果中要包含的单元格类型。 这些值可以组合在一起以返回多个类型。 默认情况下,将选择所有常量或公式,无论类型如何。

返回

注解

[ API 集:ExcelApi 1.9 ]

getSpecialCellsOrNullObject(cellType, cellValueType)

RangeAreas获取由一个或多个区域组成的 对象,该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格,则此方法返回一个 对象,其 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;

参数

cellType
Excel.SpecialCellType

要包含的单元格类型。

cellValueType
Excel.SpecialCellValueType

如果 cellTypeconstantsformulas,则此参数用于确定结果中要包含的单元格类型。 这些值可以组合在一起以返回多个类型。 默认情况下,将选择所有常量或公式,无论类型如何。

返回

注解

[ API 集:ExcelApi 1.9 ]

getSpecialCellsOrNullObject(cellTypeString, cellValueTypeString)

RangeAreas获取由一个或多个区域组成的 对象,该对象表示与指定类型和值匹配的所有单元格。 如果未找到任何特殊单元格,则此方法返回一个 对象,其 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getSpecialCellsOrNullObject(cellTypeString: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible", cellValueTypeString?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;

参数

cellTypeString

"ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible"

要包含的单元格类型。

cellValueTypeString

"All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"

如果 cellTypeconstantsformulas,则此参数用于确定结果中要包含的单元格类型。 这些值可以组合在一起以返回多个类型。 默认情况下,将选择所有常量或公式,无论类型如何。

返回

注解

[ API 集:ExcelApi 1.9 ]

getSpillingToRange()

获取 Range 对象,它在调用定位单元格时包含溢出区域。 如果应用于具有多个单元格的区域,则会失败。

getSpillingToRange(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.12 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/dynamic-arrays.yaml

await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getItem("Sample");

  // Set G4 to a formula that returns a dynamic array.
  const targetCell = sheet.getRange("G4");
  targetCell.formulas = [["=A4:D4"]];

  // Get the address of the cells that the dynamic array spilled into.
  const spillRange = targetCell.getSpillingToRange();
  spillRange.load("address");

  // Fit the columns for readability.
  sheet.getUsedRange().format.autofitColumns();
  await context.sync();

  console.log(`Copying the table headers spilled into ${spillRange.address}.`);
});

getSpillingToRangeOrNullObject()

获取 Range 对象,它在调用定位单元格时包含溢出区域。 如果区域不是定位点单元格或找不到溢出区域,则此方法返回对象,其 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getSpillingToRangeOrNullObject(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.12 ]

getSpillParent()

获取 Range 对象,它包含要将某个单元格溢出到的定位单元格。 如果应用于具有多个单元格的区域,则会失败。

getSpillParent(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.12 ]

getSpillParentOrNullObject()

获取包含要溢出到的单元格的定位单元格的范围对象。 如果它不是溢出的单元格,或者提供了多个单元格,则此方法返回一个 对象,其 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getSpillParentOrNullObject(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.12 ]

getSurroundingRegion()

返回一个 Range 对象,该对象代表此区域中左上角单元格的周围区域。 周围区域是由相对于该区域的空白行和空白列的任何组合所限定的区域。

getSurroundingRegion(): Excel.Range;

返回

注解

[ API 集:ExcelApi 1.7 ]

getTables(fullyContained)

获取与区域重叠的限定范围的表格集合。

getTables(fullyContained?: boolean): Excel.TableScopedCollection;

参数

fullyContained

boolean

如果 true为 ,则仅返回完全包含在范围边界内的表。 默认值 false为 。

返回

注解

[ API 集:ExcelApi 1.9 ]

getUsedRange(valuesOnly)

返回指定 range 对象的所用区域。 如果区域中没有使用的单元格,则此函数将引发错误 ItemNotFound

getUsedRange(valuesOnly?: boolean): Excel.Range;

参数

valuesOnly

boolean

仅将有值的单元格视为已使用的单元格。 [Api 集:ExcelApi 1.2]

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-relationships.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // We want the most recent quarter that has data, so
    // exclude quarters without data and get the last of
    // the remaining columns.
    const usedDataRange = dataRange.getUsedRange(true /* valuesOnly */);
    const currentQuarterRange = usedDataRange.getLastColumn();

    // Asian and European teams have separate contests.
    const asianSalesRange = sheet.getRange("A2:E4");
    const europeanSalesRange = sheet.getRange("A5:E7");

    // The data for each chart is the intersection of the
    // current quarter column and the rows for the continent.
    const asianContestRange = asianSalesRange.getIntersectionOrNullObject(currentQuarterRange);
    const europeanContestRange = europeanSalesRange.getIntersectionOrNullObject(currentQuarterRange);

    // Must sync before you can test the output of *OrNullObject
    // method/property.
    await context.sync();

    if (asianContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("Asian");
    } else {
        createContinentChart(
            sheet,
            "Asian",
            asianContestRange,
            "A9",
            "F24"
        );
    }

    if (europeanContestRange.isNullObject) {
        // See the declaration of this function for how to
        // test this code path.
        reportMissingData("European");
    } else {
        createContinentChart(
            sheet,
            "European",
            europeanContestRange,
            "A25",
            "F40"
        );
    }

    await context.sync();
});

getUsedRangeOrNullObject(valuesOnly)

返回指定 range 对象的所用区域。 如果区域中没有已用单元格,则此方法返回一个 对象,其 isNullObject 属性设置为 true。 有关详细信息,请参阅 *OrNullObject 方法和属性

getUsedRangeOrNullObject(valuesOnly?: boolean): Excel.Range;

参数

valuesOnly

boolean

仅将有值的单元格视为已使用的单元格。

返回

注解

[ API 集:ExcelApi 1.4 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/used-range.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const salesTable = sheet.tables.getItem("SalesTable");
    const dataRange = salesTable.getDataBodyRange();

    // Pass true so only cells with values count as used
    const usedDataRange = dataRange.getUsedRangeOrNullObject(
        true /* valuesOnly */
    );

    //Must sync before reading value returned from *OrNullObject method/property.
    await context.sync();

    if (usedDataRange.isNullObject) {
        console.log("Need Data to Make Chart");
        console.log("To create a meaningful chart, press 'Fill the table' (or add names to the Product column and numbers to some of the other cells). Then press 'Try to create chart' again.");
    } else {
        const chart = sheet.charts.add(
            Excel.ChartType.columnClustered,
            dataRange,
            "Columns"
        );
        chart.setPosition("A15", "F30");
        chart.title.text = "Quarterly sales chart";
        chart.legend.position = "Right";
        chart.legend.format.fill.setSolidColor("white");
        chart.dataLabels.format.font.size = 15;
        chart.dataLabels.format.font.color = "black";
    }

    await context.sync();
});

getVisibleView()

表示当前 range 对象的可见行。

getVisibleView(): Excel.RangeView;

返回

注解

[ API 集:ExcelApi 1.3 ]

group(groupOption)

组大纲的列和行。

group(groupOption: Excel.GroupOption): void;

参数

groupOption
Excel.GroupOption

指定如何按行或列对区域进行分组。 InvalidArgument当组选项不同于范围isEntireRowisEntireColumn属性 (即range.isEntireRow为 true 且groupOption为“ByColumns”或range.isEntireColumn为 true 且groupOption为“ByRows”) 时,将引发错误。

返回

void

注解

[ API 集:ExcelApi 1.10 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/outline.yaml

Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    
    // Group the larger, main level. Note that the outline controls
    // will be on row 10, meaning 4-9 will collapse and expand.
    sheet.getRange("4:9").group(Excel.GroupOption.byRows);

    // Group the smaller, sublevels. Note that the outline controls
    // will be on rows 6 and 9, meaning 4-5 and 7-8 will collapse and expand.
    sheet.getRange("4:5").group(Excel.GroupOption.byRows);
    sheet.getRange("7:8").group(Excel.GroupOption.byRows);
    await context.sync();
});

group(groupOptionString)

组大纲的列和行。

group(groupOptionString: "ByRows" | "ByColumns"): void;

参数

groupOptionString

"ByRows" | "ByColumns"

指定如何按行或列对区域进行分组。 InvalidArgument当组选项不同于范围isEntireRowisEntireColumn属性 (即range.isEntireRow为 true 且groupOption为“ByColumns”或range.isEntireColumn为 true 且groupOption为“ByRows”) 时,将引发错误。

返回

void

注解

[ API 集:ExcelApi 1.10 ]

hideGroupDetails(groupOption)

隐藏行或列组的详细信息。

hideGroupDetails(groupOption: Excel.GroupOption): void;

参数

groupOption
Excel.GroupOption

指定是隐藏分组行的详细信息还是分组列的详细信息。

返回

void

注解

[ API 集:ExcelApi 1.10 ]

hideGroupDetails(groupOptionString)

隐藏行或列组的详细信息。

hideGroupDetails(groupOptionString: "ByRows" | "ByColumns"): void;

参数

groupOptionString

"ByRows" | "ByColumns"

指定是隐藏分组行的详细信息还是分组列的详细信息。

返回

void

注解

[ API 集:ExcelApi 1.10 ]

insert(shift)

将单个单元格或一系列单元格插入到工作表中取代此区域,并移动其他单元格以留出空间。 返回现在空白处的新 Range 对象。

insert(shift: Excel.InsertShiftDirection): Excel.Range;

参数

shift
Excel.InsertShiftDirection

指定移动单元格的方式。 有关详细信息,请参阅 Excel.InsertShiftDirection

返回

注解

[ API 集:ExcelApi 1.1 ]

示例

await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "F5:F10";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.insert(Excel.InsertShiftDirection.down);
    await context.sync();
});

insert(shiftString)

将单个单元格或一系列单元格插入到工作表中取代此区域,并移动其他单元格以留出空间。 返回现在空白处的新 Range 对象。

insert(shiftString: "Down" | "Right"): Excel.Range;

参数

shiftString

"Down" | "Right"

指定移动单元格的方式。 有关详细信息,请参阅 Excel.InsertShiftDirection

返回

注解

[ API 集:ExcelApi 1.1 ]

load(options)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()

load(options?: Excel.Interfaces.RangeLoadOptions): Excel.Range;

参数

options
Excel.Interfaces.RangeLoadOptions

提供要加载对象的属性的选项。

返回

load(propertyNames)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()

load(propertyNames?: string | string[]): Excel.Range;

参数

propertyNames

string | string[]

逗号分隔的字符串或指定要加载的属性的字符串数组。

返回

示例

// Use the range address to get the range object.
await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "A1:F8"; 
    const worksheet = context.workbook.worksheets.getItem(sheetName);
    const range = worksheet.getRange(rangeAddress);
    range.load('cellCount');
    await context.sync();
    
    console.log(range.cellCount);
});

load(propertyNamesAndPaths)

将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Range;

参数

propertyNamesAndPaths

{ select?: string; expand?: string; }

propertyNamesAndPaths.select 是一个逗号分隔的字符串,指定要加载的属性,是 propertyNamesAndPaths.expand 一个逗号分隔的字符串,指定要加载的导航属性。

返回

merge(across)

将范围单元格合并到工作表的一个区域内。

merge(across?: boolean): void;

参数

across

boolean

可选。 设置为 true 将指定区域的每一行中的单元格合并为单独的合并单元格。 默认值 false为 。

返回

void

注解

[ API 集:ExcelApi 1.2 ]

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:C3";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.merge(true);
    await context.sync(); 
});
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-merged-ranges.yaml

await Excel.run(async (context) => {
  // Retrieve the worksheet and the table in that worksheet.
  const sheet = context.workbook.worksheets.getActiveWorksheet();
  const tableRange = sheet.getRange("B2:E6");

  // Create a merged range in the first row of the table.
  const chartTitle = tableRange.getRow(0);
  chartTitle.merge(true);

  // Format the merged range.
  chartTitle.format.horizontalAlignment = "Center";

  await context.sync();
});

moveTo(destinationRange)

将单元格值、格式和公式从当前区域移动到目标区域,替换这些单元格中的旧信息。 如果目标范围小于当前范围,则会自动扩展。 不会更改目标区域中超出原始区域区域的任何单元格。

moveTo(destinationRange: Range | string): void;

参数

destinationRange

Excel.Range | string

destinationRange 指定将移动此区域中的信息的区域。

返回

void

注解

[ API 集:ExcelApi 1.11 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-copyfrom.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    // Place a label in front of the moved data.
    sheet.getRange("F12").values = [["Moved Range:"]];

    // Move the range from A1:E1 to G12:K12.
    sheet.getRange("A1:E1").moveTo("G12");
    await context.sync();
});

removeDuplicates(columns, includesHeader)

从列指定的区域中删除重复值。

removeDuplicates(columns: number[], includesHeader: boolean): Excel.RemoveDuplicatesResult;

参数

columns

number[]

范围内可能包含重复项的列。 至少需要指定一列。 从零开始编制索引。

includesHeader

boolean

如果输入数据包含标头,则为 True。 默认为 false。

返回

生成的 对象,该对象包含删除的行数和剩余唯一行数。

注解

[ API 集:ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-remove-duplicates.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");
    const range = sheet.getRange("B2:D11");

    const deleteResult = range.removeDuplicates([0],true);    
    deleteResult.load();    
    await context.sync();

    console.log(deleteResult.removed + " entries with duplicate names removed.");
    console.log(deleteResult.uniqueRemaining + " entries with unique names remain in the range.");
});

replaceAll(text, replacement, criteria)

根据当前区域内指定的条件查找并替换给定的字符串。

replaceAll(text: string, replacement: string, criteria: Excel.ReplaceCriteria): OfficeExtension.ClientResult<number>;

参数

text

string

要查找的字符串。

replacement

string

替换原始字符串的字符串。

criteria
Excel.ReplaceCriteria

其他替换条件。

返回

执行的替换次数。

注解

[ API 集:ExcelApi 1.9 ]

select()

在 Excel UI 中选择指定的区域。

select(): void;

返回

void

注解

[ API 集:ExcelApi 1.1 ]

示例

await Excel.run(async (context) => {
    const sheetName = "Sheet1";
    const rangeAddress = "F5:F10"; 
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.select();
    await context.sync(); 
});

set(properties, options)

同时设置对象的多个属性。 可以传递具有相应属性的纯对象,也可以传递同一类型的另一个 API 对象。

set(properties: Interfaces.RangeUpdateData, options?: OfficeExtension.UpdateOptions): void;

参数

properties
Excel.Interfaces.RangeUpdateData

一个 JavaScript 对象,其属性按同构方式构造为调用方法的对象的属性。

options
OfficeExtension.UpdateOptions

提供一个选项,用于在 properties 对象尝试设置任何只读属性时禁止显示错误。

返回

void

set(properties)

基于现有的已加载对象,同时对对象设置多个属性。

set(properties: Excel.Range): void;

参数

properties
Excel.Range

返回

void

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/90-scenarios/multiple-property-set.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getItem("Sample");

    const sourceRange = sheet.getRange("B2:E2");
    sourceRange.load("format/fill/color, format/font/name, format/font/color");
    await context.sync();

    // Set properties based on the loaded and synced 
    // source range.
    const targetRange = sheet.getRange("B7:E7");
    targetRange.set(sourceRange); 
    targetRange.format.autofitColumns();
    await context.sync();
});

setCellProperties(cellPropertiesData)

基于单元格属性的 2D 数组汇报区域,封装字体、填充、边框和对齐等内容。

setCellProperties(cellPropertiesData: SettableCellProperties[][]): void;

参数

cellPropertiesData

Excel.SettableCellProperties[][]

表示在每个单元格中设置的属性的 2D 数组。

返回

void

注解

[ API 集:ExcelApi 1.9 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/cell-properties.yaml

await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();

    // Creating the SettableCellProperties objects to use for the range.
    // In your add-in, these should be created once, outside the function.
    const topHeaderProps: Excel.SettableCellProperties = {
        // The style property takes a string matching the name of an Excel style.
        // Built-in style names are listed in the `BuiltInStyle` enum.
        // Note that a style will overwrite any formatting,
        // so do not use the format property with the style property.
        style: "Heading1"
    };

    const headerProps: Excel.SettableCellProperties = {
        // Any subproperties of format that are not set will not be changed when these cell properties are set.
        format: {
            fill: {
                color: "Blue"
            },
            font: {
                color: "White",
                bold: true
            }
        }
    };

    const nonApplicableProps: Excel.SettableCellProperties = {
        format: {
            fill: {
                pattern: Excel.FillPattern.gray25
            },
            font: {
                color: "Gray",
                italic: true
            }
        }
    };

    const matchupScoreProps: Excel.SettableCellProperties = {
        format: {
            borders: {
                bottom: {
                    style: Excel.BorderLineStyle.continuous
                },
                left: {
                    style: Excel.BorderLineStyle.continuous
                },
                right: {
                    style: Excel.BorderLineStyle.continuous
                },
                top: {
                    style: Excel.BorderLineStyle.continuous
                }
            }
        }
    };

    const range = sheet.getRange("A1:E5");

    // You can use empty JSON objects to avoid changing a cell's properties.
    range.setCellProperties([
        [topHeaderProps, {}, {}, {}, {}],
        [{}, {}, headerProps, headerProps, headerProps],
        [{}, headerProps, nonApplicableProps, matchupScoreProps, matchupScoreProps],
        [{}, headerProps, matchupScoreProps, nonApplicableProps, matchupScoreProps],
        [{}, headerProps, matchupScoreProps, matchupScoreProps, nonApplicableProps]
    ]);

    sheet.getUsedRange().format.autofitColumns();
    await context.sync();
});

setColumnProperties(columnPropertiesData)

基于列属性的单维数组汇报范围,并封装字体、填充、边框和对齐方式等内容。

setColumnProperties(columnPropertiesData: SettableColumnProperties[]): void;

参数

columnPropertiesData

Excel.SettableColumnProperties[]

一个数组,表示要在每个列中设置的属性。

返回

void

注解

[ API 集:ExcelApi 1.9 ]

setDirty()

设置下一次重新计算发生时要重新计算的区域。

setDirty(): void;

返回

void

注解

[ API 集:ExcelApi 1.9 ]

setRowProperties(rowPropertiesData)

基于行属性的一维数组汇报区域,并封装字体、填充、边框和对齐方式等内容。

setRowProperties(rowPropertiesData: SettableRowProperties[]): void;

参数

rowPropertiesData

Excel.SettableRowProperties[]

一个数组,表示每行中要设置的属性。

返回

void

注解

[ API 集:ExcelApi 1.9 ]

showCard()

显示活动单元格的卡片(如果该单元格具有富值内容)。

showCard(): void;

返回

void

注解

[ API 集:ExcelApi 1.7 ]

showGroupDetails(groupOption)

显示行或列组的详细信息。

showGroupDetails(groupOption: Excel.GroupOption): void;

参数

groupOption
Excel.GroupOption

指定是显示分组行的详细信息还是分组列的详细信息。

返回

void

注解

[ API 集:ExcelApi 1.10 ]

showGroupDetails(groupOptionString)

显示行或列组的详细信息。

showGroupDetails(groupOptionString: "ByRows" | "ByColumns"): void;

参数

groupOptionString

"ByRows" | "ByColumns"

指定是显示分组行的详细信息还是分组列的详细信息。

返回

void

注解

[ API 集:ExcelApi 1.10 ]

toJSON()

重写 JavaScript toJSON() 方法,以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (,反过来又调用toJSON传递给它的 对象的 方法。) 而原始Excel.Range对象是 API 对象,toJSON该方法返回一个纯 JavaScript 对象, (类型为 Excel.Interfaces.RangeData) ,其中包含原始对象中任何已加载子属性的浅表副本。

toJSON(): Excel.Interfaces.RangeData;

返回

track()

根据文档中的相应更改来跟踪对象,以便进行自动调整。 此调用是 context.trackedObjects.add (thisObject) 的简写。 如果跨 .sync 调用和“.run”批处理的顺序执行外部使用此对象,并在设置属性或调用对象方法时收到“InvalidObjectPath”错误,则需要在首次创建对象时将该对象添加到跟踪的对象集合。

track(): Excel.Range;

返回

ungroup(groupOption)

取消对大纲的列和行的分组。

ungroup(groupOption: Excel.GroupOption): void;

参数

groupOption
Excel.GroupOption

指定如何按行或列取消组合区域。

返回

void

注解

[ API 集:ExcelApi 1.10 ]

示例

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/outline.yaml

Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    
    // This removes two levels of groups from the "A1-R10" range.
    // Any groups at the same level on the same dimension will be removed by a single call.
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byRows);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byRows);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byColumns);
    sheet.getRange("A1:R10").ungroup(Excel.GroupOption.byColumns);
    await context.sync();
});

ungroup(groupOptionString)

取消对大纲的列和行的分组。

ungroup(groupOptionString: "ByRows" | "ByColumns"): void;

参数

groupOptionString

"ByRows" | "ByColumns"

指定如何按行或列取消组合区域。

返回

void

注解

[ API 集:ExcelApi 1.10 ]

unmerge()

将范围单元格取消合并为各个单元格。

unmerge(): void;

返回

void

注解

[ API 集:ExcelApi 1.2 ]

示例

await Excel.run(async (context) => { 
    const sheetName = "Sheet1";
    const rangeAddress = "A1:C3";
    const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeAddress);
    range.unmerge();
    await context.sync(); 
});

untrack()

释放与此对象关联的内存(如果先前已跟踪过)。 此调用是 context.trackedObjects.remove (thisObject) 的简写。 拥有许多跟踪对象会降低主机应用程序的速度,因此请在使用完毕后释放所添加的任何对象。 在内存释放生效之前,需要调用 。context.sync()

untrack(): Excel.Range;

返回

示例

await Excel.run(async (context) => {
    const largeRange = context.workbook.getSelectedRange();
    largeRange.load(["rowCount", "columnCount"]);
    await context.sync();

    for (let i = 0; i < largeRange.rowCount; i++) {
        for (let j = 0; j < largeRange.columnCount; j++) {
            const cell = largeRange.getCell(i, j);
            cell.values = [[i *j]];

            // Call untrack() to release the range from memory.
            cell.untrack();
        }
    }

    await context.sync();
});