Settings.set method
Sets or creates the specified setting.
| Hosts: | Access, Excel, PowerPoint, Word |
| Available in Requirement set | Settings |
| Last changed in | 1.1 |
Office.context.document.settings.set(name, value);Parameters
name
Type: string
The case-sensitive name of the setting to set or create.
value
Type: string, number, boolean, null, object or array
Specifies the value to be stored.
Remarks
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.
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.
Example
function setMySetting() {
Office.context.document.settings.set('mySetting', 'mySetting value');
}
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.
| 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 |
| Available in requirement sets | Settings |
| Minimum permission level | Restricted |
| Add-in types | Content, task pane |
| Library | Office.js |
| Namespace | Office |
Support history
| Version | Changes |
|---|---|
| 1.1 | Added support for PowerPoint Online. |
| 1.1 | Added support for Excel, PowerPoint, and Word in Office for iPad. |
| 1.1 | Added support for custom settings in content add-ins for Access. |
| 1.0 | Introduced |