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. Значение адреса будет содержать имя листа для каждого прямоугольного блока ячеек (например, "Лист1! A1:B4, Лист1! D1:D4").
readonly address: string;
Значение свойства
string
Комментарии
addressLocal
Возвращает ссылку RangeAreas
в языковом стандарте пользователя.
readonly addressLocal: string;
Значение свойства
string
Комментарии
areaCount
Возвращает количество прямоугольных диапазонов, составляющих этот RangeAreas
объект.
readonly areaCount: number;
Значение свойства
number
Комментарии
areas
Возвращает коллекцию прямоугольных диапазонов, составляющих этот RangeAreas
объект.
readonly areas: Excel.RangeCollection;
Значение свойства
Комментарии
cellCount
Возвращает количество ячеек в объекте RangeAreas
, суммируя количество ячеек всех отдельных прямоугольных диапазонов. Возвращает значение -1, если количество ячеек превышает 2^31-1 (2 147 483 647).
readonly cellCount: number;
Значение свойства
number
Комментарии
conditionalFormats
Возвращает коллекцию условных форматов, пересекающихся с любыми ячейками в этом RangeAreas
объекте.
readonly conditionalFormats: Excel.ConditionalFormatCollection;
Значение свойства
Комментарии
context
Контекст запроса, связанный с объектом . Это соединяет процесс надстройки с процессом ведущего приложения Office.
context: RequestContext;
Значение свойства
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()
Вычисляет все ячейки RangeAreas
в .
calculate(): void;
Возвращаемое значение
void
Комментарии
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()
Преобразует все ячейки в RangeAreas
с типами данных в текст.
convertDataTypeToText(): void;
Возвращаемое значение
void
Комментарии
convertToLinkedDataType(serviceID, languageCulture)
Преобразует все ячейки в в RangeAreas
связанные типы данных.
convertToLinkedDataType(serviceID: number, languageCulture: string): void;
Параметры
- serviceID
-
number
Идентификатор службы, который будет использоваться для запроса данных.
- 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
Значение true, если пропускать пустые ячейки в исходном диапазоне или RangeAreas
. Значение по умолчанию: false.
- transpose
-
boolean
Значение true, если требуется транспонировать ячейки в целевом объекте RangeAreas
. Значение по умолчанию: false.
Возвращаемое значение
void
Комментарии
copyFrom(sourceRange, copyTypeString, skipBlanks, transpose)
Копирует данные ячейки или форматирование из исходного диапазона или RangeAreas
в текущий RangeAreas
. Размер назначения RangeAreas
может отличаться от исходного диапазона или RangeAreas
. Назначение будет развернуто автоматически, если оно меньше исходного.
copyFrom(sourceRange: Range | RangeAreas | string, copyTypeString?: "All" | "Formulas" | "Values" | "Formats" | "Link", skipBlanks?: boolean, transpose?: boolean): void;
Параметры
- sourceRange
-
Excel.Range | Excel.RangeAreas | string
Исходный диапазон или RangeAreas
для копирования. Если источник RangeAreas
имеет несколько диапазонов, их форма должна быть создана путем удаления полных строк или столбцов из прямоугольного диапазона.
- copyTypeString
-
"All" | "Formulas" | "Values" | "Formats" | "Link"
Тип данных ячейки или форматирование для копирования. Значение по умолчанию — "All".
- skipBlanks
-
boolean
Значение true, если пропускать пустые ячейки в исходном диапазоне или RangeAreas
. Значение по умолчанию: false.
- transpose
-
boolean
Значение true, если требуется транспонировать ячейки в целевом объекте 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
Предоставляет возможность подавления ошибок, если объект свойств пытается задать какие-либо свойства, доступные только для чтения.
Возвращаемое значение
void
set(properties)
Задает несколько свойств объекта одновременно на основе существующего загруженного объекта.
set(properties: Excel.RangeAreas): void;
Параметры
- properties
- Excel.RangeAreas
Возвращаемое значение
void
setDirty()
Задает объект для пересчета RangeAreas
при следующем пересчете.
setDirty(): void;
Возвращаемое значение
void
Комментарии
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;
Возвращаемое значение
Office Add-ins