office package

Reference

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

Office.Binding

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

Share via

office package

Classes

Interfaces

Type Aliases

Enums

Functions

Function Details

Office.initialize(reason)

Parameters

Returns

Remarks

Examples

Office.isSetSupported(name, minVersion)

Parameters

Returns

Office.onReady(callback)

Parameters

Returns

Office.select(expression, callback)

Parameters

Returns

Remarks

Examples

Office.useShortNamespace(useShortNamespace)

Parameters

Returns

Remarks

Examples

Additional resources