Office.Settings interface

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

Remarks

HostsAccess, Excel, PowerPoint, Word
Requirement SetsSettings

The settings created by using the methods of the Settings object are saved per add-in and per document. That is, they are available only to the add-in that created them, and only from the document in which they are saved.

The name of a setting is a string, while the value can be a string, number, boolean, null, object, or array.

The Settings object is automatically loaded as part of the Document object, and is available by calling the settings property of that object when the add-in is activated.

The developer is responsible for calling the saveAsync method after adding or deleting settings to save the settings in the document.

Methods

addHandlerAsync(eventType, handler, options, callback)

Adds an event handler for the settingsChanged event.

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 Online, and more than one user is editing the spreadsheet (co-authoring). Therefore, effectively the settingsChanged event is supported only in Excel Online in co-authoring scenarios.

get(name)

Retrieves the specified setting.

refreshAsync(callback)

Reads all settings persisted in the document and refreshes the content or task pane add-in's copy of those settings held in memory.

remove(name)

Removes the specified setting.

Important: Be aware that the Settings.remove method affects only the in-memory copy of the settings property bag. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method.

removeHandlerAsync(eventType, options, callback)

Removes an event handler for the settingsChanged event.

saveAsync(options, callback)

Persists the in-memory copy of the settings property bag in the document.

set(name, value)

Sets or creates the specified setting.

Important: Be aware that the Settings.set method affects only the in-memory copy of the settings property bag. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document.

Method Details

addHandlerAsync(eventType, handler, options, callback)

Adds an event handler for the settingsChanged event.

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 Online, and more than one user is editing the spreadsheet (co-authoring). Therefore, effectively the settingsChanged event is supported only in Excel Online in co-authoring scenarios.

addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;
Parameters
eventType
Office.EventType

Specifies the type of event to add. Required.

handler
any

The event handler function to add, whose only parameter is of typeOffice.SettingsChangedEventArgs. Required.

options
Office.AsyncContextOptions

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

callback
(result: AsyncResult<void>) => void

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

Property Use to...
AsyncResult.value Always returns undefined because there is no data or object to retrieve when adding an event handler.
AsyncResult.status Determine the success or failure of the operation.
AsyncResult.error Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContext A user-defined item of any type that is returned in the AsyncResult object without being altered.

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
Excel Y

Returns
void
Remarks
Requirement SetsSettings

You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique.

Examples

function addSelectionChangedEventHandler() {
    Office.context.document.settings.addHandlerAsync(Office.EventType.SettingsChanged, MyHandler);
}

function MyHandler(eventArgs) {
    write('Event raised: ' + eventArgs.type);
    doSomethingWithSettings(eventArgs.settings);
}

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

get(name)

Retrieves the specified setting.

get(name: string): any;
Parameters
name
string
Returns
any

An object that has property names mapped to JSON serialized values.

Remarks
Requirement SetsSettings

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
PowerPoint Y Y Y
Word Y Y Y

Examples

function displayMySetting() {
    write('Current value for mySetting: ' + Office.context.document.settings.get('mySetting'));
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

refreshAsync(callback)

Reads all settings persisted in the document and refreshes the content or task pane add-in's copy of those settings held in memory.

refreshAsync(callback?: (result: AsyncResult<Office.Settings>) => void): void;
Parameters
callback
(result: AsyncResult<Office.Settings>) => void

Optional. A function that is invoked when the callback returns, whose only parameter is of typeOffice.AsyncResult. The value property of the result is an Office.Settings object with the refreshed values.

Returns
void
Remarks
Requirement SetsSettings

This method is useful in Excel, Word, and PowerPoint coauthoring scenarios when multiple instances of the same add-in are working against the same document. Because each add-in is working against an in-memory copy of the settings loaded from the document at the time the user opened it, the settings values used by each user can get out of sync. This can happen whenever an instance of the add-in calls the Settings.saveAsync method to persist all of that user's settings to the document. Calling the refreshAsync method from the event handler for the settingsChanged event of the add-in will refresh the settings values for all users.

In the callback function passed to the refreshAsync method, you can use the properties of the AsyncResult object to return the following information.

Property Use to...
AsyncResult.value Access a Settings object with the refreshed values.
AsyncResult.status Determine the success or failure of the operation.
AsyncResult.error Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContext A user-defined item of any type that is returned in the AsyncResult object without being altered.

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
PowerPoint Y Y Y
Word Y Y Y

Examples

function refreshSettings() {
    Office.context.document.settings.refreshAsync(function (asyncResult) {
        write('Settings refreshed with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

remove(name)

Removes the specified setting.

Important: Be aware that the Settings.remove method affects only the in-memory copy of the settings property bag. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method.

remove(name: string): void;
Parameters
name
string
Returns
void
Remarks
Requirement SetsSettings

null is a valid value for a setting. Therefore, assigning null to the setting will not remove it from the settings property bag.

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
PowerPoint Y Y Y
Word Y Y

Examples

function removeMySetting() {
    Office.context.document.settings.remove('mySetting');
}

removeHandlerAsync(eventType, options, callback)

Removes an event handler for the settingsChanged event.

removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult<void>) => void): void;
Parameters
eventType
Office.EventType

Specifies the type of event to remove. Required.

options
Office.RemoveHandlerOptions

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

callback
(result: AsyncResult<void>) => void

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

Returns
void
Remarks
Requirement SetsSettings

If the optional handler parameter is omitted when calling the removeHandlerAsync method, all event handlers for the specified eventType will be removed.

When the function you passed to the callback parameter executes, it receives an AsyncResult object that you can access from the callback function's only parameter.

In the callback function passed to the removeHandlerAsync method, you can use the properties of the AsyncResult object to return the following information.

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
PowerPoint Y Y Y

Examples

function removeSettingsChangedEventHandler() {
    Office.context.document.settings.removeHandlerAsync(Office.EventType.SettingsChanged, MyHandler);
}

function MyHandler(eventArgs) {
    write('Event raised: ' + eventArgs.type);
    doSomethingWithSettings(eventArgs.settings);
}

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

saveAsync(options, callback)

Persists the in-memory copy of the settings property bag in the document.

saveAsync(options?: SaveSettingsOptions, callback?: (result: AsyncResult<void>) => void): void;
Parameters
options
Office.SaveSettingsOptions

Provides options for saving settings.

callback
(result: AsyncResult<void>) => void

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

Returns
void
Remarks

Any settings previously saved by an add-in are loaded when it is initialized, so during the lifetime of the session you can just use the set and get methods to work with the in-memory copy of the settings property bag. When you want to persist the settings so that they are available the next time the add-in is used, use the saveAsync method.

Note: The saveAsync method persists the in-memory settings property bag into the document file. However, the changes to the document file itself are saved only when the user (or AutoRecover setting) saves the document to the file system. The refreshAsync method is only useful in coauthoring scenarios when other instances of the same add-in might change the settings and those changes should be made available to all instances.

Property Use to...
AsyncResult.value Always returns undefined because there is no object or data to retrieve.
AsyncResult.status Determine the success or failure of the operation.
AsyncResult.error Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContext A user-defined item of any type that is returned in the AsyncResult object without being altered.

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
PowerPoint Y Y Y
Word Y Y Y

Examples

function persistSettings() {
    Office.context.document.settings.saveAsync(function (asyncResult) {
        write('Settings saved with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

set(name, value)

Sets or creates the specified setting.

Important: Be aware that the Settings.set method affects only the in-memory copy of the settings property bag. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document.

set(name: string, value: any): void;
Parameters
name
string
value
any

Specifies the value to be stored.

Returns
void
Remarks
Requirement SetsSettings

The set method creates a new setting of the specified name if it does not already exist, or sets an existing setting of the specified name in the in-memory copy of the settings property bag. After you call the Settings.saveAsync method, the value is stored in the document as the serialized JSON representation of its data type. A maximum of 2MB is available for the settings of each add-in.

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
PowerPoint Y Y Y
Word Y Y Y

Examples

function setMySetting() {
    Office.context.document.settings.set('mySetting', 'mySetting value');
}