Allgemeines JavaScript-API-Objektmodell

Wichtig

Dieser Artikel bezieht sich auf die allgemeinen APIs, das Office JavaScript-API-Modell, das von Office 2013 und höher unterstützt wird. 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 ermöglichen den 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 bietet 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, weist es viele unterschiedliche Objekte auf, mit denen es in der Laufzeitumgebung interagieren kann. Der Laufzeitkontext des Add-Ins wird in der API durch das Context-Objekt widergespiegelt. Das Context-Objekt ist das Hauptobjekt, das Zugriff auf die wichtigsten Objekte der API bietet, z. B. das Document- und das Mailbox-Objekt, die wiederum Zugriff auf Dokument- und Postfachinhalte bieten.

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. Mithilfe von Document Objektmembern können Sie auf folgende Weise auf Daten zugreifen.

  • 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 Objekt auch für die Document Interaktion mit Daten in Project Dokumenten verwenden. Die Project-spezifische Funktionalität der API ist in den Elementen der abstrakten Klasse ProjectDocument 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 Instanz des abstrakten Document Objekts.

Sie können auf eine Instanz des Document Objekts zugreifen, wenn das Aufgabenbereich- oder Inhalts-Add-In mithilfe der Dokumenteigenschaft des Context Objekts initialisiert wird. Das Document Objekt definiert allgemeine Datenzugriffsfunktionen, die in Word und Excel Dokumenten gemeinsam verwendet werden, und bietet auch 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)

Um Ihnen zu verdeutlichen, wie die Methoden zum auswahl- und bindungsbasierten Zugriff funktionieren, möchten wir zunächst erklären, wie die Datenzugriffs-APIs bei den verschiedenen Office-Anwendungen einen einheitlichen Datenzugriff 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 jeder Office Anwendung durch allgemeine Datentypen und die Möglichkeit, unterschiedliche Dokumentinhalte in drei allgemeine Datentypen zu umwandeln.

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. In Office 2013 werden drei Hauptdatentypen unterstützt.

Datentyp Beschreibung Unterstützung von Hostanwendungen
Text Stellt eine Zeichenfolgendarstellung der Daten in der Auswahl bereit. In Excel 2013, Project 2013 und PowerPoint 2013 wird nur unformatierter Text unterstützt. In Word 2013 werden drei Formate 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 2013 und PowerPoint 2013 unterstützen nur 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']]. Matrix-Datenzugriff wird nur in Excel 2013 und Word 2013 unterstützt.
Tabelle Stellt die Daten in der Auswahl oder Bindung als TableData-Objekt bereit. Das TableData Objekt macht die Daten über die und rows die headers Eigenschaften verfügbar. Tabellendatenzugriff wird nur in Excel 2013 und Word 2013 unterstützt.

Datentyperzwingung

Die Datenzugriffsmethoden für die Document Und Binding - Objekte 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 umwandeln. Wenn beispielsweise eine Word-Tabelle oder ein Word-Absatz ausgewählt ist, kann der Entwickler angeben, dass sie als Nur-Text, HTML, Office Open XML oder eine Tabelle gelesen werden soll, und die API-Implementierung übernimmt die erforderlichen Transformationen und Datenkonvertierungen.

Tipp

Wann sollten Sie die Matrix-Koersion der Tabellenkoersion für den Datenzugriff vorziehen? Wenn Die Tabellendaten dynamisch vergrößert werden müssen, 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 einer Document Objektdatenzugriffsmethode als "table" oder Binding 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 planen, Zeilen und Spalten hinzuzufügen, und Ihre Daten keine Kopfzeilenfunktionalität erfordern, sollten Sie den Matrixdatentyp verwenden (indem Sie den coercionType-Parameter der Datenzugriffsmethode als "matrix" oder Office.CoercionType.Matrix) angeben, der ein einfacheres Modell für die Interaktion mit den Daten bereitstellt.

Wenn die Daten nicht in den angegebenen Typ umgewandelt werden können, gibt die AsyncResult.status-Eigenschaft im Rückruf "failed" zurück. Sie können dann über die AsyncResult.error-Eigenschaft auf ein Error-Objekt mit Informationen zu den Gründen des Misserfolgs des Methodenaufrufs zugreifen.

Arbeiten mit Auswahlen mithilfe des Document-Objekts

Das Document Objekt macht Methoden verfügbar, mit denen Sie die aktuelle Auswahl des Benutzers "abrufen und festlegen" lesen und in diese schreiben können. Dazu stellt das Objekt die Document getSelectedDataAsync Und-Methoden setSelectedDataAsync 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 Bindings- und Binding-Objekte

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 den folgenden Wert für Ihr Add-In.

  • Zugriff auf allgemeine Datenstrukturen in allen unterstützten Office-Anwendungen, z. B. Tabellen, Bereiche oder Text (eine fortlaufende Folge 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 es kann zu einem späteren Zeitpunkt auf diese zugegriffen werden.

Die Herstellung einer Bindung ermöglicht auch das Abonnieren von Daten- und Auswahländerungsereignissen in diesem bestimmten Bereich des Dokuments oder der Tabelle. 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. Auf die einzelnen Bindungen kann über ihre ID unter Verwendung der Bindings.getBindingByIdAsync- oder der Office.select-Methode zugegriffen werden. Sie können neue Bindungen einrichten und vorhandene entfernen, indem Sie eine der folgenden Methoden des Bindings Objekts verwenden: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync oder releaseByIdAsync.

Es gibt drei verschiedene Arten von Bindungen, die Sie mit dem parameter bindingType angeben, wenn Sie eine Bindung mit dem oder addFromNamedItemAsync addFromPromptAsync den addFromSelectionAsyncMethoden erstellen.

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 einen festen Bereich eines Dokuments, der tabulierte Daten ohne Kopfzeilen enthält. Daten in einer Matrixbindung werden als zweidimensionales Array-Objekt geschrieben bzw. gelesen, das in JavaScript als ein Array von Arrays implementiert wird. Beispielsweise können zwei Zeilen mit string-Werten in zwei Spalten als [['a', 'b'], ['c', 'd']] gelesen oder geschrieben werden, und eine einzelne Spalte mit drei Zeilen kann als [['a'], ['b'], ['c']] gelesen oder geschrieben 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 Kopf- 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 eine Bindung mithilfe einer der drei "Add"-Methoden des Bindings Objekts erstellt wurde, können Sie mit den Daten und Eigenschaften der Bindung mithilfe der Methoden des entsprechenden Objekts arbeiten: MatrixBinding, TableBinding oder TextBinding. Alle drei dieser Objekte erben die Methoden getDataAsync und setDataAsync des Binding Objekts, mit denen Sie mit den gebundenen Daten interagieren können.

Codebeispiele, die veranschaulichen, wie Aufgaben mit Bindungen ausgeführt werden, finden Sie unter Einrichten einer Bindung an Regionen in einem Dokument oder Arbeitsblatt.

Arbeiten mit benutzerdefinierten XML-Komponenten 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 dem CustomXmlParts Und-Objekten CustomXmlPart finden Sie im Codebeispiel für 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 Elemente der Objekte File und Slice sollen Funktionalität zum Aufteilen ganzer Word- und PowerPoint-Dokumentdateien in Segmente (Blöcke) von jeweils bis zu 4 MB bereitstellen. 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. Für den Zugriff auf die Objekte und Elemente, die insbesondere in Outlook-Add-Ins verwendet werden, z. B. das Item-Objekt, greifen Sie mithilfe der mailbox-Eigenschaft des Context-Objekts auf das Mailbox-Objekt zu (siehe die folgende Codezeile).

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

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

  • Office object: for initialization.

  • Context object: for access to content and display language properties.

  • RoamingSettingsobject: for saving Outlook add-in-specific custom settings to the user's mailbox where the add-in is installed.

Informationen zum Verwenden von JavaScript in Mail-Apps für Outlook finden Sie unter Outlook-Add-Ins.