Excel.WorksheetCollection class
Представляет коллекцию объектов листа, включенных в книгу.
- Extends
Свойства
| context | Контекст запроса, связанный с объектом. Это соединяет процесс надстройки с процессом основного приложения Office. |
| items | Получает загруженные дочерние элементы в этой коллекции. |
Методы
| add(name) | Добавляет новый лист в книгу. Лист будет добавлен после существующих листов. Если вы хотите активировать только что добавленный лист, вызовите |
| add |
Вставляет указанные листы книги в текущую книгу.
Примечание. В настоящее время этот API поддерживается только для Office на компьютерах с Windows и Mac. И это устарело, используйте |
| add |
Вставляет указанные листы книги в текущую книгу.
Примечание. В настоящее время этот API поддерживается только для Office на компьютерах с Windows и Mac. И это устарело, используйте |
| get |
Получает текущий активный лист в книге. |
| get |
Получает количество листов в коллекции. |
| get |
Получает первый лист в коллекции. |
| get |
Получает объект листа по его имени или ИД. |
| get |
Получает объект листа по его имени или ИД. Если листа не существует, этот метод возвращает объект со свойством |
| get |
Получает последний лист в коллекции. |
| load(options) | Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод |
| load(property |
Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод |
| load(property |
Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод |
| toJSON() | Переопределяет метод JavaScript |
События
| on |
Возникает при активации любого листа в книге. |
| on |
Возникает при добавлении в книгу нового листа. |
| on |
Возникает при пересчете любого листа в книге. |
| on |
Возникают, когда ячейки на листе вычисляются асинхронно. Это событие запускается в конце цикла вычислений, аналогично Функции формул, такие как функции JavaScript User-Defined и формулы =PY, могут вызывать это событие. |
| on |
Возникает при изменении любого листа в книге. |
| on |
Возникает при сортировке одного или нескольких столбцов. Происходит в результате операции сортировки слева направо. |
| on |
Возникает при деактивации любого листа в книге. |
| on |
Возникает при удалении листа из книги. |
| on |
Возникает при применении любого фильтра листа в книге. |
| on |
Возникают, когда формат какого-либо листа в книге изменен. |
| on |
Возникает при изменении одной или нескольких формул на любом листе этой коллекции. Это событие сообщает об изменении самой формулы, а не значения данных, полученного в результате вычисления формулы. |
| on |
Возникает при перемещении листа в книге. Это событие запускается только при непосредственном перемещении листа в книге. Это событие не срабатывает, если положение листа косвенно изменяется, например при вставке нового листа, что приводит к изменению положения существующих листов. |
| on |
Возникает при изменении имени листа в коллекции листов. |
| on |
Возникает при изменении состояния защиты листа. |
| on |
Возникают, когда на листе изменилось скрытое состояние одной или нескольких строк. |
| on |
Возникает при сортировке одной или нескольких строк. Происходит в результате операции сортировки сверху вниз. |
| on |
Возникает при изменениях выделения на любом листе. |
| on |
Возникает при выполнении операции щелчка левой кнопкой мыши или касания в коллекции листов. Это событие не будет срабатывать при нажатии в следующих случаях: - Пользователь перетаскивает мышь для множественного выбора. - Пользователь выбирает ячейку в режиме, когда для ссылок на формулы выбираются аргументы ячейки. |
| on |
Возникает при изменении видимости листа в коллекции листов. |
Сведения о свойстве
context
Контекст запроса, связанный с объектом. Это соединяет процесс надстройки с процессом основного приложения Office.
context: RequestContext;Значение свойства
items
Получает загруженные дочерние элементы в этой коллекции.
readonly items: Excel.Worksheet[];Значение свойства
Сведения о методе
add(name)
Добавляет новый лист в книгу. Лист будет добавлен после существующих листов. Если вы хотите активировать только что добавленный лист, вызовите .activate() его.
add(name?: string): Excel.Worksheet;Параметры
- name
-
string
Необязательный параметр. Имя добавляемого листа. Если указано имя, оно должно быть уникальным. В противном случае Excel определяет имя нового листа.
Возвращаемое значение
Комментарии
Примеры
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[]>
Массив идентификаторов, соответствующих каждому вставленному листу.
Комментарии
addFromBase64(base64File, sheetNamesToInsert, positionType, relativeTo)
Примечание
Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.
Вставляет указанные листы книги в текущую книгу.
Примечание. В настоящее время этот API поддерживается только для Office на компьютерах с Windows и Mac. И это устарело, используйте Workbook.insertWorksheetFromBase64 вместо него.
addFromBase64(base64File: string, sheetNamesToInsert?: string[], positionType?: "None" | "Before" | "After" | "Beginning" | "End", relativeTo?: Worksheet | string): OfficeExtension.ClientResult<string[]>;Параметры
- base64File
-
string
Обязательно. Строка в кодировке Base64, представляющая исходный файл книги.
- sheetNamesToInsert
-
string[]
Необязательный параметр. Имена отдельных листов для вставки. По умолчанию вставляются все листы исходной книги.
- positionType
-
"None" | "Before" | "After" | "Beginning" | "End"
Необязательный параметр. Место в текущей книге, в которое вставляются новые листы. См. Excel.WorksheetPositionType дополнительные сведения. По умолчанию используется меню "Пуск".
- relativeTo
-
Excel.Worksheet | string
Необязательный параметр. Лист в текущей книге, на который ссылается параметр positionType . Значение по умолчанию — null и в зависимости positionTypeот , вставляет листы в начало или конец текущей книги.
Возвращаемое значение
OfficeExtension.ClientResult<string[]>
Массив идентификаторов, соответствующих каждому вставленному листу.
Комментарии
getActiveWorksheet()
Получает текущий активный лист в книге.
getActiveWorksheet(): 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, рассматриваются только видимые листы, пропуская скрытые.
Возвращаемое значение
Комментарии
Примеры
// 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
Имя или идентификатор листа.
Возвращаемое значение
Комментарии
getItemOrNullObject(key)
Получает объект листа по его имени или ИД. Если листа не существует, этот метод возвращает объект со свойством isNullObjecttrue. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
getItemOrNullObject(key: string): Excel.Worksheet;Параметры
- key
-
string
Имя или идентификатор листа.
Возвращаемое значение
Комментарии
getLast(visibleOnly)
Получает последний лист в коллекции.
getLast(visibleOnly?: boolean): Excel.Worksheet;Параметры
- visibleOnly
-
boolean
Необязательный параметр. Если true, рассматриваются только видимые листы, пропуская скрытые.
Возвращаемое значение
Комментарии
Примеры
// 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;Параметры
Предоставляет параметры для загружаемых свойств объекта.
Возвращаемое значение
load(propertyNames)
Добавляет в очередь команду для загрузки указанных свойств объекта. Перед чтением свойств требуется вызвать метод context.sync().
load(propertyNames?: string | string[]): Excel.WorksheetCollection;Параметры
- propertyNames
-
string | string[]
Строка с разделителями-запятыми или массив строк, которые определяют свойства для загрузки.
Возвращаемое значение
Примеры
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 через запятую, указывающая свойства навигации для загрузки.
Возвращаемое значение
toJSON()
Переопределяет метод JavaScript toJSON() , чтобы обеспечить более полезные выходные данные при передаче объекта API в JSON.stringify(). (JSON.stringify, в свою очередь, вызывает toJSON метод переданного ему объекта.) В то время как исходный Excel.WorksheetCollection объект является объектом API, toJSON метод возвращает простой объект JavaScript (типизированный как Excel.Interfaces.WorksheetCollectionData), который содержит массив «items» с неглубокими копиями любых загруженных свойств из элементов коллекции.
toJSON(): Excel.Interfaces.WorksheetCollectionData;Возвращаемое значение
Сведения о событии
onActivated
Возникает при активации любого листа в книге.
readonly onActivated: 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>;Тип события
Комментарии
Примеры
// 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>;Тип события
Комментарии
onCalculationBusy
Примечание
Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.
Возникают, когда ячейки на листе вычисляются асинхронно.
Это событие запускается в конце цикла вычислений, аналогично onCalculated самому событию. Обычно, когда завершается вычисление для ячейки, onCalculated запускается событие. Однако если при вычислении в ячейке помещается временное ожидающее значение (например, "#BUSY!"), оно запускается, чтобы показать, onCalculationBusy что состояние ячейки изменилось, хотя вычисление окончательного значения еще не завершено. Когда последующий цикл вычислений завершает вычисление этой ячейки onCalculated , запускается событие.
Функции формул, такие как функции JavaScript User-Defined и формулы =PY, могут вызывать это событие.
readonly onCalculationBusy: OfficeExtension.EventHandlers<Excel.WorksheetCalculationBusyEventArgs>;Тип события
Комментарии
onChanged
Возникает при изменении любого листа в книге.
readonly onChanged: OfficeExtension.EventHandlers<Excel.WorksheetChangedEventArgs>;Тип события
Комментарии
onColumnSorted
Возникает при сортировке одного или нескольких столбцов. Происходит в результате операции сортировки слева направо.
readonly onColumnSorted: OfficeExtension.EventHandlers<Excel.WorksheetColumnSortedEventArgs>;Тип события
Комментарии
onDeactivated
Возникает при деактивации любого листа в книге.
readonly onDeactivated: 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>;Тип события
Комментарии
onFiltered
Примечание
Этот API предоставляется в качестве предварительной версии для разработчиков и может быть изменен на основе полученных нами отзывов. Не используйте этот API в рабочей среде.
Возникает при применении любого фильтра листа в книге.
readonly onFiltered: OfficeExtension.EventHandlers<Excel.WorksheetFilteredEventArgs>;Тип события
Комментарии
onFormatChanged
Возникают, когда формат какого-либо листа в книге изменен.
readonly onFormatChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormatChangedEventArgs>;Тип события
Комментарии
onFormulaChanged
Возникает при изменении одной или нескольких формул на любом листе этой коллекции. Это событие сообщает об изменении самой формулы, а не значения данных, полученного в результате вычисления формулы.
readonly onFormulaChanged: OfficeExtension.EventHandlers<Excel.WorksheetFormulaChangedEventArgs>;Тип события
Комментарии
onMoved
Возникает при перемещении листа в книге. Это событие запускается только при непосредственном перемещении листа в книге. Это событие не срабатывает, если положение листа косвенно изменяется, например при вставке нового листа, что приводит к изменению положения существующих листов.
readonly onMoved: OfficeExtension.EventHandlers<Excel.WorksheetMovedEventArgs>;Тип события
Комментарии
onNameChanged
Возникает при изменении имени листа в коллекции листов.
readonly onNameChanged: OfficeExtension.EventHandlers<Excel.WorksheetNameChangedEventArgs>;Тип события
Комментарии
onProtectionChanged
Возникает при изменении состояния защиты листа.
readonly onProtectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetProtectionChangedEventArgs>;Тип события
Комментарии
onRowHiddenChanged
Возникают, когда на листе изменилось скрытое состояние одной или нескольких строк.
readonly onRowHiddenChanged: OfficeExtension.EventHandlers<Excel.WorksheetRowHiddenChangedEventArgs>;Тип события
Комментарии
onRowSorted
Возникает при сортировке одной или нескольких строк. Происходит в результате операции сортировки сверху вниз.
readonly onRowSorted: OfficeExtension.EventHandlers<Excel.WorksheetRowSortedEventArgs>;Тип события
Комментарии
onSelectionChanged
Возникает при изменениях выделения на любом листе.
readonly onSelectionChanged: OfficeExtension.EventHandlers<Excel.WorksheetSelectionChangedEventArgs>;Тип события
Комментарии
onSingleClicked
Возникает при выполнении операции щелчка левой кнопкой мыши или касания в коллекции листов. Это событие не будет срабатывать при нажатии в следующих случаях: - Пользователь перетаскивает мышь для множественного выбора. - Пользователь выбирает ячейку в режиме, когда для ссылок на формулы выбираются аргументы ячейки.
readonly onSingleClicked: OfficeExtension.EventHandlers<Excel.WorksheetSingleClickedEventArgs>;Тип события
Комментарии
onVisibilityChanged
Возникает при изменении видимости листа в коллекции листов.
readonly onVisibilityChanged: OfficeExtension.EventHandlers<Excel.WorksheetVisibilityChangedEventArgs>;