Edit

Share via


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

Applications: Excel, PowerPoint, Word

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

addHandlerAsync(eventType, handler, 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 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.

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.

removeHandlerAsync(eventType, 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.

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

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 type Office.SettingsChangedEventArgs. Required.

options
Office.AsyncContextOptions

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

callback

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

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

Property Use
AsyncResult.value Always returns undefined because there's 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 Define an item of any type that's returned in the AsyncResult object without being altered.

Returns

void

Remarks

Requirement set: Not in a set

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

addHandlerAsync(eventType, handler, 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 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.

addHandlerAsync(eventType: Office.EventType, handler: any, 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 type Office.SettingsChangedEventArgs. Required.

callback

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

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

Property Use
AsyncResult.value Always returns undefined because there's 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 Define an item of any type that's returned in the AsyncResult object without being altered.

Returns

void

Remarks

Requirement set: Not in a set

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 set: Settings

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: Office.AsyncResult<Office.Settings>) => void

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

Returns

void

Remarks

Requirement set: Not in a set

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
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 Define an item of any type that's returned in the AsyncResult object without being altered.

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 set: Settings

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

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: Office.AsyncResult<void>) => void

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

Returns

void

Remarks

Requirement set: Not in a set

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.

Property Use
AsyncResult.value Always returns undefined because there's no data or object to retrieve when setting formats.
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 Define an item of any type that's returned in the AsyncResult object without being altered.

removeHandlerAsync(eventType, callback)

Removes an event handler for the settingsChanged event.

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

Parameters

eventType
Office.EventType

Specifies the type of event to remove. Required.

callback

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

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

Returns

void

Remarks

Requirement set: Not in a set

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.

Property Use
AsyncResult.value Always returns undefined because there's no data or object to retrieve when setting formats.
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 Define an item of any type that's returned in the AsyncResult object without being altered.

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: Office.AsyncResult<void>) => void

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

Returns

void

Remarks

Requirement set: Settings

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
AsyncResult.value Always returns undefined because there's 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 Define an item of any type that's returned in the AsyncResult object without being altered.

saveAsync(callback)

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

saveAsync(callback?: (result: AsyncResult<void>) => void): void;

Parameters

callback

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

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

Returns

void

Remarks

Requirement set: Settings

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
AsyncResult.value Always returns undefined because there's 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 Define an item of any type that's returned in the AsyncResult object without being altered.

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 set: Settings

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.

Examples

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