Excel.Worksheet interface

Лист Excel представляет собой сетку ячеек. Она может содержать данные, таблицы, диаграммы и т. д. Чтобы узнать больше об объектной модели листа, прочтите Работа с листами с помощью API JavaScript для Excel.

Свойства

autoFilter

Представляет объект AutoFilter листа.

charts

Возвращает коллекцию диаграмм, которые являются частью листа.

comments

Возвращает коллекцию всех объектов Comments на листе.

enableCalculation

Определяет, должен ли Excel пересчитывать лист при необходимости. Имеет значение true, если Excel пересчитывает лист при необходимости. False, если Excel не пересчитывает лист.

freezePanes

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

horizontalPageBreaks

Получает коллекцию горизонтальных разрывов страницы для листа. Эта коллекция содержит только добавленные вручную разрывы страниц.

id

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

name

Отображаемое имя листа.

names

Коллекция имен, относящих к текущему листу.

pageLayout

Получает объект PageLayout листа.

pivotTables

Коллекция сводных таблиц на листе.

position

Положение листа (начиная с нуля) в книге.

protection

Возвращает объект защиты листа.

shapes

Возвращает коллекцию всех объектов Shape на листе.

showGridlines

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

showHeadings

Указывает, видимы ли заголовки для пользователя.

slicers

Возвращает коллекцию срезов, которые входят в состав рабочего листа.

standardHeight

Возвращает стандартную (по умолчанию) высоту всех строк на листе (в пунктах).

standardWidth

Задает стандартную (по умолчанию) ширину всех столбцов в рабочем листе. Одна единица измерения ширины столбца равна ширине одного символа в стиле Normal. Для пропорциональных шрифтов используется ширина знака 0 (ноль).

tabColor

Цвет вкладки листа. При получении цвета вкладки, если лист невидим, значение будет равно null. Если лист является видимым, но для цвета вкладки задано значение Авто, возвращается пустая строка. В противном случае для свойства задается цвет, в виде " # 123456" при задании цвета используйте пустую строку для установки "Авто" или "реальный цвет" в противном случае.

tables

Коллекция таблиц, имеющихся на листе.

verticalPageBreaks

Получает коллекцию вертикальных разрывов страницы для листа. Эта коллекция содержит только добавленные вручную разрывы страниц.

visibility

Видимость листа.

Методы

activate()

Активация листа в пользовательском интерфейсе Excel.

calculate(markAllDirty)

Вычисляет все ячейки на листе.

copy(positionType, relativeTo)

Копирует лист и размещает его в указанной позиции.

delete()

Удаляет лист из книги. Обратите внимание, что если для отображения листа задано значение "Верихидден", операция удаления завершится с InvalidOperation исключением. Прежде чем удалять его, необходимо сначала изменить его видимость на скрытую или видимую.

findAll(text, criteria)

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

findAllOrNullObject(text, criteria)

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

getCell(row, column)

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

getNext(visibleOnly)

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

getNextOrNullObject(visibleOnly)

Получает лист, следующий по отношению к элементу. Если после этого листа нет ни одного листа, этот метод возвратит нулевой объект.

getPrevious(visibleOnly)

Получает лист, который предшествует этому. Если нет предыдущих листов, этот метод выдаст ошибку.

getPreviousOrNullObject(visibleOnly)

Получает лист, который предшествует этому. Если нет предыдущих листов, этот метод возвратит значение NULL обжет.

getRange(address)

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

getRangeByIndexes(startRow, startColumn, rowCount, columnCount)

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

getRanges(address)

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

getUsedRange(valuesOnly)

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

getUsedRangeOrNullObject(valuesOnly)

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

load(propertyNames)

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

replaceAll(text, replacement, criteria)

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

showOutlineLevels(rowLevels, columnLevels)

Отображает группы строк или столбцов по их уровням структуры. Группирование и суммирование списка данных на листе. rowLevelsПараметры и columnLevels определяют, сколько уровней структуры будет отображаться. Допустимый диапазон аргументов находится в пределах от 0 до 8. Значение 0 не изменяет текущее отображение. Значение, превышающее текущее число уровней, отображает все уровни.

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

autoFilter

Представляет объект AutoFilter листа.

readonly autoFilter: AutoFilter;

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

Примеры

async function main(context: Excel.RequestContext) {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let farmData = sheet.getUsedRange();

    // This filter will only show the rows with the top 25% of values in column 3.
    sheet.autoFilter.apply(farmData, 3, { criterion1: "25", filterOn: Excel.FilterOn.topPercent });
    await context.sync();
}

charts

Возвращает коллекцию диаграмм, которые являются частью листа.

readonly charts: ChartCollection;

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

comments

Возвращает коллекцию всех объектов Comments на листе.

readonly comments: CommentCollection;

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

enableCalculation

Определяет, должен ли Excel пересчитывать лист при необходимости. Имеет значение true, если Excel пересчитывает лист при необходимости. False, если Excel не пересчитывает лист.

enableCalculation: boolean;

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

boolean

freezePanes

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

readonly freezePanes: WorksheetFreezePanes;

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

horizontalPageBreaks

Получает коллекцию горизонтальных разрывов страницы для листа. Эта коллекция содержит только добавленные вручную разрывы страниц.

readonly horizontalPageBreaks: PageBreakCollection;

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

id

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

readonly id: string;

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

string

name

Отображаемое имя листа.

name: string;

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

string

names

Коллекция имен, относящих к текущему листу.

readonly names: NamedItemCollection;

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

pageLayout

Получает объект PageLayout листа.

readonly pageLayout: PageLayout;

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

pivotTables

Коллекция сводных таблиц на листе.

readonly pivotTables: PivotTableCollection;

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

position

Положение листа (начиная с нуля) в книге.

position: number;

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

number

protection

Возвращает объект защиты листа.

readonly protection: WorksheetProtection;

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

shapes

Возвращает коллекцию всех объектов Shape на листе.

readonly shapes: ShapeCollection;

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

showGridlines

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

showGridlines: boolean;

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

boolean

Примеры

async function main(context: Excel.RequestContext) {
    let sheet = context.workbook.worksheets.getActiveWorksheet();
    sheet.showGridlines = true;

    await context.sync();
}

showHeadings

Указывает, видимы ли заголовки для пользователя.

showHeadings: boolean;

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

boolean

slicers

Возвращает коллекцию срезов, которые входят в состав рабочего листа.

readonly slicers: SlicerCollection;

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

Примеры

async function main(context: Excel.RequestContext) {
    let sheet = context.workbook.worksheets.getItem("Pivot");
    let slicer = sheet.slicers.add(
        "Farm Sales", /* The slicer data source. For PivotTables, this can be the PivotTable object reference or name. */
        "Type" /* The field in the data source to filter by. For PivotTables, this can be a PivotField object reference or ID. */
    );
    slicer.name = "Fruit Slicer";
    await context.sync();
}

standardHeight

Возвращает стандартную (по умолчанию) высоту всех строк на листе (в пунктах).

readonly standardHeight: number;

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

number

standardWidth

Задает стандартную (по умолчанию) ширину всех столбцов в рабочем листе. Одна единица измерения ширины столбца равна ширине одного символа в стиле Normal. Для пропорциональных шрифтов используется ширина знака 0 (ноль).

standardWidth: number;

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

number

tabColor

Цвет вкладки листа. При получении цвета вкладки, если лист невидим, значение будет равно null. Если лист является видимым, но для цвета вкладки задано значение Авто, возвращается пустая строка. В противном случае для свойства задается цвет, в виде " # 123456" при задании цвета используйте пустую строку для установки "Авто" или "реальный цвет" в противном случае.

tabColor: string;

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

string

Примеры

async function main(context: Excel.RequestContext) {
    let activeSheet = context.workbook.worksheets.getActiveWorksheet();
    activeSheet.tabColor = "#FF0000";

    await context.sync();
}

tables

Коллекция таблиц, имеющихся на листе.

readonly tables: TableCollection;

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

verticalPageBreaks

Получает коллекцию вертикальных разрывов страницы для листа. Эта коллекция содержит только добавленные вручную разрывы страниц.

readonly verticalPageBreaks: PageBreakCollection;

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

visibility

Видимость листа.

visibility: SheetVisibility | "Visible" | "Hidden" | "VeryHidden";

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

SheetVisibility | "Visible" | "Hidden" | "VeryHidden"

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

activate()

Активация листа в пользовательском интерфейсе Excel.

activate(): void;

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

void

calculate(markAllDirty)

Вычисляет все ячейки на листе.

calculate(markAllDirty: boolean): void;

Параметры

markAllDirty
boolean

Значение true, чтобы пометить все как "грязный".

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

void

copy(positionType, relativeTo)

Копирует лист и размещает его в указанной позиции.

copy(
            positionType?:
                | WorksheetPositionType
                | "None"
                | "Before"
                | "After"
                | "Beginning"
                | "End",
            relativeTo?: Worksheet
        ): Worksheet;

Параметры

positionType
| WorksheetPositionType | "None" | "Before" | "After" | "Beginning" | "End"

Расположение в книге, в которое будет помещен созданный лист. Значение по умолчанию — "None", которое вставляет лист в начало листа.

relativeTo
Worksheet

Существующий лист, который определяет положение вновь созданного листа. Это необходимо, только если positionType это "до" или "после".

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

Примеры

async function main(context: Excel.RequestContext) {
    let myWorkbook = context.workbook;
    let sampleSheet = myWorkbook.worksheets.getActiveWorksheet();
    let copiedSheet = sampleSheet.copy("End")

    sampleSheet.load("name");
    copiedSheet.load("name");

    await context.sync();

    console.log("'" + sampleSheet.name + "' was copied to '" + copiedSheet.name + "'")
}

delete()

Удаляет лист из книги. Обратите внимание, что если для отображения листа задано значение "Верихидден", операция удаления завершится с InvalidOperation исключением. Прежде чем удалять его, необходимо сначала изменить его видимость на скрытую или видимую.

delete(): void;

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

void

findAll(text, criteria)

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

findAll(text: string, criteria: WorksheetSearchCriteria): RangeAreas;

Параметры

text
string

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

criteria
WorksheetSearchCriteria

Дополнительные условия поиска, в том числе поиск соответствия требованиям к ячейкам целиком или с учетом регистра.

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

findAllOrNullObject(text, criteria)

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

findAllOrNullObject(
            text: string,
            criteria: WorksheetSearchCriteria
        ): RangeAreas;

Параметры

text
string

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

criteria
WorksheetSearchCriteria

Дополнительные условия поиска, в том числе поиск соответствия требованиям к ячейкам целиком или с учетом регистра.

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

Примеры

async function main(context: Excel.RequestContext) {
    let sheet = context.workbook.worksheets.getItem("Sample");
    let foundRanges = sheet.findAllOrNullObject("Complete", {
        completeMatch: true,
        matchCase: false
    });

    await context.sync();

    if (foundRanges.isNullObject) {
        console.log("No complete projects");
    } else {
        foundRanges.format.fill.color = "green"
    }
}

getCell(row, column)

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

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

Параметры

row
number

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

column
number

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

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

getNext(visibleOnly)

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

getNext(visibleOnly?: boolean): Worksheet;

Параметры

visibleOnly
boolean

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

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

getNextOrNullObject(visibleOnly)

Получает лист, следующий по отношению к элементу. Если после этого листа нет ни одного листа, этот метод возвратит нулевой объект.

getNextOrNullObject(visibleOnly?: boolean): Worksheet;

Параметры

visibleOnly
boolean

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

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

getPrevious(visibleOnly)

Получает лист, который предшествует этому. Если нет предыдущих листов, этот метод выдаст ошибку.

getPrevious(visibleOnly?: boolean): Worksheet;

Параметры

visibleOnly
boolean

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

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

getPreviousOrNullObject(visibleOnly)

Получает лист, который предшествует этому. Если нет предыдущих листов, этот метод возвратит значение NULL обжет.

getPreviousOrNullObject(visibleOnly?: boolean): Worksheet;

Параметры

visibleOnly
boolean

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

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

getRange(address)

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

getRange(address?: string): Range;

Параметры

address
string

Необязательный параметр. Строка, представляющая адрес или имя диапазона. Например, "a1: B2". Если аргумент не указан, возвращается весь диапазон листа.

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

getRangeByIndexes(startRow, startColumn, rowCount, columnCount)

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

getRangeByIndexes(
            startRow: number,
            startColumn: number,
            rowCount: number,
            columnCount: number
        ): Range;

Параметры

startRow
number

Строка начала (с нулевым индексированием).

startColumn
number

Столбец "начало" (с нулевым индексом).

rowCount
number

Количество строк, включаемых в диапазон.

columnCount
number

Число столбцов, включаемых в диапазон.

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

getRanges(address)

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

getRanges(address?: string): RangeAreas;

Параметры

address
string

Необязательный параметр. Строка, содержащая разделенные запятыми адреса или имена отдельных диапазонов. Например, "a1: B2, A5: B5". Если этот параметр не указан, возвращается объект Ранжеареа для всего листа.

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

Примеры

async function main(context: Excel.RequestContext) {

    let sheet = context.workbook.worksheets.getActiveWorksheet();
    let specifiedRanges = sheet.getRanges("D3:D5, G3:G5");
    specifiedRanges.format.fill.color = "pink";

    await context.sync();
})

getUsedRange(valuesOnly)

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

getUsedRange(valuesOnly?: boolean): Range;

Параметры

valuesOnly
boolean

Необязательный параметр. Если этот параметр имеет значение true, учитываются только ячейки со значениями в качестве используемых ячеек (игнорируя форматирование).

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

getUsedRangeOrNullObject(valuesOnly)

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

getUsedRangeOrNullObject(valuesOnly?: boolean): Range;

Параметры

valuesOnly
boolean

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

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

load(propertyNames)

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

load(propertyNames?: string | string[]): void;

Параметры

propertyNames
string | string[]

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

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

void

replaceAll(text, replacement, criteria)

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

replaceAll(
            text: string,
            replacement: string,
            criteria: ReplaceCriteria
        ): ClientResult<number>;

Параметры

text
string

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

replacement
string

Строка для замены оригинала на.

criteria
ReplaceCriteria

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

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

ClientResult<number>

showOutlineLevels(rowLevels, columnLevels)

Отображает группы строк или столбцов по их уровням структуры. Группирование и суммирование списка данных на листе. rowLevelsПараметры и columnLevels определяют, сколько уровней структуры будет отображаться. Допустимый диапазон аргументов находится в пределах от 0 до 8. Значение 0 не изменяет текущее отображение. Значение, превышающее текущее число уровней, отображает все уровни.

showOutlineLevels(rowLevels: number, columnLevels: number): void;

Параметры

rowLevels
number

Количество отображаемых уровней строк в структуре.

columnLevels
number

Число уровней столбцов структуры для отображения.

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

void

Примеры

Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();

    // This collapses the entire outline.
    sheet.showOutlineLevels(1, 1);
    await context.sync();
}
Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getActiveWorksheet();

    // This shows the top 3 outline levels; collapsing any additional sublevels.
    sheet.showOutlineLevels(3, 3);
    await context.sync();
}