Office.Settings interface

Ajoute un gestionnaire d’événements pour l’événement settingsChanged.

Important : le code de votre complément peut inscrire un gestionnaire pour l’événement settingsChanged lorsque le complément s’exécute avec n’importe quel client Excel, mais l’événement se déclenche uniquement lorsque le complément est chargé avec une feuille de calcul ouverte dans Excel sur le web et que plusieurs utilisateurs modifient la feuille de calcul (co-création). Par conséquent, l’événement settingsChanged est pris en charge uniquement dans Excel sur le web dans les scénarios de co-création.

addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Paramètres

Retours

Remarques

Ensemble de conditions requises : pas dans un ensemble

Vous pouvez ajouter plusieurs gestionnaires d’événements pour le eventType spécifié tant que le nom de chaque fonction de gestionnaire d’événements est unique.

Ajoute un gestionnaire d’événements pour l’événement settingsChanged.

Important : le code de votre complément peut inscrire un gestionnaire pour l’événement settingsChanged lorsque le complément s’exécute avec n’importe quel client Excel, mais l’événement se déclenche uniquement lorsque le complément est chargé avec une feuille de calcul ouverte dans Excel sur le web et que plusieurs utilisateurs modifient la feuille de calcul (co-création). Par conséquent, l’événement settingsChanged est pris en charge uniquement dans Excel sur le web dans les scénarios de co-création.

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

Paramètres

Retours

Remarques

Ensemble de conditions requises : pas dans un ensemble

Vous pouvez ajouter plusieurs gestionnaires d’événements pour le eventType spécifié tant que le nom de chaque fonction de gestionnaire d’événements est unique.

Exemples

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; 
}

Récupère le paramètre spécifié.

get(name: string): any;

Paramètres

Retours

Objet dont les noms de propriétés sont mappés à des valeurs sérialisées JSON.

Remarques

Ensemble de conditions requises : Paramètres

Exemples

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; 
}

Lit tous les paramètres persistants dans le document et actualise la copie de ces paramètres en mémoire pour le complément de contenu ou du volet Office.

refreshAsync(callback?: (result: AsyncResult<Office.Settings>) => void): void;

Paramètres

Retours

Remarques

Ensemble de conditions requises : pas dans un ensemble

Cette méthode est utile dans les scénarios de co-création Excel, Word et PowerPoint lorsque plusieurs instances du même complément fonctionnent sur le même document. Étant donné que chaque complément fonctionne sur une copie en mémoire des paramètres chargés à partir du document au moment où l’utilisateur l’a ouvert, les valeurs de paramètres utilisées par chaque utilisateur peuvent être désynchronisées. Cela peut se produire chaque fois qu’une instance du complément appelle la méthode Settings.saveAsync pour conserver tous les paramètres de cet utilisateur dans le document. L’appel de la méthode refreshAsync à partir du gestionnaire d’événements pour l’événement settingsChanged du complément actualise les valeurs de paramètres pour tous les utilisateurs.

Dans la fonction de rappel passée à la méthode refreshAsync, vous pouvez utiliser les propriétés de l’objet AsyncResult pour renvoyer les informations suivantes.

Exemples

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; 
}

Supprime le paramètre spécifié.

Important : n’oubliez pas que la méthode Settings.remove affecte uniquement la copie en mémoire du conteneur de propriétés de paramètres. 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;

Paramètres

Retours

Remarques

Ensemble de conditions requises : Paramètres

null est une valeur valide pour un paramètre. Ainsi, l’affectation de la valeur null au paramètre n’entraînera pas sa suppression du conteneur des propriétés des paramètres.

Exemples

function removeMySetting() {
    Office.context.document.settings.remove('mySetting');
}

Supprime un gestionnaire d’événements pour l’événement settingsChanged.

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

Paramètres

Retours

Remarques

Ensemble de conditions requises : pas dans un ensemble

Si le paramètre handler facultatif est omis lors de l’appel de la méthode removeHandlerAsync, tous les gestionnaires d’événements pour le type d’événement spécifié seront supprimés.

Lorsque la fonction que vous avez passée au paramètre de rappel s’exécute, elle reçoit un objet AsyncResult auquel vous pouvez accéder à partir du seul paramètre de la fonction de rappel.

Dans la fonction de rappel passée à la méthode removeHandlerAsync, vous pouvez utiliser les propriétés de l’objet AsyncResult pour renvoyer les informations suivantes.

Supprime un gestionnaire d’événements pour l’événement settingsChanged.

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

Paramètres

Retours

Remarques

Ensemble de conditions requises : pas dans un ensemble

Si le paramètre handler facultatif est omis lors de l’appel de la méthode removeHandlerAsync, tous les gestionnaires d’événements pour le type d’événement spécifié seront supprimés.

Lorsque la fonction que vous avez passée au paramètre de rappel s’exécute, elle reçoit un objet AsyncResult auquel vous pouvez accéder à partir du seul paramètre de la fonction de rappel.

Dans la fonction de rappel passée à la méthode removeHandlerAsync, vous pouvez utiliser les propriétés de l’objet AsyncResult pour renvoyer les informations suivantes.

Exemples

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; 
}

Fait persister la copie en mémoire du conteneur de propriétés des paramètres dans le document.

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

Paramètres

Retours

Remarques

Ensemble de conditions requises : Paramètres

Tous les paramètres précédemment enregistrés par un complément sont chargés lorsqu’il est initialisé. Par conséquent, pendant la durée de vie de la session, vous pouvez simplement utiliser les méthodes set et get pour travailler avec la copie en mémoire du conteneur de propriétés de paramètres. Si vous souhaitez conserver les paramètres afin qu’ils soient disponibles lors de la prochaine utilisation du complément, utilisez la méthode saveAsync.

Remarque : La méthode saveAsync conserve le conteneur de propriétés des paramètres en mémoire dans le fichier de document. Toutefois, les modifications apportées au fichier document lui-même sont enregistrées uniquement lorsque l’utilisateur (ou le paramètre de récupération automatique) enregistre le document dans le système de fichiers. La méthode refreshAsync n’est utile que dans les scénarios de co-création lorsque d’autres instances du même complément peuvent modifier les paramètres et que ces modifications doivent être mises à la disposition de toutes les instances.

Fait persister la copie en mémoire du conteneur de propriétés des paramètres dans le document.

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

Paramètres

Retours

Remarques

Ensemble de conditions requises : Paramètres

Tous les paramètres précédemment enregistrés par un complément sont chargés lorsqu’il est initialisé. Par conséquent, pendant la durée de vie de la session, vous pouvez simplement utiliser les méthodes set et get pour travailler avec la copie en mémoire du conteneur de propriétés de paramètres. Si vous souhaitez conserver les paramètres afin qu’ils soient disponibles lors de la prochaine utilisation du complément, utilisez la méthode saveAsync.

Remarque : La méthode saveAsync conserve le conteneur de propriétés des paramètres en mémoire dans le fichier de document. Toutefois, les modifications apportées au fichier document lui-même sont enregistrées uniquement lorsque l’utilisateur (ou le paramètre de récupération automatique) enregistre le document dans le système de fichiers. La méthode refreshAsync n’est utile que dans les scénarios de co-création lorsque d’autres instances du même complément peuvent modifier les paramètres et que ces modifications doivent être mises à la disposition de toutes les instances.

Exemples

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; 
}

Définit ou crée le paramètre spécifié.

Important : n’oubliez pas que la méthode Settings.set affecte uniquement la copie en mémoire du conteneur de propriétés settings. 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;

Paramètres

Retours

Remarques

Ensemble de conditions requises : Paramètres

La méthode set crée un nouveau paramètre du nom spécifié s’il n’existe pas déjà, ou définit un paramètre existant du nom spécifié dans la copie en mémoire du conteneur de propriétés de paramètres. Après avoir appelé la méthode Settings.saveAsync, la valeur est stockée dans le document en tant que représentation JSON sérialisée de son type de données.

Exemples

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