Excel.Workbook class

Represents the Excel application instance that contains this workbook.

readonly application: Excel.Application;

Property Value

Remarks

[ API set: ExcelApi 1.1 ]

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

readonly bindings: Excel.BindingCollection;

Property Value

Remarks

[ API set: ExcelApi 1.1 ]

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

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

readonly customXmlParts: Excel.CustomXmlPartCollection;

Property Value

Remarks

[ API set: ExcelApi 1.5 ]

Represents all data connections in the workbook.

readonly dataConnections: Excel.DataConnectionCollection;

Property Value

Remarks

[ API set: ExcelApi 1.7 ]

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

readonly functions: Excel.Functions;

Property Value

Remarks

[ API set: ExcelApi 1.2 ]

Gets the workbook name.

readonly name: string;

Property Value

Remarks

[ API set: ExcelApi 1.7 ]

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

readonly names: Excel.NamedItemCollection;

Property Value

Remarks

[ API set: ExcelApi 1.1 ]

Represents a collection of PivotTables associated with the workbook.

readonly pivotTables: Excel.PivotTableCollection;

Property Value

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

Gets the workbook properties.

readonly properties: Excel.DocumentProperties;

Property Value

Remarks

[ API set: ExcelApi 1.7 ]

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

Returns the protection object for a workbook.

readonly protection: Excel.WorkbookProtection;

Property Value

Remarks

[ API set: ExcelApi 1.7 ]

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

readonly readOnly: boolean;

Property Value

Remarks

[ API set: ExcelApi 1.8 ]

Represents a collection of settings associated with the workbook.

readonly settings: Excel.SettingCollection;

Property Value

Remarks

[ API set: ExcelApi 1.4 ]

Represents a collection of styles associated with the workbook.

readonly styles: Excel.StyleCollection;

Property Value

Remarks

[ API set: ExcelApi 1.7 ]

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

Represents a collection of tables associated with the workbook.

readonly tables: Excel.TableCollection;

Property Value

Remarks

[ API set: ExcelApi 1.1 ]

Represents a collection of worksheets associated with the workbook.

readonly worksheets: Excel.WorksheetCollection;

Property Value

Remarks

[ API set: ExcelApi 1.1 ]

Gets the currently active cell from the workbook.

getActiveCell(): Excel.Range;

Returns

Remarks

[ API set: ExcelApi 1.7 ]

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

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

Remarks

[ API set: ExcelApi 1.1 ]

Examples

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

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

Returns

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

Returns

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

Returns

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

Returns

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

set(properties: Excel.Workbook): void;

Parameters

Returns

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

Occurs when the selection in the document is changed.

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

Event Type

Remarks

[ API set: ExcelApi 1.2 ]