Beibehalten des Add-In-Zustands und der Einstellungen

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 verwendet dieser Artikel "Browsersteuerelement", um "Browser- oder Webansichtssteuerelement" zu bedeuten. Wenn das Add-In verwendet wird, muss ihr Add-In möglicherweise Daten beibehalten, um die Kontinuität bestimmter Vorgänge oder Features über Sitzungen hinweg aufrechtzuerhalten. Beispielsweise kann Ihr Add-In benutzerdefinierte Einstellungen oder andere Werte aufweisen, die gespeichert und neu geladen werden müssen, wenn es das nächste Mal initialisiert wird, z. B. die bevorzugte Ansicht oder den Standardspeicherort eines Benutzers. Zum Beibehalten von Daten haben Sie folgende Möglichkeiten:

• Verwenden Sie techniken, die vom zugrunde liegenden Browsersteuerelement bereitgestellt werden.
• Verwenden Sie die anwendungsspezifischen Office JavaScript-APIs für Excel, Word und Outlook, die Daten speichern.

Wenn Sie den Zustand dokumentübergreifend beibehalten müssen, z. B. die Nachverfolgung von Benutzereinstellungen für alle geöffneten Dokumente, verwenden Sie einen anderen Ansatz. 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, indem Sie Tools aus dem zugrunde liegenden Browsersteuerelement verwenden, z. B. Browsercookies oder HTML5-Webspeicher (localStorage oder sessionStorage).

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

Speicherpartitionierung

Speichern Sie alle privaten Daten in partitioniertem localStorage. Verwenden Sie Office.context.partitionKey als Schlüssel für den lokalen Speicher. Dieser Ansatz stellt sicher, dass im lokalen Speicher gespeicherte Daten nur im gleichen Kontext verfügbar sind.

Das folgende Beispiel zeigt, wie der Partitionsschlüssel mit localStorageverwendet wird.

// 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.

Anwendungsspezifische Einstellungen und Persistenz

Excel, Word und Outlook stellen anwendungsspezifische APIs zum Speichern von Einstellungen und anderen Daten bereit. Verwenden Sie diese APIs 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);
});

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

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 speichern die SettingsObjekte , CustomPropertiesund RoamingSettings Daten als serialisiertes Json-Objekt (JavaScript Object Notation), das Name-Wert-Paare enthält. Der Name (Schlüssel) für jeden Wert muss ein stringsein. Der gespeicherte Wert kann eine JavaScript string-, number- , date- oder object-Funktion sein, 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 einer vorherigen Add-In-Sitzung gespeichert wurde, kann das Add-In die Einstellungen laden, wenn das Add-In initialisiert wird, oder zu einem beliebigen Zeitpunkt danach während der aktuellen Sitzung des Add-Ins. Während der Sitzung verwaltet das Add-In die Einstellungen vollständig im Arbeitsspeicher mithilfe der getMethoden , setund remove des Objekts, das der Art von Einstellungen entspricht, die Sie erstellen (Settings, CustomProperties oder RoamingSettings).

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 Eigenschaftenbehälter, den Sie mithilfe der Methoden des Settings Objekts erstellen, 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 Sie ihn speichern.

Das Settings Objekt wird automatisch als Teil des Document-Objekts geladen und ist verfügbar, wenn das Aufgabenbereich- oder Inhalts-Add-In aktiviert ist. Nachdem Sie das Document Objekt instanziiert haben, können Sie mithilfe der Settingssettings-Eigenschaft des Objekts auf das Document Objekt zugreifen. Verwenden Sie während der Lebensdauer der Sitzung die Settings.getMethoden , Settings.setund Settings.remove , 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 mit dem angegebenen Namen wird erstellt, wenn sie noch nicht vorhanden ist, oder ihr Wert wird aktualisiert, wenn 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

Rufen Sie die Settings.saveAsync-Methode auf, um alle Ergänzungen, Änderungen oder Löschungen zu speichern, die Ihr Add-In während der aktuellen Sitzung an der In-Memory-Kopie des Einstellungseigenschaftenbehälters vorgenommen hat, um sie im Dokument zu speichern. 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

Verwenden Sie ein benutzerdefiniertes XML-Teil, um Informationen zu speichern, die ein strukturiertes Zeichen aufweisen, oder wenn Sie den Zugriff auf die Daten über Instanzen Ihres Add-Ins hinweg benötigen. Auch andere Add-Ins können auf diese Weise gespeicherte Daten zugreifen. 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. Die XML-Zeichenfolge muss ein xmlns -Attribut enthalten.

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 einer benutzerdefinierten XML-Komponente die getByIdAsync-Methode . Die ID ist eine GUID, die beim Erstellen des XML-Teils generiert wird, sodass Sie die ID beim Codieren nicht kennen. Aus diesem Grund speichern Sie die ID des XML-Teils als Einstellung, und geben Sie ihm beim Erstellen eines XML-Teils einen einprägsamen Schlüssel. 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

• Grundlegendes zur JavaScript-API für Office
• Outlook-Add-Ins
• Abrufen und Festlegen von Add-In-Metadaten für ein Outlook-Add-In
• Abrufen und Festlegen von Internetheadern für eine Nachricht in einem Outlook-Add-In
• Speichern benutzerdefinierter Einstellungen in Ihrem Office-Add-In