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
| add |
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. |
| add |
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. |
| refresh |
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. |
| remove |
Removes an event handler for the settingsChanged event. |
| remove |
Removes an event handler for the settingsChanged event. |
| save |
Persists the in-memory copy of the settings property bag in the document. |
| save |
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');
}