diff --git a/types/office-js/index.d.ts b/types/office-js/index.d.ts index e885bfe235b3bb..490063fb773aa6 100644 --- a/types/office-js/index.d.ts +++ b/types/office-js/index.d.ts @@ -4276,6 +4276,7 @@ declare namespace Office { * * 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. */ interface Settings { @@ -4293,7 +4294,7 @@ declare namespace Office { * You can add multiple event handlers for the specified eventType as long as the name of each event handler function is unique. * * @param eventType Specifies the type of event to add. Required. - * @param handler The event handler function to add. Required. + * @param handler The event handler function to add, whose only parameter is of type {@link Office.SettingsChangedEventArgs}. Required. * @param options Provides an option for preserving context data of any type, unchanged, for use in a callback. * @param callback Optional. A function that is invoked when the callback returns, whose only parameter is of type {@link Office.AsyncResult}. * @@ -4585,6 +4586,52 @@ declare namespace Office { */ set(name: string, value: any): void; } + /** + * Provides information about the settings that raised the settingsChanged event. + * + * @remarks + *
Requirement SetsSettings
+ * + * To add an event handler for the settingsChanged event, use the addHandlerAsync method of the + * {@link Office.Settings} object. + * + * The settingsChanged event fires only when your add-in's script calls the Settings.saveAsync method to persist + * the in-memory copy of the settings into the document file. The settingsChanged event is not triggered when the + * Settings.set or Settings.remove methods are called. + * + * The settingsChanged event was designed to let you to handle potential conflicts when two or more users are + * attempting to save settings at the same time when your add-in is used in a shared (co-authored) document. + * + * **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. + * + * **Support details** + * + * A capital Y in the following matrix indicates that this interface is supported in the corresponding Office host application. + * An empty cell indicates that the Office host application doesn't support this interface. + * + * For more information about Office host application and server requirements, see + * {@link https://docs.microsoft.com/office/dev/add-ins/concepts/requirements-for-running-office-add-ins | Requirements for running Office Add-ins}. + * + * *Supported hosts, by platform* + * + * + * + * + *
Office for Windows desktop Office Online (in browser) Office for iPad
Excel Y
Word Y Y
+ */ + interface SettingsChangedEventArgs { + /** + * Gets an {@link Office.Settings} object that represents the settings that raised the settingsChanged event. + */ + settings: Settings; + /** + * Get an {@link Office.EventType} enumeration value that identifies the kind of event that was raised. + */ + type: EventType; + } /** * Represents a slice of a document file. *