Freigeben über

Allgemeines JavaScript-API-Objektmodell

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.

Office-JavaScript-APIs gewähren Zugriff auf die zugrunde liegende Funktionalität der Office-Clientanwendung. Der Großteil des Zugriffs erfolgt über ein paar wichtige Objekte. Das Context-Objekt bietet Zugriff auf die Laufzeitumgebung nach der Initialisierung. Das Document-Objekt bietet dem Benutzer die Kontrolle über ein Excel-, PowerPoint- oder Word-Dokument. Das Mailbox-Objekt gewährt einem Outlook-Add-In Zugriff auf Nachrichten, Termine und Benutzerprofile. Das Verständnis der Beziehungen zwischen diesen allgemeinen Objekten ist die Grundlage eines Office-Add-Ins.

Context-Objekt

Betrifft: Alle Add-In-Typen

Wenn ein Add-In initialisiert wird, erhält es Zugriff auf viele verschiedene Objekte in der Laufzeitumgebung. Das Context-Objekt spiegelt den Laufzeitkontext des Add-Ins in der API wider. Das Context-Objekt ist das Hauptobjekt, das Zugriff auf die wichtigsten Objekte der API ermöglicht, z. B. die Objekte Document und Mailbox . Diese Objekte bieten Zugriff auf Dokument- und Postfachinhalte.

In Aufgabenbereichs- oder Inhalts-Add-ins können Sie über die document-Eigenschaft des Context-Objekts auf die Eigenschaften und Methoden des Document-Objekts zugreifen, um mit dem Inhalt von Word-Dokumenten, Excel-Arbeitsblättern oder Project-Zeitplänen zu interagieren. Gleichsam können Sie in Outlook-Add-ins über die mailbox-Eigenschaft des Context-Objekts auf die Eigenschaften und Methoden des Mailbox-Objekts zugreifen, um mit dem Nachrichten-, Besprechungsanfragen- oder Termininhalt zu interagieren.

Das Context-Objekt bietet auch Zugriff auf die Eigenschaften contentLanguage und displayLanguage , mit denen Sie das Gebietsschema (Sprache) bestimmen können, das im Dokument oder Element oder von der Office-Anwendung verwendet wird. Über die roamingSettings-Eigenschaften können Sie auf die Mitglieder des RoamingSettings-Objekts zugreifen, das Einstellungen speichert, die spezifisch für Ihr Add-In für die Postfächer von einzelnen Benutzer sind. Das Context-Objekt bietet eine ui-Eigenschaft, über die das Add-In Popup-Dialogfelder starten kann.

Document-Objekt

Betrifft: Add-ins vom Typ „Inhalt" und „Aufgabenbereich"

Zum Interagieren mit Dokumentdaten in Excel, PowerPoint und Word bietet die API das Document-Objekt. Verwenden Sie Document Objektmember, um wie folgt auf Daten zuzugreifen.

  • Lesen und Schreiben in aktive Auswahlen in Form von Text, zusammenhängenden Zellen (Matrizen) oder Tabellen.

  • Tabellendaten (Matrizen oder Tabellen).

  • Bindungen (erstellt mit den "add"-Methoden des Bindings -Objekts).

  • Benutzerdefinierte XML-Komponenten (nur bei Word).

  • Einstellungen oder Add-in-Status (pro Add-in im Dokument dauerhaft gespeichert).

Sie können das Document -Objekt auch verwenden, um mit Daten in Project-Dokumenten zu interagieren. Die project-spezifische Funktionalität der API ist in den Membern der abstrakten ProjectDocument-Klasse dokumentiert. Weitere Informationen zum Erstellen von Aufgabenbereichs-Add-ins für Project finden Sie unter Aufgabenbereich-Add-ins für Project.

Alle diese Formen des Datenzugriffs beginnen mit einer instance des abstrakten Document Objekts.

Sie können auf eine instance des Document Objekts zugreifen, wenn das Aufgabenbereich- oder Inhalts-Add-In initialisiert wird, indem Sie die document-Eigenschaft des Context Objekts verwenden. Das Document -Objekt definiert allgemeine Datenzugriffsmethoden, die in Word- und Excel-Dokumenten gemeinsam verwendet werden, und bietet außerdem Zugriff auf das CustomXmlParts Objekt für Word Dokumente.

Das Document -Objekt unterstützt vier Möglichkeiten für Entwickler, auf Dokumentinhalte zuzugreifen.

  • Auswahlbasierten Zugriff

  • Bindungsbasierten Zugriff

  • Benutzerdefinierten Zugriff auf Basis von XML-Elementen (nur Word)

  • Zugriff auf Basis des gesamten Dokuments (nur PowerPoint und Word)

Damit Sie verstehen können, wie auswahl- und bindungsbasierte Datenzugriffsmethoden funktionieren, wird in diesem Artikel zunächst erläutert, wie die Datenzugriffs-APIs einen konsistenten Datenzugriff über verschiedene Office-Anwendungen hinweg ermöglichen.

Einheitlicher Datenzugriff in allen Office-Anwendungen

Betrifft: Add-ins vom Typ „Inhalt" und „Aufgabenbereich"

Um Erweiterungen zu erstellen, die nahtlos in verschiedenen Office-Dokumenten funktionieren, abstrahiert die Office JavaScript-API die Besonderheiten der einzelnen Office-Anwendungen durch gemeinsame Datentypen und die Möglichkeit, verschiedene Dokumentinhalte in drei gängige Datentypen zu wandeln.

Allgemeine Datentypen

Sowohl beim auswahl- als auch beim bindungsbasierten Datenzugriff werden Dokumentinhalte über Datentypen zur Verfügung gestellt, die alle unterstützten Office-Anwendungen gemeinsam haben. Drei Hauptdatentypen werden unterstützt.

Datentyp Beschreibung Hostanwendungsunterstützung
Text Stellt eine Zeichenfolgendarstellung der Daten in der Auswahl bereit. In Excel, Project und PowerPoint wird nur Nur-Text unterstützt. In Word werden drei Textformate unterstützt: Nur-Text, HTML und Office Open XML (OOXML). Wenn Text in einer Zelle in Excel ausgewählt wird, lesen und schreiben auswahlbasierte Methoden den gesamten Inhalt der Zelle, auch wenn nur ein Teil des Texts in der Zelle ausgewählt ist. Wenn Text in Word ausgewählt ist, lesen und schreiben auswahlbasierte Methoden nur die Zeichenfolge, die ausgewählt ist. Project und PowerPoint unterstützen nur den auswahlbasierten Datenzugriff.
Matrix Stellt die Daten in der Auswahl oder Bindung als zweidimensionales Array-Objekt bereit, das in JavaScript als ein Array von Arrays implementiert wird. Zwei Zeilen mit string-Werten in zwei Spalten sind beispielsweise [['a', 'b'], ['c', 'd']], und eine einzelne Spalte mit drei Zeilen ist beispielsweise [['a'], ['b'], ['c']]. Der Zugriff auf Matrixdaten wird nur in Excel und Word unterstützt.
Tabelle Stellt die Daten in der Auswahl oder Bindung als TableData-Objekt bereit. Das TableData -Objekt macht die Daten über die headers Eigenschaften und rows verfügbar. Der Zugriff auf Tabellendaten wird nur in Excel und Word unterstützt.

Datentyperzwingung

Die Datenzugriffsmethoden für die DocumentBinding-Objekte und unterstützen das Angeben des gewünschten Datentyps mithilfe des coercionType-Parameters dieser Methoden und der entsprechenden CoercionType-Enumerationswerte . Unabhängig von der tatsächlichen Form der Bindung unterstützen die verschiedenen Office-Anwendungen die allgemeinen Datentypen, indem sie versuchen, die Daten in den angeforderten Datentyp zu überteilen. Wenn z. B. eine Word Tabelle oder ein Absatz ausgewählt ist, kann der Entwickler angeben, dass er als Nur-Text, HTML, Office Open XML oder tabelle gelesen werden soll, und die API-Implementierung verarbeitet die erforderlichen Transformationen und Datenkonvertierungen.

Tipp

Wann sollten Sie die Matrix-Koersion der Tabellenkoersion für den Datenzugriff vorziehen? Wenn Ihre tabellarischen Daten dynamisch wachsen sollen, wenn Zeilen und Spalten hinzugefügt werden, und Sie mit Tabellenüberschriften arbeiten müssen, sollten Sie den Tabellendatentyp verwenden (indem Sie den coercionType-Parameter einer - oder Binding -DocumentObjektdatenzugriffsmethode als "table" oder Office.CoercionType.Tableangeben). Das Hinzufügen von Zeilen und Spalten innerhalb der Datenstruktur wird sowohl für Tabellen- als auch Matrixdaten unterstützt, das Anfügen von Zeilen und Spalten wird jedoch nur für Tabellendaten unterstützt. Wenn Sie nicht beabsichtigen, Zeilen und Spalten hinzuzufügen, und Ihre Daten keine Headerfunktionen erfordern, sollten Sie den Matrixdatentyp verwenden (indem Sie den coercionType-Parameter der Datenzugriffsmethode als "matrix" oder Office.CoercionType.Matrixangeben), der ein einfacheres Modell für die Interaktion mit den Daten bietet.

Wenn die Daten nicht in den angegebenen Typ umgewandelt werden können, gibt die Eigenschaft AsyncResult.status im Rückruf zurück"failed". Verwenden Sie die AsyncResult.error-Eigenschaft , um auf ein Error-Objekt mit Informationen darüber zuzugreifen, warum der Methodenaufruf fehlgeschlagen ist.

Arbeiten mit Auswahlen mithilfe des Document-Objekts

Das Document -Objekt verfügt über Methoden, die Sie verwenden können, um die aktuelle Auswahl des Benutzers auf "Get and set"-Weise zu lesen und zu schreiben. Dazu stellt das -Objekt die Document -Methode und setSelectedDataAsync die getSelectedDataAsync -Methode bereit.

Codebeispiele, die das Anwenden von Aufgaben auf Auswahlen veranschaulichen, finden Sie unter Lesen und Schreiben von Daten in der aktiven Auswahl in einem Dokument oder Arbeitsblatt.

Arbeiten mit Bindungen mithilfe der Objekte "Bindings" und "Binding"

Der bindungsbasierte Datenzugriff ermöglicht Inhalts- und Aufgabenbereichs-Add-ins einen einheitlichen Zugriff auf einen bestimmten Bereich eines Dokuments oder Arbeitsblatts über eine einer Bindung zugeordnete ID. Das Add-in muss zunächst die Bindung herstellen, indem eine der Methoden aufgerufen wird, über die ein Teil des Dokuments einer eindeutigen ID zugeordnet wird: addFromPromptAsync, addFromSelectionAsync oder addFromNamedItemAsync. Nachdem die Bindung eingerichtet wurde, kann das Add-in über die bereitgestellte ID auf die Daten im zugeordneten Bereich des Dokuments oder Arbeitsblatts zugreifen. Das Erstellen von Bindungen bietet dem Add-In den folgenden Wert.

  • Ermöglicht den Zugriff auf allgemeine Datenstrukturen für unterstützte Office-Anwendungen, z. B. Tabellen, Bereiche oder Text (eine zusammenhängende Reihe von Zeichen).

  • Lese-/Schreibzugriffvorgänge, ohne dass der Benutzer eine Auswahl vornehmen muss

  • Herstellung einer Beziehung zwischen dem Add-In und den Daten im Dokument. Bindungen bleiben im Dokument erhalten, und Benutzer können später darauf zugreifen.

Wenn Sie eine Bindung einrichten, können Sie Daten- und Auswahländerungsereignisse abonnieren, die auf diesen bestimmten Bereich des Dokuments oder der Kalkulationstabelle ausgerichtet sind. Dies bedeutet, dass das Add-in nur von Änderungen benachrichtigt wird, die in dem gebundenen Bereich stattfinden und nicht von solchen, innerhalb des gesamten Dokuments oder der gesamten Tabelle.

Das Bindings-Objekt macht eine getAllAsync-Methode verfügbar, die den Zugriff auf alle in dem Dokument oder in der Tabelle hergestellten Bindungen ermöglicht. Sie können auf eine einzelne Bindung anhand ihrer ID zugreifen, indem Sie entweder die Bindings.getBindingByIdAsync-Methode oder die Office.select-Funktion verwenden . Richten Sie neue Bindungen ein, und entfernen Sie vorhandene Bindungen mithilfe einer der folgenden Methoden des Bindings Objekts: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync oder releaseByIdAsync.

Wenn Sie eine Bindung mit den addFromSelectionAsyncMethoden , addFromPromptAsyncoder addFromNamedItemAsync erstellen, geben Sie den Bindungstyp mithilfe des bindingType-Parameters an.

Bindungstyp Beschreibung Unterstützung von Hostanwendungen
Textbindung Bindet einen Bereich des Dokuments, der als Text dargestellt werden kann. In Word sind die meisten zusammenhängenden Auswahlen gültig, während in Excel nur Auswahlen mit einer Zelle das Ziel einer Textbindung sein können. In Excel wird nur unformatierter Text unterstützt. Word unterstützt drei Formate: Nur-Text, HTML und Open XML für Office.
Matrixbindung Bindet an einen festen Bereich eines Dokuments, der Tabellendaten ohne Überschriften enthält. Daten in einer Matrixbindung werden als zweidimensionales Array geschrieben oder gelesen, das in JavaScript als Array von Arrays implementiert wird. Beispielsweise können zwei Zeilen mit Zeichenfolgenwerten in zwei Spalten als [['a', 'b'], ['c', 'd']]geschrieben oder gelesen werden, und eine einzelne Spalte mit drei Zeilen kann als [['a'], ['b'], ['c']]geschrieben oder gelesen werden. In Excel kann eine beliebige Auswahl benachbarter Zellen für die Herstellung einer Matrixbindung verwendet werden. In Word wird die Matrixbindung nur für Tabellen unterstützt.
Tabellenbindung Bindet einen Bereich eines Dokuments, der eine Tabelle mit Kopfzeilen enthält. Daten in einer Tabellenbindung werden als TableData-Objekt geschrieben oder gelesen. Das TableData -Objekt macht die Daten über die Header - und Zeileneigenschaften verfügbar. Jede Excel- oder Word-Tabelle kann die Basis einer Tabellenbindung sein. Nach Herstellen einer Tabellenbindung wird jede neue Zeile oder Spalte, die Benutzer der Tabelle hinzugefügt haben, automatisch in die Bindung einbezogen.

Nachdem Sie eine Bindung mit einer der drei "add"-Methoden des Bindings Objekts erstellt haben, können Sie mit den Daten und Eigenschaften der Bindung arbeiten, indem Sie die Methoden des entsprechenden Objekts verwenden: MatrixBinding, TableBinding oder TextBinding. Diese drei Objekte erben die Methoden getDataAsyncund setDataAsync des Binding-Objekts, die Ihnen die Interaktion mit den gebundenen Daten ermöglichen.

Codebeispiele, die veranschaulichen, wie Aufgaben mithilfe von Bindungen ausgeführt werden, finden Sie unter Binden an Regionen in einem Dokument oder arbeitsblatt.

Arbeiten mit benutzerdefinierten XML-Teilen mithilfe der Objekte CustomXmlParts und CustomXmlPart

Betrifft: Add-ins für den Aufgabenbereich

Die Objekte CustomXmlParts und CustomXmlPart der API bieten Zugriff auf benutzerdefinierte XML-Komponenten in Word, die die XML-gesteuerte Bearbeitung des Dokumentinhalts ermöglichen. Demonstrationen zum Arbeiten mit den CustomXmlParts Objekten und CustomXmlPart finden Sie im Codebeispiel Word-add-in-Work-with-custom-XML-parts.

Arbeiten mit dem gesamten Dokument mithilfe der getFileAsync-Methode

Betrifft: Add-Ins für den Aufgabenbereich für Word und PowerPoint

Die Document.getFileAsync-Methode und Member der File- und Slice-Objekte bieten Funktionen zum Abrufen von gesamten Word- und PowerPoint-Dokumentdateien in Slices (Blöcken) von bis zu 4 MB gleichzeitig. Weitere Informationen finden Sie unter Abrufen des gesamten Dokuments aus einem Add-In für PowerPoint oder Word.

Objekt „Postfach“

Betrifft: Outlook-Add-ins

Outlook-Add-Ins verwenden hauptsächlich eine Untergruppe der API, die über das Mailbox-Objekt zur Verfügung gestellt wird. Um auf die Objekte und Elemente für die Verwendung in Outlook-Add-Ins zuzugreifen, z. B. das Item-Objekt im Verfassen- oder Lesemodus, verwenden Sie die mailbox-Eigenschaft des Context-Objekts , um auf das Mailbox-Objekt zuzugreifen. Hier ein Beispielcode:

// Access the Item object.
const item = Office.context.mailbox.item;

Wichtig

Beachten Sie beim Aufrufen Office.context.mailbox.item einer Nachricht, dass der Lesebereich im Outlook-Client aktiviert sein muss. Eine Anleitung zum Konfigurieren des Lesebereichs finden Sie unter Verwenden und Konfigurieren des Lesebereichs für die Vorschau von Nachrichten.

Darüber hinaus können Outlook-Add-Ins die folgenden Objekte verwenden.

  • Office-Objekt: zur Initialisierung.

  • Context-Objekt: für Zugriff auf die Inhalts- und Anzeigespracheneigenschaften.

Informationen zur Verwendung von JavaScript in Outlook-Add-Ins finden Sie unter Outlook-Add-Ins. Informationen zur Outlook-JavaScript-API finden Sie auf der Outlook-API-Referenzseite .

  • Last updated on