Excel. Workbook class

Properties

application	Represents the Excel application instance that contains this workbook.
autoSave	Specifies if the workbook is in AutoSave mode.
bindings	Represents a collection of bindings that are part of the workbook.
calculationEngineVersion	Returns a number about the version of Excel Calculation Engine.
chartDataPointTrack	True if all charts in the workbook are tracking the actual data points to which they are attached. False if the charts track the index of the data points.
comments	Represents a collection of comments associated with the workbook.
context	The request context associated with the object. This connects the add-in's process to the Office host application's process.
customXmlParts	Represents the collection of custom XML parts contained by this workbook.
dataConnections	Represents all data connections in the workbook.
functions	Represents a collection of worksheet functions that can be used for computation.
isDirty	Specifies if changes have been made since the workbook was last saved. You can set this property to `true` if you want to close a modified workbook without either saving it or being prompted to save it.
name	Gets the workbook name.
names	Represents a collection of workbook-scoped named items (named ranges and constants).
pivotTables	Represents a collection of PivotTables associated with the workbook.
pivotTableStyles	Represents a collection of PivotTableStyles associated with the workbook.
previouslySaved	Specifies if the workbook has ever been saved locally or online.
properties	Gets the workbook properties.
protection	Returns the protection object for a workbook.
readOnly	Returns `true` if the workbook is open in read-only mode.
settings	Represents a collection of settings associated with the workbook.
slicers	Represents a collection of slicers associated with the workbook.
slicerStyles	Represents a collection of SlicerStyles associated with the workbook.
styles	Represents a collection of styles associated with the workbook.
tables	Represents a collection of tables associated with the workbook.
tableStyles	Represents a collection of TableStyles associated with the workbook.
timelineStyles	Represents a collection of TimelineStyles associated with the workbook.
usePrecisionAsDisplayed	True if calculations in this workbook will be done using only the precision of the numbers as they're displayed. Data will permanently lose accuracy when switching this property from `false` to `true`.
worksheets	Represents a collection of worksheets associated with the workbook.

Methods

getActiveCell()	Gets the currently active cell from the workbook.
getActiveChart()	Gets the currently active chart in the workbook. If there is no active chart, an `ItemNotFound` exception is thrown.
getActiveChartOrNullObject()	Gets the currently active chart in the workbook. If there is no active chart, then this method returns an object with its `isNullObject` property set to `true`. For further information, see *OrNullObject methods and properties.
getActiveSlicer()	Gets the currently active slicer in the workbook. If there is no active slicer, an `ItemNotFound` exception is thrown.
getActiveSlicerOrNullObject()	Gets the currently active slicer in the workbook. If there is no active slicer, then this method returns an object with its `isNullObject` property set to `true`. For further information, see *OrNullObject methods and properties.
getIsActiveCollabSession()	Returns `true` if the workbook is being edited by multiple users (through co-authoring). Please be aware there might be some delay between when the workbook status changes and when the changes are reflected on the result of the method.
getSelectedRange()	Gets the currently selected single range from the workbook. If there are multiple ranges selected, this method will throw an error.
getSelectedRanges()	Gets the currently selected one or more ranges from the workbook. Unlike `getSelectedRange()`, this method returns a `RangeAreas` object that represents all the selected ranges.
load(options)	Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties.
load(propertyNames)	Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties.
load(propertyNamesAndPaths)	Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading the properties.
set(properties, options)	Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.
set(properties)	Sets multiple properties on the object at the same time, based on an existing loaded object.
toJSON()	Overrides the JavaScript `toJSON()` method in order to provide more useful output when an API object is passed to `JSON.stringify()`. (`JSON.stringify`, in turn, calls the `toJSON` method of the object that is passed to it.) Whereas the original `Excel.Workbook` object is an API object, the `toJSON` method returns a plain JavaScript object (typed as `Excel.Interfaces.WorkbookData`) that contains shallow copies of any loaded child properties from the original object.

Events

onAutoSaveSettingChanged	Occurs when the AutoSave setting is changed on the workbook.
onSelectionChanged	Occurs when the selection in the document is changed.

Property Details

application

Represents the Excel application instance that contains this workbook.

readonly application: Excel.Application;

Property Value

Excel.Application

Remarks

autoSave

Specifies if the workbook is in AutoSave mode.

readonly autoSave: boolean;

Property Value

boolean

Remarks

bindings

Represents a collection of bindings that are part of the workbook.

readonly bindings: Excel.BindingCollection;

Property Value

Excel.BindingCollection

Remarks

calculationEngineVersion

Returns a number about the version of Excel Calculation Engine.

readonly calculationEngineVersion: number;

Property Value

number

Remarks

chartDataPointTrack

True if all charts in the workbook are tracking the actual data points to which they are attached. False if the charts track the index of the data points.

chartDataPointTrack: boolean;

Property Value

boolean

Remarks

comments

Represents a collection of comments associated with the workbook.

readonly comments: Excel.CommentCollection;

Property Value

Excel.CommentCollection

Remarks

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

Excel.RequestContext

customXmlParts

Represents the collection of custom XML parts contained by this workbook.

readonly customXmlParts: Excel.CustomXmlPartCollection;

Property Value

Excel.CustomXmlPartCollection

Remarks

[ API set: ExcelApi 1.5 ]

dataConnections

Represents all data connections in the workbook.

readonly dataConnections: Excel.DataConnectionCollection;

Property Value

Excel.DataConnectionCollection

Remarks

functions

Represents a collection of worksheet functions that can be used for computation.

readonly functions: Excel.Functions;

Property Value

Excel.Functions

Remarks

[ API set: ExcelApi 1.2 ]

isDirty

Specifies if changes have been made since the workbook was last saved. You can set this property to true if you want to close a modified workbook without either saving it or being prompted to save it.

isDirty: boolean;

Property Value

boolean

Remarks

name

Gets the workbook name.

readonly name: string;

Property Value

string

Remarks

names

Represents a collection of workbook-scoped named items (named ranges and constants).

readonly names: Excel.NamedItemCollection;

Property Value

Excel.NamedItemCollection

Remarks

pivotTables

Represents a collection of PivotTables associated with the workbook.

readonly pivotTables: Excel.PivotTableCollection;

Property Value

Excel.PivotTableCollection

Remarks

[ API set: ExcelApi 1.3 ]

Examples

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

Represents a collection of PivotTableStyles associated with the workbook.

readonly pivotTableStyles: Excel.PivotTableStyleCollection;

Property Value

Excel.PivotTableStyleCollection

Remarks

previouslySaved

Specifies if the workbook has ever been saved locally or online.

readonly previouslySaved: boolean;

Property Value

boolean

Remarks

properties

Gets the workbook properties.

readonly properties: Excel.DocumentProperties;

Property Value

Excel.DocumentProperties

Remarks

Examples

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

Returns the protection object for a workbook.

readonly protection: Excel.WorkbookProtection;

Property Value

Excel.WorkbookProtection

Remarks

readOnly

Returns true if the workbook is open in read-only mode.

readonly readOnly: boolean;

Property Value

boolean

Remarks

[ API set: ExcelApi 1.8 ]

settings

Represents a collection of settings associated with the workbook.

readonly settings: Excel.SettingCollection;

Property Value

Excel.SettingCollection

Remarks

[ API set: ExcelApi 1.4 ]

slicers

Represents a collection of slicers associated with the workbook.

readonly slicers: Excel.SlicerCollection;

Property Value

Excel.SlicerCollection

Remarks

slicerStyles

Represents a collection of SlicerStyles associated with the workbook.

readonly slicerStyles: Excel.SlicerStyleCollection;

Property Value

Excel.SlicerStyleCollection

Remarks

styles

Represents a collection of styles associated with the workbook.

readonly styles: Excel.StyleCollection;

Property Value

Excel.StyleCollection

Remarks

Examples

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

Represents a collection of tables associated with the workbook.

readonly tables: Excel.TableCollection;

Property Value

Excel.TableCollection

Remarks

tableStyles

Represents a collection of TableStyles associated with the workbook.

readonly tableStyles: Excel.TableStyleCollection;

Property Value

Excel.TableStyleCollection

Remarks

timelineStyles

Represents a collection of TimelineStyles associated with the workbook.

readonly timelineStyles: Excel.TimelineStyleCollection;

Property Value

Excel.TimelineStyleCollection

Remarks

usePrecisionAsDisplayed

True if calculations in this workbook will be done using only the precision of the numbers as they're displayed. Data will permanently lose accuracy when switching this property from false to true.

usePrecisionAsDisplayed: boolean;

Property Value

boolean

Remarks

worksheets

Represents a collection of worksheets associated with the workbook.

readonly worksheets: Excel.WorksheetCollection;

Property Value

Excel.WorksheetCollection

Remarks

Method Details

getActiveCell()

Gets the currently active cell from the workbook.

getActiveCell(): Excel.Range;

Returns

Excel.Range

Remarks

Examples

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

Gets the currently active chart in the workbook. If there is no active chart, an ItemNotFound exception is thrown.

getActiveChart(): Excel.Chart;

Returns

Excel.Chart

Remarks

getActiveChartOrNullObject()

Gets the currently active chart in the workbook. If there is no active chart, then this method returns an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.

getActiveChartOrNullObject(): Excel.Chart;

Returns

Excel.Chart

Remarks

getActiveSlicer()

Gets the currently active slicer in the workbook. If there is no active slicer, an ItemNotFound exception is thrown.

getActiveSlicer(): Excel.Slicer;

Returns

Excel.Slicer

Remarks

getActiveSlicerOrNullObject()

Gets the currently active slicer in the workbook. If there is no active slicer, then this method returns an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.

getActiveSlicerOrNullObject(): Excel.Slicer;

Returns

Excel.Slicer

Remarks

getIsActiveCollabSession()

Returns true if the workbook is being edited by multiple users (through co-authoring). Please be aware there might be some delay between when the workbook status changes and when the changes are reflected on the result of the method.

getIsActiveCollabSession(): OfficeExtension.ClientResult<boolean>;

Returns

OfficeExtension.ClientResult<boolean>

Remarks

getSelectedRange()

Gets the currently selected single range from the workbook. If there are multiple ranges selected, this method will throw an error.

getSelectedRange(): Excel.Range;

Returns

Excel.Range

Remarks

Examples

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

getSelectedRanges()

Gets the currently selected one or more ranges from the workbook. Unlike getSelectedRange(), this method returns a RangeAreas object that represents all the selected ranges.

getSelectedRanges(): Excel.RangeAreas;

Returns

Excel.RangeAreas

Remarks

OfficeExtension.EventHandlers<Excel.WorkbookAutoSaveSettingChangedEventArgs>

Examples

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

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

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

Parameters

options: Excel.Interfaces.WorkbookLoadOptions

Provides options for which properties of the object to load.

Returns

Excel.Workbook

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

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

Parameters

propertyNames: string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns

Excel.Workbook

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

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

Parameters

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

propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.

Returns

Excel.Workbook

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

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

Parameters

properties: Excel.Interfaces.WorkbookUpdateData

A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.

options: OfficeExtension.UpdateOptions

Provides an option to suppress errors if the properties object tries to set any read-only properties.

Returns

void

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Excel.Workbook): void;

Parameters

properties: Excel.Workbook

Returns

void

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.Workbook object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.WorkbookData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Excel.Interfaces.WorkbookData;

Returns

Excel.Interfaces.WorkbookData

Event Details

onAutoSaveSettingChanged

Occurs when the AutoSave setting is changed on the workbook.

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

Event Type

Remarks