Excel.Range class

Ссылка

Пакет:: excel

Диапазон представляет набор из одной или нескольких смежных ячеек, таких как ячейка, строка, столбец или блок ячеек. Чтобы узнать больше о том, как диапазоны используются в API, начните с ranges in the Excel JavaScript API.

Extends: OfficeExtension.ClientObject

// 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. Значение address содержит ссылку на лист (например, "Лист1! A1:B4").
addressLocal	Представляет ссылку на диапазон для указанного диапазона на языке пользователя.
cellCount	Указывает количество ячеек в диапазоне. Этот API возвращает значение -1, если количество ячеек превышает 2^31-1 (2,147,483,647).
columnCount	Задает общее количество столбцов в диапазоне.
columnHidden	Представляет, если все столбцы в текущем диапазоне скрыты. Значение — это `true` , когда все столбцы в диапазоне скрыты. Значение имеет значение, `false` если столбцы в диапазоне не скрыты. Значением считается, `null` когда некоторые столбцы в диапазоне скрыты, а другие столбцы в том же диапазоне не скрыты.
columnIndex	Задает номер столбца первой ячейки в диапазоне. Используется нулевой индекс.
conditionalFormats	Коллекция, `ConditionalFormats` пересекающая диапазон.
context	Контекст запроса, связанный с объектом . Это соединяет процесс надстройки с процессом ведущего приложения Office.
dataValidation	Возвращает объект проверки данных.
format	Возвращает объект формата, в который включены шрифт, заливка, границы, выравнивание и другие свойства диапазона.
formulas	Представляет формулу в формате A1. Если в ячейке нет формулы, возвращается ее значение.
formulasLocal	Представляет формулу в нотации стиля A1 на языке пользователя и в соответствии с его языковым стандартом. Например, английская формула =SUM(A1, 1.5) превратится в "=СУММ(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 для заданного диапазона на основе языковых параметров пользователя. Excel не выполняет приведение языка или формата при получении или задании `numberFormatLocal` свойства. Любой возвращаемый текст использует строки в локальном формате на основе языка, указанного в параметрах системы.
rowCount	Возвращает общее количество строк в диапазоне.
rowHidden	Представляет, скрыты ли все строки в текущем диапазоне. Значение — это `true` , когда все строки в диапазоне скрыты. Значение — это значение `false` , когда строки в диапазоне не скрыты. Значением является, `null` когда некоторые строки в диапазоне скрыты, а другие строки в том же диапазоне не скрыты.
rowIndex	Возвращает номер строки первой ячейки диапазона. Используется нулевой индекс.
savedAsArray	Представляет, будут ли все ячейки сохранены в виде формулы массива. Возвращает значение `true` , если все ячейки будут сохранены в виде формулы массива или `false` если все ячейки не будут сохранены в виде формулы массива. Возвращает значение `null` , если некоторые ячейки будут сохранены в виде формулы массива, а некоторые — нет.
sort	Представляет порядок сортировки текущего диапазона.
style	Представляет стиль текущего диапазона. Если стили ячеек несогласованны, `null` возвращается. Для пользовательских стилей будет возвращено имя стиля. Для встроенных стилей возвращается строка, представляющая значение в перечислении `BuiltInStyle` .
text	Текстовые значения указанного диапазона. Текстовое значение не зависит от ширины ячейки. Подстановка числового знака (#), выполняемая в пользовательском интерфейсе Excel, не повлияет на текстовое значение, возвращаемое API.
top	Возвращает расстояние в точках для 100% увеличения от верхнего края листа до верхнего края диапазона.
values	Представляет необработанные значения указанного диапазона. Возвращаемые данные могут быть строковыми, числовыми или логическими. Ячейки, содержащие ошибку, вернут строку ошибки. Если возвращаемое значение начинается с плюса ("+"), минуса ("-") или знака равенства ("="), Excel интерпретирует это значение как формулу.
valueTypes	Указывает тип данных в каждой ячейке.
width	Возвращает расстояние в точках для 100 %-го увеличения от левого края диапазона до правого края диапазона.
worksheet	Лист, содержащий текущий диапазон.

Методы

autoFill(destinationRange, autoFillType)	Заполняет диапазон от текущего до целевого диапазона с помощью указанной логики автозаполнения. Диапазон назначения может быть `null` или может расширять диапазон источника по горизонтали или по вертикали. Несогласоные диапазоны не поддерживаются. Дополнительные сведения см. в разделе Использование автозаполнения и флэш-заливки.
autoFill(destinationRange, autoFillTypeString)	Заполняет диапазон от текущего до целевого диапазона с помощью указанной логики автозаполнения. Диапазон назначения может быть `null` или может расширять диапазон источника по горизонтали или по вертикали. Несогласоные диапазоны не поддерживаются. Дополнительные сведения см. в разделе Использование автозаполнения и флэш-заливки.
calculate()	Вычисляет диапазон ячеек на листе.
clear(applyTo)	Очистите значения диапазона и форматирование, например заливку и границу.
clear(applyToString)	Очистите значения диапазона и форматирование, например заливку и границу.
convertDataTypeToText()	Преобразует ячейки диапазона с типами данных в текст.
convertToLinkedDataType(serviceID, languageCulture)	Преобразует ячейки диапазона в связанные типы данных на листе.
copyFrom(sourceRange, copyType, skipBlanks, transpose)	Копирует данные ячейки или форматирование из исходного диапазона или `RangeAreas` в текущий диапазон. Диапазон назначения может отличаться от исходного диапазона или `RangeAreas`. Назначение развертывается автоматически, если оно меньше исходного. Примечание. Как и функция копирования в пользовательском интерфейсе Excel, если диапазон назначения точно больше исходного диапазона в строках или столбцах, исходное содержимое реплицируется несколько раз. Например, копирование диапазона 2x2 в диапазон 2x6 приведет к 3 копиям исходного диапазона 2x2.
copyFrom(sourceRange, copyTypeString, skipBlanks, transpose)	Копирует данные ячейки или форматирование из исходного диапазона или `RangeAreas` в текущий диапазон. Диапазон назначения может отличаться от исходного диапазона или `RangeAreas`. Назначение развертывается автоматически, если оно меньше исходного. Примечание. Как и функция копирования в пользовательском интерфейсе Excel, если диапазон назначения точно больше исходного диапазона в строках или столбцах, исходное содержимое реплицируется несколько раз. Например, копирование диапазона 2x2 в диапазон 2x6 приведет к 3 копиям исходного диапазона 2x2.
delete(shift)	Удаляет ячейки, связанные с диапазоном.
delete(shiftString)	Удаляет ячейки, связанные с диапазоном.
find(text, criteria)	Находит определенную строку на основе указанных условий. Если текущий диапазон больше одной ячейки, поиск будет ограничен этим диапазоном, в противном случае поиск будет охватывать весь лист, начиная с этой ячейки.
findOrNullObject(text, criteria)	Находит определенную строку на основе указанных условий. Если текущий диапазон больше одной ячейки, поиск будет ограничен этим диапазоном, в противном случае поиск будет охватывать весь лист, начиная с этой ячейки. Если совпадений нет, этот метод возвращает объект со свойством `isNullObjecttrue`. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
flashFill()	Выполняется заполнение флэш-памяти в текущем диапазоне. Flash Fill автоматически заполняет данные, когда он чувствует шаблон, поэтому диапазон должен быть одним диапазоном столбцов и содержать данные вокруг него, чтобы найти шаблон.
getAbsoluteResizedRange(numRows, numColumns)	`Range` Возвращает объект с той же левой верхней ячейкой, что и текущий `Range` объект, но с указанным числом строк и столбцов.
getBoundingRect(anotherRange)	Возвращает наименьший объект диапазона, включающий в себя заданные диапазоны. Например, значения `GetBoundingRect` "B2:C5" и "D10:E15" — "B2:E15".
getCell(row, column)	Получает объект диапазона, содержащий одну ячейку, по номеру строки и столбца. Ячейка может находиться за пределами родительского диапазона, если она находится в сетке листа. Возвращаемая ячейка располагается относительно верхней левой ячейки диапазона.
getCellProperties(cellPropertiesLoadOptions)	Возвращает двумерный массив, в который включены данные для шрифта, заливки, границ, выравнивания и других свойств каждой ячейки.
getColumn(column)	Возвращает столбец в диапазоне.
getColumnProperties(columnPropertiesLoadOptions)	Возвращает одномерный массив, в который включены данные для шрифта, заливки, границ, выравнивания и других свойств каждого столбца. Для свойств, не являющихся одинаковыми в каждой ячейке определенного столбца, возвращается значение null.
getColumnsAfter(count)	Возвращает определенное количество столбцов справа от текущего `Range` объекта.
getColumnsBefore(count)	Возвращает определенное количество столбцов слева от текущего `Range` объекта.
getDirectPrecedents()	`WorkbookRangeAreas` Возвращает объект , представляющий диапазон, содержащий все ячейки прямого прецедента указанного диапазона на одном листе или на нескольких листах. Примечание. Этот API возвращает ошибку, `ItemNotFound` если прецеденты не найдены.
getEntireColumn()	Возвращает объект, представляющий весь столбец диапазона (например, если текущий диапазон представляет ячейки "B4:E11", он `getEntireColumn` представляет собой диапазон, представляющий столбцы "B:E").
getEntireRow()	Возвращает объект, представляющий всю строку диапазона (например, если текущий диапазон представляет ячейки "B4:E11", он `GetEntireRow` представляет собой диапазон, представляющий строки "4:11").
getImage()	Отображает диапазон в виде изображения PNG в кодировке Base64. Важно*. В настоящее время этот API не поддерживается в Excel для Mac. Сведения о текущем состоянии см. в статье OfficeDev/office-js Issue No 235 .
getIntersection(anotherRange)	Возвращает объект диапазона, представляющий прямоугольное пересечение заданных диапазонов.
getIntersectionOrNullObject(anotherRange)	Возвращает объект диапазона, представляющий прямоугольное пересечение заданных диапазонов. Если пересечение не найдено, этот метод возвращает объект со свойством `isNullObjecttrue`. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
getLastCell()	Возвращает последнюю ячейку в диапазоне. Например, последняя ячейка диапазона B2:D5 — D5.
getLastColumn()	Возвращает последний столбец в диапазоне. Например, последний столбец диапазона B2:D5 — D2:D5.
getLastRow()	Возвращает последнюю строку в диапазоне. Например, последняя строка в диапазоне "B2:D5" — "B5:D5".
getOffsetRange(rowOffset, columnOffset)	Возвращает объект, представляющий диапазон, который смещен от указанного диапазона. Измерение возвращаемого диапазона будет соответствовать этому диапазону. Если результирующий диапазон выходит за пределы таблицы листа, возникнет ошибка.
getPivotTables(fullyContained)	Возвращает коллекцию сводных таблиц с заданной областью, перекрывающуюся с диапазоном.
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` из одного или нескольких диапазонов, который представляет все ячейки, соответствующие указанному типу и значению. Если специальные ячейки не найдены, этот метод возвращает объект со свойством `isNullObjecttrue`. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
getSpecialCellsOrNullObject(cellTypeString, cellValueTypeString)	Возвращает объект , состоящий `RangeAreas` из одного или нескольких диапазонов, который представляет все ячейки, соответствующие указанному типу и значению. Если специальные ячейки не найдены, этот метод возвращает объект со свойством `isNullObjecttrue`. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
getSpillingToRange()	Получает объект range, содержащий диапазон переноса при вызове для базовой ячейки. Возвращает ошибку, если применяется к диапазону с несколькими ячейками.
getSpillingToRangeOrNullObject()	Получает объект range, содержащий диапазон переноса при вызове для базовой ячейки. Если диапазон не является ячейкой привязки или не удается найти диапазон разлива, то этот метод возвращает объект со свойством `isNullObject` .`true` Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
getSpillParent()	Получает объект диапазона, содержащий базовую ячейку для переносимой ячейки. Возвращает ошибку, если применяется к диапазону с несколькими ячейками.
getSpillParentOrNullObject()	Возвращает объект диапазона, содержащий ячейку привязки для ячейки, в нее попадает. Если это не разлитая ячейка или задано несколько ячеек, то этот метод возвращает объект со свойством `isNullObject` , равным `true`. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
getSurroundingRegion()	`Range` Возвращает объект , представляющий окружающую область для левой верхней ячейки в этом диапазоне. Это диапазон, ограниченный любым сочетанием пустых строк и столбцов, относящихся к этому диапазону.
getTables(fullyContained)	Получает коллекцию таблиц с заданной областью, перекрывающую диапазон.
getUsedRange(valuesOnly)	Возвращает используемый диапазон заданного объекта диапазона. Если в диапазоне нет используемых ячеек, эта функция вызовет ошибку `ItemNotFound` .
getUsedRangeOrNullObject(valuesOnly)	Возвращает используемый диапазон заданного объекта диапазона. Если в диапазоне нет используемых ячеек, этот метод возвращает объект со свойством `isNullObjecttrue`. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
getVisibleView()	Представляет видимые строки текущего диапазона.
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.
set(properties, options)	Задает несколько свойств объекта одновременно. Можно передать обычный объект с соответствующими свойствами или другой объект API того же типа.
set(properties)	Задает несколько свойств объекта одновременно на основе существующего загруженного объекта.
setCellProperties(cellPropertiesData)	Обновления диапазон на основе двухмерного массива свойств ячейки, инкапсулирующего такие элементы, как шрифт, заливка, границы и выравнивание.
setColumnProperties(columnPropertiesData)	Обновления диапазон на основе одномерного массива свойств столбца, инкапсулирующего такие элементы, как шрифт, заливка, границы и выравнивание.
setDirty()	Устанавливает диапазон, предназначенный для пересчета при выполнении следующего пересчета.
setRowProperties(rowPropertiesData)	Обновления диапазон на основе одномерного массива свойств строки, инкапсулирующего такие элементы, как шрифт, заливка, границы и выравнивание.
showCard()	Отображает карточку для активной ячейки, если она имеет содержимое c форматированным значением.
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. Значение address содержит ссылку на лист (например, "Лист1! A1:B4").

readonly address: string;

Значение свойства

string

addressLocal

Представляет ссылку на диапазон для указанного диапазона на языке пользователя.

readonly addressLocal: string;

Значение свойства

string

cellCount

Указывает количество ячеек в диапазоне. Этот API возвращает значение -1, если количество ячеек превышает 2^31-1 (2,147,483,647).

readonly cellCount: number;

Значение свойства

number

columnCount

Задает общее количество столбцов в диапазоне.

readonly columnCount: number;

Значение свойства

number

columnHidden

Представляет, если все столбцы в текущем диапазоне скрыты. Значение — это true , когда все столбцы в диапазоне скрыты. Значение имеет значение, false если столбцы в диапазоне не скрыты. Значением считается, null когда некоторые столбцы в диапазоне скрыты, а другие столбцы в том же диапазоне не скрыты.

columnHidden: boolean;

Значение свойства

boolean

columnIndex

Задает номер столбца первой ячейки в диапазоне. Используется нулевой индекс.

readonly columnIndex: number;

Значение свойства

number

conditionalFormats

Коллекция, ConditionalFormats пересекающая диапазон.

readonly conditionalFormats: Excel.ConditionalFormatCollection;

Значение свойства

Excel.ConditionalFormatCollection

context

Контекст запроса, связанный с объектом . Это соединяет процесс надстройки с процессом ведущего приложения Office.

context: RequestContext;

Значение свойства

Excel.RequestContext

dataValidation

Возвращает объект проверки данных.

readonly dataValidation: Excel.DataValidation;

Значение свойства

Excel.DataValidation

format

Возвращает объект формата, в который включены шрифт, заливка, границы, выравнивание и другие свойства диапазона.

readonly format: Excel.RangeFormat;

Значение свойства

Excel.RangeFormat

formulas

Представляет формулу в формате A1. Если в ячейке нет формулы, возвращается ее значение.

formulas: any[][];

Значение свойства

any[][]

formulasLocal

Представляет формулу в нотации стиля A1 на языке пользователя и в соответствии с его языковым стандартом. Например, английская формула =SUM(A1, 1.5) превратится в "=СУММ(A1; 1,5)" на русском языке. Если в ячейке нет формулы, возвращается ее значение.

formulasLocal: any[][];

Значение свойства

any[][]

formulasR1C1

Представляет формулу в формате R1C1. Если в ячейке нет формулы, возвращается ее значение.

formulasR1C1: any[][];

Значение свойства

any[][]

hasSpill

Указывает, есть ли во всех ячейках граница переноса. Возвращает значение true , если все ячейки имеют границу разлива или false если у всех ячеек нет границы разлива. Возвращает, null если в диапазоне имеются ячейки как с границами разлива, так и без них.

readonly hasSpill: boolean;

Значение свойства

boolean

height

Возвращает расстояние в точках для 100 %-го увеличения от верхнего края диапазона до нижнего края диапазона.

readonly height: number;

Значение свойства

number

hidden

Представляет, скрыты ли все ячейки в текущем диапазоне. Значение — это true , когда все ячейки в диапазоне скрыты. Значение — это значение false , когда ячейки в диапазоне не скрыты. Значение — это null , когда некоторые ячейки в диапазоне скрыты, а другие ячейки в том же диапазоне не скрыты.

readonly hidden: boolean;

Значение свойства

boolean

hyperlink

Представляет гиперссылку для текущего диапазона.

hyperlink: Excel.RangeHyperlink;

Значение свойства

Excel.RangeHyperlink

Примеры

// 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

isEntireRow

Указывает, является ли текущий диапазон целой строкой.

readonly isEntireRow: boolean;

Значение свойства

boolean

left

Возвращает расстояние в точках для 100 % увеличения от левого края листа до левого края диапазона.

readonly left: number;

Значение свойства

number

linkedDataTypeState

Представляет состояние типа данных каждой ячейки.

readonly linkedDataTypeState: Excel.LinkedDataTypeState[][];

Значение свойства

Excel.LinkedDataTypeState[][]

numberFormat

Представляет код числового формата Excel для заданного диапазона. Дополнительные сведения о форматировании чисел в Excel см. в разделе Коды числового формата.

numberFormat: any[][];

Значение свойства

any[][]

Примеры

// 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[][];

Значение свойства

Excel.NumberFormatCategory[][]

numberFormatLocal

Представляет код числового формата Excel для заданного диапазона на основе языковых параметров пользователя. Excel не выполняет приведение языка или формата при получении или задании numberFormatLocal свойства. Любой возвращаемый текст использует строки в локальном формате на основе языка, указанного в параметрах системы.

numberFormatLocal: any[][];

Значение свойства

any[][]

rowCount

Возвращает общее количество строк в диапазоне.

readonly rowCount: number;

Значение свойства

number

rowHidden

Представляет, скрыты ли все строки в текущем диапазоне. Значение — это true , когда все строки в диапазоне скрыты. Значение — это значение false , когда строки в диапазоне не скрыты. Значением является, null когда некоторые строки в диапазоне скрыты, а другие строки в том же диапазоне не скрыты.

rowHidden: boolean;

Значение свойства

boolean

rowIndex

Возвращает номер строки первой ячейки диапазона. Используется нулевой индекс.

readonly rowIndex: number;

Значение свойства

number

savedAsArray

Представляет, будут ли все ячейки сохранены в виде формулы массива. Возвращает значение true , если все ячейки будут сохранены в виде формулы массива или false если все ячейки не будут сохранены в виде формулы массива. Возвращает значение null , если некоторые ячейки будут сохранены в виде формулы массива, а некоторые — нет.

readonly savedAsArray: boolean;

Значение свойства

boolean

sort

Представляет порядок сортировки текущего диапазона.

readonly sort: Excel.RangeSort;

Значение свойства

Excel.RangeSort

Примеры

// 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

Примеры

// 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, не повлияет на текстовое значение, возвращаемое API.

readonly text: string[][];

Значение свойства

string[][]

top

Возвращает расстояние в точках для 100% увеличения от верхнего края листа до верхнего края диапазона.

readonly top: number;

Значение свойства

number

values

Представляет необработанные значения указанного диапазона. Возвращаемые данные могут быть строковыми, числовыми или логическими. Ячейки, содержащие ошибку, вернут строку ошибки. Если возвращаемое значение начинается с плюса ("+"), минуса ("-") или знака равенства ("="), Excel интерпретирует это значение как формулу.

values: any[][];

Значение свойства

any[][]

valueTypes

Указывает тип данных в каждой ячейке.

readonly valueTypes: Excel.RangeValueType[][];

Значение свойства

Excel.RangeValueType[][]

width

Возвращает расстояние в точках для 100 %-го увеличения от левого края диапазона до правого края диапазона.

readonly width: number;

Значение свойства

number

worksheet

Лист, содержащий текущий диапазон.

readonly worksheet: Excel.Worksheet;

Значение свойства

Excel.Worksheet

Сведения о методе

autoFill(destinationRange, autoFillType)

Заполняет диапазон от текущего до целевого диапазона с помощью указанной логики автозаполнения. Диапазон назначения может быть null или может расширять диапазон источника по горизонтали или по вертикали. Несогласоные диапазоны не поддерживаются.

Дополнительные сведения см. в разделе Использование автозаполнения и флэш-заливки.

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

Параметры

destinationRange: Excel.Range | string

Диапазон назначения для автозаполнения. Если целевой диапазон — null, данные заполняются на основе окружающих ячеек (что является поведением при двойном щелчке маркера заполнения диапазона пользовательского интерфейса).

autoFillType: Excel.AutoFillType

Тип автозаполнения. Указывает способ заполнения целевого диапазона на основе содержимого текущего диапазона. Значение по умолчанию — FillDefault.

Возвращаемое значение

void

Примеры

// 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)

Дополнительные сведения см. в разделе Использование автозаполнения и флэш-заливки.

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

Параметры

destinationRange: Excel.Range | string

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

Возвращаемое значение

void

calculate()

Вычисляет диапазон ячеек на листе.

calculate(): void;

Возвращаемое значение

void

clear(applyTo)

Очистите значения диапазона и форматирование, например заливку и границу.

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

Параметры

applyTo: Excel.ClearApplyTo

Необязательный параметр. Определяет тип действия очистки. Дополнительные сведения см. в этой Excel.ClearApplyTo статье.

Возвращаемое значение

void

Примеры

// 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"): void;

Параметры

applyToString: "All" | "Formats" | "Contents" | "Hyperlinks" | "RemoveHyperlinks"

Возвращаемое значение

void

convertDataTypeToText()

Преобразует ячейки диапазона с типами данных в текст.

convertDataTypeToText(): void;

Возвращаемое значение

void

convertToLinkedDataType(serviceID, languageCulture)

Преобразует ячейки диапазона в связанные типы данных на листе.

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

Параметры

serviceID: number

Идентификатор службы, который будет использоваться для запроса данных.

languageCulture: string

Язык и региональные параметры для запроса к службе.

Возвращаемое значение

void

copyFrom(sourceRange, copyType, skipBlanks, transpose)

Копирует данные ячейки или форматирование из исходного диапазона или RangeAreas в текущий диапазон. Диапазон назначения может отличаться от исходного диапазона или RangeAreas. Назначение развертывается автоматически, если оно меньше исходного. Примечание. Как и функция копирования в пользовательском интерфейсе Excel, если диапазон назначения точно больше исходного диапазона в строках или столбцах, исходное содержимое реплицируется несколько раз. Например, копирование диапазона 2x2 в диапазон 2x6 приведет к 3 копиям исходного диапазона 2x2.

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

Значение true, если требуется транспонировать ячейки в целевом диапазоне. Значение по умолчанию: false.

Возвращаемое значение

void

Примеры

// 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)

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

Параметры

sourceRange: Excel.Range | Excel.RangeAreas | string

copyTypeString: "All" | "Formulas" | "Values" | "Formats" | "Link"

Тип данных ячейки или форматирование для копирования. Значение по умолчанию — "All".

skipBlanks: boolean

Значение true, если пропускать пустые ячейки в исходном диапазоне. Значение по умолчанию: false.

transpose: boolean

Значение true, если требуется транспонировать ячейки в целевом диапазоне. Значение по умолчанию: false.

Возвращаемое значение

void

delete(shift)

Удаляет ячейки, связанные с диапазоном.

delete(shift: Excel.DeleteShiftDirection): void;

Параметры

shift: Excel.DeleteShiftDirection

Определяет способ сдвига ячеек. Дополнительные сведения см. в этой Excel.DeleteShiftDirection статье.

Возвращаемое значение

void

Примеры

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

find(text, criteria)

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

Параметры

text: string

Строка для поиска.

criteria: Excel.SearchCriteria

Дополнительные критерии поиска, включая направление поиска и то, должен ли поиск соответствовать всей ячейке или учитывать регистр.

Возвращаемое значение

Excel.Range

Объект Range , представляющий первую ячейку, содержащую значение, соответствующее тексту поиска и условиям.

Примеры

// 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)

Находит определенную строку на основе указанных условий. Если текущий диапазон больше одной ячейки, поиск будет ограничен этим диапазоном, в противном случае поиск будет охватывать весь лист, начиная с этой ячейки. Если совпадений нет, этот метод возвращает объект со свойством isNullObjecttrue. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

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

Параметры

text: string

Строка для поиска.

criteria: Excel.SearchCriteria

Возвращаемое значение

Excel.Range

Объект Range , соответствующий условиям поиска.

Примеры

// 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()

Выполняется заполнение флэш-памяти в текущем диапазоне. Flash Fill автоматически заполняет данные, когда он чувствует шаблон, поэтому диапазон должен быть одним диапазоном столбцов и содержать данные вокруг него, чтобы найти шаблон.

flashFill(): void;

Возвращаемое значение

void

getAbsoluteResizedRange(numRows, numColumns)

Range Возвращает объект с той же левой верхней ячейкой, что и текущий Range объект, но с указанным числом строк и столбцов.

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

Параметры

numRows: number

Количество строк нового размера диапазона.

numColumns: number

Количество столбцов нового размера диапазона.

Возвращаемое значение

Excel.Range

getBoundingRect(anotherRange)

Возвращает наименьший объект диапазона, включающий в себя заданные диапазоны. Например, значения GetBoundingRect "B2:C5" и "D10:E15" — "B2:E15".

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

Параметры

anotherRange: Excel.Range | string

Объект диапазона, адрес или имя диапазона.

Возвращаемое значение

Excel.Range

Примеры

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)

Получает объект диапазона, содержащий одну ячейку, по номеру строки и столбца. Ячейка может находиться за пределами родительского диапазона, если она находится в сетке листа. Возвращаемая ячейка располагается относительно верхней левой ячейки диапазона.

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

Параметры

row: number

Номер строки ячейки, которую требуется извлечь. Используется нулевой индекс.

column: number

Номер столбца ячейки, которую требуется извлечь. Используется нулевой индекс.

Возвращаемое значение

Excel.Range

Примеры

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)

Возвращает двумерный массив, в который включены данные для шрифта, заливки, границ, выравнивания и других свойств каждой ячейки.

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

Параметры

cellPropertiesLoadOptions: Excel.CellPropertiesLoadOptions

Объект , представляющий свойства ячейки для загрузки.

Возвращаемое значение

OfficeExtension.ClientResult<Excel.CellProperties[][]>

Двухмерный массив, где каждый элемент представляет запрошенные свойства соответствующей ячейки.

Примеры

// 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

Номер столбца диапазона, который требуется извлечь. Используется нулевой индекс.

Возвращаемое значение

Excel.Range

Примеры

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

Объект , представляющий свойства столбца для загрузки.

Возвращаемое значение

OfficeExtension.ClientResult<Excel.ColumnProperties[]>

Массив, где каждый элемент представляет запрошенные свойства соответствующего столбца.

getColumnsAfter(count)

Возвращает определенное количество столбцов справа от текущего Range объекта.

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

Параметры

count: number

Необязательный параметр. Количество столбцов, включаемых в полученный диапазон. Чтобы создать диапазон за пределами текущего диапазона, используйте положительное число. Вы также можете использовать отрицательное число, чтобы создать диапазон в рамках текущего диапазона. Значение по умолчанию равно 1.

Возвращаемое значение

Excel.Range

getColumnsBefore(count)

Возвращает определенное количество столбцов слева от текущего Range объекта.

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

Параметры

count: number

Возвращаемое значение

Excel.Range

getDirectPrecedents()

WorkbookRangeAreas Возвращает объект , представляющий диапазон, содержащий все ячейки прямого прецедента указанного диапазона на одном листе или на нескольких листах. Примечание. Этот API возвращает ошибку, ItemNotFound если прецеденты не найдены.

getDirectPrecedents(): Excel.WorkbookRangeAreas;

Возвращаемое значение

Excel.WorkbookRangeAreas

Примеры

// 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;

Возвращаемое значение

Excel.Range

Примеры

// 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;

Возвращаемое значение

Excel.Range

Примеры

// 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);
});

getImage()

Отображает диапазон в виде изображения PNG в кодировке Base64. Важно*. В настоящее время этот API не поддерживается в Excel для Mac. Сведения о текущем состоянии см. в статье OfficeDev/office-js Issue No 235 .

getImage(): OfficeExtension.ClientResult<string>;

Возвращаемое значение

OfficeExtension.ClientResult<string>

getIntersection(anotherRange)

Возвращает объект диапазона, представляющий прямоугольное пересечение заданных диапазонов.

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

Параметры

anotherRange: Excel.Range | string

Объект диапазона или адрес диапазона, который будет использоваться для определения пересечения диапазонов.

Возвращаемое значение

Excel.Range

Примеры

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)

Возвращает объект диапазона, представляющий прямоугольное пересечение заданных диапазонов. Если пересечение не найдено, этот метод возвращает объект со свойством isNullObjecttrue. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

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

Параметры

anotherRange: Excel.Range | string

Объект диапазона или адрес диапазона, который будет использоваться для определения пересечения диапазонов.

Возвращаемое значение

Excel.Range

Примеры

// 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;

Возвращаемое значение

Excel.Range

Примеры

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;

Возвращаемое значение

Excel.Range

Примеры

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;

Возвращаемое значение

Excel.Range

Примеры

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
});

getOffsetRange(rowOffset, columnOffset)

Возвращает объект, представляющий диапазон, который смещен от указанного диапазона. Измерение возвращаемого диапазона будет соответствовать этому диапазону. Если результирующий диапазон выходит за пределы таблицы листа, возникнет ошибка.

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

Параметры

rowOffset: number

Количество строк (положительное, отрицательное или нулевое), на которое необходимо сместить диапазон. Положительные значения соответствуют смещению вниз, а отрицательные — вверх.

columnOffset: number

Количество столбцов (положительное, отрицательное или 0), на который нужно сместить диапазон. Положительные значения соответствуют смещению вправо, а отрицательные — влево.

Возвращаемое значение

Excel.Range

Примеры

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.

Возвращаемое значение

Excel.PivotTableScopedCollection

Примеры

// 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}`);
  });
});

getResizedRange(deltaRows, deltaColumns)

Возвращает объект, аналогичный Range текущему Range объекту, но с его правым нижним углом, развернутым (или с сокращением) на некоторое количество строк и столбцов.

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

Параметры

deltaRows: number

Количество строк, добавляемых в правый нижний угол, относительно текущего диапазона. Используйте положительное число, чтобы расширить диапазон или отрицательное число, чтобы уменьшить его.

deltaColumns: number

Число столбцов, на которые необходимо развернуть правый нижний угол относительно текущего диапазона. Используйте положительное число, чтобы расширить диапазон или отрицательное число, чтобы уменьшить его.

Возвращаемое значение

Excel.Range

getRow(row)

Возвращает строку из диапазона.

getRow(row: number): Excel.Range;

Параметры

row: number

Номер строки диапазона, который требуется извлечь. Используется нулевой индекс.

Возвращаемое значение

Excel.Range

Примеры

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

Объект , представляющий свойства строки для загрузки.

Возвращаемое значение

OfficeExtension.ClientResult<Excel.RowProperties[]>

Массив, где каждый элемент представляет запрошенные свойства соответствующей строки.

getRowsAbove(count)

Возвращает определенное количество строк над текущим Range объектом .

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

Параметры

count: number

Необязательный параметр. Количество строк, включаемых в полученный диапазон. Чтобы создать диапазон за пределами текущего диапазона, используйте положительное число. Вы также можете использовать отрицательное число, чтобы создать диапазон в рамках текущего диапазона. Значение по умолчанию равно 1.

Возвращаемое значение

Excel.Range

getRowsBelow(count)

Возвращает определенное количество строк под текущим Range объектом .

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

Параметры

count: number

Возвращаемое значение

Excel.Range

getSpecialCells(cellType, cellValueType)

Возвращает объект , состоящий RangeAreas из одного или нескольких прямоугольных диапазонов, который представляет все ячейки, соответствующие указанному типу и значению. Если специальные ячейки не найдены, будет выдана ItemNotFound ошибка.

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

Параметры

cellType: Excel.SpecialCellType

Тип включаемых ячеек.

cellValueType: Excel.SpecialCellValueType

Если cellType имеет значение constants или formulas, этот аргумент используется для определения типов ячеек, которые следует включить в результат. Эти значения можно объединить для возврата нескольких типов. По умолчанию выбирается все константы или формулы независимо от типа.

Возвращаемое значение

Excel.RangeAreas

Примеры

// 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)

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"

Возвращаемое значение

Excel.RangeAreas

getSpecialCellsOrNullObject(cellType, cellValueType)

Возвращает объект , состоящий RangeAreas из одного или нескольких диапазонов, который представляет все ячейки, соответствующие указанному типу и значению. Если специальные ячейки не найдены, этот метод возвращает объект со свойством isNullObjecttrue. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

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

Параметры

cellType: Excel.SpecialCellType

Тип включаемых ячеек.

cellValueType: Excel.SpecialCellValueType

Возвращаемое значение

Excel.RangeAreas

getSpecialCellsOrNullObject(cellTypeString, cellValueTypeString)

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"

Возвращаемое значение

Excel.RangeAreas

getSpillingToRange()

Получает объект range, содержащий диапазон переноса при вызове для базовой ячейки. Возвращает ошибку, если применяется к диапазону с несколькими ячейками.

getSpillingToRange(): Excel.Range;

Возвращаемое значение

Excel.Range

Примеры

// 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;

Возвращаемое значение

Excel.Range

getSpillParent()

Получает объект диапазона, содержащий базовую ячейку для переносимой ячейки. Возвращает ошибку, если применяется к диапазону с несколькими ячейками.

getSpillParent(): Excel.Range;

Возвращаемое значение

Excel.Range

getSpillParentOrNullObject()

Возвращает объект диапазона, содержащий ячейку привязки для ячейки, в нее попадает. Если это не разлитая ячейка или задано несколько ячеек, то этот метод возвращает объект со свойством isNullObject , равным true. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

getSpillParentOrNullObject(): Excel.Range;

Возвращаемое значение

Excel.Range

getSurroundingRegion()

Range Возвращает объект , представляющий окружающую область для левой верхней ячейки в этом диапазоне. Это диапазон, ограниченный любым сочетанием пустых строк и столбцов, относящихся к этому диапазону.

getSurroundingRegion(): Excel.Range;

Возвращаемое значение

Excel.Range

getTables(fullyContained)

Получает коллекцию таблиц с заданной областью, перекрывающую диапазон.

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

Параметры

fullyContained: boolean

Если trueзначение , возвращает только те таблицы, которые полностью содержатся в пределах диапазона. Значение по умолчанию — false.

Возвращаемое значение

Excel.TableScopedCollection

getUsedRange(valuesOnly)

Возвращает используемый диапазон заданного объекта диапазона. Если в диапазоне нет используемых ячеек, эта функция вызовет ошибку ItemNotFound .

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

Параметры

valuesOnly: boolean

Учитывает только ячейки со значениями. [Набор API: ExcelApi 1.2]

Возвращаемое значение

Excel.Range

Примеры

// 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)

Возвращает используемый диапазон заданного объекта диапазона. Если в диапазоне нет используемых ячеек, этот метод возвращает объект со свойством isNullObjecttrue. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.

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

Параметры

valuesOnly: boolean

Учитывает только ячейки со значениями.

Возвращаемое значение

Excel.Range

Примеры

// 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()

Представляет видимые строки текущего диапазона.

getVisibleView(): Excel.RangeView;

Возвращаемое значение

Excel.RangeView

group(groupOption)

Группы столбцы и строки для структуры.

group(groupOption: Excel.GroupOption): void;

Параметры

groupOption: Excel.GroupOption

Указывает, как можно группировать диапазон по строкам или столбцам. Ошибка InvalidArgument возникает, если параметр группы отличается от свойства диапазона isEntireRow или isEntireColumn (т. е. имеет значение true и range.isEntireRowgroupOption имеет значение "ByColumns" или range.isEntireColumn true и groupOption имеет значение "ByRows").

Возвращаемое значение

void

Примеры

// 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"

Возвращаемое значение

void

hideGroupDetails(groupOption)

Скрывает сведения о группе строк или столбцов.

hideGroupDetails(groupOption: Excel.GroupOption): void;

Параметры

groupOption: Excel.GroupOption

Указывает, следует ли скрывать сведения о сгруппированных строках или сгруппированных столбцах.

Возвращаемое значение

void

hideGroupDetails(groupOptionString)

Скрывает сведения о группе строк или столбцов.

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

Параметры

groupOptionString: "ByRows" | "ByColumns"

Указывает, следует ли скрывать сведения о сгруппированных строках или сгруппированных столбцах.

Возвращаемое значение

void

insert(shift)

Вставляет ячейку или диапазон ячеек на лист вместо этого диапазона, а также сдвигает другие ячейки, чтобы освободить место. Возвращает новый Range объект в пустом пространстве.

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

Параметры

shift: Excel.InsertShiftDirection

Определяет способ сдвига ячеек. Дополнительные сведения см. в этой Excel.InsertShiftDirection статье.

Возвращаемое значение

Excel.Range

Примеры

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)

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

Параметры

shiftString: "Down" | "Right"

Определяет способ сдвига ячеек. Дополнительные сведения см. в этой Excel.InsertShiftDirection статье.

Возвращаемое значение

Excel.Range

load(options)

Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().

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

Параметры

options: Excel.Interfaces.RangeLoadOptions

Предоставляет параметры свойств объекта для загрузки.

Возвращаемое значение

Excel.Range

load(propertyNames)

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

Параметры

propertyNames: string | string[]

Строка с разделителями-запятыми или массив строк, указывающих свойства для загрузки.

Возвращаемое значение

Excel.Range

Примеры

// 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)

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

Параметры

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

propertyNamesAndPaths.select — это строка с разделителями-запятыми, указывающая загружаемые свойства, и propertyNamesAndPaths.expand строка с разделителями-запятыми, указывающая загружаемые свойства навигации.

Возвращаемое значение

Excel.Range

merge(across)

Объединяет ячейки диапазона в одну область на листе.

merge(across?: boolean): void;

Параметры

across: boolean

Необязательный параметр. Задайте true для объединения ячеек в каждой строке указанного диапазона в виде отдельных объединенных ячеек. Значение по умолчанию — false.

Возвращаемое значение

void

Примеры

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

Примеры

// 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.

Возвращаемое значение

Excel.RemoveDuplicatesResult

Результирующий объект, содержащий количество удаленных строк и количество оставшихся уникальных строк.

Примеры

// 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

Дополнительные условия замены.

Возвращаемое значение

OfficeExtension.ClientResult<number>

Количество выполненных замен.

select()

Выбирает указанный диапазон в пользовательском интерфейсе Excel.

select(): void;

Возвращаемое значение

void

Примеры

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

Предоставляет возможность подавления ошибок, если объект свойств пытается задать какие-либо свойства, доступные только для чтения.

Возвращаемое значение

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)

Обновления диапазон на основе двухмерного массива свойств ячейки, инкапсулирующего такие элементы, как шрифт, заливка, границы и выравнивание.

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

Параметры

cellPropertiesData: Excel.SettableCellProperties[][]

Двухмерный массив, представляющий, какие свойства следует задать в каждой ячейке.

Возвращаемое значение

void

Примеры

// 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

setDirty()

Устанавливает диапазон, предназначенный для пересчета при выполнении следующего пересчета.

setDirty(): void;

Возвращаемое значение

void

setRowProperties(rowPropertiesData)

Обновления диапазон на основе одномерного массива свойств строки, инкапсулирующего такие элементы, как шрифт, заливка, границы и выравнивание.

setRowProperties(rowPropertiesData: SettableRowProperties[]): void;

Параметры

rowPropertiesData: Excel.SettableRowProperties[]

Массив, представляющий свойства, которые следует задать в каждой строке.

Возвращаемое значение

void

showCard()

Отображает карточку для активной ячейки, если она имеет содержимое c форматированным значением.

showCard(): void;

Возвращаемое значение

void

showGroupDetails(groupOption)

Показывает сведения о группе строк или столбцов.

showGroupDetails(groupOption: Excel.GroupOption): void;

Параметры

groupOption: Excel.GroupOption

Указывает, следует ли отображать сведения о сгруппированных строках или сгруппированных столбцах.

Возвращаемое значение

void

showGroupDetails(groupOptionString)

Показывает сведения о группе строк или столбцов.

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

Параметры

groupOptionString: "ByRows" | "ByColumns"

Указывает, следует ли отображать сведения о сгруппированных строках или сгруппированных столбцах.

Возвращаемое значение

void

toJSON()

Переопределяет метод JavaScript toJSON() , чтобы обеспечить более полезные выходные данные при передаче объекта API в JSON.stringify(). (JSON.stringifyв свою очередь вызывает toJSON метод переданного ему объекта.) В то время как исходный Excel.Range объект является объектом API, toJSON метод возвращает обычный объект JavaScript (типизированный как Excel.Interfaces.RangeData), который содержит неглубокие копии всех загруженных дочерних свойств из исходного объекта.

toJSON(): Excel.Interfaces.RangeData;

Возвращаемое значение

Excel.Interfaces.RangeData

track()

Отслеживает объект для автоматической корректировки с учетом окружающих изменений в документе. Этот вызов является сокращением для context.trackedObjects.add(thisObject). Если вы используете этот объект в вызовах .sync и вне последовательного выполнения пакета .run и получаете ошибку InvalidObjectPath при задании свойства или вызове метода для объекта, необходимо добавить объект в отслеживаемую коллекцию объектов при первом создании объекта.

track(): Excel.Range;

Возвращаемое значение

Excel.Range

ungroup(groupOption)

Разгруппирует столбцы и строки для структуры.

ungroup(groupOption: Excel.GroupOption): void;

Параметры

groupOption: Excel.GroupOption

Указывает, как можно разгруппировать диапазон по строкам или столбцам.

Возвращаемое значение

void

Примеры

// 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

unmerge()

Разъединяет ячейки диапазона на отдельные ячейки.

unmerge(): void;

Возвращаемое значение

void

Примеры

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;

Возвращаемое значение

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();
});

Поделиться через

Excel.Range class

Комментарии

Примеры

Свойства

Методы

Сведения о свойстве

address

Значение свойства

Комментарии

addressLocal

Значение свойства

Комментарии

cellCount

Значение свойства

Комментарии

columnCount

Значение свойства

Комментарии

columnHidden

Значение свойства

Комментарии

columnIndex

Значение свойства

Комментарии

conditionalFormats

Значение свойства

Комментарии

context

Значение свойства

dataValidation

Значение свойства

Комментарии

format

Значение свойства

Комментарии

formulas

Значение свойства

Комментарии

formulasLocal

Значение свойства

Комментарии

formulasR1C1

Значение свойства

Комментарии

hasSpill

Значение свойства

Комментарии

height

Значение свойства

Комментарии

hidden

Значение свойства

Комментарии

hyperlink

Значение свойства

Комментарии

Примеры

isEntireColumn

Значение свойства

Комментарии

isEntireRow

Значение свойства

Комментарии

left

Значение свойства

Комментарии

linkedDataTypeState

Значение свойства

Комментарии

numberFormat

Значение свойства

Комментарии

Примеры

numberFormatCategories

Значение свойства

Комментарии

numberFormatLocal

Значение свойства

Комментарии