office package

Classes

Office.TableData

Represents the data in a table or a 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 host 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 the data in a table or a Office.TableBinding.

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 data in a table or a Office.TableBinding.

OfficeExtension.EventHandlerResult

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

OfficeExtension.EventHandlers

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

OfficeExtension.TrackedObjects

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

Interfaces

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 configuring the prompt and identifying the binding that is created.

Office.AddinCommands.Event

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

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.

Office.Binding

Represents a binding to a section of the document.

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 is accessed using Office.context.

Office.ContextInformation

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

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.Dialog

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

Office.DialogOptions

Provides options for how a dialog is displayed.

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

Provides options for configuring the binding that is created.

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.IPromiseConstructor

Provides options for configuring the binding that is created.

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 with File > Office Account > Office Theme UI, which is applied across all Office host applications. Using Office theme colors is appropriate for mail and task pane add-ins.

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 what Requirement Sets are supported in current environment.

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.

Office.Slice

Represents a slice of a document file.

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.

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.

OfficeExtension.DebugInfo

Provides information about an error.

OfficeExtension.EmbeddedOptions

Provides options for configuring the binding that is created.

OfficeExtension.EventInfo

Provides options for configuring the binding that is created.

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.

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

BindingDataChanged and BindingSelectionChanged hosts
Access, Excel, Word
Office.FileType

Specifies the format in which to return the document.

Office.FilterType

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

Office.GoToType

Specifies the type of place or object to navigate to.

Office.HostType

Specifies the host 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 host 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.Table

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

Office.ValueFormat

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

Functions

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 host 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.

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 host 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 host application, it will call the callback and resolve the promise with "null" for both the host and platform.

select(expression, callback)

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

useShortNamespace(useShortNamespace)

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

Function Details

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

A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

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

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad OWA for Devices Office for Mac
Access Y
Excel Y Y Y
Outlook Y Y Y Y
PowerPoint Y Y Y
Project Y
Word Y Y Y

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 function.
    $(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; 
}

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 host 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 host application, it will call the callback and resolve the promise with "null" for both the host and platform.

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

Parameters

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

An optional callback method, that will receive the host 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: HostType, platform: PlatformType }>

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

select(expression, callback)

Returns a promise of an object described in the expression. Callback is invoked only if method 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: AsyncResult<any>) => void

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

Returns

Binding

Remarks

Support details

A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

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

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad
Access Y
Excel Y Y Y
Word Y Y

Examples

// The following code example uses the select method 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);
    });
}

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

A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

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

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad OWA for Devices Office for Mac
Access Y
Excel Y Y Y
Outlook Y Y Y Y
PowerPoint Y Y Y
Project Y
Word Y Y Y

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