Persister l’état et les paramètres des compléments

Les compléments Office sont essentiellement des applications web qui s’exécutent dans l’environnement sans état d’un navigateur, d’un iframe ou d’un contrôle WebView. Pour des raisons de concision, cet article utilise « contrôle de navigateur » pour signifier « contrôle de navigateur ou d’affichage web ». Lorsqu’il est utilisé, votre complément peut avoir besoin de conserver des données pour assurer la continuité de certaines opérations ou fonctionnalités entre les sessions. Par exemple, votre complément peut avoir des paramètres personnalisés ou d’autres valeurs qu’il doit enregistrer et recharger la prochaine fois qu’il est initialisé, comme l’affichage préféré d’un utilisateur ou son emplacement par défaut. Pour conserver les données, vous pouvez :

Si votre complément doit conserver les données côté utilisateur, telles que les préférences ou l’historique des conversations, utilisez une base de données en ligne associée à l’identité de l’utilisateur plutôt que de vous appuyer uniquement sur le stockage du navigateur. Cette approche maintient les données disponibles entre les sessions et les documents, même si le stockage du navigateur local est effacé ou devient indisponible. Par exemple, vous pouvez utiliser l’authentification unique pour obtenir l’identité de l’utilisateur et associer ses données enregistrées à cette identité dans une base de données.

Remarque

Cet article s’applique uniquement à l’état persistant dans la même application Office. N’utilisez pas de cookies ou localStorage pour conserver ou partager l’état entre les applications Office (par exemple, ne pas enregistrer les données dans Word et tenter de les lire dans Excel). La persistance inter-applications n’est pas prise en charge et il n’est pas garanti qu’elle fonctionne sur n’importe quelle plateforme.

Stockage du navigateur

Conservez les données sur plusieurs instances de complément à l’aide des outils du contrôle de navigateur sous-jacent, tels que les cookies du navigateur ou le stockage web HTML5 (localStorage ou sessionStorage).

Remarque

Le stockage du navigateur est lié au profil de navigateur ou d’affichage web et peut être effacé par l’utilisateur, y compris par le biais des opérations d’effacement du cache des compléments Office. Utilisez-le pour les données temporaires ou récupérables, ou comme cache local, plutôt que comme seule copie persistante des données utilisateur importantes.

Certains navigateurs ou les paramètres de navigateur de l’utilisateur peuvent bloquer les techniques de stockage basées sur le navigateur. Testez la disponibilité, comme indiqué dans Utilisation de l’API de stockage web.

Partitionnement du stockage

Stockez toutes les données privées dans le stockage partitionné localStorage. Utiliser Office.context.partitionKey comme clé pour le stockage local. Cette approche garantit que les données stockées dans le stockage local ne sont disponibles que dans le même contexte.

Remarque

La clé de partition n’est pas définie dans les environnements sans partitionnement, tels que les contrôles WebView pour Office sur Windows. Là où elle est définie, la clé de partition est un hachage des deux domaines suivants.

  • Domaine où se trouve la fenêtre de navigateur de niveau supérieur, comme excel.cloud.microsoft dans le cas d’Excel sur le Web.
  • Domaine du complément, par myAddin.contoso.comexemple .

Ainsi, chacune des combinaisons suivantes crée une partition différente :

  • excel.cloud.microsoft + myAddin.contoso.com
  • word.cloud.microsoft + myAddin.contoso.com
  • word.cloud.microsoft + myOtherAddin.contoso.com

L’exemple suivant montre comment utiliser la clé de partition avec localStorage.

// Store the value "Hello" in local storage with the key "myKey1".
setInLocalStorage("myKey1", "Hello");

// ... 

// Retrieve the value stored in local storage under the key "myKey1".
const message = getFromLocalStorage("myKey1");
console.log(message);

// ...

function setInLocalStorage(key: string, value: string) {
  const myPartitionKey = Office.context.partitionKey;

  // Check if local storage is partitioned. 
  // If so, use the partition to ensure the data is only accessible by your add-in.
  if (myPartitionKey) {
    localStorage.setItem(myPartitionKey + key, value);
  } else {
    localStorage.setItem(key, value);
  }
}

function getFromLocalStorage(key: string) {
  const myPartitionKey = Office.context.partitionKey;

  // Check if local storage is partitioned.
  if (myPartitionKey) {
    return localStorage.getItem(myPartitionKey + key);
  } else {
    return localStorage.getItem(key);
  }
}

À compter de la version 115 des navigateurs basés sur Chromium, tels que Chrome et Edge, le partitionnement du stockage est activé pour empêcher le suivi intersite par canal auxiliaire spécifique (voir aussi stratégies de navigateur Microsoft Edge). À l’instar du partitionnement Office basé sur les clés, les données stockées par les API de stockage, telles que le stockage local, ne sont disponibles que pour les contextes ayant la même origine et le même site de niveau supérieur.

Paramètres spécifiques à l’application et persistance

Excel, Word et Outlook fournissent des API spécifiques aux applications pour enregistrer les paramètres et d’autres données. Utilisez ces API au lieu des API courantes mentionnées plus loin dans cet article afin que votre complément suive des modèles cohérents et soit optimisé pour l’application ciblée.

Paramètres dans Excel et Word

Les API JavaScript spécifiques à l’application pour Excel et pour Word permettent également d’accéder aux paramètres personnalisés. Les paramètres sont propres à un seul fichier Excel et au couplage de compléments. Pour plus d’informations, consultez Excel.SettingCollection et Word. SettingCollection.

L’exemple suivant montre comment créer et accéder à un paramètre dans Excel. Le processus est fonctionnellement équivalent dans Word, qui utilise Document.settings au lieu de Workbook.settings.

await Excel.run(async (context) => {
    const settings = context.workbook.settings;
    settings.add("NeedsReview", true);
    const needsReview = settings.getItem("NeedsReview");
    needsReview.load("value");

    await context.sync();
    console.log("Workbook needs review : " + needsReview.value);
});

Données XML personnalisées dans Excel et Word

Les formats de fichier Open XML.xlsxet .docx permettent à votre complément d’incorporer des données XML personnalisées dans le classeur Excel ou dans Word document. Ces données sont conservées avec le fichier, indépendamment du complément.

A Word. Document et Excel.Workbook contiennent un , qui est une CustomXmlPartCollectionliste de CustomXmlParts. Ceci octroie l’accès aux chaînes XML et ID correspondantes uniques. En stockant ces ID en tant que paramètres, votre complément peut stocker les touches de ses parties XML entre les sessions.

Les exemples suivants montrent comment utiliser des parties XML personnalisées avec un classeur Excel. Le premier bloc de code montre comment incorporer des données XML. Il contient une liste de relecteurs, puis en utilisant les paramètres du classeur pour enregistrer le fichier XMLid pour leur récupération future. Le deuxième bloc montre comment accéder à ce XML ultérieurement. Le paramètre « ContosoReviewXmlPartId » est chargé et transmis au classeurcustomXmlParts. Les données XML sont imprimées puis dans la console. Le processus est fonctionnellement équivalent dans Word, qui utilise Document.customXmlParts au lieu de Workbook.customXmlParts.

await Excel.run(async (context) => {
    // Add reviewer data to the document as XML
    const originalXml = "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
    const customXmlPart = context.workbook.customXmlParts.add(originalXml);
    customXmlPart.load("id");
    await context.sync();

    // Store the XML part's ID in a setting
    const settings = context.workbook.settings;
    settings.add("ContosoReviewXmlPartId", customXmlPart.id);
});

Remarque

CustomXMLPart.namespaceUri est renseigné uniquement si l’élément XML personnalisé niveau supérieur contient l’attributxmlns.

Propriétés personnalisées dans Excel et Word

Excel.DocumentProperties.custom et Word. Les propriétés DocumentProperties.customProperties représentent des collections de paires clé-valeur pour les propriétés définies par l’utilisateur. L’exemple Excel suivant montre comment créer une propriété personnalisée nommée Introduction avec la valeur « Hello », puis la récupérer.

await Excel.run(async (context) => {
    const customDocProperties = context.workbook.properties.custom;
    customDocProperties.add("Introduction", "Hello");
    await context.sync();
});

// ...

await Excel.run(async (context) => {
    const customDocProperties = context.workbook.properties.custom;
    const customProperty = customDocProperties.getItem("Introduction");
    customProperty.load(["key", "value"]);
    await context.sync();

    console.log("Custom key  : " + customProperty.key); // "Introduction"
    console.log("Custom value : " + customProperty.value); // "Hello"
});

Conseil

Dans Excel, les propriétés personnalisées peuvent également être définies au niveau de la feuille de calcul avec la propriété Worksheet.customProperties . Ces propriétés sont similaires aux propriétés personnalisées au niveau du document, sauf que la même clé peut être répétée sur plusieurs feuilles de calcul.

Comment enregistrer les paramètres dans un complément Outlook

Pour plus d’informations sur la procédure d’enregistrement des paramètres dans un complément Outlook, consultez Obtenir et définir les métadonnées d’un complément Outlook et Obtenir et définir des en-têtes Internet sur un message dans un complément Outlook.

Paramètres communs et persistance d’API

Les API communes fournissent des objets pour enregistrer l’état des compléments entre les sessions. Les valeurs des paramètres enregistrés sont associées à l’ID du complément qui les a créées. En interne, les objets , CustomPropertieset RoamingSettings stockent les données sous la Settingsforme d’un objet JSON (JavaScript Object Notation) sérialisé contenant des paires nom/valeur. Le nom (clé) de chaque valeur doit être un string. La valeur stockée peut être un code JavaScript string, , number, dateou object, mais pas une fonction.

Cet exemple de structure de conteneur de propriétés contient trois valeurs de chaîne définies nommées firstName, locationet defaultView.

{
    "firstName":"Erik",
    "location":"98052",
    "defaultView":"basic"
}

Une fois que le conteneur de propriétés settings a été enregistré lors d’une session de complément précédente, celui-ci peut charger les paramètres lors de l’initialisation du complément ou à tout moment par la suite pendant la session en cours du complément. Pendant la session, le complément gère les paramètres entièrement en mémoire à l’aide getdes méthodes , setet remove de l’objet qui correspond au type de paramètres que vous créez (Paramètres, CustomProperties ou RoamingSettings).

Importante

Pour conserver à l’emplacement de stockage les ajouts, mises à jour ou suppressions effectués au cours de la session active du complément, appelez la méthode de l’objet saveAsync correspondant utilisée pour utiliser ce type de paramètres. Les getméthodes , setet remove fonctionnent uniquement sur la copie en mémoire de l’emballage de propriétés paramètres. Si votre complément est fermé sans appel saveAsync, les modifications apportées aux paramètres au cours de cette session sont perdues.

Enregistrement de l’état et des paramètres d’un complément par document pour les compléments de contenu et du volet Office

Pour conserver l’état ou les paramètres personnalisés d’un complément de contenu ou de volet Office pour Word, Excel ou PowerPoint, utilisez l’objet Paramètres et ses méthodes. L’ensemble de propriétés que vous créez à l’aide des méthodes de l’objet Settings est disponible uniquement pour l’instance du complément de contenu ou de volet Office qui l’a créé, et uniquement à partir du document dans lequel vous l’enregistrez.

L’objet Settings se charge automatiquement en tant que partie de l’objet Document et est disponible lorsque le volet Office ou le complément de contenu est activé. Après avoir instancié l’objet Document , vous pouvez y accéder à l’aide Settings de la propriété settings de l’objet Document . Pendant la durée de vie de la session, utilisez les Settings.getméthodes , Settings.setet Settings.remove pour lire, écrire ou supprimer les paramètres persistants et l’état des compléments à partir de la copie en mémoire du conteneur de propriétés.

Étant donné que les méthodes d’ensemble et de suppression fonctionnent uniquement sur la copie en mémoire de l’ensemble de propriétés paramètres, pour enregistrer les paramètres nouveaux ou modifiés dans le document auquel le complément est associé, vous devez appeler la méthode Settings.saveAsync .

Créer ou mettre à jour la valeur d’un paramètre

L’exemple de code suivant montre comment utiliser la méthode Settings.set pour créer un paramètre appelé 'themeColor' avec la valeur 'green'. Le premier paramètre de la méthode set est le nom (Id) sensible à la casse du paramètre à définir ou à créer. Le second paramètre est la value du paramètre.

Office.context.document.settings.set('themeColor', 'green');

Le paramètre portant le nom spécifié est créé s’il n’existe pas déjà, ou sa valeur est mise à jour s’il existe. Utilisez la Settings.saveAsync méthode pour conserver les paramètres nouveaux ou mis à jour dans le document.

Obtenir la valeur d’un paramètre

L’exemple suivant illustre comment utiliser la méthode Settings.get pour obtenir la valeur d’un paramètre nommé « themeColor ». Le seul paramètre de la get méthode est le nom du paramètre qui respecte la casse.

write('Current value for mySetting: ' + Office.context.document.settings.get('themeColor'));

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

La get méthode renvoie la valeur qui a été enregistrée précédemment pour le nom du paramètre qui a été transmis. Si le paramètre n’existe pas, la méthode retourne null.

Supprimer un paramètre

L’exemple suivant illustre comment utiliser la méthode Settings.remove pour supprimer un paramètre portant le nom « themeColor ». Le seul paramètre de la remove méthode est le nom du paramètre qui respecte la casse.

Office.context.document.settings.remove('themeColor');

Rien ne se passe si le paramètre n’existe pas. Utilisez la Settings.saveAsync méthode pour conserver la suppression du paramètre du document.

Enregistrer vos paramètres

Pour enregistrer les ajouts, modifications ou suppressions que votre complément a effectués dans la copie en mémoire du conteneur de propriétés settings au cours de la session active, appelez la méthode Settings.saveAsync pour les stocker dans le document. Le seul paramètre de la saveAsync méthode est callback, qui est une fonction de rappel avec un seul paramètre.

Office.context.document.settings.saveAsync(function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Settings save failed. Error: ' + asyncResult.error.message);
    } else {
        write('Settings saved.');
    }
});
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

La fonction anonyme transmise à la saveAsync méthode en tant que paramètre de rappel s’exécute une fois l’opération terminée. Le paramètre asyncResult du rappel fournit l’accès à un AsyncResult objet qui contient le status de l’opération. Dans l’exemple suivant, la fonction vérifie la AsyncResult.status propriété pour voir si l’opération de sauvegarde a réussi ou échoué, puis affiche le résultat sur la page du complément.

Enregistrement du XML personnalisé dans le document

Utilisez un composant XML personnalisé pour stocker des informations qui comportent un caractère structuré ou lorsque vous souhaitez que les données soient accessibles dans plusieurs instances de votre complément. D’autres compléments peuvent également accéder aux données stockées de cette manière. Vous pouvez conserver le balisage XML personnalisé dans un complément de volet Office pour Word (et pour Excel et Word à l’aide de l’API spécifique à l’application, comme mentionné dans le paragraphe précédent). Dans Word, vous pouvez utiliser l’objet CustomXmlPart et ses méthodes. Le code suivant crée une partie XML personnalisée, puis affiche son ID et son contenu dans des balises div sur la page. La chaîne XML doit inclure un xmlns attribut.

function createCustomXmlPart() {
    const xmlString = "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
    Office.context.document.customXmlParts.addAsync(xmlString,
        (asyncResult) => {
            $("#xml-id").text("Your new XML part's ID: " + asyncResult.value.id);
            asyncResult.value.getXmlAsync(
                (asyncResult) => {
                    $("#xml-blob").text(asyncResult.value);
                }
            );
        }
    );
}

Pour récupérer un composant XML personnalisé, utilisez la méthode getByIdAsync . L’ID est un GUID généré lorsque vous créez la partie XML. Vous ne connaissez donc pas l’ID lors du codage. Pour cette raison, stockez l’ID de la partie XML en tant que paramètre et dotez-la d’une clé mémorable lors de la création d’une partie XML. L’exemple de méthode suivant montre comment procéder.

function createCustomXmlPartAndStoreId() {
   const xmlString = "<Reviewers xmlns='http://schemas.contoso.com/review/1.0'><Reviewer>Juan</Reviewer><Reviewer>Hong</Reviewer><Reviewer>Sally</Reviewer></Reviewers>";
   Office.context.document.customXmlParts.addAsync(xmlString,
       (asyncResult) => {
           Office.context.document.settings.set('ReviewersID', asyncResult.value.id);
           Office.context.document.settings.saveAsync();
       }
   );
}

Le code suivant montre comment récupérer la partie XML en obtenant d’abord son identifiant partir d’un paramètre.

function getReviewers() {
   const reviewersXmlId = Office.context.document.settings.get('ReviewersID');
   Office.context.document.customXmlParts.getByIdAsync(reviewersXmlId,
       (asyncResult) => {
           asyncResult.value.getXmlAsync(
               (asyncResult) => {
                   $("#xml-blob").text(asyncResult.value);
               }
           );
       }
   );
}

Voir aussi