Excel.Range class

Ссылка

Пакет:: excel

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

Extends: OfficeExtension.ClientObject

Свойства

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. Если в ячейке нет формулы, возвращается ее значение.
hidden	Представляет, скрыты ли все ячейки в текущем диапазоне. Значение — это `true` , когда все ячейки в диапазоне скрыты. Значение — это значение `false` , когда ячейки в диапазоне не скрыты. Значение — это `null` , когда некоторые ячейки в диапазоне скрыты, а другие ячейки в том же диапазоне не скрыты.
hyperlink	Представляет гиперссылку для текущего диапазона.
isEntireColumn	Указывает, является ли текущий диапазон целым столбцом.
isEntireRow	Указывает, является ли текущий диапазон целой строкой.
numberFormat	Представляет код числового формата Excel для заданного диапазона. Дополнительные сведения о форматировании чисел в Excel см. в разделе Коды числового формата.
numberFormatLocal	Представляет код числового формата Excel для заданного диапазона на основе языковых параметров пользователя. Excel не выполняет приведение языка или формата при получении или задании `numberFormatLocal` свойства. Любой возвращаемый текст использует строки в локальном формате на основе языка, указанного в параметрах системы.
rowCount	Возвращает общее количество строк в диапазоне.
rowHidden	Представляет, скрыты ли все строки в текущем диапазоне. Значение — это `true` , когда все строки в диапазоне скрыты. Значение — это значение `false` , когда строки в диапазоне не скрыты. Значением является, `null` когда некоторые строки в диапазоне скрыты, а другие строки в том же диапазоне не скрыты.
rowIndex	Возвращает номер строки первой ячейки диапазона. Используется нулевой индекс.
sort	Представляет порядок сортировки текущего диапазона.
style	Представляет стиль текущего диапазона. Если стили ячеек несогласованны, `null` возвращается. Для пользовательских стилей будет возвращено имя стиля. Для встроенных стилей возвращается строка, представляющая значение в перечислении `BuiltInStyle` .
text	Текстовые значения указанного диапазона. Текстовое значение не зависит от ширины ячейки. Подстановка числового знака (#), выполняемая в пользовательском интерфейсе Excel, не повлияет на текстовое значение, возвращаемое API.
values	Представляет необработанные значения указанного диапазона. Возвращаемые данные могут быть строковыми, числовыми или логическими. Ячейки, содержащие ошибку, вернут строку ошибки. Если возвращаемое значение начинается с плюса ("+"), минуса ("-") или знака равенства ("="), Excel интерпретирует это значение как формулу.
valueTypes	Указывает тип данных в каждой ячейке.
worksheet	Лист, содержащий текущий диапазон.

Методы

calculate()	Вычисляет диапазон ячеек на листе.
clear(applyTo)	Очищает значения, формат, заливку, границу диапазона и т. д.
clear(applyToString)	Очищает значения, формат, заливку, границу диапазона и т. д.
delete(shift)	Удаляет ячейки, связанные с диапазоном.
delete(shiftString)	Удаляет ячейки, связанные с диапазоном.
getAbsoluteResizedRange(numRows, numColumns)	`Range` Возвращает объект с той же левой верхней ячейкой, что и текущий `Range` объект, но с указанным числом строк и столбцов.
getBoundingRect(anotherRange)	Возвращает наименьший объект диапазона, включающий в себя заданные диапазоны. Например, значения `GetBoundingRect` "B2:C5" и "D10:E15" — "B2:E15".
getCell(row, column)	Получает объект диапазона, содержащий одну ячейку, по номеру строки и столбца. Ячейка может находиться за пределами родительского диапазона, если она находится в сетке листа. Возвращаемая ячейка располагается относительно верхней левой ячейки диапазона.
getColumn(column)	Возвращает столбец в диапазоне.
getColumnsAfter(count)	Возвращает определенное количество столбцов справа от текущего `Range` объекта.
getColumnsBefore(count)	Возвращает определенное количество столбцов слева от текущего `Range` объекта.
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)	Возвращает объект, представляющий диапазон, который смещен от указанного диапазона. Измерение возвращаемого диапазона будет соответствовать этому диапазону. Если результирующий диапазон выходит за пределы таблицы листа, возникнет ошибка.
getResizedRange(deltaRows, deltaColumns)	Возвращает объект, аналогичный `Range` текущему `Range` объекту, но с его правым нижним углом, развернутым (или с сокращением) на некоторое количество строк и столбцов.
getRow(row)	Возвращает строку из диапазона.
getRowsAbove(count)	Возвращает определенное количество строк над текущим `Range` объектом .
getRowsBelow(count)	Возвращает определенное количество строк под текущим `Range` объектом .
getSurroundingRegion()	`Range` Возвращает объект , представляющий окружающую область для левой верхней ячейки в этом диапазоне. Это диапазон, ограниченный любым сочетанием пустых строк и столбцов, относящихся к этому диапазону.
getUsedRange(valuesOnly)	Возвращает используемый диапазон заданного объекта диапазона. Если в диапазоне нет используемых ячеек, эта функция вызовет ошибку `ItemNotFound` .
getUsedRangeOrNullObject(valuesOnly)	Возвращает используемый диапазон заданного объекта диапазона. Если в диапазоне нет используемых ячеек, этот метод возвращает объект со свойством `isNullObjecttrue`. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
getVisibleView()	Представляет видимые строки текущего диапазона.
insert(shift)	Вставляет ячейку или диапазон ячеек на лист вместо этого диапазона, а также сдвигает другие ячейки, чтобы освободить место. Возвращает новый `Range` объект в пустом пространстве.
insert(shiftString)	Вставляет ячейку или диапазон ячеек на лист вместо этого диапазона, а также сдвигает другие ячейки, чтобы освободить место. Возвращает новый `Range` объект в пустом пространстве.
load(options)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNames)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNamesAndPaths)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
merge(across)	Объединяет ячейки диапазона в одну область на листе.
select()	Выбирает указанный диапазон в пользовательском интерфейсе Excel.
set(properties, options)	Задает несколько свойств объекта одновременно. Можно передать обычный объект с соответствующими свойствами или другой объект API того же типа.
set(properties)	Задает несколько свойств объекта одновременно на основе существующего загруженного объекта.
showCard()	Отображает карточку для активной ячейки, если она имеет содержимое c форматированным значением.
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 при задании свойства или вызове метода для объекта, необходимо добавить объект в отслеживаемую коллекцию объектов при первом создании объекта.
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[][]

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

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

numberFormatLocal

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

numberFormatLocal: any[][];

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

any[][]

rowCount

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

readonly rowCount: number;

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

number

rowHidden

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

rowHidden: boolean;

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

boolean

rowIndex

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

readonly rowIndex: number;

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

number

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

values

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

values: any[][];

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

any[][]

valueTypes

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

readonly valueTypes: Excel.RangeValueType[][];

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

Excel.RangeValueType[][]

worksheet

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

readonly worksheet: Excel.Worksheet;

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

Excel.Worksheet

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

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

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

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

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

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

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

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

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

getSurroundingRegion()

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

getSurroundingRegion(): Excel.Range;

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

Excel.Range

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

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

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

showCard()

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

showCard(): void;

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

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

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

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

Комментарии

hidden

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

Комментарии

hyperlink

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

Комментарии

Примеры

isEntireColumn

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

Комментарии

isEntireRow

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

Комментарии

numberFormat

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

Комментарии

Примеры

numberFormatLocal

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

Комментарии

rowCount

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

Комментарии

rowHidden

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

Комментарии

rowIndex

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

Комментарии

sort

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

Комментарии

Примеры

style

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

Комментарии

Примеры