Beibehalten des Add-In-Zustands und der Einstellungen

  • Artikel

Office-Add-Ins sind im Wesentlichen Webanwendungen, die in der zustandslosen Umgebung eines Browser-iframes oder webview-Steuerelements ausgeführt werden. (Aus Gründen der Übersichtlichkeit wird in diesem Artikel "Browsersteuerelement" verwendet, um "Browser- oder Webansichtssteuerelement" zu bedeuten.) Wenn Das Add-In verwendet wird, müssen möglicherweise Daten beibehalten werden, um die Kontinuität bestimmter Vorgänge oder Features über Sitzungen hinweg aufrechtzuerhalten. Wenn Ihr Add-in beispielsweise benutzerdefinierte Einstellungen oder andere Werte aufweist, die gespeichert und bei der nächsten Initialisierung neu geladen werden müssen, wie z. B. eine vom Benutzer bevorzugte Ansicht oder ein Standardspeicherort. Dazu können Sie:

Wenn Sie den Zustand dokumentübergreifend beibehalten müssen, z. B. die Nachverfolgung von Benutzereinstellungen für alle geöffneten Dokumente, müssen Sie einen anderen Ansatz verwenden. Beispielsweise können Sie SSO verwenden, um die Benutzeridentität abzurufen und dann die Benutzer-ID und ihre Einstellungen in einer Onlinedatenbank zu speichern.

Browserspeicher

Speichern Sie Daten über Add-In-Instanzen hinweg mit Tools aus dem zugrunde liegenden Browsersteuerelement, z. B. Browsercookies oder HTML5-Webspeicher (localStorage oder sessionStorage).

Einige Browser oder die Browsereinstellungen des Benutzers können browserbasierte Speichertechniken blockieren. Sie sollten die Verfügbarkeit testen, wie unter Verwenden der Webspeicher-API dokumentiert.

Speicherpartitionierung

Als bewährte Methode sollten alle privaten Daten in partitioniert localStoragegespeichert werden. Office.context.partitionKey stellt einen Schlüssel für die Verwendung mit lokalem Speicher bereit. Dadurch wird sichergestellt, dass im lokalen Speicher gespeicherte Daten nur im gleichen Kontext verfügbar sind. Das folgende Beispiel zeigt, wie der Partitionsschlüssel mit localStorageverwendet wird. Beachten Sie, dass der Partitionsschlüssel in Umgebungen ohne Partitionierung nicht definiert ist, z. B. in den Browsersteuerelementen für Windows-Anwendungen.

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

Ab Version 115 von Chromium-basierten Browsern wie Chrome und Edge ist die Speicherpartitionierung aktiviert, um bestimmte seitenkanalübergreifende Nachverfolgung zu verhindern (siehe auch Microsoft Edge-Browserrichtlinien). Ähnlich wie bei der schlüsselbasierten Office-Partitionierung sind daten, die von Speicher-APIs wie lokalem Speicher gespeichert werden, nur für Kontexte mit demselben Ursprung und demselben Standort der obersten Ebene verfügbar.

Tipp

Um dies zu umgehen, wechseln Sie in Ihrem Browser zu chrome://flags oder edge://flags, und legen Sie dann das Flag Experimentelle Speicherpartitionierung von Drittanbietern (#third-party-storage-partitioning) auf Deaktiviert fest.

Anwendungsspezifische Einstellungen und Persistenz

Excel, Word und Outlook stellen anwendungsspezifische APIs zum Speichern von Einstellungen und anderen Daten bereit. Verwenden Sie diese anstelle der weiter unten in diesem Artikel erwähnten allgemeinen APIs , damit Ihr Add-In konsistenten Mustern folgt und für die Zielanwendung optimiert ist.

Einstellungen in Excel und Word

Die anwendungsspezifischen JavaScript-APIs für Excel und für Word bieten ebenfalls Zugriff auf die benutzerdefinierten Einstellungen. Einstellungen sind für eine einzelne Excel-Datei und Add-In-Kopplung eindeutig. Weitere Informationen finden Sie unter Excel.SettingCollection und Word. SettingCollection.

Das folgende Beispiel zeigt, wie Sie eine Einstellung in Excel erstellen und darauf zugreifen. Der Prozess ist funktional äquivalent in Word, die Document.settings anstelle von Workbook.settingsverwendet.

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

Benutzerdefinierte XML-Daten in Excel und Word

Mit den Open XML -.xlsx- und .docx-Dateiformaten können Add-In benutzerdefinierte XML-Daten in die Excel-Arbeitsmappe oder Word Dokument einbetten. Diese Daten bleiben unabhängig vom Add-In in der Datei erhalten.

Ein Word. Document und Excel.Workbook enthalten eine CustomXmlPartCollection, bei der es sich um eine Liste von CustomXmlPartshandelt. Diese ermöglichen Zugriff auf die XML-Zeichenfolgen und eine entsprechende eindeutige ID. Durch Speichern dieser IDs als Einstellungen kann das Add-In die Schlüssel zu seinen XML-Abschnitten zwischen Sitzungen speichern.

Die folgenden Beispiele zeigen, wie Sie benutzerdefinierte XML-Teile mit einer Excel-Arbeitsmappe verwenden. Der erste Codeblock veranschaulicht das Einbetten von XML-Daten. Er speichert eine Liste von Prüfern und verwendet dann die Einstellungen der Arbeitsmappe, um die id der XML zu speichern, damit diese später abgerufen werden können. Der zweite Block zeigt, wie später auf diese XML zugegriffen wird. Die Einstellung „ContosoReviewXmlPartId“ wird geladen und an die customXmlParts der Arbeitsmappe übergeben. Die XML-Daten werden dann an die Konsole ausgegeben. Der Prozess ist funktional äquivalent in Word, die Document.customXmlParts anstelle von Workbook.customXmlPartsverwendet.

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

Hinweis

CustomXMLPart.namespaceUri wird nur aufgefüllt, wenn das benutzerdefinierte XML-Element der obersten Ebene das xmlns-Attribut enthält.

Benutzerdefinierte Eigenschaften in Excel und Word

Excel.DocumentProperties.custom und Word. DocumentProperties.customProperties-Eigenschaften stellen Sammlungen von Schlüssel-Wert-Paaren für benutzerdefinierte Eigenschaften dar. Das folgende Excel-Beispiel zeigt, wie Sie eine benutzerdefinierte Eigenschaft namens Introduction mit dem Wert "Hello" erstellen und dann abrufen.

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

Tipp

In Excel können benutzerdefinierte Eigenschaften auch auf Arbeitsblattebene mit der Worksheet.customProperties-Eigenschaft festgelegt werden. Diese ähneln benutzerdefinierten Eigenschaften auf Dokumentebene, mit der Ausnahme, dass derselbe Schlüssel auf verschiedenen Arbeitsblättern wiederholt werden kann.

Speichern von Einstellungen in einem Outlook-Add-In

Informationen zum Speichern von Einstellungen in einem Outlook-Add-In finden Sie unter Abrufen und Festlegen von Add-In-Metadaten für ein Outlook-Add-In und Abrufen und Festlegen von Internetheadern für eine Nachricht in einem Outlook-Add-In.

Allgemeine API-Einstellungen und Persistenz

Die allgemeinen APIs stellen Objekte bereit, um den Add-In-Zustand sitzungsübergreifend zu speichern. Die gespeicherten Einstellungswerte sind der ID des Add-Ins zugeordnet, das sie erstellt hat. Intern werden die Daten, auf die mit den SettingsObjekten , CustomPropertiesoder RoamingSettings zugegriffen wird, als serialisiertes Json-Objekt (JavaScript Object Notation) gespeichert, das Name-Wert-Paare enthält. Der Name (Schlüssel) für jeden Wert muss ein stringsein, und der gespeicherte Wert kann ein JavaScript string, number, date, oder objectsein, aber keine Funktion.

Dieses Beispiel der Eigenschaftenbehälterstruktur enthält drei definierte Zeichenfolgenwerte mit den Namen firstName, locationund defaultView.

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

Nachdem der Eigenschaftenbehälter für Einstellungen während der vorherigen Add-In-Sitzung gespeichert wurde, kann er geladen werden, wenn das Add-In initialisiert wird, oder zu einem beliebigen Zeitpunkt danach während der aktuellen Sitzung des Add-Ins. Während der Sitzung werden die Einstellungen vollständig im Arbeitsspeicher mit den getMethoden , setund remove des Objekts verwaltet, das der Art der von Ihnen erstellten Einstellungen entspricht (Settings, CustomProperties oder RoamingSettings).

Wichtig

Um alle Ergänzungen, Aktualisierungen oder Löschungen, die während der aktuellen Sitzung des Add-Ins am Speicherort vorgenommen wurden, beizubehalten, müssen Sie die saveAsync -Methode des entsprechenden Objekts aufrufen, das zum Arbeiten mit dieser Art von Einstellungen verwendet wird. Die getMethoden , setund remove funktionieren nur für die Speicherkopie des Eigenschaftenbehälters für Einstellungen. Wenn Ihr Add-In geschlossen wird, ohne aufzurufen saveAsync, gehen alle Änderungen, die während dieser Sitzung an den Einstellungen vorgenommen wurden, verloren.

So speichern Sie Add-In-Status und -Einstellungen für Inhalts- und Aufgabenbereich-Add-Ins

Um den Zustand oder benutzerdefinierte Einstellungen eines Inhalts- oder Aufgabenbereich-Add-Ins für Word, Excel oder PowerPoint beizubehalten, verwenden Sie das Settings-Objekt und seine Methoden. Der mit den Methoden des Settings Objekts erstellte Eigenschaftenbehälter ist nur für die instance des Inhalts- oder Aufgabenbereich-Add-Ins verfügbar, von dem er erstellt wurde, und nur aus dem Dokument, in dem er gespeichert ist.

Das Settings Objekt wird automatisch als Teil des Document-Objekts geladen und ist verfügbar, wenn das Aufgabenbereich- oder Inhalts-Add-In aktiviert wird. Nachdem das Document Objekt instanziiert wurde, können Sie mit der Settingssettings-Eigenschaft des Objekts auf das Document Objekt zugreifen. Während der Lebensdauer der Sitzung können Sie die Settings.getMethoden , Settings.setund Settings.remove verwenden, um persistente Einstellungen und den Add-In-Zustand aus der Speicherkopie des Eigenschaftenbehälters zu lesen, zu schreiben oder zu entfernen.

Da die Set- und Remove-Methoden nur mit der Speicherkopie des Eigenschaftenbehälters für Einstellungen arbeiten, müssen Sie die Settings.saveAsync-Methode aufrufen, um neue oder geänderte Einstellungen wieder in dem Dokument zu speichern, dem das Add-In zugeordnet ist.

Erstellen oder Aktualisieren eines Einstellungswerts

Das folgende Codebeispiel veranschaulicht, wie die Settings.set-Methode verwendet werden kann, um eine Einstellung namens 'themeColor' mit einem Wert 'green' zu erstellen. Der erste Parameter der set-Methode ist der Name (ID) der festzulegenden oder zu erstellenden Einstellung, bei dem die Groß-/Kleinschreibung beachtet wird. Der zweite Parameter ist der value der Einstellung.

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

Die Einstellung wird mit dem angegebenen Namen erstellt, falls sie nicht bereits vorhanden ist oder ihr Wert wird aktualisiert, fall sie vorhanden ist. Verwenden Sie die Settings.saveAsync -Methode, um die neuen oder aktualisierten Einstellungen im Dokument beizubehalten.

Abrufen des Werts einer Einstellung

Das folgende Beispiel veranschaulicht die Verwendung der Settings.get-Methode, um den Wert einer Einstellung namens „themeColor“ abzurufen. Der einzige Parameter der get -Methode ist der Name der Einstellung, bei dem die Groß-/Kleinschreibung beachtet wird.

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

Die get Methode gibt den Wert zurück, der zuvor für den übergebenen Einstellungsnamen gespeichert wurde. If the setting doesn't exist, the method returns null.

Entfernen einer Einstellung

Das folgende Beispiel veranschaulicht die Verwendung der Settings.remove-Methode, um eine Einstellung namens „themeColor“ zu entfernen. Der einzige Parameter der remove -Methode ist der Name der Einstellung, bei dem die Groß-/Kleinschreibung beachtet wird.

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

Wenn die Einstellung nicht vorhanden ist, geschieht nichts. Verwenden Sie die Settings.saveAsync -Methode, um die Einstellung weiterhin aus dem Dokument zu entfernen.

Speichern Der Einstellungen

Um die Hinzufügungen, Änderungen und Entfernungen an Ihrem Add-in in der Speicherkopie der Einstellungs-Eigenschaftssammlung zu speichern, müssen Sie die Settings.saveAsync-Methode aufrufen, damit sie im Dokument gespeichert werden. Der einzige Parameter der saveAsync Methode ist callback, eine Rückruffunktion mit einem einzelnen Parameter.

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

Die anonyme Funktion, die an die saveAsync -Methode übergeben wird, während der Rückrufparameter ausgeführt wird, wenn der Vorgang abgeschlossen ist. Der asyncResult-Parameter des Rückrufs ermöglicht den Zugriff auf ein AsyncResult Objekt, das die status des Vorgangs enthält. Im Beispiel überprüft die Funktion die AsyncResult.status -Eigenschaft, um festzustellen, ob der Speichervorgang erfolgreich war oder fehlgeschlagen ist, und zeigt dann das Ergebnis auf der Add-In-Seite an.

Speichern von benutzerdefiniertem XML-Code im Dokument

Ein benutzerdefiniertes XML-Teil ist eine verfügbare Speicheroption, wenn Sie Informationen speichern möchten, die einen strukturierten Charakter aufweisen oder auf die Daten über Instanzen Ihres Add-Ins hinweg zugänglich sein müssen. Beachten Sie, dass auf diese Weise gespeicherte Daten auch von anderen Add-Ins zugegriffen werden kann. Sie können benutzerdefiniertes XML-Markup in einem Aufgabenbereich-Add-In für Word (und für Excel und Word mithilfe der anwendungsspezifischen API beibehalten, wie im vorherigen Absatz erwähnt). In Word können Sie das CustomXmlPart-Objekt und seine Methoden verwenden. Der folgende Code erstellt ein benutzerdefiniertes XML-Teil und zeigt seine ID und dann seinen Inhalt in divs auf der Seite an. Beachten Sie, dass in der XML-Zeichenfolge ein xmlns Attribut vorhanden sein muss.

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

Verwenden Sie zum Abrufen eines benutzerdefinierten XML-Teils die getByIdAsync-Methode , aber die ID ist eine GUID, die beim Erstellen des XML-Teils generiert wird. Sie können also beim Codieren der ID nicht wissen, was die ID ist. Aus diesem Grund ist es eine bewährte Methode beim Erstellen eines XML-Teils, die ID des XML-Teils sofort als Einstellung zu speichern und ihm einen einprägsamen Schlüssel zu geben. Im der folgenden Methode wird dies veranschaulicht.

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

Im folgenden Code wird gezeigt, wie Sie das XML-Webpart abrufen, indem Sie zuerst die ID aus den Einstellungen erhalten.

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

Siehe auch