Conserver l’état et les paramètres du complément

Article
08/07/2024

Les compléments Office sont essentiellement des applications web s’exécutant dans l’environnement sans état d’un iframe de navigateur ou d’un contrôle webview. (Par souci de concision ci-dessous, cet article utilise « contrôle de navigateur » pour désigner « contrôle de navigateur ou de webview ». Lorsqu’il est utilisé, votre complément peut avoir besoin de conserver les données pour maintenir la continuité de certaines opérations ou fonctionnalités entre les sessions. Par exemple, votre complément peut disposer de paramètres personnalisés ou d’autres valeurs dont il a besoin pour l’enregistrement et le rechargement à la prochaine initialisation, tels que l’affichage préféré d’un utilisateur ou l’emplacement par défaut. Pour ce faire, vous pouvez procéder comme suit :

Utilisez les techniques fournies par le contrôle de navigateur sous-jacent.
Utilisez les API JavaScript Office spécifiques à l’application pour Excel, Word et Outlook qui stockent des données.

Si vous avez besoin de conserver l’état sur les documents, comme le suivi des préférences utilisateur dans tous les documents qu’ils ouvrent, vous devez utiliser une approche différente. Par exemple, vous pouvez utiliser l’authentification unique pour obtenir l’identité de l’utilisateur, puis enregistrer l’ID utilisateur et ses paramètres dans une base de données en ligne.

Stockage du navigateur

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

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

Partitionnement du stockage

En guise de bonne pratique, toutes les données privées doivent être stockées dans partitionné localStorage. Office.context.partitionKey fournit une clé à utiliser avec le stockage local. Cela garantit que les données stockées dans le stockage local sont uniquement disponibles dans le même contexte. L’exemple suivant montre comment utiliser la clé de partition avec localStorage. Notez que la clé de partition n’est pas définie dans les environnements sans partitionnement, tels que les contrôles de navigateur pour les applications Windows.

// 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 chromium, tels que Chrome et Edge, le partitionnement du stockage est activé pour empêcher le suivi intersites par canal latéral spécifique (voir aussi stratégies de navigateur Microsoft Edge). À l’instar du partitionnement basé sur une clé Office, les données stockées par les API de stockage, telles que le stockage local, sont uniquement disponibles 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 à l’application pour enregistrer des paramètres et d’autres données. Utilisez-les au lieu des API communes 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 fichier Excel unique et à un appairage de compléments. Pour plus d’informations, voir 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.xlsx et .docx Open XML permettent à votre complément d’incorporer des données XML personnalisées dans le classeur Excel ou le document Word. Ces données sont conservées avec le fichier, indépendamment du complément.

Word.Document et Excel.Workbook contiennent un CustomXmlPartCollection, qui est une liste 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 composants XML personnalisés 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

Les propriétés Excel.DocumentProperties.custom et Word.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 . Celles-ci sont similaires aux propriétés personnalisées au niveau du document, sauf que la même clé peut être répétée dans différentes feuilles de calcul.

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

Pour plus d’informations sur l’enregistrement des paramètres dans un complément Outlook, voir Obtenir et définir des métadonnées de complément pour un complément Outlook et Obtenir et définir des en-têtes Internet sur un message dans un complément Outlook.

Paramètres d’API courants et persistance

Les API communes fournissent des objets pour enregistrer l’état du complément entre les sessions. Les valeurs de paramètres enregistrées sont associées à l’ID du complément qui les a créées. En interne, les données accessibles avec les Settingsobjets , CustomPropertiesou RoamingSettings sont stockées sous la forme d’un objet JSON (JavaScript Object Notation) sérialisé qui contient des paires nom/valeur. Le nom (clé) de chaque valeur doit être un string, et la valeur stockée peut être 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"
}

Après avoir enregistré le conteneur des propriétés de paramètres durant la session de complément précédente, vous pouvez le charger pendant ou après l’initialisation du complément, durant la session actuelle du complément. Pendant la session, les paramètres sont gérés 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 les ajouts, mises à jour ou suppressions effectués pendant la session active du complément dans l’emplacement de stockage, vous devez appeler la saveAsync méthode de l’objet correspondant utilisé pour utiliser ce type de paramètres. Les getméthodes , setet remove fonctionnent uniquement sur la copie en mémoire du conteneur de propriétés des paramètres. Si votre complément est fermé sans appeler saveAsync, toutes les modifications apportées aux paramètres au cours de cette session seront 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 Settings et ses méthodes. Le conteneur de propriétés créé avec les méthodes de l’objet Settings est disponible uniquement pour l’instance du complément de contenu ou du volet Office qui l’a créé, et uniquement à partir du document dans lequel il est enregistré.

L’objet Settings est automatiquement chargé dans le cadre de l’objet Document et est disponible lorsque le complément de volet Office ou de contenu est activé. Une fois l’objet Document instancié, vous pouvez accéder à l’objet Settings avec la propriété settings de l’objet Document . Pendant la durée de vie de la session, vous pouvez utiliser les Settings.getméthodes , Settings.setet Settings.remove pour lire, écrire ou supprimer les paramètres persistants et l’état du complément de la copie en mémoire du conteneur de propriétés.

Étant donné que les méthodes set et remove fonctionnent uniquement sur la copie en mémoire du conteneur de propriétés de 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 une valeur de 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) respectant 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 avec 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 respectant la casse du paramètre.

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 retourne la valeur précédemment enregistrée pour le nom du paramètre qui a été passé. 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 respectant la casse du paramètre.

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

Rien ne se produit 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 sur la copie en mémoire du conteneur de propriétés des paramètres pendant la session en cours, vous devez appeler 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 passée à la saveAsync méthode en tant que paramètre de rappel est exécutée une fois l’opération terminée. Le paramètre asyncResult du rappel permet d’accéder à un AsyncResult objet qui contient l’état de l’opération. Dans l’exemple, la fonction vérifie la AsyncResult.status propriété pour voir si l’opération d’enregistrement a réussi ou échoué, puis affiche le résultat dans la page du complément.

Enregistrement du XML personnalisé dans le document

Une partie XML personnalisée est une option de stockage disponible lorsque vous souhaitez stocker des informations qui ont un caractère structuré ou que les données doivent être accessibles entre les instances de votre complément. Notez que les données stockées de cette façon sont également accessibles par d’autres compléments. Vous pouvez conserver le balisage XML personnalisé dans un complément du volet Office pour Word (et pour Excel et Word à l’aide de l’API spécifique à l’application, comme indiqué 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. Un attribut xmlns doit figurer dans la chaîne XML.

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 , mais l’ID est un GUID généré lors de la création de la partie XML, de sorte que vous ne pouvez pas savoir lors du codage de l’ID. Pour cette raison, lors de la création d’un composant XML, il est recommandé de stocker immédiatement l’ID du composant XML en tant que paramètre et de lui donner une clé mémorable. 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);
               }
           );
       }
   );
}

Partager via