Office.RoamingSettings interface

  • Référence
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. Autrement dit, ils sont disponibles uniquement pour le complément qui les a créés, et uniquement à partir de la boîte aux lettres de l’utilisateur dans laquelle ils sont enregistrés.

Bien que l’API de complément Outlook limite l’accès à ces paramètres uniquement au complément qui les a créés, ces paramètres ne doivent pas être considérés comme du 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 des informations d’identification utilisateur ou des jetons de sécurité.

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 en savoir plus sur RoamingSettings, consultez Obtenir et définir des métadonnées de complément pour un complément Outlook.

Remarques

[ Ensemble d’API : Boîte aux lettres 1.1 ]

Important:

  • L’objet RoamingSettings est initialisé à partir du stockage persistant uniquement lorsque le complément est chargé pour la première fois. Pour les volets office, cela signifie qu’il est initialisé uniquement lors de l’ouverture initiale du volet Office. Si le volet Office accède à 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 conservé des modifications. Les modifications persistantes ne seront pas disponibles tant que le volet Office (ou l’élément dans le cas de compléments sans interface utilisateur) n’est pas fermé et rouvert.

  • Lorsqu’ils sont définis et enregistrés via Outlook sur Windows ou mac, ces paramètres sont répercutés dans Outlook sur le web uniquement après une actualisation du navigateur.

Niveau d’autorisation minimal : restreint

Mode Outlook applicable : Rédiger ou Lire

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 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 la prochaine fois que le complément est utilisé, utilisez la saveAsync méthode .
set(name, value)

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

La set méthode crée un 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 pas enregistrées sur le serveur tant que la saveAsync méthode n’est pas 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 : String | Nombre | Boolean | Objet | Array

Remarques

[ Ensemble 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 = $("#settingName").val();
const settingValue = Office.context.roamingSettings.get(settingName);
$("#settingValue").val(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

[ Ensemble d’API : Boîte aux lettres 1.1 ]

Niveau d’autorisation minimal : restreint

Mode Outlook applicable : Rédiger ou Lire

saveAsync(callback)

Enregistre les 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 la prochaine fois que le complément est utilisé, utilisez la saveAsync méthode .

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

Paramètres

callback

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

Optional. Une fois la méthode 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

[ Ensemble 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 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 pas enregistrées sur le serveur tant que la saveAsync méthode n’est pas 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

[ Ensemble 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 = $("#settingName").val();
const settingValue = $("#settingValue").val();
Office.context.roamingSettings.set(settingName, settingValue);
console.log(`Setting "${settingName}" set to value "${settingValue}".`);