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

Excel.WorksheetCollection class

  • Ссылка
Пакет:
excel

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

Extends
OfficeExtension.ClientObject

Комментарии

[ Набор API: ExcelApi 1.1 ]

Свойства

context

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

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

Методы

add(name)

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

Вставляет указанные листы книги в текущую книгу.

Примечание*. В настоящее время этот API поддерживается только для Office в Windows и Mac. И он был не рекомендуется, пожалуйста, используйте Workbook.insertWorksheetFromBase64 вместо этого.
addFromBase64(base64File, sheetNamesToInsert, positionTypeString, relativeTo)

Вставляет указанные листы книги в текущую книгу.

Примечание*. В настоящее время этот API поддерживается только для Office в Windows и Mac. И он был не рекомендуется, пожалуйста, используйте Workbook.insertWorksheetFromBase64 вместо этого.
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

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

Возникает при применении любого фильтра листа в книге.
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

Комментарии

[ Набор API: ExcelApi 1.1 ]

Примеры

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

addFromBase64(base64File, sheetNamesToInsert, positionType, relativeTo)

Примечание

Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.

Вставляет указанные листы книги в текущую книгу.

Примечание*. В настоящее время этот API поддерживается только для Office в Windows и Mac. И он был не рекомендуется, пожалуйста, используйте Workbook.insertWorksheetFromBase64 вместо этого.

addFromBase64(base64File: string, sheetNamesToInsert?: string[], positionType?: Excel.WorksheetPositionType, relativeTo?: Worksheet | string): OfficeExtension.ClientResult<string[]>;

Параметры

base64File

string

Обязательно. Строка в кодировке Base64, представляющая файл исходной книги.

sheetNamesToInsert

string[]

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

positionType
Excel.WorksheetPositionType

Необязательный параметр. В текущую книгу будут вставлены новые листы. Дополнительные сведения см. в этой Excel.WorksheetPositionType статье. Значение по умолчанию — "Пуск".

relativeTo

Excel.Worksheet | string

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

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

OfficeExtension.ClientResult<string[]>

Массив идентификаторов, соответствующих каждому вновь вставленному листу.

Комментарии

[ Набор API: ExcelApi BETA (ТОЛЬКО ПРЕДВАРИТЕЛЬНАЯ ВЕРСИЯ) ]

addFromBase64(base64File, sheetNamesToInsert, positionTypeString, relativeTo)

Примечание

Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.

Вставляет указанные листы книги в текущую книгу.

Примечание*. В настоящее время этот API поддерживается только для Office в Windows и Mac. И он был не рекомендуется, пожалуйста, используйте Workbook.insertWorksheetFromBase64 вместо этого.

addFromBase64(base64File: string, sheetNamesToInsert?: string[], positionTypeString?: "None" | "Before" | "After" | "Beginning" | "End", relativeTo?: Worksheet | string): OfficeExtension.ClientResult<string[]>;

Параметры

base64File

string

Обязательно. Строка в кодировке Base64, представляющая файл исходной книги.

sheetNamesToInsert

string[]

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

positionTypeString

"None" | "Before" | "After" | "Beginning" | "End"

Необязательный параметр. В текущую книгу будут вставлены новые листы. Дополнительные сведения см. в этой Excel.WorksheetPositionType статье. Значение по умолчанию — "Пуск".

relativeTo

Excel.Worksheet | string

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

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

OfficeExtension.ClientResult<string[]>

Массив идентификаторов, соответствующих каждому вновь вставленному листу.

Комментарии

[ Набор API: ExcelApi BETA (ТОЛЬКО ПРЕДВАРИТЕЛЬНАЯ ВЕРСИЯ) ]

getActiveWorksheet()

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

getActiveWorksheet(): Excel.Worksheet;

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

Excel.Worksheet

Комментарии

[ Набор API: ExcelApi 1.1 ]

Примеры

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>

Комментарии

[ Набор API: ExcelApi 1.4 ]

getFirst(visibleOnly)

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

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

Параметры

visibleOnly

boolean

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

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

Excel.Worksheet

Комментарии

[ Набор API: ExcelApi 1.5 ]

Примеры

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

Комментарии

[ Набор API: ExcelApi 1.1 ]

getItemOrNullObject(key)

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

getItemOrNullObject(key: string): Excel.Worksheet;

Параметры

key

string

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

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

Excel.Worksheet

Комментарии

[ Набор API: ExcelApi 1.4 ]

getLast(visibleOnly)

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

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

Параметры

visibleOnly

boolean

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

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

Excel.Worksheet

Комментарии

[ Набор API: ExcelApi 1.5 ]

Примеры

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

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

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)

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

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>

Комментарии

[ Набор API: ExcelApi 1.7 ]

Примеры

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

Комментарии

[ Набор API: ExcelApi 1.7 ]

Примеры

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

Комментарии

[ Набор API: ExcelApi 1.8 ]

onChanged

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.9 ]

onColumnSorted

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetColumnSortedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.10 ]

onDeactivated

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetDeactivatedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.7 ]

Примеры

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

Комментарии

[ Набор API: ExcelApi 1.7 ]

onFiltered

Примечание

Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.

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

readonly onFiltered: OfficeExtension.EventHandlers<Excel.WorksheetFilteredEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetFilteredEventArgs>

Комментарии

[ Набор API: ExcelApi BETA (ТОЛЬКО ПРЕДВАРИТЕЛЬНАЯ ВЕРСИЯ) ]

onFormatChanged

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.9 ]

onFormulaChanged

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetFormulaChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.13 ]

onMoved

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetMovedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.17 ]

onNameChanged

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetNameChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.17 ]

onProtectionChanged

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetProtectionChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.14 ]

onRowHiddenChanged

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetRowHiddenChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.11 ]

onRowSorted

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetRowSortedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.10 ]

onSelectionChanged

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.9 ]

onSingleClicked

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.10 ]

onVisibilityChanged

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

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

Тип события

OfficeExtension.EventHandlers<Excel.WorksheetVisibilityChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.17 ]