Settings object (JavaScript API for Office)

Office Add-ins

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

Last modified: June 22, 2015

Note Note

The name "apps for Office" is changing to "Office Add-ins". During the transition, the documentation and the UI of some Office host applications and Visual Studio tools might still use the term "apps for Office". For details, see New name for apps for Office and SharePoint.

Hosts:

Access, Excel, PowerPoint, Word

Available in Requirement set

Settings

Last changed in

1.1

See all support details

Office.context.document.settings

Methods

Name

Description

addHandlerAsync

Adds an event handler for the settingsChanged event.

get

Retrieves the specified setting.

refreshAsync

Reads all settings persisted in the document and refreshes the app's copy of those settings held in memory.

remove

Removes the specified setting.

removeHandlerAsync

Removes an event handler for the settingsChanged event.

saveAsync

Saves the settings.

set

Sets or creates the specified setting.

Events

Name

Description

settingsChanged

Occurs when a setting is changed.

The settings created by using the methods of the Settings object are saved per app and per document. That is, they are available only to the app 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.

A checkmark (√) in the following matrix indicates that this object is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this object.

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

Office for Windows desktop

Office Online
(in browser)

Office for iPad

Access

Excel

PowerPoint

Word

Available in requirement sets

Settings

App types

Content, task pane

Library

Office.js

Namespace

Office

Version

Changes

1.1

Added support for Excel and Word in Office for iPad.

1.1

1.0

Introduced

Show:
© 2015 Microsoft