Excel.RangeAreas class
RangeAreas 表示同一工作表中一个或多个矩形范围的集合。 若要了解如何使用不连续范围，请阅读 在 Excel 加载项中同时使用多个区域。
注解
使用方
- Excel.Application： union
- Excel.ConditionalFormat： getRanges， setRanges
- Excel.DataValidation： getInvalidCells， getInvalidCellsOrNullObject
- Excel.PageLayout： getPrintArea， getPrintAreaOrNullObject， setPrintArea
- Excel.Range： copyFrom， getMergedAreasOrNullObject， getSpecialCells， getSpecialCellsOrNullObject
- Excel.RangeAreasCollection： getItemAt， items
- Excel.Window： rangeSelection
- Excel.Workbook： getSelectedRanges
- Excel.WorkbookRangeAreas： getRangeAreasBySheet， getRangeAreasOrNullObjectBySheet
- Excel.Worksheet： findAll， findAllOrNullObject， getRanges
属性
| address | 以 A1 样式返回 |
| address |
返回 |
| area |
返回构成此 |
| areas | 返回构成此 |
| cell |
返回对象中的 |
| conditional |
返回与此 |
| context | 与对象关联的请求上下文。 这将加载项的进程连接到 Office 主机应用程序的进程。 |
| data |
返回 中所有区域 |
| format | 返回 |
| is |
指定此 |
| is |
指定此 |
| style | 表示此 |
| worksheet | 返回当前 |
方法
| calculate() | 计算 中的所有单元格 |
| clear(apply |
清除构成此 |
| clear(apply |
清除构成此 |
| clear |
清除区域中单元格的值，并特别考虑包含控件的单元格。 如果区域仅包含空白值且控件设置为默认值，则删除值和控件格式。 否则，会将包含控件的单元格设置为其默认值，并清除区域中其他单元格的值。 |
| convert |
将 with 数据类型中的所有 |
| convert |
将 中的 |
| copy |
将单元格数据或格式从源区域或 |
| copy |
将单元格数据或格式从源区域或 |
| get |
返回 |
| get |
返回 |
| get |
返回 |
| get |
返回 |
| get |
返回 |
| get |
返回表示 |
| get |
返回表示 |
| get |
返回表示 |
| get |
返回表示 |
| get |
返回与此 |
| get |
返回包含对象中 |
| get |
返回包含对象中 |
| load(options) | 将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| load(property |
将命令加入队列以加载对象的指定属性。 阅读属性前必须先调用 |
| select() | 在 Excel UI 中选择指定的范围区域。 |
| set(properties, options) | 同时设置对象的多个属性。 可以传递具有相应属性的纯文本对象，也可以传递另一个相同类型的 API 对象。 |
| set(properties) | 基于现有加载的对象，同时在对象上设置多个属性。 |
| set |
设置 |
| toJSON() | 覆盖 JavaScript |
| track() | 根据文档中的相应更改来跟踪对象，以便进行自动调整。 此调用是 context.trackedObjects.add (thisObject) 的简写。 如果在调用中 |
| untrack() | 释放与此对象关联的内存（如果先前已跟踪过）。 此调用是 context.trackedObjects.remove (thisObject) 的简写。 拥有许多跟踪对象会降低主机应用程序的速度，因此请在使用完毕后释放所添加的任何对象。 需要在内存释放生效之前调用 |
属性详细信息
address
以 A1 样式返回 RangeAreas 引用。 地址值将包含每个矩形单元格块的工作表名称 (例如，“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
方法详细信息
calculate()
clear(applyTo)
清除构成此 RangeAreas 对象的每个区域的值、格式、填充、边框和其他属性。
clear(applyTo?: Excel.ClearApplyTo): void;参数
- applyTo
- Excel.ClearApplyTo
可选。 确定清除操作的类型。 有关详细信息，请参阅 Excel.ClearApplyTo。 默认为“全部”。
返回
void
注解
clear(applyTo)
清除构成此 RangeAreas 对象的每个区域的值、格式、填充、边框和其他属性。
clear(applyTo?: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks" | "ResetContents"): void;参数
- applyTo
-
"All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks" | "ResetContents"
可选。 确定清除操作的类型。 有关详细信息，请参阅 Excel.ClearApplyTo。 默认为“全部”。
返回
void
注解
clearOrResetContents()
清除区域中单元格的值，并特别考虑包含控件的单元格。 如果区域仅包含空白值且控件设置为默认值，则删除值和控件格式。 否则，会将包含控件的单元格设置为其默认值，并清除区域中其他单元格的值。
clearOrResetContents(): void;返回
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
要复制的单元格数据或格式的类型。 默认为“全部”。
- skipBlanks
-
boolean
如果跳过源区域或源区域 RangeAreas中的空白单元格，则为 True。 默认为 false。
- transpose
-
boolean
如果转置目标 RangeAreas中的单元格，则为 True。 默认为 false。
返回
void
注解
copyFrom(sourceRange, copyType, skipBlanks, transpose)
将单元格数据或格式从源区域或 RangeAreas 当前 RangeAreas区域复制到 目标 RangeAreas 的大小可以与源区域或 RangeAreas. 如果目标小于源，则目标将自动扩展。
copyFrom(sourceRange: Range | RangeAreas | string, copyType?: "All" | "Formulas" | "Values" | "Formats" | "Link" | "ColumnWidths", skipBlanks?: boolean, transpose?: boolean): void;参数
- sourceRange
-
Excel.Range | Excel.RangeAreas | string
源区域或 RangeAreas 要从其复制。 当源 RangeAreas 有多个区域时，必须能够通过从矩形区域中删除整行或整列来创建其窗体。
- copyType
-
"All" | "Formulas" | "Values" | "Formats" | "Link" | "ColumnWidths"
要复制的单元格数据或格式的类型。 默认为“全部”。
- skipBlanks
-
boolean
如果跳过源区域或源区域 RangeAreas中的空白单元格，则为 True。 默认为 false。
- transpose
-
boolean
如果转置目标 RangeAreas中的单元格，则为 True。 默认为 false。
返回
void
注解
getEntireColumn()
返回 RangeAreas 表示 (的整个列 RangeAreas 的对象 例如，如果当前表示 RangeAreas 单元格 “B4：E11， H2”，则它返回 RangeAreas 表示列 “B：E， H：H”) 。
getEntireColumn(): Excel.RangeAreas;返回
注解
getEntireRow()
返回 RangeAreas 表示该 (的 RangeAreas 整行的对象 例如，如果当前表示 RangeAreas 单元格 “B4：E11”，则返回表示行 “4：11”) 的对象 RangeAreas 。
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
要偏移 (RangeAreas 正、负或 0) 的行数。 正值表示向下偏移，负值表示向上偏移。
- columnOffset
-
number
正值、负值或 0) (要偏移的 RangeAreas 列数。 正值表示向右偏移，负值表示向左偏移。
返回
注解
getSpecialCells(cellType, cellValueType)
返回表示 RangeAreas 与指定类型和值匹配的所有单元格的对象。 如果未找到符合条件的特殊单元格，则会引发错误。
getSpecialCells(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;参数
- cellType
- Excel.SpecialCellType
要包含的单元格类型。
- cellValueType
- Excel.SpecialCellValueType
如果为某一constants或 formulas，则cellType此参数用于确定要在结果中包含的单元格类型。 可以将这些值组合在一起以返回多个类型。 默认情况下，将选择所有常量或公式，无论类型如何。
返回
注解
getSpecialCells(cellType, cellValueType)
返回表示 RangeAreas 与指定类型和值匹配的所有单元格的对象。 如果未找到符合条件的特殊单元格，则会引发错误。
getSpecialCells(cellType: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible" | "DirtyFormulas", cellValueType?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;参数
- cellType
-
"ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible" | "DirtyFormulas"
要包含的单元格类型。
- cellValueType
-
"All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"
如果为某一constants或 formulas，则cellType此参数用于确定要在结果中包含的单元格类型。 可以将这些值组合在一起以返回多个类型。 默认情况下，将选择所有常量或公式，无论类型如何。
返回
注解
getSpecialCellsOrNullObject(cellType, cellValueType)
返回表示 RangeAreas 与指定类型和值匹配的所有单元格的对象。 如果未找到与条件匹配的特殊单元格，则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getSpecialCellsOrNullObject(cellType: Excel.SpecialCellType, cellValueType?: Excel.SpecialCellValueType): Excel.RangeAreas;参数
- cellType
- Excel.SpecialCellType
要包含的单元格类型。
- cellValueType
- Excel.SpecialCellValueType
如果为某一constants或 formulas，则cellType此参数用于确定要在结果中包含的单元格类型。 可以将这些值组合在一起以返回多个类型。 默认情况下，将选择所有常量或公式，无论类型如何。
返回
注解
getSpecialCellsOrNullObject(cellType, cellValueType)
返回表示 RangeAreas 与指定类型和值匹配的所有单元格的对象。 如果未找到与条件匹配的特殊单元格，则此方法将返回其 isNullObject 属性设置为 true的对象。 有关详细信息，请参阅 *OrNullObject 方法和属性。
getSpecialCellsOrNullObject(cellType: "ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible" | "DirtyFormulas", cellValueType?: "All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"): Excel.RangeAreas;参数
- cellType
-
"ConditionalFormats" | "DataValidations" | "Blanks" | "Constants" | "Formulas" | "SameConditionalFormat" | "SameDataValidation" | "Visible" | "DirtyFormulas"
要包含的单元格类型。
- cellValueType
-
"All" | "Errors" | "ErrorsLogical" | "ErrorsNumbers" | "ErrorsText" | "ErrorsLogicalNumber" | "ErrorsLogicalText" | "ErrorsNumberText" | "Logical" | "LogicalNumbers" | "LogicalText" | "LogicalNumbersText" | "Numbers" | "NumbersText" | "Text"
如果为某一constants或 formulas，则cellType此参数用于确定要在结果中包含的单元格类型。 可以将这些值组合在一起以返回多个类型。 默认情况下，将选择所有常量或公式，无论类型如何。
返回
注解
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 指定要加载的导航属性的逗号分隔字符串。
返回
select()
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;