office package

Classes

Office.TableData

Represents the data in a table or an Office.TableBinding.

OfficeExtension.ClientObject

An abstract proxy object that represents an object in an Office document. You create proxy objects from the context (or from other proxy objects), add commands to a queue to act on the object, and then synchronize the proxy object state with the document by calling context.sync().

OfficeExtension.ClientRequestContext

An abstract RequestContext object that facilitates requests to the Office application. The Excel.run and Word.run methods provide a request context.

OfficeExtension.ClientResult

Contains the result for methods that return primitive types. The object's value property is retrieved from the document after context.sync() is invoked.

OfficeExtension.EmbeddedSession

Represents a session of a Visio diagram embedded in a SharePoint page. For more information, see Visio JavaScript API overview.

OfficeExtension.Error

The error object returned by context.sync(), if a promise is rejected due to an error while processing the request.

OfficeExtension.ErrorCodes

Represents the error code that can be returned by OfficeExtension.Error.code.

To learn more about the error codes, see Office Common API error codes.

OfficeExtension.EventHandlerResult

Enables the removal of an event handler. Returned by the EventHandlers.add method.

Note: The same RequestContext object that the handler was added in must be used when removing the handler. More information can be found in Remove an event handler.

OfficeExtension.EventHandlers
OfficeExtension.TrackedObjects

Collection of tracked objects, contained within a request context. See context.trackedObjects for more information.

Interfaces

Office.Actions

Manages actions and keyboard shortcuts.

Office.AddBindingFromNamedItemOptions

Provides options for configuring the binding that is created.

Office.AddBindingFromPromptOptions

Provides options for configuring the prompt and identifying the binding that is created.

Office.AddBindingFromSelectionOptions

Provides options for identifying the binding that is created.

Office.Addin

Represents add-in level functionality for operating or configuring various aspects of the add-in.

Office.AddinCommands.Event

The Event object is passed as a parameter to add-in functions invoked by function command buttons. The object allows the add-in to identify which button was clicked and to signal the Office application that it has completed its processing.

Office.AddinCommands.EventCompletedOptions

Specifies the behavior of an on-send add-in in Outlook when it completes processing an ItemSend event.

Office.AddinCommands.Source

Encapsulates source data for add-in events.

Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

Office.AsyncResult

An object which encapsulates the result of an asynchronous request, including status and error information if the request failed.

When the function you pass to the callback parameter of an "Async" method executes, it receives an AsyncResult object that you can access from the callback function's only parameter.

Office.Auth

The Office Auth namespace, Office.auth, provides a method that allows the Office client application to obtain an access token to the add-in's web application. Indirectly, this also enables the add-in to access the signed-in user's Microsoft Graph data without requiring the user to sign in a second time.

Office.AuthOptions

Provides options for the user experience when Office obtains an access token to the add-in from AAD v. 2.0 with the getAccessToken method.

Office.BeforeDocumentCloseNotification

Represents a modal notification dialog that can appear when the user attempts to close a document. The document won't close until the user responds. The notification dialog will allow the user to confirm the request to close the document or cancel the request to close the document. This API is only supported in Excel.

Office.Binding

Represents a binding to a section of the document.

The Binding object exposes the functionality possessed by all bindings regardless of type.

The Binding object is never called directly. It is the abstract parent class of the objects that represent each type of binding: Office.MatrixBinding, Office.TableBinding, or Office.TextBinding. All three of these objects inherit the getDataAsync and setDataAsync methods from the Binding object that enable to you interact with the data in the binding. They also inherit the ID and type properties for querying those property values. Additionally, the MatrixBinding and TableBinding objects expose additional methods for matrix- and table-specific features, such as counting the number of rows and columns.

Office.BindingDataChangedEventArgs

Provides information about the binding that raised the DataChanged event.

Office.Bindings

Represents the bindings the add-in has within the document.

Office.BindingSelectionChangedEventArgs

Provides information about the binding that raised the SelectionChanged event.

Office.Context

Represents the runtime environment of the add-in and provides access to key objects of the API. The current context exists as a property of Office. It's accessed using Office.context.

Office.ContextInformation

Provides information about the environment in which the add-in is running.

Office.Control

Represents an individual control or command and the state it should have.

Office.CustomXmlNode

Represents an XML node in a tree in a document.

Office.CustomXmlPart

Represents a single CustomXMLPart in an Office.CustomXmlParts collection.

Office.CustomXmlParts

Represents a collection of CustomXmlPart objects.

Office.CustomXmlPrefixMappings

Represents a collection of CustomXmlPart objects.

Office.DevicePermission

Provides methods for an add-in to request permission from a user to access their device capabilities. A user's device capabilities include their camera, geolocation, and microphone.

Office.Dialog

The object that is returned when UI.displayDialogAsync is called. It exposes methods for registering event handlers and closing the dialog.

Office.DialogMessageOptions

Provides options for how to send messages, in either direction, between a dialog and its parent.

Office.DialogOptions

Provides options for how a dialog is displayed.

Office.DialogParentMessageReceivedEventArgs

Provides information about the message from the parent page that raised the DialogParentMessageReceived event.

To add an event handler for the DialogParentMessageReceived event, use the addHandlerAsync method of the Office.UI object.

Office.Document

An abstract class that represents the document the add-in is interacting with.

Office.DocumentSelectionChangedEventArgs

Provides information about the document that raised the SelectionChanged event.

Office.Error

Provides specific information about an error that occurred during an asynchronous data operation.

Office.File

Represents the document file associated with an Office Add-in.

Office.FileProperties
Office.GetBindingDataOptions

Provides options for how to get the data in a binding.

Office.GetFileOptions

Provides options for setting the size of slices that the document will be divided into.

Office.GetSelectedDataOptions

Provides options for customizing what data is returned and how it is formatted.

Office.GoToByIdOptions

Provides options for whether to select the location that is navigated to.

Office.Group

Represents a group of controls on a ribbon tab.

Requirement set: RibbonAPI 1.1

Office.IPromiseConstructor
Office.MatrixBinding

Represents a binding in two dimensions of rows and columns.

Office.NodeDeletedEventArgs

Provides information about the deleted node that raised the nodeDeleted event.

Office.NodeInsertedEventArgs

Provides information about the inserted node that raised the nodeInserted event.

Office.NodeReplacedEventArgs

Provides information about the replaced node that raised the nodeReplaced event.

Office.OfficeTheme

Provides access to the properties for Office theme colors.

Using Office theme colors lets you coordinate the color scheme of your add-in with the current Office theme selected by the user. The user sets a theme in an Office application through File > Account or Office Account > Office Theme. The selected theme is then applied across all Office applications. Using Office theme colors is appropriate for mail and task pane add-ins.

For more information on Office themes, see Change the look and feel of Microsoft 365.

Office.RangeCoordinates

Specifies a cell, or row, or column, by its zero-based row and/or column number. Example: {row: 3, column: 4} specifies the cell in the 3rd (zero-based) row in the 4th (zero-based) column.

Office.RangeFormatConfiguration

Specifies a range and its formatting.

Office.RemoveHandlerOptions

Provides options to determine which event handler or handlers are removed.

Office.RequirementSetSupport

Provides information about which Requirement Sets are supported in the current environment.

Office.Ribbon

An interface that contains all the functionality provided to manage the state of the Office ribbon.

Office.RibbonUpdaterData

Specifies changes to the ribbon, such as the enabled or disabled status of a button.

Office.SaveSettingsOptions

Provides options for saving settings.

Office.SetBindingDataOptions

Provides options for how to set the data in a binding.

Office.SetSelectedDataOptions

Provides options for how to insert data to the selection.

Office.Settings

Represents custom settings for a task pane or content add-in that are stored in the host document as name/value pairs.

Office.SettingsChangedEventArgs

Provides information about the settings that raised the settingsChanged event.

To add an event handler for the settingsChanged event, use the addHandlerAsync method of the Office.Settings object.

The settingsChanged event fires only when your add-in's script calls the Settings.saveAsync method to persist the in-memory copy of the settings into the document file. The settingsChanged event is not triggered when the Settings.set or Settings.remove methods are called.

The settingsChanged event was designed to let you to handle potential conflicts when two or more users are attempting to save settings at the same time when your add-in is used in a shared (coauthored) document.

Important: Your add-in's code can register a handler for the settingsChanged event when the add-in is running with any Excel client, but the event will fire only when the add-in is loaded with a spreadsheet that is opened in Excel on the web, and more than one user is editing the spreadsheet (coauthoring). Therefore, effectively the settingsChanged event is supported only in Excel on the web in coauthoring scenarios.

Office.Slice

Represents a slice of a document file. The Slice object is accessed with the File.getSliceAsync method.

Office.Tab

Represents an individual tab and the state it should have. For code examples, see Enable and Disable Add-in Commands and Create custom contextual tabs.

Office.TableBinding

Represents a binding in two dimensions of rows and columns, optionally with headers.

Office.TextBinding

Represents a bound text selection in the document.

The TextBinding object inherits the id property, type property, getDataAsync method, and setDataAsync method from the Office.Binding object. It does not implement any additional properties or methods of its own.

Office.UI

Provides objects and methods that you can use to create and manipulate UI components, such as dialog boxes, in your Office Add-ins.

Visit "Use the Dialog API in your Office Add-ins" for more information.

Office.Urls

Provides the URLs of the runtime environments used by an add-in.

Office.VisibilityModeChangedMessage

Message used in the onVisibilityModeChanged invocation.

OfficeExtension.DebugInfo

Provides information about an error.

OfficeExtension.EmbeddedOptions

Specifies options for a session of a Visio diagram embedded in a SharePoint page. Called by constructor of EmbeddedSession. For more information, see Visio JavaScript API overview.

OfficeExtension.EventInfo

Used by Office to construct event handlers. Do not call in your code.

OfficeExtension.LoadOption

Specifies which properties of an object should be loaded. This load happens when the sync() method is executed. This synchronizes the states between Office objects and corresponding JavaScript proxy objects.

OfficeExtension.RequestContextDebugInfo

Contains debug information about the request context.

OfficeExtension.RequestUrlAndHeaderInfo

Request URL and headers

OfficeExtension.RunOptions

Additional options passed into {Host}.run(...).

OfficeExtension.UpdateOptions

Provides an option for suppressing an error when the object that is used to set multiple properties tries to set read-only properties.

Type Aliases

OfficeExtension.IPromise

Enums

Office.ActiveView

Specifies the state of the active view of the document, for example, whether the user can edit the document.

Office.AsyncResultStatus

Specifies the result of an asynchronous call.

Office.BindingType

Specifies the type of the binding object that should be returned.

Office.CoercionType

Specifies how to coerce data returned or set by the invoked method.

Office.CustomXMLNodeType

Specifies the type of the XML node.

Office.DevicePermissionType

Specifies the device capability to which an add-in is requesting access.

Office.DocumentMode

Specifies whether the document in the associated application is read-only or read-write.

Office.EventType

Specifies the kind of event that was raised. Returned by the type property of an *EventArgs object.

Add-ins for Project support the Office.EventType.ResourceSelectionChanged, Office.EventType.TaskSelectionChanged, and Office.EventType.ViewSelectionChanged event types.

Only task pane add-ins for Outlook support Mailbox API set event types.

Office.FileType

Specifies the format in which to return the document.

Office.FilterType

Specifies whether filtering from the Office application is applied when the data is retrieved.

Office.GoToType

Specifies the type of place or object to navigate to.

Office.HostType

Specifies the Office application in which the add-in is running.

Office.Index

Specifies the relative PowerPoint slide.

Office.InitializationReason

Specifies whether the add-in was just inserted or was already contained in the document.

Office.PlatformType

Specifies the OS or other platform on which the Office application is running.

Office.ProjectProjectFields

Specifies the project fields that are available as a parameter for the Document.getProjectFieldAsync method.

Office.ProjectResourceFields

Specifies the resource fields that are available as a parameter for the Document.getResourceFieldAsync method.

Office.ProjectTaskFields

Specifies the task fields that are available as a parameter for the Document.getTaskFieldAsync method.

Office.ProjectViewTypes

Specifies the types of views that the Document.getSelectedViewAsync method can recognize.

Office.SelectionMode

Specifies whether to select (highlight) the location to navigate to (when using the Document.goToByIdAsync method).

Office.StartupBehavior

Provides options to determine the startup behavior of the add-in upon next start-up.

Office.Table

Specifies enumerated values for the cells property in the cellFormat parameter of table formatting methods.

Office.ThemeId

Specifies the Office theme that's currently selected.

For information on Office themes, see Change the look and feel of Microsoft 365.

Office.ValueFormat

Specifies whether values, such as numbers and dates, returned by the invoked method are returned with their formatting applied.

Office.VisibilityMode

Visibility mode of the add-in.

Functions

Office.initialize(reason)

Occurs when the runtime environment is loaded and the add-in is ready to start interacting with the application and hosted document.

The reason parameter of the initialize event listener function returns an InitializationReason enumeration value that specifies how initialization occurred. A task pane or content add-in can be initialized in two ways:

  • The user just inserted it from Recently Used Add-ins section of the Add-in drop-down list on the Insert tab of the ribbon in the Office application, or from Insert add-in dialog box.

  • The user opened a document that already contains the add-in.

Note: The reason parameter of the initialize event listener function only returns an InitializationReason enumeration value for task pane and content add-ins. It does not return a value for Outlook add-ins.

Office.isSetSupported(name, minVersion)

Checks if the specified requirement set is supported by the Office application.

Office.onReady(callback)

Ensures that the Office JavaScript APIs are ready to be called by the add-in. If the framework hasn't initialized yet, the callback or promise will wait until the Office application is ready to accept API calls. Note that though this API is intended to be used inside an Office add-in, it can also be used outside the add-in. In that case, once Office.js determines that it is running outside of an Office application, it will call the callback and resolve the promise with "null" for both the application and platform.

Office.select(expression, callback)

Returns a promise of an object described in the expression. Callback is invoked only if the function fails.

Office.useShortNamespace(useShortNamespace)

Toggles on and off the Office alias for the full Microsoft.Office.WebExtension namespace.

Function Details

Office.initialize(reason)

Occurs when the runtime environment is loaded and the add-in is ready to start interacting with the application and hosted document.

The reason parameter of the initialize event listener function returns an InitializationReason enumeration value that specifies how initialization occurred. A task pane or content add-in can be initialized in two ways:

  • The user just inserted it from Recently Used Add-ins section of the Add-in drop-down list on the Insert tab of the ribbon in the Office application, or from Insert add-in dialog box.

  • The user opened a document that already contains the add-in.

Note: The reason parameter of the initialize event listener function only returns an InitializationReason enumeration value for task pane and content add-ins. It does not return a value for Outlook add-ins.

export function initialize(reason: InitializationReason): void;

Parameters

reason
Office.InitializationReason

Indicates how the app was initialized.

Returns

void

Remarks

Support details

For more information about Office application and server requirements, see Requirements for running Office Add-ins.

Supported applications, by platform

Office on the web Office on Windows Office on Mac Office on iPad Outlook on mobile devices
Excel Supported Supported Supported Supported Not applicable
Outlook Supported Supported Supported Supported Supported
PowerPoint Supported Supported Supported Supported Not applicable
Project Not supported Supported Supported Not supported Not applicable
Word Supported Supported Supported Supported Not applicable

Examples

// You can use the value of the InitializationEnumeration to implement different logic for
// when the add-in is first inserted versus when it is already part of the document.
// The following example shows some simple logic that uses the value of the reason parameter
// to display how the task pane or content add-in was initialized.
Office.initialize = function (reason) {
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
    // After the DOM is loaded, code specific to the add-in can run.
    // Display initialization reason.
    if (reason == "inserted")
    write("The add-in was just inserted.");

    if (reason == "documentOpened")
    write("The add-in is already part of the document.");
    });
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Office.isSetSupported(name, minVersion)

Checks if the specified requirement set is supported by the Office application.

export function isSetSupported(name: string, minVersion?: string): boolean;

Parameters

name

string

Set name; e.g., "MatrixBindings".

minVersion

string

The minimum required version; e.g., "1.4".

Returns

boolean

Office.onReady(callback)

Ensures that the Office JavaScript APIs are ready to be called by the add-in. If the framework hasn't initialized yet, the callback or promise will wait until the Office application is ready to accept API calls. Note that though this API is intended to be used inside an Office add-in, it can also be used outside the add-in. In that case, once Office.js determines that it is running outside of an Office application, it will call the callback and resolve the promise with "null" for both the application and platform.

export function onReady(callback?: (info: { host: HostType, platform: PlatformType }) => any): Promise<{ host: HostType, platform: PlatformType }>;

Parameters

callback

(info: { host: Office.HostType, platform: Office.PlatformType }) => any

An optional callback function, that will receive the application and platform info. Alternatively, rather than use a callback, an add-in may simply wait for the Promise returned by the function to resolve.

Returns

Promise<{ host: Office.HostType, platform: Office.PlatformType }>

A Promise that contains the application and platform info, once initialization is completed.

Office.select(expression, callback)

Returns a promise of an object described in the expression. Callback is invoked only if the function fails.

export function select(expression: string, callback?: (result: AsyncResult<any>) => void): Binding;

Parameters

expression

string

The object to be retrieved. Example "bindings#BindingName", retrieves a binding promise for a binding named 'BindingName'

callback

(result: Office.AsyncResult<any>) => void

Optional. A function that is invoked when the callback returns, whose only parameter is of type Office.AsyncResult.

Returns

Remarks

Support details

For more information about Office application and server requirements, see Requirements for running Office Add-ins.

Supported applications, by platform

Office on the web Office on Windows Office on iPad
Excel Supported Supported Supported
Word Not supported Supported Supported

Examples

// The following code example uses the select function to retrieve a binding with the id "cities" from
// the Bindings collection, and then calls the addHandlerAsync method to add an event handler for the
// dataChanged event of the binding.
function addBindingDataChangedEventHandler() {
    Office.select("bindings#cities", function onError(){}).addHandlerAsync(Office.EventType.BindingDataChanged,
    function (eventArgs) {
        doSomethingWithBinding(eventArgs.binding);
    });
}

Office.useShortNamespace(useShortNamespace)

Toggles on and off the Office alias for the full Microsoft.Office.WebExtension namespace.

export function useShortNamespace(useShortNamespace: boolean): void;

Parameters

useShortNamespace

boolean

True to use the shortcut alias; otherwise false to disable it. The default is true.

Returns

void

Remarks

Support details

For more information about Office application and server requirements, see Requirements for running Office Add-ins.

Supported applications, by platform

Office on the web Office on Windows Office on Mac Office on iPad Outlook on mobile devices
Excel Supported Supported Not supported Supported Not applicable
Outlook Supported Supported Supported Supported Supported
PowerPoint Supported Supported Not supported Supported Not applicable
Project Not supported Supported Not supported Not supported Not applicable
Word Supported Supported Not supported Supported Not applicable

Examples

function startUsingShortNamespace() {
    if (typeof Office === 'undefined') {
        Microsoft.Office.WebExtension.useShortNamespace(true);
    }
    else {
        Office.useShortNamespace(true);
    }
    write('Office alias is now ' + typeof Office);
}

function stopUsingShortNamespace() {
    if (typeof Office === 'undefined') {
        Microsoft.Office.WebExtension.useShortNamespace(false);
    }
    else {
        Office.useShortNamespace(false);
    }
    write('Office alias is now ' + typeof Office);
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}