Excel.RangeAreas class
RangeAreas 表示同一工作表中一个或多个矩形区域的集合。 若要了解如何使用不明确的区域，请阅读 在 Excel 外接程序中同时处理多个区域。
- Extends
注解
属性
| address | 返回 |
| address |
返回 |
| area |
返回构成此 |
| areas | 返回构成此 |
| cell |
返回 对象中的 |
| conditional |
返回与此 |
| context | 与 对象关联的请求上下文。 这会将加载项的进程连接到 Office 主机应用程序的进程。 |
| data |
返回 中所有范围 |
| format | 返回一个 |
| is |
指定此 |
| is |
指定此 |
| style | 表示此 |
| worksheet | 返回当前 |
方法
| calculate() | 计算 中的所有 |
| clear(apply |
清除构成此 |
| clear(apply |
清除构成此 |
| convert |
将 中 |
| convert |
将 中的所有 |
| copy |
将单元格数据或格式从源区域 或 |
| copy |
将单元格数据或格式从源区域 或 |
| get |
返回一个 |
| get |
返回一个 |
| get |
返回 |
| get |
返回 |
| get |
返回由 |
| get |
返回一个 |
| get |
返回一个 |
| get |
返回一个 |
| get |
返回一个 |
| get |
返回与此 |
| get |
返回包含对象中 |
| get |
返回包含对象中 |
| load(options) | 将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| set(properties, options) | 同时设置对象的多个属性。 可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。 |
| set(properties) | 基于现有的已加载对象，同时对对象设置多个属性。 |
| set |
|
| toJSON() | 重写 JavaScript |
| track() | 根据文档中的相应更改来跟踪对象，以便进行自动调整。 此调用是 context.trackedObjects.add (thisObject) 的简写。 如果跨 |
| untrack() | 释放与此对象关联的内存（如果先前已跟踪过）。 此调用是 context.trackedObjects.remove (thisObject) 的简写。 拥有许多跟踪对象会降低主机应用程序的速度，因此请在使用完毕后释放所添加的任何对象。 在内存释放生效之前，需要调用 。 |
属性详细信息
address
返回 RangeAreas A1 样式的引用。 地址值将包含每个矩形单元格块的工作表名称， (例如“Sheet1！A1：B4，Sheet1！D1：D4“) 。
readonly address: string;属性值
string
注解
addressLocal
areaCount
areas
返回构成此 RangeAreas 对象的矩形范围的集合。
readonly areas: Excel.RangeCollection;属性值
注解
cellCount
返回 对象中的 RangeAreas 单元格数，并汇总所有单个矩形区域的单元格计数。 如果单元格计数超过 2^31-1 (2,147,483,647)，则返回 -1。
readonly cellCount: number;属性值
number
注解
conditionalFormats
返回与此 RangeAreas 对象中的任何单元格相交的条件格式的集合。
readonly conditionalFormats: Excel.ConditionalFormatCollection;属性值
注解
context
dataValidation
返回 中所有范围 RangeAreas的数据验证对象。
readonly dataValidation: Excel.DataValidation;属性值
注解
format
返回一个 RangeFormat 对象，该对象封装对象中 RangeAreas 所有区域的字体、填充、边框、对齐方式和其他属性。
readonly format: Excel.RangeFormat;属性值
注解
示例
// 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 formulas.
const formulaRanges = usedRange.getSpecialCells("Formulas");
formulaRanges.format.fill.color = "lightgreen";
await context.sync();
});
isEntireColumn
指定此 RangeAreas 对象上的所有区域是否表示整个列 (例如“A：C， Q：Z”) 。
readonly isEntireColumn: boolean;属性值
boolean
注解
isEntireRow
指定此 RangeAreas 对象上的所有区域是否表示 (整行，例如“1：3， 5：7”) 。
readonly isEntireRow: boolean;属性值
boolean
注解
style
表示此 RangeAreas 对象中所有区域的样式。 如果单元格的样式不一致， null 将返回 。 对于自定义样式，将返回样式名称。 对于内置样式，将返回表示枚举中的 BuiltInStyle 值的字符串。
style: string;属性值
string
注解
worksheet
返回当前 RangeAreas的工作表。
readonly worksheet: Excel.Worksheet;属性值
注解
方法详细信息
calculate()
clear(applyTo)
清除构成此 RangeAreas 对象的每个区域的值、格式、填充、边框和其他属性。
clear(applyTo?: Excel.ClearApplyTo): void;参数
- applyTo
- Excel.ClearApplyTo
可选。 确定清除操作的类型。 有关详细信息，请参阅 Excel.ClearApplyTo。 默认值为“All”。
返回
void
注解
clear(applyToString)
清除构成此 RangeAreas 对象的每个区域的值、格式、填充、边框和其他属性。
clear(applyToString?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"): void;参数
- applyToString
-
"All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"
可选。 确定清除操作的类型。 有关详细信息，请参阅 Excel.ClearApplyTo。 默认值为“All”。
返回
void
注解
convertDataTypeToText()
convertToLinkedDataType(serviceID, languageCulture)
将 中的所有 RangeAreas 单元格转换为链接数据类型。
convertToLinkedDataType(serviceID: number, languageCulture: string): void;参数
- serviceID
-
number
用于查询数据的服务 ID。
- languageCulture
-
string
要查询服务的语言区域性。
返回
void
注解
copyFrom(sourceRange, copyType, skipBlanks, transpose)
将单元格数据或格式从源区域 或 RangeAreas 复制到当前 RangeAreas。 目标 RangeAreas 的大小可以不同于源范围或 RangeAreas。 如果目标小于源，则会自动展开。
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
如此 如果跳过源区域或 RangeAreas中的空白单元格。 默认为 false。
- transpose
-
boolean
如此 如果转置目标 RangeAreas中的单元格。 默认为 false。
返回
void
注解
copyFrom(sourceRange, copyTypeString, skipBlanks, transpose)
将单元格数据或格式从源区域 或 RangeAreas 复制到当前 RangeAreas。 目标 RangeAreas 的大小可以不同于源范围或 RangeAreas。 如果目标小于源，则会自动展开。
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
如此 如果跳过源区域或 RangeAreas中的空白单元格。 默认为 false。
- transpose
-
boolean
如此 如果转置目标 RangeAreas中的单元格。 默认为 false。
返回
void
注解
getEntireColumn()
返回一个 RangeAreas 对象，该对象代表 (的 RangeAreas 整个列，例如，如果当前 RangeAreas 表示单元格“B4：E11， H2”，则返回一个 RangeAreas 表示列“B：E， H：H”) 。
getEntireColumn(): Excel.RangeAreas;返回
注解
getEntireRow()
返回一个 RangeAreas 对象，该对象代表 (的整个行 RangeAreas ，例如，如果当前 RangeAreas 表示单元格“B4：E11”，则返回表示 RangeAreas 行“4：11”) 。
getEntireRow(): Excel.RangeAreas;返回
注解
getIntersection(anotherRange)
返回 RangeAreas 表示给定区域或 RangeAreas的交集的对象。 如果未找到任何交集， ItemNotFound 将引发错误。
getIntersection(anotherRange: Range | RangeAreas | string): Excel.RangeAreas;参数
- anotherRange
-
Excel.Range | Excel.RangeAreas | string
用于确定交集的区域、 RangeAreas 对象或范围地址。
返回
注解
getIntersectionOrNullObject(anotherRange)
返回 RangeAreas 表示给定区域或 RangeAreas的交集的对象。 如果未找到交集，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getIntersectionOrNullObject(anotherRange: Range | RangeAreas | string): Excel.RangeAreas;参数
- anotherRange
-
Excel.Range | Excel.RangeAreas | string
用于确定交集的区域、 RangeAreas 对象或地址。
返回
注解
getOffsetRangeAreas(rowOffset, columnOffset)
返回由 RangeAreas 特定行和列偏移量移动的对象。 返回 RangeAreas 的 维度将与原始对象匹配。 如果生成的 RangeAreas 强制超出工作表网格的边界，将引发错误。
getOffsetRangeAreas(rowOffset: number, columnOffset: number): Excel.RangeAreas;参数
- rowOffset
-
number
要偏移的行数 (正、负或 0) RangeAreas 。 正值表示向下偏移，负值表示向上偏移。
- columnOffset
-
number
正、负或 0) 的列数 (，将按其 RangeAreas 进行偏移。 正值表示向右偏移，负值表示向左偏移。
返回
注解
getSpecialCells(cellType, cellValueType)
返回一个 RangeAreas 对象，该对象表示与指定类型和值匹配的所有单元格。 如果未找到符合条件的特殊单元格，则会引发错误。
getSpecialCells(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;参数
- cellType
- Excel.SpecialCellType
要包含的单元格类型。
- cellValueType
- Excel.SpecialCellValueType
如果 cellType 为 constants 或 formulas，则此参数用于确定结果中要包含的单元格类型。 这些值可以组合在一起以返回多个类型。 默认情况下，将选择所有常量或公式，无论类型如何。
返回
注解
getSpecialCells(cellTypeString, cellValueTypeString)
返回一个 RangeAreas 对象，该对象表示与指定类型和值匹配的所有单元格。 如果未找到符合条件的特殊单元格，则会引发错误。
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"
如果 cellType 为 constants 或 formulas，则此参数用于确定结果中要包含的单元格类型。 这些值可以组合在一起以返回多个类型。 默认情况下，将选择所有常量或公式，无论类型如何。
返回
注解
getSpecialCellsOrNullObject(cellType, cellValueType)
返回一个 RangeAreas 对象，该对象表示与指定类型和值匹配的所有单元格。 如果未找到与条件匹配的特殊单元格，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;参数
- cellType
- Excel.SpecialCellType
要包含的单元格类型。
- cellValueType
- Excel.SpecialCellValueType
如果 cellType 为 constants 或 formulas，则此参数用于确定结果中要包含的单元格类型。 这些值可以组合在一起以返回多个类型。 默认情况下，将选择所有常量或公式，无论类型如何。
返回
注解
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"
如果 cellType 为 constants 或 formulas，则此参数用于确定结果中要包含的单元格类型。 这些值可以组合在一起以返回多个类型。 默认情况下，将选择所有常量或公式，无论类型如何。
返回
注解
getTables(fullyContained)
返回与此 RangeAreas 对象中的任何范围重叠的表的作用域集合。
getTables(fullyContained?: boolean): Excel.TableScopedCollection;参数
- fullyContained
-
boolean
如果 true为 ，则仅返回完全包含在范围边界内的表。 默认值为 false。
返回
注解
getUsedRangeAreas(valuesOnly)
返回包含对象中RangeAreas各个矩形区域的所有已用区域的使用的 RangeAreas 。 如果 中 RangeAreas没有已用单元格， ItemNotFound 则会引发错误。
getUsedRangeAreas(valuesOnly?: boolean): Excel.RangeAreas;参数
- valuesOnly
-
boolean
是否仅将具有值的单元格视为已用单元格。 默认值为 false。
返回
注解
getUsedRangeAreasOrNullObject(valuesOnly)
返回包含对象中RangeAreas各个矩形区域的所有已用区域的使用的 RangeAreas 。 如果 中 RangeAreas没有使用的单元格，则此方法返回一个 对象，其 isNullObject 属性设置为 true。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getUsedRangeAreasOrNullObject(valuesOnly?: boolean): Excel.RangeAreas;参数
- valuesOnly
-
boolean
是否仅将具有值的单元格视为已用单元格。
返回
注解
load(options)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(options?: Excel.Interfaces.RangeAreasLoadOptions): Excel.RangeAreas;参数
提供要加载对象的属性的选项。
返回
load(propertyNames)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(propertyNames?: string | string[]): Excel.RangeAreas;参数
- propertyNames
-
string | string[]
逗号分隔的字符串或指定要加载的属性的字符串数组。
返回
load(propertyNamesAndPaths)
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 context.sync()。
load(propertyNamesAndPaths?: {
select?: string;
expand?: string;
}): Excel.RangeAreas;参数
- propertyNamesAndPaths
-
{ select?: string; expand?: string; }
propertyNamesAndPaths.select 是一个逗号分隔的字符串，指定要加载的属性，是 propertyNamesAndPaths.expand 一个逗号分隔的字符串，指定要加载的导航属性。
返回
set(properties, options)
同时设置对象的多个属性。 可以传递具有相应属性的纯对象，也可以传递同一类型的另一个 API 对象。
set(properties: Interfaces.RangeAreasUpdateData, options?: OfficeExtension.UpdateOptions): void;参数
- properties
- Excel.Interfaces.RangeAreasUpdateData
一个 JavaScript 对象，其属性按同构方式构造为调用方法的对象的属性。
- options
- OfficeExtension.UpdateOptions
提供一个选项，用于在 properties 对象尝试设置任何只读属性时禁止显示错误。
返回
void
set(properties)
基于现有的已加载对象，同时对对象设置多个属性。
set(properties: Excel.RangeAreas): void;参数
- properties
- Excel.RangeAreas
返回
void
setDirty()
toJSON()
重写 JavaScript toJSON() 方法，以便在将 API 对象传递给 JSON.stringify()时提供更有用的输出。 JSON.stringify (，反过来，调用toJSON传递给它的 对象的 方法。) 虽然原始 Excel.RangeAreas 对象是 API 对象，toJSON但该方法返回一个纯 JavaScript 对象， (类型为 Excel.Interfaces.RangeAreasData) ，其中包含从原始对象加载的任何子属性的浅表副本。
toJSON(): Excel.Interfaces.RangeAreasData;返回
track()
根据文档中的相应更改来跟踪对象，以便进行自动调整。 此调用是 context.trackedObjects.add (thisObject) 的简写。 如果跨 .sync 调用和在“.run”批处理的顺序执行之外使用此对象，并在设置属性或调用对象方法时收到“InvalidObjectPath”错误，则需要在首次创建对象时将该对象添加到跟踪的对象集合。
track(): Excel.RangeAreas;返回
untrack()
释放与此对象关联的内存（如果先前已跟踪过）。 此调用是 context.trackedObjects.remove (thisObject) 的简写。 拥有许多跟踪对象会降低主机应用程序的速度，因此请在使用完毕后释放所添加的任何对象。 在内存释放生效之前，需要调用 。context.sync()
untrack(): Excel.RangeAreas;返回
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈