Office.Settings interface

Paquet:

office

Représente des paramètres personnalisés pour un complément de contenu ou de volet des tâches qui sont stockés dans le document hôte comme paires nom/valeur.

Remarques

Applications : Excel, PowerPoint, Word

Les paramètres créés à l’aide des méthodes de l’objet Settings sont enregistrés par complément et par document. En d’autres termes, ils ne sont disponibles que pour le complément qui les a créés et uniquement dans le document où ils sont enregistrés.

Le nom d’un paramètre est une chaîne, tandis que la valeur peut être une chaîne, un nombre, une valeur booléenne, une valeur null, un objet ou un tableau.

L’objet Settings est automatiquement chargé dans le cadre de l’objet Document et est disponible en appelant la propriété settings de cet objet lorsque le complément est activé.

Le développeur est chargé d’appeler la méthode saveAsync après avoir ajouté ou supprimé des paramètres pour enregistrer les paramètres dans le document.

Méthodes

addHandlerAsync(eventType, handler, options, callback)	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, handler, callback)	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.
get(name)	Récupère le paramètre spécifié.
refreshAsync(callback)	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.
remove(name)	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.
removeHandlerAsync(eventType, options, callback)	Supprime un gestionnaire d’événements pour l’événement settingsChanged.
removeHandlerAsync(eventType, callback)	Supprime un gestionnaire d’événements pour l’événement settingsChanged.
saveAsync(options, callback)	Fait persister la copie en mémoire du conteneur de propriétés des paramètres dans le document.
saveAsync(callback)	Fait persister la copie en mémoire du conteneur de propriétés des paramètres dans le document.
set(name, value)	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.

Détails de la méthode

addHandlerAsync(eventType, handler, options, callback)

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

eventType

Office.EventType

Spécifie le type d’événement à ajouter. Obligatoire.

handler

any

Fonction de gestionnaire d’événements à ajouter, dont le seul paramètre est de type Office.SettingsChangedEventArgs. Obligatoire.

options

Office.AsyncContextOptions

Fournit une option permettant de conserver les données de contexte de tout type, inchangées, pour une utilisation dans un rappel.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Propriété	Utilisation
AsyncResult.value	Retourne undefined toujours, car il n’y a pas de données ou d’objet à récupérer lors de l’ajout d’un gestionnaire d’événements.
AsyncResult.status	Déterminer si l’opération a réussi ou échoué.
AsyncResult.error	Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext	Définissez un élément de tout type retourné dans l’objet AsyncResult sans être modifié.

Retours

void

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.

addHandlerAsync(eventType, handler, callback)

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

eventType

Office.EventType

Spécifie le type d’événement à ajouter. Obligatoire.

handler

any

Fonction de gestionnaire d’événements à ajouter, dont le seul paramètre est de type Office.SettingsChangedEventArgs. Obligatoire.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Propriété	Utilisation
AsyncResult.value	Retourne undefined toujours, car il n’y a pas de données ou d’objet à récupérer lors de l’ajout d’un gestionnaire d’événements.
AsyncResult.status	Déterminer si l’opération a réussi ou échoué.
AsyncResult.error	Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext	Définissez un élément de tout type retourné dans l’objet AsyncResult sans être modifié.

Retours

void

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

get(name)

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

get(name: string): any;

Paramètres

name

string

Retours

any

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

refreshAsync(callback)

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

callback

(result: Office.AsyncResult<Office.Settings>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult. La value propriété du résultat est un objet Office.Settings avec les valeurs actualisées.

Retours

void

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’un 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.

Propriété	Utilisation
AsyncResult.value	Accéder à un objet Settings avec les valeurs actualisées.
AsyncResult.status	Déterminer si l’opération a réussi ou échoué.
AsyncResult.error	Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext	Définissez un élément de tout type retourné dans l’objet AsyncResult sans être modifié.

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

remove(name)

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

name

string

Retours

void

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

removeHandlerAsync(eventType, options, callback)

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

eventType

Office.EventType

Spécifie le type d’événement à supprimer. Obligatoire.

options

Office.RemoveHandlerOptions

Fournit des options pour déterminer le ou les gestionnaires d’événements qui sont supprimés.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

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.

Propriété	Utilisation
AsyncResult.value	Retourne undefined toujours, car il n’y a pas de données ou d’objet à récupérer lors de la définition des formats.
AsyncResult.status	Déterminer si l’opération a réussi ou échoué.
AsyncResult.error	Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext	Définissez un élément de tout type retourné dans l’objet AsyncResult sans être modifié.

removeHandlerAsync(eventType, callback)

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

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

Paramètres

eventType

Office.EventType

Spécifie le type d’événement à supprimer. Obligatoire.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

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.

Propriété	Utilisation
AsyncResult.value	Retourne undefined toujours, car il n’y a pas de données ou d’objet à récupérer lors de la définition des formats.
AsyncResult.status	Déterminer si l’opération a réussi ou échoué.
AsyncResult.error	Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext	Définissez un élément de tout type retourné dans l’objet AsyncResult sans être modifié.

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

saveAsync(options, callback)

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

options

Office.SaveSettingsOptions

Fournit des options d’enregistrement des paramètres.

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

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.

Propriété	Utilisation
AsyncResult.value	Retourne undefined toujours, car il n’y a pas d’objet ou de données à récupérer.
AsyncResult.status	Déterminer si l’opération a réussi ou échoué.
AsyncResult.error	Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext	Définissez un élément de tout type retourné dans l’objet AsyncResult sans être modifié.

saveAsync(callback)

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

callback

(result: Office.AsyncResult<void>) => void

Optional. Fonction appelée lorsque le rappel est retourné, dont le seul paramètre est de type Office.AsyncResult.

Retours

void

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.

Propriété	Utilisation
AsyncResult.value	Retourne undefined toujours, car il n’y a pas d’objet ou de données à récupérer.
AsyncResult.status	Déterminer si l’opération a réussi ou échoué.
AsyncResult.error	Accéder à un objet Error fournissant des informations sur l’erreur en cas d’échec de l’opération.
AsyncResult.asyncContext	Définissez un élément de tout type retourné dans l’objet AsyncResult sans être modifié.

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

set(name, value)

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

name

string

value

any

Spécifie la valeur à stocker.

Retours

void

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