Office.RoamingSettings interface

Paquet:

outlook

Les paramètres créés à l’aide des méthodes de l’objet RoamingSettings sont enregistrés par complément et par utilisateur. En d’autres termes, elles ne sont disponibles que pour le complément qui les a créées et uniquement dans la boîte aux lettres de l’utilisateur dans laquelle elles sont enregistrées.

Bien que l’API du complément Outlook limite l’accès à ces paramètres au complément qui les a créés, ces paramètres ne doivent pas être considérés comme un stockage sécurisé. Ils sont accessibles via les services web Exchange ou l’interface MAPI étendue. Ils ne doivent pas être utilisés pour stocker des informations sensibles, telles que les informations d’identification ou les jetons de sécurité des utilisateurs.

Le nom d’un paramètre est une donnée String, alors que sa valeur peut être une donnée String, Number, Boolean, Null, Object ou Array.

L’objet RoamingSettings est accessible via la propriété roamingSettings dans l’espace de noms Office.context.

Pour plus d’informations sur RoamingSettings, consultez l’article Obtenir et définir les métadonnées d’un complément Outlook.

Remarques

Jeu d’API : Boîte aux lettres 1.1

Important:

• L’objet RoamingSettings est initialisé à partir du stockage persistant uniquement lors du premier chargement du complément. Pour les volets Office, cela signifie qu’il n’est initialisé que lorsque le volet Office s’ouvre pour la première fois. Si le volet Office navigue vers une autre page ou recharge la page active, l’objet en mémoire est réinitialisé à ses valeurs initiales, même si votre complément a des modifications persistantes. Les modifications persistantes ne sont pas disponibles tant que le volet des tâches (ou l’élément dans le cas des compléments sans interface utilisateur) est fermé et rouvert.

• Dans Outlook classique sur Windows, si les paramètres d’itinérance étaient configurés sur un autre client Outlook, le client de bureau n’a pas besoin d’être redémarré. Toutefois, le complément doit être rechargé pour accéder à ces paramètres. Dans Outlook sur le web, sur Mac et dans le nouvel Outlook sur Windows, vous devez actualiser le navigateur ou redémarrer le client pour accéder aux paramètres d’itinérance définis sur un autre client.

Niveau d’autorisation minimal : restreint

Mode Outlook applicable : Rédiger ou Lire

Utilisateur

• Office.Context : roamingSettings

Méthodes

get(name)	Récupère le paramètre spécifié.
remove(name)	Supprime le paramètre spécifié.
saveAsync(callback)	Enregistre les paramètres. Tous les paramètres précédemment enregistrés par un complément sont chargés lors de son initialisation. Pendant la durée de vie de la session, vous pouvez donc simplement utiliser les méthodes set and get pour travailler avec la copie en mémoire du conteneur de propriétés settings. Pour conserver les paramètres afin qu’ils soient disponibles lors de la prochaine utilisation du complément, utilisez la méthode correspondante saveAsync .
set(name, value)	Définit ou crée le paramètre spécifié. La set méthode 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é. La valeur est stockée dans le document sous forme de représentation JSON sérialisée de son type de données. Un maximum de 32 Ko est disponible pour les paramètres de chaque complément. Une erreur avec le code 9057 est générée lorsque cette limite de taille est dépassée. Les modifications apportées aux paramètres à l’aide de la set méthode ne sont enregistrées sur le serveur que lorsque la saveAsync méthode est appelée.

Détails de la méthode

get(name)

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

get(name: string): any;

Paramètres

name

string

Nom respectant l’emploi des majuscules et minuscules pour le paramètre à récupérer.

Retours

any

Type : chaîne | Nombre | Booléen | Objet | Tableau

Remarques

Jeu d’API : Boîte aux lettres 1.1

Niveau d’autorisation minimal : restreint

Mode Outlook applicable : Rédiger ou Lire

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

const settingName = (document.getElementById("settingName") as HTMLInputElement).value;
const settingValue = Office.context.roamingSettings.get(settingName);
(document.getElementById("settingValue") as HTMLInputElement).value = settingValue;
console.log(`The value of setting "${settingName}" is "${settingValue}".`);

remove(name)

Supprime le paramètre spécifié.

remove(name: string): void;

Paramètres

name

string

Nom respectant l’emploi des majuscules et minuscules pour le paramètre à supprimer.

Retours

void

Remarques

Jeu d’API : Boîte aux lettres 1.1

Niveau d’autorisation minimal : restreint

Mode Outlook applicable : Rédiger ou Lire

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

// Remove the specified setting from the mailbox.
const settingName = (document.getElementById("settingName") as HTMLInputElement).value;
Office.context.roamingSettings.remove(settingName);
console.log(`The "${settingName}" setting has been removed.`);

saveAsync(callback)

Enregistre les paramètres.

Tous les paramètres précédemment enregistrés par un complément sont chargés lors de son initialisation. Pendant la durée de vie de la session, vous pouvez donc simplement utiliser les méthodes set and get pour travailler avec la copie en mémoire du conteneur de propriétés settings. Pour conserver les paramètres afin qu’ils soient disponibles lors de la prochaine utilisation du complément, utilisez la méthode correspondante saveAsync .

saveAsync(callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Paramètres

callback

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

Facultatif. Lorsque la méthode est terminée, la fonction passée dans le callback paramètre est appelée avec un seul paramètre de type Office.AsyncResult.

Retours

void

Remarques

Jeu d’API : Boîte aux lettres 1.1

Niveau d’autorisation minimal : restreint

Mode Outlook applicable : Rédiger ou Lire

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

// Save settings in the mailbox to make it available in future sessions.
Office.context.roamingSettings.saveAsync(function(result) {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
  } else {
    console.log(`Settings saved with status: ${result.status}`);
  }
});

set(name, value)

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

La set méthode 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é. La valeur est stockée dans le document sous forme de représentation JSON sérialisée de son type de données.

Un maximum de 32 Ko est disponible pour les paramètres de chaque complément. Une erreur avec le code 9057 est générée lorsque cette limite de taille est dépassée.

Les modifications apportées aux paramètres à l’aide de la set méthode ne sont enregistrées sur le serveur que lorsque la saveAsync méthode est appelée.

set(name: string, value: any): void;

Paramètres

name

string

Nom qui respecte la casse du paramètre à définir ou créer.

value

any

Spécifie la valeur à stocker.

Retours

void

Remarques

Jeu d’API : Boîte aux lettres 1.1

Niveau d’autorisation minimal : restreint

Mode Outlook applicable : Rédiger ou Lire

Exemples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

const settingName = (document.getElementById("settingName") as HTMLInputElement).value;
const settingValue = (document.getElementById("settingValue") as HTMLInputElement).value;
Office.context.roamingSettings.set(settingName, settingValue);
console.log(`Setting "${settingName}" set to value "${settingValue}".`);