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

Excel.Workbook class

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

Workbook — это объект верхнего уровня, содержащий связанные объекты книги, такие как листы, таблицы и диапазоны. Дополнительные сведения об объектной модели книг см. в статье Работа с книгами с помощью API JavaScript для Excel.

Extends
OfficeExtension.ClientObject

Комментарии

[ Набор API: ExcelApi 1.1 ]

Свойства

application

Представляет экземпляр приложения Excel, содержащий эту книгу.
autoSave

Указывает, находится ли книга в режиме автосохранений.
bindings

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

Возвращает номер версии модуля вычислений Excel.
chartDataPointTrack

Значение true, если все диаграммы в книге отслеживают точки фактических данных, с которыми они связаны. False, если диаграммы отслеживают индекс точек данных.
comments

Представляет коллекцию комментариев, связанных с книгой.
context

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

Представляет коллекцию настраиваемых XML-частей, содержащихся в этой книге.
dataConnections

Представляет все подключения к данным в книге.
functions

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

Указывает, были ли изменения внесены с момента последнего сохранения книги. Для этого свойства можно присвоить значение , true если нужно закрыть измененную книгу, не сохраняя ее или не запрашивая ее сохранение.
name

Получает имя книги.
names

Представляет коллекцию именованных элементов с областью книги (именованные диапазоны и константы).
pivotTables

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

Представляет коллекцию объектов PivotTableStyles, связанных с книгой.
previouslySaved

Указывает, сохранялась ли книга локально или в сети.
properties

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

Возвращает объект защиты для книги.
readOnly

Возвращает значение true , если книга открыта в режиме только для чтения.
settings

Представляет коллекцию параметров, связанных с книгой.
slicers

Представляет коллекцию срезов, связанных с книгой.
slicerStyles

Представляет коллекцию объектов SlicerStyles, связанных с книгой.
styles

Представляет коллекцию стилей, связанных с книгой.
tables

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

Представляет коллекцию объектов TableStyles, связанных с книгой.
timelineStyles

Представляет коллекцию объектов TimelineStyles, связанных с книгой.
usePrecisionAsDisplayed

Значение true, если вычисления в книге выполняются только с той точностью чисел, с которой они отображаются. Данные навсегда потеряют точность при переключении этого свойства с false на true.
worksheets

Представляет коллекцию листов, сопоставленных с книгой.

Методы

close(closeBehavior)

Закрывает текущую книгу.
close(closeBehaviorString)

Закрывает текущую книгу.
getActiveCell()

Получает текущую активную ячейку из книги.
getActiveChart()

Получает текущую активную диаграмму в книге. Если нет активной диаграммы, ItemNotFound возникает исключение.
getActiveChartOrNullObject()

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

Получает текущий активный срез в книге. Если активный срез отсутствует, ItemNotFound возникает исключение.
getActiveSlicerOrNullObject()

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

Возвращает значение true , если книга редактируется несколькими пользователями (с помощью совместного редактирования). Обратите внимание, что между изменением состояния книги и их отражением в результатах метода может возникнуть некоторая задержка.
getSelectedRange()

Возвращает выбранный в данный момент один диапазон из книги. Если выбрано несколько диапазонов, этот метод вызовет ошибку.
getSelectedRanges()

Получает текущий выделенный диапазон (один или несколько) в книге. В отличие от getSelectedRange(), этот метод возвращает RangeAreas объект, представляющий все выбранные диапазоны.
load(options)

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

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

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

Сохраняет текущую книгу.
save(saveBehaviorString)

Сохраняет текущую книгу.
set(properties, options)

Задает несколько свойств объекта одновременно. Можно передать обычный объект с соответствующими свойствами или другой объект API того же типа.
set(properties)

Задает несколько свойств объекта одновременно на основе существующего загруженного объекта.
toJSON()

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

События

onAutoSaveSettingChanged

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

Происходит при изменении выбора в документе.

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

application

Представляет экземпляр приложения Excel, содержащий эту книгу.

readonly application: Excel.Application;

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

Excel.Application

Комментарии

[ Набор API: ExcelApi 1.1 ]

autoSave

Указывает, находится ли книга в режиме автосохранений.

readonly autoSave: boolean;

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

boolean

Комментарии

[ Набор API: ExcelApi 1.9 ]

bindings

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

readonly bindings: Excel.BindingCollection;

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

Excel.BindingCollection

Комментарии

[ Набор API: ExcelApi 1.1 ]

calculationEngineVersion

Возвращает номер версии модуля вычислений Excel.

readonly calculationEngineVersion: number;

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

number

Комментарии

[ Набор API: ExcelApi 1.9 ]

chartDataPointTrack

Значение true, если все диаграммы в книге отслеживают точки фактических данных, с которыми они связаны. False, если диаграммы отслеживают индекс точек данных.

chartDataPointTrack: boolean;

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

boolean

Комментарии

[ Набор API: ExcelApi 1.9 ]

comments

Представляет коллекцию комментариев, связанных с книгой.

readonly comments: Excel.CommentCollection;

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

Excel.CommentCollection

Комментарии

[ Набор API: ExcelApi 1.10 ]

context

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

context: RequestContext;

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

Excel.RequestContext

customXmlParts

Представляет коллекцию настраиваемых XML-частей, содержащихся в этой книге.

readonly customXmlParts: Excel.CustomXmlPartCollection;

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

Excel.CustomXmlPartCollection

Комментарии

[ Набор API: ExcelApi 1.5 ]

dataConnections

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

readonly dataConnections: Excel.DataConnectionCollection;

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

Excel.DataConnectionCollection

Комментарии

[ Набор API: ExcelApi 1.7 ]

functions

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

readonly functions: Excel.Functions;

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

Excel.Functions

Комментарии

[ Набор API: ExcelApi 1.2 ]

isDirty

Указывает, были ли изменения внесены с момента последнего сохранения книги. Для этого свойства можно присвоить значение , true если нужно закрыть измененную книгу, не сохраняя ее или не запрашивая ее сохранение.

isDirty: boolean;

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

boolean

Комментарии

[ Набор API: ExcelApi 1.9 ]

name

Получает имя книги.

readonly name: string;

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

string

Комментарии

[ Набор API: ExcelApi 1.7 ]

names

Представляет коллекцию именованных элементов с областью книги (именованные диапазоны и константы).

readonly names: Excel.NamedItemCollection;

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

Excel.NamedItemCollection

Комментарии

[ Набор API: ExcelApi 1.1 ]

pivotTables

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

readonly pivotTables: Excel.PivotTableCollection;

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

Excel.PivotTableCollection

Комментарии

[ Набор API: ExcelApi 1.3 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/38-pivottable/pivottable-get-pivottables.yaml

await Excel.run(async (context) => {
  // Get the names of all the PivotTables in the workbook.
  const pivotTables = context.workbook.pivotTables;
  pivotTables.load("name");
  await context.sync();

  // Display the names in the console.
  console.log("PivotTables in the workbook:")
  pivotTables.items.forEach((pivotTable) => {
    console.log(`\t${pivotTable.name}`);
  });
});

pivotTableStyles

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

readonly pivotTableStyles: Excel.PivotTableStyleCollection;

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

Excel.PivotTableStyleCollection

Комментарии

[ Набор API: ExcelApi 1.10 ]

previouslySaved

Указывает, сохранялась ли книга локально или в сети.

readonly previouslySaved: boolean;

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

boolean

Комментарии

[ Набор API: ExcelApi 1.9 ]

properties

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

readonly properties: Excel.DocumentProperties;

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

Excel.DocumentProperties

Комментарии

[ Набор API: ExcelApi 1.7 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/26-document/properties.yaml

await Excel.run(async (context) => {
    let titleValue = "Excel document properties API";
    let subjectValue = "Set and get document properties";
    let keywordsValue = "Set and get operations";
    let commentsValue = "This is an Excel document properties API code sample";
    let categoryValue = "Office Add-ins";
    let managerValue = "John";
    let companyValue = "Microsoft";

    let docProperties = context.workbook.properties;

    // Set the writeable document properties.
    docProperties.title = titleValue;
    docProperties.subject = subjectValue;
    docProperties.keywords = keywordsValue;
    docProperties.comments = commentsValue;
    docProperties.category = categoryValue;
    docProperties.manager = managerValue;
    docProperties.company = companyValue;

    await context.sync();

    console.log("Set the following document properties: title, subject, keywords, comments, category, manager, company.");
});

protection

Возвращает объект защиты для книги.

readonly protection: Excel.WorkbookProtection;

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

Excel.WorkbookProtection

Комментарии

[ Набор API: ExcelApi 1.7 ]

readOnly

Возвращает значение true , если книга открыта в режиме только для чтения.

readonly readOnly: boolean;

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

boolean

Комментарии

[ Набор API: ExcelApi 1.8 ]

settings

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

readonly settings: Excel.SettingCollection;

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

Excel.SettingCollection

Комментарии

[ Набор API: ExcelApi 1.4 ]

slicers

Представляет коллекцию срезов, связанных с книгой.

readonly slicers: Excel.SlicerCollection;

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

Excel.SlicerCollection

Комментарии

[ Набор API: ExcelApi 1.10 ]

slicerStyles

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

readonly slicerStyles: Excel.SlicerStyleCollection;

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

Excel.SlicerStyleCollection

Комментарии

[ Набор API: ExcelApi 1.10 ]

styles

Представляет коллекцию стилей, связанных с книгой.

readonly styles: Excel.StyleCollection;

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

Excel.StyleCollection

Комментарии

[ Набор API: ExcelApi 1.7 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/style.yaml

await Excel.run(async (context) => {
    let styles = context.workbook.styles;

    // Add a new style to the style collection.
    // Styles is in the Home tab ribbon.
    styles.add("Diagonal Orientation Style");
          
    let newStyle = styles.getItem("Diagonal Orientation Style");
    
    // The "Diagonal Orientation Style" properties.
    newStyle.textOrientation = 38;
    newStyle.autoIndent = true;
    newStyle.includeProtection = true;
    newStyle.shrinkToFit = true;
    newStyle.locked = false;
    
    await context.sync();

    console.log("Successfully added a new style with diagonal orientation to the Home tab ribbon.");
});

tables

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

readonly tables: Excel.TableCollection;

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

Excel.TableCollection

Комментарии

[ Набор API: ExcelApi 1.1 ]

tableStyles

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

readonly tableStyles: Excel.TableStyleCollection;

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

Excel.TableStyleCollection

Комментарии

[ Набор API: ExcelApi 1.10 ]

timelineStyles

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

readonly timelineStyles: Excel.TimelineStyleCollection;

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

Excel.TimelineStyleCollection

Комментарии

[ Набор API: ExcelApi 1.10 ]

usePrecisionAsDisplayed

Значение true, если вычисления в книге выполняются только с той точностью чисел, с которой они отображаются. Данные навсегда потеряют точность при переключении этого свойства с false на true.

usePrecisionAsDisplayed: boolean;

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

boolean

Комментарии

[ Набор API: ExcelApi 1.9 ]

worksheets

Представляет коллекцию листов, сопоставленных с книгой.

readonly worksheets: Excel.WorksheetCollection;

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

Excel.WorksheetCollection

Комментарии

[ Набор API: ExcelApi 1.1 ]

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

close(closeBehavior)

Закрывает текущую книгу.

close(closeBehavior?: Excel.CloseBehavior): void;

Параметры

closeBehavior
Excel.CloseBehavior

поведение закрытия книги.

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

void

Комментарии

[ Набор API: ExcelApi 1.11 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-save-and-close.yaml

await Excel.run(async (context) => {
    context.workbook.close(Excel.CloseBehavior.save);
});

close(closeBehaviorString)

Закрывает текущую книгу.

close(closeBehaviorString?: "Save" | "SkipSave"): void;

Параметры

closeBehaviorString

"Save" | "SkipSave"

поведение закрытия книги.

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

void

Комментарии

[ Набор API: ExcelApi 1.11 ]

getActiveCell()

Получает текущую активную ячейку из книги.

getActiveCell(): Excel.Range;

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

Excel.Range

Комментарии

[ Набор API: ExcelApi 1.7 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-get-active-cell.yaml

await Excel.run(async (context) => {

    let myWorkbook = context.workbook;
    let activeCell = myWorkbook.getActiveCell();
    activeCell.load("address");

    await context.sync();
    
    console.log("The active cell is " + activeCell.address);
});

getActiveChart()

Получает текущую активную диаграмму в книге. Если нет активной диаграммы, ItemNotFound возникает исключение.

getActiveChart(): Excel.Chart;

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

Excel.Chart

Комментарии

[ Набор API: ExcelApi 1.9 ]

getActiveChartOrNullObject()

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

getActiveChartOrNullObject(): Excel.Chart;

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

Excel.Chart

Комментарии

[ Набор API: ExcelApi 1.9 ]

getActiveSlicer()

Получает текущий активный срез в книге. Если активный срез отсутствует, ItemNotFound возникает исключение.

getActiveSlicer(): Excel.Slicer;

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

Excel.Slicer

Комментарии

[ Набор API: ExcelApi 1.10 ]

getActiveSlicerOrNullObject()

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

getActiveSlicerOrNullObject(): Excel.Slicer;

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

Excel.Slicer

Комментарии

[ Набор API: ExcelApi 1.10 ]

getIsActiveCollabSession()

Возвращает значение true , если книга редактируется несколькими пользователями (с помощью совместного редактирования). Обратите внимание, что между изменением состояния книги и их отражением в результатах метода может возникнуть некоторая задержка.

getIsActiveCollabSession(): OfficeExtension.ClientResult<boolean>;

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

OfficeExtension.ClientResult<boolean>

Комментарии

[ Набор API: ExcelApi 1.9 ]

getSelectedRange()

Возвращает выбранный в данный момент один диапазон из книги. Если выбрано несколько диапазонов, этот метод вызовет ошибку.

getSelectedRange(): Excel.Range;

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

Excel.Range

Комментарии

[ Набор API: ExcelApi 1.1 ]

Примеры

await Excel.run(async (context) => { 
    const selectedRange = context.workbook.getSelectedRange();
    selectedRange.load('address');
    await context.sync();
    console.log(selectedRange.address);
});

getSelectedRanges()

Получает текущий выделенный диапазон (один или несколько) в книге. В отличие от getSelectedRange(), этот метод возвращает RangeAreas объект, представляющий все выбранные диапазоны.

getSelectedRanges(): Excel.RangeAreas;

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

Excel.RangeAreas

Комментарии

[ Набор API: ExcelApi 1.9 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/42-range/range-areas.yaml

await Excel.run(async (context) => {

    const selectedRanges = context.workbook.getSelectedRanges();
    selectedRanges.format.fill.color = "lightblue";

    await context.sync();
})

load(options)

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

load(options?: Excel.Interfaces.WorkbookLoadOptions): Excel.Workbook;

Параметры

options
Excel.Interfaces.WorkbookLoadOptions

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

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

Excel.Workbook

load(propertyNames)

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

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

Параметры

propertyNames

string | string[]

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

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

Excel.Workbook

load(propertyNamesAndPaths)

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

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.Workbook;

Параметры

propertyNamesAndPaths

{ select?: string; expand?: string; }

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

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

Excel.Workbook

save(saveBehavior)

Сохраняет текущую книгу.

save(saveBehavior?: Excel.SaveBehavior): void;

Параметры

saveBehavior
Excel.SaveBehavior

Поведение сохранения должно быть "Сохранить" или "Запрос". Значение по умолчанию — "Сохранить".

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

void

Комментарии

[ Набор API: ExcelApi 1.11 ]

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/50-workbook/workbook-save-and-close.yaml

await Excel.run(async (context) => {
    context.workbook.save(Excel.SaveBehavior.save);
});

save(saveBehaviorString)

Сохраняет текущую книгу.

save(saveBehaviorString?: "Save" | "Prompt"): void;

Параметры

saveBehaviorString

"Save" | "Prompt"

Поведение сохранения должно быть "Сохранить" или "Запрос". Значение по умолчанию — "Сохранить".

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

void

Комментарии

[ Набор API: ExcelApi 1.11 ]

set(properties, options)

Задает несколько свойств объекта одновременно. Можно передать обычный объект с соответствующими свойствами или другой объект API того же типа.

set(properties: Interfaces.WorkbookUpdateData, options?: OfficeExtension.UpdateOptions): void;

Параметры

properties
Excel.Interfaces.WorkbookUpdateData

Объект JavaScript со свойствами, структурированными изоморфно по свойствам объекта, для которого вызывается метод .

options
OfficeExtension.UpdateOptions

Предоставляет возможность подавления ошибок, если объект свойств пытается задать какие-либо свойства, доступные только для чтения.

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

void

set(properties)

Задает несколько свойств объекта одновременно на основе существующего загруженного объекта.

set(properties: Excel.Workbook): void;

Параметры

properties
Excel.Workbook

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

void

toJSON()

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

toJSON(): Excel.Interfaces.WorkbookData;

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

Excel.Interfaces.WorkbookData

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

onAutoSaveSettingChanged

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

readonly onAutoSaveSettingChanged: OfficeExtension.EventHandlers<Excel.WorkbookAutoSaveSettingChangedEventArgs>;

Тип события

OfficeExtension.EventHandlers<Excel.WorkbookAutoSaveSettingChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.9 ]

onSelectionChanged

Происходит при изменении выбора в документе.

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

Тип события

OfficeExtension.EventHandlers<Excel.SelectionChangedEventArgs>

Комментарии

[ Набор API: ExcelApi 1.2 ]