Excel.WorksheetCollection class

Ссылка

Пакет:: excel

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

Extends: OfficeExtension.ClientObject

Свойства

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

Методы

add(name)	Добавляет новый лист в книгу. Лист будет добавлен после существующих листов. Если вы хотите активировать только что добавленный лист, вызовите `.activate()` его.
getActiveWorksheet()	Получает текущий активный лист в книге.
getCount(visibleOnly)	Получает количество листов в коллекции.
getFirst(visibleOnly)	Получает первый лист в коллекции.
getItem(key)	Получает объект листа по его имени или ИД.
getItemOrNullObject(key)	Получает объект листа по его имени или ИД. Если лист не существует, этот метод возвращает объект со свойством `isNullObjecttrue`. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
getLast(visibleOnly)	Получает последний лист в коллекции.
load(options)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNames)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
load(propertyNamesAndPaths)	Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод `context.sync()`.
toJSON()	Переопределяет метод JavaScript `toJSON()` , чтобы обеспечить более полезные выходные данные при передаче объекта API в `JSON.stringify()`. (`JSON.stringify`в свою очередь вызывает `toJSON` метод переданного ему объекта.) В то время как исходный `Excel.WorksheetCollection` объект является объектом API, `toJSON` метод возвращает обычный объект JavaScript (типизированный как `Excel.Interfaces.WorksheetCollectionData`), содержащий массив "items" с мелкими копиями всех загруженных свойств из элементов коллекции.

События

onActivated	Происходит при активации любого листа в книге.
onAdded	Происходит при добавлении в книгу нового листа.
onCalculated	Происходит при вычислении любого листа в книге.
onChanged	Возникает при изменении любого листа в книге.
onColumnSorted	Возникает при сортировке одного или нескольких столбцов. Происходит в результате операции сортировки слева направо.
onDeactivated	Происходит при отключении любого листа в книге.
onDeleted	Происходит при удалении листа из книги.
onFormatChanged	Происходит при изменении формата любого листа в книге.
onFormulaChanged	Происходит при изменении одной или нескольких формул на любом листе этой коллекции. Это событие происходит при изменении самой формулы, а не значения данных, полученных в результате вычисления формулы.
onMoved	Происходит при перемещении листа внутри книги. Это событие активируется только при непосредственном перемещении листа внутри книги. Это событие не активируется при косвенном изменении положения листа, например при вставке нового листа и изменении позиций существующих листов.
onNameChanged	Происходит при изменении имени листа в коллекции листов.
onProtectionChanged	Происходит при изменении состояния защиты листа.
onRowHiddenChanged	Происходит при изменении скрытого состояния одной или нескольких строк на определенном листе.
onRowSorted	Возникает при сортировке одной или нескольких строк. Происходит в результате операции сортировки сверху вниз.
onSelectionChanged	Возникает при изменениях выделения на любом листе.
onSingleClicked	Происходит при щелчке левой кнопкой мыши или нажатии в коллекции листа. Это событие не будет запущено при щелчке в следующих случаях: - Пользователь перетаскивает мышь для множественного выбора. — Пользователь выбирает ячейку в режиме, когда для ссылок на формулы выбираются аргументы ячеек.
onVisibilityChanged	Происходит при изменении видимости листа в коллекции листов.

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

context

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

context: RequestContext;

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

Excel.RequestContext

items

Получает загруженные дочерние элементы в этой коллекции.

readonly items: Excel.Worksheet[];

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

Excel.Worksheet[]

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

add(name)

Добавляет новый лист в книгу. Лист будет добавлен после существующих листов. Если вы хотите активировать только что добавленный лист, вызовите .activate() его.

add(name?: string): Excel.Worksheet;

Параметры

name: string

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

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

Excel.Worksheet

Примеры

await Excel.run(async (context) => { 
    const wSheetName = 'Sample Name';
    const worksheet = context.workbook.worksheets.add(wSheetName);
    worksheet.load('name');
    await context.sync();
    
    console.log(worksheet.name);
});

getActiveWorksheet()

Получает текущий активный лист в книге.

getActiveWorksheet(): Excel.Worksheet;

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

Excel.Worksheet

Примеры

await Excel.run(async (context) => {  
    const activeWorksheet = context.workbook.worksheets.getActiveWorksheet();
    activeWorksheet.load('name');
    await context.sync();
    console.log(activeWorksheet.name);
});

getCount(visibleOnly)

Получает количество листов в коллекции.

getCount(visibleOnly?: boolean): OfficeExtension.ClientResult<number>;

Параметры

visibleOnly: boolean

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

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

OfficeExtension.ClientResult<number>

getFirst(visibleOnly)

Получает первый лист в коллекции.

getFirst(visibleOnly?: boolean): Excel.Worksheet;

Параметры

visibleOnly: boolean

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

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

Excel.Worksheet

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/reference-worksheets-by-relative-position.yaml

await Excel.run(async (context) => {
    const sheets = context.workbook.worksheets;

    // We don't want to include the default worksheet that was created
    // when the workbook was created, so our "firstSheet" will be the one
    // after the literal first. Note chaining of navigation methods.
    const firstSheet = sheets.getFirst().getNext();
    const lastSheet = sheets.getLast();
    const firstTaxRateRange = firstSheet.getRange("B2");
    const lastTaxRateRange = lastSheet.getRange("B2");

    firstSheet.load("name");
    lastSheet.load("name");
    firstTaxRateRange.load("text");
    lastTaxRateRange.load("text");

    await context.sync();

    let firstYear = firstSheet.name.substr(5, 4);
    let lastYear = lastSheet.name.substr(5, 4);
    console.log(`Tax Rate change from ${firstYear} to ${lastYear}`, `Tax rate for ${firstYear}: ${firstTaxRateRange.text[0][0]}\nTax rate for ${lastYear}: ${lastTaxRateRange.text[0][0]}`)

    await context.sync();
});

getItem(key)

Получает объект листа по его имени или ИД.

getItem(key: string): Excel.Worksheet;

Параметры

key: string

Имя или идентификатор листа.

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

Excel.Worksheet

getItemOrNullObject(key)

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

getItemOrNullObject(key: string): Excel.Worksheet;

Параметры

key: string

Имя или идентификатор листа.

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

Excel.Worksheet

getLast(visibleOnly)

Получает последний лист в коллекции.

getLast(visibleOnly?: boolean): Excel.Worksheet;

Параметры

visibleOnly: boolean

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

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

Excel.Worksheet

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/reference-worksheets-by-relative-position.yaml

await Excel.run(async (context) => {
    const sheets = context.workbook.worksheets;

    // We don't want to include the default worksheet that was created
    // when the workbook was created, so our "firstSheet" will be the one
    // after the literal first. Note chaining of navigation methods.
    const firstSheet = sheets.getFirst().getNext();
    const lastSheet = sheets.getLast();
    const firstTaxRateRange = firstSheet.getRange("B2");
    const lastTaxRateRange = lastSheet.getRange("B2");

    firstSheet.load("name");
    lastSheet.load("name");
    firstTaxRateRange.load("text");
    lastTaxRateRange.load("text");

    await context.sync();

    let firstYear = firstSheet.name.substr(5, 4);
    let lastYear = lastSheet.name.substr(5, 4);
    console.log(`Tax Rate change from ${firstYear} to ${lastYear}`, `Tax rate for ${firstYear}: ${firstTaxRateRange.text[0][0]}\nTax rate for ${lastYear}: ${lastTaxRateRange.text[0][0]}`)

    await context.sync();
});

load(options)

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

load(options?: Excel.Interfaces.WorksheetCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions): Excel.WorksheetCollection;

Параметры

options: Excel.Interfaces.WorksheetCollectionLoadOptions & Excel.Interfaces.CollectionLoadOptions

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

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

Excel.WorksheetCollection

load(propertyNames)

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

Параметры

propertyNames: string | string[]

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

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

Excel.WorksheetCollection

Примеры

await Excel.run(async (context) => { 
    const worksheets = context.workbook.worksheets;
    worksheets.load('items');
    await context.sync();
    
    for (let i = 0; i < worksheets.items.length; i++) {
        console.log(worksheets.items[i].name);
    }
});

load(propertyNamesAndPaths)

load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Excel.WorksheetCollection;

Параметры

propertyNamesAndPaths: OfficeExtension.LoadOption

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

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

Excel.WorksheetCollection

toJSON()

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

toJSON(): Excel.Interfaces.WorksheetCollectionData;

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

Excel.Interfaces.WorksheetCollectionData

Сведения о событии

onActivated

Происходит при активации любого листа в книге.

readonly onActivated: OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetActivatedEventArgs>

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml

await Excel.run(async (context) => {
    let sheets = context.workbook.worksheets;
    sheets.onActivated.add(onActivate);

    await context.sync();
    console.log("A handler has been registered for the OnActivate event.");
});

onAdded

Происходит при добавлении в книгу нового листа.

readonly onAdded: OfficeExtension.EventHandlers<Excel.WorksheetAddedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetAddedEventArgs>

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets;
    sheet.onAdded.add(onWorksheetAdd);

    await context.sync();
    console.log("A handler has been registered for the OnAdded event.");
});

onCalculated

Происходит при вычислении любого листа в книге.

readonly onCalculated: OfficeExtension.EventHandlers<Excel.WorksheetCalculatedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetCalculatedEventArgs>

onChanged

Возникает при изменении любого листа в книге.

readonly onChanged: OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>

onColumnSorted

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

readonly onColumnSorted: OfficeExtension.EventHandlers<Excel.WorksheetColumnSortedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetColumnSortedEventArgs>

onDeactivated

Происходит при отключении любого листа в книге.

readonly onDeactivated: OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/30-events/events-workbook-and-worksheet-collection.yaml

await Excel.run(async (context) => {
    let sheets = context.workbook.worksheets;
    sheets.onDeactivated.add(onDeactivate);

    await context.sync();
    console.log("A handler has been registered for the OnDeactivate event.");
});

onDeleted

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

readonly onDeleted: OfficeExtension.EventHandlers<Excel.WorksheetDeletedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetDeletedEventArgs>

onFormatChanged

Происходит при изменении формата любого листа в книге.

readonly onFormatChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>

onFormulaChanged

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

readonly onFormulaChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormulaChangedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetFormulaChangedEventArgs>

onMoved

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

readonly onMoved: OfficeExtension.EventHandlers<Excel.WorksheetMovedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetMovedEventArgs>

onNameChanged

Происходит при изменении имени листа в коллекции листов.

readonly onNameChanged: OfficeExtension.EventHandlers<Excel.WorksheetNameChangedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetNameChangedEventArgs>

onProtectionChanged

Происходит при изменении состояния защиты листа.

readonly onProtectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetProtectionChangedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetProtectionChangedEventArgs>

onRowHiddenChanged

Происходит при изменении скрытого состояния одной или нескольких строк на определенном листе.

readonly onRowHiddenChanged: OfficeExtension.EventHandlers<Excel.WorksheetRowHiddenChangedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetRowHiddenChangedEventArgs>

onRowSorted

Возникает при сортировке одной или нескольких строк. Происходит в результате операции сортировки сверху вниз.

readonly onRowSorted: OfficeExtension.EventHandlers<Excel.WorksheetRowSortedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetRowSortedEventArgs>

onSelectionChanged

Возникает при изменениях выделения на любом листе.

readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>

onSingleClicked

Происходит при щелчке левой кнопкой мыши или нажатии в коллекции листа. Это событие не будет запущено при щелчке в следующих случаях: - Пользователь перетаскивает мышь для множественного выбора. — Пользователь выбирает ячейку в режиме, когда для ссылок на формулы выбираются аргументы ячеек.

readonly onSingleClicked: OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>

onVisibilityChanged

Происходит при изменении видимости листа в коллекции листов.

readonly onVisibilityChanged: OfficeExtension.EventHandlers<Excel.WorksheetVisibilityChangedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetVisibilityChangedEventArgs>

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

Excel.WorksheetCollection class

Комментарии

Свойства

Методы

События

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

context

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

items

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

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

add(name)

Параметры

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

Комментарии

Примеры

getActiveWorksheet()

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

Комментарии

Примеры

getCount(visibleOnly)

Параметры

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

Комментарии

getFirst(visibleOnly)

Параметры

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

Комментарии

Примеры

getItem(key)

Параметры

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

Комментарии

getItemOrNullObject(key)

Параметры

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

Комментарии

getLast(visibleOnly)

Параметры

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

Комментарии

Примеры

load(options)

Параметры

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

load(propertyNames)

Параметры

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

Примеры

load(propertyNamesAndPaths)

Параметры

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

toJSON()

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

Сведения о событии

onActivated

Тип события

Комментарии

Примеры

onAdded

Тип события

Комментарии

Примеры

onCalculated

Тип события

Комментарии

onChanged

Тип события

Комментарии

onColumnSorted

Тип события

Комментарии

onDeactivated

Тип события

Комментарии

Примеры

onDeleted

Тип события

Комментарии