Allgemeines JavaScript-API-Objektmodell

  • Artikel

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, 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. Sie können Objektmember verwenden Document , um über die folgenden Methoden 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 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 instance des abstrakten Document Objekts.

Sie können auf eine instance des Document Objekts zugreifen, wenn das Aufgabenbereich- oder Inhalts-Add-In mithilfe der document-Eigenschaft des Context Objekts initialisiert wird. 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)

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 über verschiedene Office-Dokumente hinweg funktionieren, abstrahiert die Office JavaScript-API die Besonderheiten jeder Office-Anwendung durch gemeinsame Datentypen und die Möglichkeit, verschiedene Dokumentinhalte in drei allgemeine 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 Standard Datentypen 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 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 auf "Get and set"-Weise lesen und schreiben können. 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.

  • 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 eine einzelne Bindung kann über ihre ID über die Bindings.getBindingByIdAsync-Methode oder die Office.select-Funktion 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 bindingType-Parameter angeben, wenn Sie eine Bindung mit den addFromSelectionAsyncMethoden , addFromPromptAsync oder addFromNamedItemAsync 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 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 eine Bindung mit einer der drei "add"-Methoden des Bindings Objekts erstellt wurde, können Sie mit den Daten und Eigenschaften der Bindung arbeiten, indem Sie die Methoden des entsprechenden Objekts verwenden: MatrixBinding, TableBinding oder TextBinding. Alle drei Objekte erben die GetDataAsync- und setDataAsync-Methoden 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-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 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. Um auf die Objekte und Elemente zuzugreifen, die speziell für die Verwendung in Outlook-Add-Ins wie dem Item-Objekt verwendet werden, verwenden Sie die mailbox-Eigenschaft des Context-Objekts , um auf das Mailbox-Objekt zuzugreifen, wie in der folgenden Codezeile gezeigt.

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