Excel.Workbook class

Workbook is the top level object which contains related workbook objects such as worksheets, tables, ranges, etc.

[ API set: ExcelApi 1.1 ]

Extends
OfficeExtension.ClientObject

Properties

application

Represents the Excel application instance that contains this workbook. Read-only.

[ API set: ExcelApi 1.1 ]

bindings

Represents a collection of bindings that are part of the workbook. Read-only.

[ API set: ExcelApi 1.1 ]

customXmlParts

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

[ API set: ExcelApi 1.5 ]

dataConnections

Represents all data connections in the workbook. Read-only.

[ API set: ExcelApi 1.7 ]

functions

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

[ API set: ExcelApi 1.2 ]

name

Gets the workbook name. Read-only.

[ API set: ExcelApi 1.7 ]

names

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

[ API set: ExcelApi 1.1 ]

pivotTables

Represents a collection of PivotTables associated with the workbook. Read-only.

[ API set: ExcelApi 1.3 ]

properties

Gets the workbook properties. Read-only.

[ API set: ExcelApi 1.7 ]

protection

Returns workbook protection object for a workbook. Read-only.

[ API set: ExcelApi 1.7 ]

readOnly

True if the workbook is open in Read-only mode. Read-only.

[ API set: ExcelApi 1.8 ]

settings

Represents a collection of Settings associated with the workbook. Read-only.

[ API set: ExcelApi 1.4 ]

styles

Represents a collection of styles associated with the workbook. Read-only.

[ API set: ExcelApi 1.7 ]

tables

Represents a collection of tables associated with the workbook. Read-only.

[ API set: ExcelApi 1.1 ]

worksheets

Represents a collection of worksheets associated with the workbook. Read-only.

[ API set: ExcelApi 1.1 ]

Methods

getActiveCell()

Gets the currently active cell from the workbook.

[ API set: ExcelApi 1.7 ]

getSelectedRange()

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

[ API set: ExcelApi 1.1 ]

load(option)

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

toJSON()

Events

onSelectionChanged

Occurs when the selection in the document is changed.

[ API set: ExcelApi 1.2 ]

Property Details

application

Represents the Excel application instance that contains this workbook. Read-only.

[ API set: ExcelApi 1.1 ]

readonly application: Excel.Application;
Property Value

bindings

Represents a collection of bindings that are part of the workbook. Read-only.

[ API set: ExcelApi 1.1 ]

readonly bindings: Excel.BindingCollection;
Property Value

customXmlParts

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

[ API set: ExcelApi 1.5 ]

readonly customXmlParts: Excel.CustomXmlPartCollection;
Property Value

dataConnections

Represents all data connections in the workbook. Read-only.

[ API set: ExcelApi 1.7 ]

readonly dataConnections: Excel.DataConnectionCollection;
Property Value

functions

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

[ API set: ExcelApi 1.2 ]

readonly functions: Excel.Functions;
Property Value

name

Gets the workbook name. Read-only.

[ API set: ExcelApi 1.7 ]

readonly name: string;
Property Value
string

names

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

[ API set: ExcelApi 1.1 ]

readonly names: Excel.NamedItemCollection;
Property Value

pivotTables

Represents a collection of PivotTables associated with the workbook. Read-only.

[ API set: ExcelApi 1.3 ]

readonly pivotTables: Excel.PivotTableCollection;
Property Value

properties

Gets the workbook properties. Read-only.

[ API set: ExcelApi 1.7 ]

readonly properties: Excel.DocumentProperties;
Property Value

Examples

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

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

protection

Returns workbook protection object for a workbook. Read-only.

[ API set: ExcelApi 1.7 ]

readonly protection: Excel.WorkbookProtection;
Property Value

readOnly

True if the workbook is open in Read-only mode. Read-only.

[ API set: ExcelApi 1.8 ]

readonly readOnly: boolean;
Property Value
boolean

settings

Represents a collection of Settings associated with the workbook. Read-only.

[ API set: ExcelApi 1.4 ]

readonly settings: Excel.SettingCollection;
Property Value

styles

Represents a collection of styles associated with the workbook. Read-only.

[ API set: ExcelApi 1.7 ]

readonly styles: Excel.StyleCollection;
Property Value

tables

Represents a collection of tables associated with the workbook. Read-only.

[ API set: ExcelApi 1.1 ]

readonly tables: Excel.TableCollection;
Property Value

worksheets

Represents a collection of worksheets associated with the workbook. Read-only.

[ API set: ExcelApi 1.1 ]

readonly worksheets: Excel.WorksheetCollection;
Property Value

Method Details

getActiveCell()

Gets the currently active cell from the workbook.

[ API set: ExcelApi 1.7 ]

getActiveCell(): Excel.Range;
Returns

Examples

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);
});

getSelectedRange()

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

[ API set: ExcelApi 1.1 ]

getSelectedRange(): Excel.Range;
Returns

Examples

Excel.run(function (ctx) { 
    var selectedRange = ctx.workbook.getSelectedRange();
    selectedRange.load('address');
    return ctx.sync().then(function() {
            console.log(selectedRange.address);
    });
}).catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

load(option)

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

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

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

Returns
Remarks

In addition to this signature, this method has the following signatures:

load(option?: { select?: string; expand?: string; }): Excel.Workbook - Where option.select is a comma-delimited string that specifies the properties to load, and options.expand is a comma-delimited string that specifies the navigation properties to load.

load(option?: { select?: string; expand?: string; top?: number; skip?: number }): Excel.Workbook - Only available on collection types. It is similar to the preceding signature. Option.top specifies the maximum number of collection items that can be included in the result. Option.skip specifies the number of items that are to be skipped and not included in the result. If option.top is specified, the result set will start after skipping the specified number of items.

toJSON()

toJSON(): Excel.Interfaces.WorkbookData;
Returns

Event Details

onSelectionChanged

Occurs when the selection in the document is changed.

[ API set: ExcelApi 1.2 ]

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