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
Имя или идентификатор листа.
Возвращаемое значение
Комментарии
Примеры
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-axis-formatting.yaml
function displayUnit(context: Excel.RequestContext) {
let sheet = context.workbook.worksheets.getItem("Sample");
let chart = sheet.charts.getItem("SalesChart");
let axis = chart.axes.valueAxis;
axis.displayUnit = "Thousands";
}
getItemOrNullObject(key)
Получает объект листа по его имени или ИД. Если листа не существует, этот метод возвращает объект со свойством isNullObjecttrue. Дополнительные сведения см. в разделе Методы и свойства *OrNullObject.
getItemOrNullObject(key: string): Excel.Worksheet;Параметры
- key
-
string
Имя или идентификатор листа.
Возвращаемое значение
Комментарии
Примеры
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/90-scenarios/performance-optimization.yaml
/** Helper to create or recreate a worksheet. */
async function forceCreateSheet(workbook: Excel.Workbook, sheetName: string): Promise<Excel.Worksheet> {
workbook.worksheets.getItemOrNullObject(sheetName).delete();
await workbook.context.sync();
return workbook.worksheets.add(sheetName);
}
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>;Тип события
Комментарии
Примеры
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/54-worksheet/worksheet-visibility.yaml
await Excel.run(async (context) => {
// Register an event handler for visibility changes to any worksheet in the collection.
context.workbook.worksheets.onVisibilityChanged.add(onWorksheetCollectionVisibilityChanged);
await context.sync();
console.log("Registered the worksheet collection visibility changed event handler.");
});
...
async function onWorksheetCollectionVisibilityChanged(args: Excel.WorksheetVisibilityChangedEventArgs) {
console.log(`Worksheet collection event: Worksheet ${args.worksheetId} visibility changed from ${args.visibilityBefore} to ${args.visibilityAfter}.`);
}