Office JavaScript-API-Unterstützung für Inhalts- und Aufgabenbereich-Add-Ins

2025-02-14

Wichtig

Dieser Artikel bezieht sich auf die allgemeinen APIs, das Office JavaScript-API-Modell, das mit Office 2013 eingeführt wurde. Diese APIs enthalten Features wie z. B. Benutzeroberflächen, Dialogfelder und Clienteinstellungen, die in mehreren Office-Anwendungen enthalten sind. Outlook-Add-Ins verwenden ausschließlich allgemeine APIs, insbesondere die Teilmenge der APIs, die über das Postfach-Objekt verfügbar gemacht werden.

Sie sollten allgemeine APIs nur für Szenarien verwenden, die nicht von anwendungsspezifischen APIs unterstützt werden. Informationen dazu, wann Sie allgemeine APIs anstelle von anwendungsspezifischen APIs verwenden sollten, finden Sie unter Grundlegendes zur Office JavaScript-API.

Sie können die Office JavaScript-API verwenden, um Aufgabenbereich- oder Inhalts-Add-Ins für Office-Clientanwendungen zu erstellen. Die Objekte und Methoden, die Inhalts- und Aufgabenbereich-Add-Ins unterstützen, sind wie folgt kategorisiert:

Gemeinsame Objekte, die für andere Office-Add-Ins freigegeben werden. Zu diesen Objekten gehören Office, Context und AsyncResult. Das Office -Objekt ist das Stammobjekt der Office JavaScript-API. Das Context -Objekt stellt die Laufzeitumgebung des Add-Ins dar. Sowohl als Context auch Office sind die grundlegenden Objekte für jedes Office-Add-In. Das AsyncResult -Objekt stellt die Ergebnisse eines asynchronen Vorgangs dar, z. B. die Daten, die an die getSelectedDataAsync -Methode zurückgegeben werden, die liest, was ein Benutzer in einem Dokument ausgewählt hat.
Das Document-Objekt. Der Großteil der für Inhalts- und Aufgabenbereich-Add-Ins verfügbaren API wird über die Methoden, Eigenschaften und Ereignisse des Document-Objekt verfügbar gemacht. Ein Inhalts- oder Aufgabenbereich-Add-In kann die Office.context.document-Eigenschaft verwenden, um auf das DocumentObjekt und über dieses auf die zentralen Elemente der API zum Arbeiten mit Daten in Dokumenten zuzugreifen, wie die Bindings- und CustomXmlPartsObjekte und die getselecteddataasync-, setSelectedDataAsync- und getFileAsync-Methoden. Das Document -Objekt stellt auch die Mode-Eigenschaft bereit, um zu bestimmen, ob ein Dokument schreibgeschützt ist oder sich im Bearbeitungsmodus befindet, die URL-Eigenschaft zum Abrufen der URL des aktuellen Dokuments und den Zugriff auf das Settings-Objekt . Das Document -Objekt unterstützt auch das Hinzufügen von Ereignishandlern für das SelectionChanged-Ereignis , sodass Sie erkennen können, wann ein Benutzer seine Auswahl im Dokument ändert.

Ein Inhalts- oder Aufgabenbereich-Add-In kann erst auf das Document Objekt zugreifen, nachdem das DOM und die Laufzeitumgebung geladen wurden, in der Regel im Ereignishandler für das Office.initialize-Ereignis . Informationen zum Ablauf der Ereignisse, wenn ein Add-In initialisiert wird, und dazu, wie Sie überprüfen, ob das DOM und die Laufzeitumgebung erfolgreich geladen wurden, finden Sie unter Laden des DOM und der Laufzeitumgebung.
Objekte zum Arbeiten mit speziellen Features. Verwenden Sie die folgenden Objekte und Methoden, um mit bestimmten Features der API zu arbeiten.
- Die Methoden des Bindings-Objekts, um Bindungen zu erstellen oder abzurufen, und die Methoden und Eigenschaften des Binding-Objekts, um mit Daten zu arbeiten.
- Die Objekte CustomXmlParts, CustomXmlPart und verwandte Objekte, um benutzerdefinierte XML-Komponenten in Word-Dokumenten zu erstellen und zu bearbeiten.
- Die Objekte File und Slice, um eine Kopie des gesamten Dokuments zu erstellen, es in Blöcke oder Segmente zu unterteilen und dann die Daten in diese Segmente einzulesen oder zu übertragen.
- Das Settings-Objekt, um benutzerdefinierte Daten wie Benutzereinstellungen und Add-In-Status zu speichern.

Wichtig

Einige API-Elemente werden nicht in allen Office-Anwendungen unterstützt, die Inhalts- und Aufgabenbereich-Add-ins hosten können. Informationen dazu, wie Sie herausfinden, welche Elemente unterstützt werden, finden Sie in den folgenden Ressourcen:

Eine Zusammenfassung der Office JavaScript-API-Unterstützung für Office-Clientanwendungen finden Sie unter Grundlegendes zur Office JavaScript-API.

Lesen und Schreiben einer aktiven Auswahl in einem Dokument, einer Kalkulationstabelle oder einer Präsentation

Sie können die aktuelle Auswahl eines Benutzers in einem Dokument, einem Tabellenblatt oder einer Präsentation lesen oder in diese schreiben. Abhängig von der Office-Anwendung für Ihr Add-In können Sie den Typ der zu lesenden oder zu schreibenden Datenstruktur als Parameter in den Methoden getSelectedDataAsync und setSelectedDataAsync des Document-Objekts angeben. Sie können beispielsweise jede Art von Daten (Text, HTML, Tabellendaten oder Office Open XML) für Word, Text- und Tabellendaten für Excel und Text für PowerPoint und Projekt angeben. Sie können auch Ereignishandler erstellen, um Änderungen an der Auswahl des Benutzers zu erkennen. Im folgenden Beispiel werden Daten aus der Auswahl mithilfe der getSelectedDataAsync -Methode als Text abgerufen.

Office.context.document.getSelectedDataAsync(
    Office.CoercionType.Text, function (asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write('Action failed. Error: ' + asyncResult.error.message);
        }
        else {
            write('Selected data: ' + asyncResult.value);
        }
    });

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

Weitere Informationen und Beispiele finden Sie unter Lesen und Schreiben von Daten in der aktiven Auswahl in einem Dokument oder Arbeitsblatt.

Binden an eine Region in einem Dokument oder arbeitsblatt

Sie können die getSelectedDataAsync Methoden und setSelectedDataAsync verwenden, um die aktuelle Auswahl des Benutzers in einem Dokument, einer Kalkulationstabelle oder einer Präsentation zu lesen oder in diese zu schreiben. Wenn Sie jedoch über mehrere Sitzungen des Add-Ins hinweg auf dieselbe Region in einem Dokument zugreifen möchten, ohne dass der Benutzer eine Auswahl vornehmen muss, sollten Sie zuerst eine Bindung an diese Region einrichten. Sie können Daten- und Auswahländerungsereignisse für die gebundene Region auch abonnieren.

Sie können eine Bindung mithilfe der Methoden addFromNamedItemAsync, addFromPromptAsync oder addFromSelectionAsync des Bindings-Objekts hinzufügen. Diese Methoden geben eine ID zurück, die Sie für den Zugriff auf Daten in der Bindung verwenden können, oder mit der Sie deren Datenänderungs- oder Auswahlereignisse abonnieren können.

Im folgenden Beispiel wird dem aktuell markierten Text in einem Dokument mithilfe der Bindings.addFromSelectionAsync -Methode eine Bindung hinzugefügt.

Office.context.document.bindings.addFromSelectionAsync(
    Office.BindingType.Text, { id: 'myBinding' }, function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write('Added new binding with type: ' +
            asyncResult.value.type + ' and id: ' + asyncResult.value.id);
    }
});

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

Weitere Informationen und Beispiele finden Sie unter Einrichten einer Bindung in einem Dokument oder Arbeitsblatt.

Abrufen ganzer Dokumente

Wenn Ihr Aufgabenbereich-Add-In in PowerPoint oder Word ausgeführt wird, können Sie die Document.getFileAsync-, die File.getSliceAsync- und die File.closeAsync-Methode verwenden, um eine ganze Präsentation oder ein gesamtes Dokument abzurufen.

Wenn Sie aufrufen Document.getFileAsync , erhalten Sie eine Kopie des Dokuments in einem File-Objekt . Das File -Objekt ermöglicht den Zugriff auf das Dokument in "Blöcken", die als Slice-Objekte dargestellt werden. Wenn Sie aufrufen getFileAsync, können Sie den Dateityp (Text oder komprimiertes Open Office XML-Format) und die Größe der Slices (bis zu 4 MB) angeben. Um auf den Inhalt des File Objekts zuzugreifen, rufen Sie dann auf File.getSliceAsync , wodurch die Rohdaten in der Slice.data-Eigenschaft zurückgegeben werden. Wenn Sie das komprimierte Format angegeben haben, erhalten Sie die Dateidaten als Bytearray. Wenn Sie die Datei an einen Webdienst übertragen, können Sie die komprimierten Rohdaten vor der Übermittlung in eine Zeichenfolge mit Base64-Codierung umwandeln. Wenn Sie mit dem Abrufen von Slices der Datei fertig sind, verwenden Sie die File.closeAsync -Methode, um das Dokument zu schließen.

Weitere Informationen finden Sie unter der Vorgehensweise: Abrufen des gesamten Dokuments aus einem Add-In für PowerPoint oder Word.

Lesen und Schreiben benutzerdefinierter XML-Teile eines Word Dokuments

Mithilfe des Open Office XML-Dateiformats und der Inhaltssteuerelemente können Sie einem Word Dokument benutzerdefinierte XML-Teile hinzufügen und Elemente in den XML-Teilen an Inhaltssteuerelemente in diesem Dokument binden. Wenn Sie das Dokument öffnen, liest Word gebundene Inhaltssteuerelemente und füllt sie automatisch mit Daten aus den benutzerdefinierten XML-Teilen auf. Benutzer können auch Daten in die Inhaltssteuerelemente schreiben, und wenn der Benutzer das Dokument speichert, werden die Daten in den Steuerelementen in den gebundenen XML-Teilen gespeichert. Aufgabenbereich-Add-Ins für Word können die Document.customXmlParts-Eigenschaft, CustomXmlParts-, CustomXmlPart- und CustomXmlNode-Objekte verwenden, um Daten dynamisch in das Dokument zu lesen und zu schreiben.

Benutzerdefinierte XML-Komponenten können Namespaces zugeordnet werden. Verwenden Sie zum Abrufen von Daten in einem Namespace die Methode CustomXmlParts.getByNamespaceAsync.

Sie können auch die Methode CustomXmlParts.getByIdAsync verwenden, um auf benutzerdefinierte XML-Komponenten anhand ihrer GUID zuzugreifen. Nachdem Sie eine benutzerdefinierte XML-Komponente abgerufen haben, verwenden Sie die Methode CustomXmlPart.getXmlAsync zum Abrufen der XML-Daten.

Um einem Dokument eine neue benutzerdefinierte XML-Komponente hinzuzufügen, verwenden Sie die Document.customXmlParts -Eigenschaft, um die benutzerdefinierten XML-Teile abzurufen, die sich im Dokument befinden, und rufen Sie die CustomXmlParts.addAsync-Methode auf.

Ausführliche Informationen zum Verwalten benutzerdefinierter XML-Teile mit einem Aufgabenbereich-Add-In finden Sie unter Verstehen, wann und wie Office Open XML in Ihrem Word-Add-In verwendet wird.

Beibehalten von Add-in-Einstellungen

Häufig müssen Sie benutzerdefinierte Daten für Ihr Add-In speichern, etwa Einstellungen eines Benutzers oder den Status eines Add-Ins, und beim nächsten Öffnen des Add-Ins auf diese Daten zugreifen. Zum Speichern dieser Daten können Sie gängige Techniken für die Webprogrammierung wie Browsercookies oder HTML 5-Webspeicher verwenden. Wenn Ihr Add-In in Excel, PowerPoint oder Word ausgeführt wird, können Sie alternativ die Methoden des Settings-Objekts verwenden. Mit dem Settings -Objekt erstellte Daten werden in der Kalkulationstabelle, Präsentation oder dem Dokument gespeichert, in die das Add-In eingefügt und mit dem das Add-In gespeichert wurde. Diese Daten sind nur für das Add-In verfügbar, durch das sie erstellt wurden.

Um Roundtrips zu dem Server zu vermeiden, auf dem das Dokument gespeichert ist, werden mit dem Settings -Objekt erstellte Daten zur Laufzeit im Arbeitsspeicher verwaltet. Zuvor gespeicherte Einstellungsdaten werden in den Speicher geladen, wenn das Add-in initialisiert wird, und Änderungen an den Daten werden nur wieder im Dokument gespeichert, wenn Sie die Settings.saveAsync-Methode aufrufen. Die Daten werden intern in einem serialisierten JSON-Objekt als Namen-/Wertepaare gespeichert. Sie können die get-, set- und remove-Methoden des Settings-Objekts verwenden, um Elemente in der speicherinternen Kopie der Daten zu beschreiben, zu lesen oder zu löschen. Die folgende Codezeile zeigt, wie Sie eine Einstellung mit dem Namen themeColor erstellen und deren Wert auf "grün" festlegen.

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

Da einstellungsdaten, die mit den set Methoden und remove erstellt oder gelöscht wurden, auf eine In-Memory-Kopie der Daten reagieren, müssen Sie aufrufen saveAsync , um Änderungen an Einstellungsdaten in dem Dokument beizubehalten, mit dem Ihr Add-In arbeitet.

Weitere Informationen zum Arbeiten mit benutzerdefinierten Daten mithilfe der Methoden des Settings -Objekts finden Sie unter Beibehalten des Add-In-Zustands und der Einstellungen.

Berechtigungsmodell und Steuerung

Ihr Add-In verwendet das App-Manifest, um die Berechtigung für den Zugriff auf die erforderliche Funktionalitätsebene über die Office JavaScript-API anzufordern. Die Methode variiert je nach Art des Manifests.

Einheitliches Manifest für Microsoft 365: Verwenden Sie die "authorization.permissions.resourceSpecific" -Eigenschaft. Wenn ihr Add-In beispielsweise Lese-/Schreibzugriff auf das Dokument erfordert, muss das Manifest als Wert in der "authorization.permissions.resourceSpecific.name" -Eigenschaft angebenDocument.ReadWrite.User. Im folgenden Beispiel wird die Berechtigung "Dokument lesen " angefordert, die nur Methoden zulässt, die das Dokument lesen (aber nicht schreiben können).
```
"authorization": {
    "permissions": {
      "resourceSpecific": [
        ...
        {
          "name": "Document.Read.User",
          "type": "Delegated"
        },
      ]
    }
},
```
Hinweis

Das einheitliche Manifest für Microsoft 365 kann in Outlook-Produktions-Add-Ins verwendet werden. Es ist nur als Vorschau für Excel-, PowerPoint- und Word-Add-Ins verfügbar.
Reines Add-In-Manifest: Verwenden Sie das Permissions -Element im Manifest. Wenn Ihr Add-In beispielsweise Lese-/Schreibzugriff auf das Dokument erfordert, muss das Manifest als Textwert im Permissions -Element angebenReadWriteDocument. Da Berechtigungen dazu da sind, einem Benutzer Datenschutz und Sicherheit zu bieten, sollten Sie als bewährte Vorgehensweise die Mindestberechtigungen anfordern, die sie für ihre Features benötigt. Das folgende Beispiel zeigt, wie Die Leseberechtigung für Dokumente im Manifest eines Aufgabenbereichs angefordert wird.
```
<?xml version="1.0" encoding="utf-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:type="TaskPaneApp">
    
    <Permissions>ReadDocument</Permissions>
    ...
</OfficeApp>
```

Weitere Informationen finden Sie unter Anfordern von Berechtigungen für die API-Verwendung in Add-Ins.

Freigeben über