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 |
Возникает при изменении любого листа в книге. |
| 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[]>
Массив идентификаторов, соответствующих каждому вновь вставленному листу.
Комментарии
[ Набор 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;Возвращаемое значение
Комментарии
Примеры
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>;Тип события
Комментарии
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>;Тип события
Комментарии
[ Набор API: ExcelApi BETA (ТОЛЬКО ПРЕДВАРИТЕЛЬНАЯ ВЕРСИЯ) ]
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>;Тип события
Комментарии
Office Add-ins
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по