Grundlegendes zur JavaScript-API für OfficeUnderstanding the JavaScript API for Office

Dieser Artikel enthält Informationen zu der JavaScript-API für Office und zu deren Verwendung. Referenzinformationen finden Sie unter JavaScript-API für Office. Informationen zum Aktualisieren von Visual Studio-Projektdateien auf die aktuelle Version der JavaScript-API für Office finden Sie unter Aktualisieren der Version der JavaScript-API für Office und der Manifestschemadateien.This article provides information about the JavaScript API for Office and how to use it. For reference information, see JavaScript API for Office. For information about updating Visual Studio project files to the most current version of the JavaScript API for Office, see Update the version of your JavaScript API for Office and manifest schema files.

Hinweis

Wenn Sie Ihr Add-In in AppSource veröffentlichen und innerhalb der Office-Benutzererfahrung verfügbar machen möchten, vergewissern Sie sich beim Erstellen des Add-Ins, dass es den AppSource-Validierungsrichtlinien entspricht. Damit das Add-In die Validierung besteht, muss es beispielsweise auf allen Plattformen funktionieren, die die Methoden unterstützen, die Sie definieren (weitere Informationen finden Sie im Abschnitt 4.12 und auf der Host- und Verfügbarkeitsseite von Office-Add-Ins).If you plan to publish your add-in to AppSource and make it available within the Office experience, make sure that you conform to the AppSource validation policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 4.12 and the Office Add-in host and availability page).

Verweisen auf die Bibliothek der JavaScript-API für Office in Ihrem Add-InReferencing the JavaScript API for Office library in your add-in

Die JavaScript-API für Office-Bibliothek besteht aus der Datei „Office.js“ und den zugehörigen hostanwendungsspezifischen JS-Dateien, wie z. B. „Excel-15.js“ und „Outlook-15.js“. Die einfachste Methode zum Verweisen auf die API ist mithilfe unseres CDN. Fügen Sie dazu das folgende <script> zum Tag <head> Ihrer Seite hinzu:The JavaScript API for Office library consists of the Office.js file and associated host application-specific .js files, such as Excel-15.js and Outlook-15.js. The simplest method of referencing the API is using our CDN by adding the following <script> to your page's <head> tag:

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>

Dadurch wird ein Download der Dateien der JavaScript-API für Office beim ersten Laden Ihres Add-ins gestartet, um zu gewährleisten, dass die neueste Implementierung der Datei Office.js und die dazugehörigen Dateien für die angegebene Version verwendet werden.This will download and cache the JavaScript API for Office files the first time your add-in loads to make sure that it is using the most up-to-date implementation of Office.js and its associated files for the specified version.

Weitere Informationen zum Office.js-CDN, u. a. zu Versionsverwaltung und Abwärtskompatibilität, finden Sie unter Referencing the JavaScript API for Office library from its content delivery network (CDN) (Verweisen auf die Bibliothek der JavaScript-API für Office über das CDN).For more details around the Office.js CDN, including how versioning and backward compatability is handled, see Referencing the JavaScript API for Office library from its content delivery network (CDN).

Initialisierung Ihres Add-insInitializing your add-in

Betrifft: Alle Add-In-TypenApplies to: All add-in types

Office-Add-Ins weisen häufig eine Startlogik für Vorgänge wie diese auf:Office Add-ins often have start-up logic to do things such as:

  • Überprüfen, ob die Office-Version des Benutzers alle von Ihrem Code aufgerufenen Office-APIs unterstützt.Check that the user's version of Office will support all the Office APIs that your code calls.

  • Sicherstellen des Vorhandenseins bestimmter Artefakte, wie etwa eines Arbeitsblatts mit einem bestimmten Namen.Ensure the existence of certain artifacts, such as worksheet with a specific name.

  • Auffordern des Benutzers, einige Zellen in Excel auszuwählen, und anschließend Einfügen eines Diagramms, das mit diesen ausgewählten Werten initialisiert ist.You can use the initialize event handler to implement common add-in initialization scenarios, such as prompting the user to select some cells in Excel, and then inserting a chart initialized with those selected values.

  • Einrichten von Bindungen.Establish bindings.

  • Verwenden Sie die Office-Dialogfeld-API, um den Benutzer zur Eingabe der Standardwerte für Add-In-Einstellungen aufzufordern.Use the Office dialog API to prompt the user for default add-in settings values.

Ihr Startcode darf jedoch bis zum vollständigen Laden der Bibliothek keine Office.js-APIs aufrufen.But your start-up code must not call any Office.js APIs until the library is fully loaded. Es gibt zwei Möglichkeiten, wie Sie in Ihrem Code sicherstellen können, dass die Bibliothek geladen ist.There are two ways that your code can ensure that the library is loaded. Diese sind in den folgenden Abschnitten beschrieben:The methods are described in the following sections of this article.

Informationen zu den Unterschieden zwischen diesen beiden Techniken finden Sie unter Hauptunterschiede zwischen Office.initialize und Office.onReady().For information about the differences in these techniques, see Major differences between Office.initialize and Office.onReady(). Weitere Details zur Ereignisabfolge beim Initialisieren eines Add-Ins finden Sie unter Laden des DOM und der Laufzeitumgebung.For more detail about the sequence of events when an add-in is initialized, see Loading the DOM and runtime environment.

Initialisieren mit Office.onReady()Initialize with Office.onReady()

Office.onReady() ist eine asynchrone Methode, die ein Zusageobjekt zurückgibt, während sie überprüft, ob die Office.js-Bibliothek vollständig geladen ist.Office.onReady() is an asynchronous method that returns a Promise object while it checks to see if the Office.js library is fully loaded. Wenn und nur wenn die Bibliothek geladen ist, löst sie die Zusage zu einem Objekt auf, das die Office-Hostanwendung mithilfe eines Office.HostType-Enumerationswerts (Excel, Word usw.) und die Plattform mithilfe eines Office.PlatformType-Enumerationswerts (PC, Mac, OfficeOnline usw.) angibt.When, and only when, the library is loaded, it resolves the Promise as an object that specifies the Office host application with an Office.HostType enum value (Excel, Word, etc.) and the platform with an Office.PlatformType enum value (PC, Mac, OfficeOnline, etc.). Wenn die Bibliothek beim Aufruf von Office.onReady() bereits geladen ist, wird die Zusage sofort aufgelöst.If the library is already loaded when Office.onReady() is called, then the Promise resolves immediately.

Eine Möglichkeit zum Aufrufen von Office.onReady() besteht in der Übergabe einer Rückrufmethode.One way to call Office.onReady() is to pass it a callback method. Hier ein Beispiel:Here's an example:

Office.onReady(function(info) {
    if (info.host === Office.HostType.Excel) {
        // Do Excel-specific initialization (for example, make add-in task pane's
        // appearance compatible with Excel "green").
    }
    if (info.platform === Office.PlatformType.PC) {
        // Make minor layout changes in the task pane.
    }
    console.log(`Office.js is now ready in ${info.host} on ${info.platform}`);
});

Alternativ können Sie eine then()-Methode mit dem Aufruf von Office.onReady() verketten, anstatt eine Rückrufmethode zu übergeben.Alternatively, you can chain a then() method to the call of Office.onReady(), instead of passing a callback. Beispielsweise überprüft der folgende Code, ob die Excel-Version des Benutzers alle APIs unterstützt, die möglicherweise vom Add-In aufgerufen werden.For example, the following code checks to see that the user's version of Excel supports all the APIs that the add-in might call.

Office.onReady()
    .then(function() {
        if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
            console.log("Sorry, this add-in only works with newer versions of Excel.");
        }
    });

Hier das gleiche Beispiel unter Verwendung der Schlüsselwörter async und await in TypeScript:Here is the same example using the async and await keywords in TypeScript:

(async () => {
    await Office.onReady();
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
})();

Wenn Sie zusätzliche JavaScript-Frameworks verwenden, die eigene Initialisierungshandler oder Tests enthalten, sollten diese normalerweise innerhalb der Antwort auf Office.onReady() platziert werden.If you are using additional JavaScript frameworks that include their own initialization handler or tests, these should be placed within the Office.initialize event. Bei Verwendung von JQuery beispielsweise würde wie folgt auf die $(document).ready()-Funktion verwiesen werden:For example, JQuery's $(document).ready() function would be referenced as follows:

Office.onReady(function() {
    // Office is ready
    $(document).ready(function () {
        // The document is ready
    });
});

Es gibt jedoch Ausnahmen von dieser Vorgehensweise.However, there are exceptions to this practice. Nehmen wir beispielsweise an, dass Sie Ihr Add-In in einem Browser öffnen möchten (statt es in einem Office-Host querzuladen), um Ihre Benutzeroberfläche mit Browsertools zu debuggen.For example, suppose you want to open your add-in in a browser (instead of sideload it in an Office host) in order to debug your UI with browser tools. Da Office.js im Browser nicht geladen wird, wird onReady nicht ausgeführt, und $(document).ready wird beim Aufruf innerhalb der Office-Methode onReady nicht ausgeführt.Since Office.js won't load in the browser, onReady won't run and the $(document).ready won't run if it's called inside the Office onReady. Ein weiteres Beispiel: Sie möchten während des Ladens des Add-Ins eine Statusanzeige im Aufgabenbereich anzeigen.Another exception: you want a progress indicator to appear in the task pane while the add-in is loading. In diesem Szenario sollte Ihr Code jQuery ready aufrufen und den entsprechenden Rückruf zum Rendern der Statusanzeige verwenden.In this scenario, your code should call the jQuery ready and use it's callback to render the progress indicator. Anschließend kann der Rückruf von Office onReady die Statusanzeige durch die endgültige Benutzeroberfläche ersetzen.Then the Office onReady's callback can replace the progress indicator with the final UI.

Initialisieren mit Office.initializeInitialize with Office.initialize

Ein Initialisierungsereignis wird ausgelöst, wenn die Office.js-Bibliothek vollständig geladen und für die Benutzerinteraktion bereit ist.An initialize event fires when the Office.js library is fully loaded and ready for user interaction. Sie können Office.initialize einen Handler zuweisen, der Ihre Initialisierungslogik implementiert.You can assign a handler to Office.initialize that implements your initialization logic. Beispielsweise wird im folgenden Beispiel überprüft, ob die Excel-Version des Benutzers alle APIs unterstützt, die möglicherweise vom Add-In aufgerufen werden.The following is an example that checks to see that the user's version of Excel supports all the APIs that the add-in might call.

Office.initialize = function () {
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
};

Wenn Sie zusätzliche JavaScript-Frameworks verwenden, die eigene Initialisierungshandler oder Tests enthalten, sollten diese normalerweise innerhalb des Office.initialize-Ereignisses platziert werden.If you are using additional JavaScript frameworks that include their own initialization handler or tests, these should be placed within the Office.initialize event. (Aber die im Abschnitt Initialisieren mit Office.onReady() beschriebenen Ausnahmen gelten auch in diesem Fall.) Beispielsweise würde auf die Funktion $(document).ready() von JQuery in folgender Weise verwiesen:(But the exceptions described in the Initialize with Office.onReady() section earlier apply in this case also.) For example, JQuery's $(document).ready() function would be referenced as follows:

Office.initialize = function () {
    // Office is ready
    $(document).ready(function () {
        // The document is ready
    });
  };

Für Add-Ins zu Aufgabenbereich und Inhalten stellt Office.initialize einen zusätzlichen Parameter reason bereit.For task pane and content add-ins, Office.initialize provides an additional reason parameter. Dieser Parameter gibt an, wie ein Add-In zum aktuellen Dokument hinzugefügt wurde.This parameter specifies how an add-in was added to the current document. Verwenden Sie ihn, um eine andere Logik für Add-Ins, die eingefügt wurden, und Add-Ins, die bereits im Dokument vorhanden waren, bereitzustellen.For task pane and content add-ins, Office.initialize provides an additional reason parameter. This parameter can be used to determine how an add-in was added to the current document. You can use this to provide different logic for when an add-in is first inserted versus when it already existed within the document.

Office.initialize = function (reason) {
    $(document).ready(function () {
        switch (reason) {
            case 'inserted': console.log('The add-in was just inserted.');
            case 'documentOpened': console.log('The add-in is already part of the document.');
        }
    });
 };

Weitere Informationen finden Sie unter Office.initialize-Ereignis und Enumeration InitializationReason.For more information, see Office.initialize Event and InitializationReason Enumeration.

Hinweis

Aktuell müssen Sie Office.Initialize festlegen, unabhängig davon, ob auch Office.onReady() aufgerufen wird.Currently, you must set Office.Initialize, regardless of whether Office.onReady() is also called. Wenn Sie keine Verwendung für Office.Initialize haben, können Sie es auf eine leere Funktion festlegen, wie im folgenden Beispiel dargestellt.If you have no use for Office.Initialize, you can set it to an empty function as shown in the following example.

Office.initialize = function () {};

Hauptunterschiede zwischen Office.initialize und Office.onReadyMajor differences between Office.initialize and Office.onReady

  • Sie können Office.initialize nur einen Handler zuweisen, und dieser wird von der Office-Infrastruktur nur einmal aufgerufen; Office.onReady() können Sie hingegen an verschiedenen Stellen in Ihrem Code aufrufen und verschiedene Rückrufe verwenden.You can assign only one handler to Office.initialize and it is called, only once, by the Office infrastructure; but you can call Office.onReady() in different places in your code and use different callbacks. Beispielsweise kann Ihr Code Office.onReady() direkt nach dem Laden Ihres benutzerdefinierten Skripts mit einem Rückruf aufrufen, der Initialisierungslogik ausführt; und Ihr Code kann darüber hinaus eine Schaltfläche im Aufgabenbereich aufweisen, dessen Skript Office.onReady() mit einem anderen Rückruf aufruft.For example, your code could call Office.onReady() as soon as your custom script loads with a callback that runs initialization logic; and your code could also have a button in the task pane, whose script calls Office.onReady() with a different callback. In diesem Fall wird der zweite Rückruf ausgeführt, wenn auf die Schaltfläche geklickt wird.If so, the second callback runs when the button is clicked.

  • Das Office.initialize-Ereignis wird am Ende des internen Prozesses ausgelöst, bei dem Office.js sich selbst initialisiert.The Office.initialize event fires at the end of the internal process in which Office.js initializes itself. Und die Auslösung erfolgt unmittelbar nach dem Ende des internen Prozesses.And it fires immediately after the internal process ends. Wenn der Code, in dem Sie dem Ereignis einen Handler zuweisen, zu lange nach dem Auslösen des Ereignisses ausgeführt wird, wird Ihr Handler nicht ausgeführt.If the code in which you assign a handler to the event executes too long after the event fires, then your handler doesn't run. Wenn Sie beispielsweise den WebPack-Task-Manager verwenden, konfiguriert dieser möglicherweise die Startseite des Add-Ins für das Laden von Polyfill-Dateien, nachdem Office.js geladen, doch bevor Ihr benutzerdefiniertes JavaScript geladen wurde.For example, if you are using the WebPack task manager, it might configure the add-in's home page to load polyfill files after it loads Office.js but before it loads your custom JavaScript. Zu dem Zeitpunkt, da Ihr Skript geladen wird und den Handler zuweist, ist das Initialisierungsereignis bereits geschehen.By the time your script loads and assigns the handler, the initialize event has already happened. Es ist aber nie "zu spät" für einen Aufruf von Office.onReady().But it is never "too late" to call Office.onReady(). Wenn das Initialisierungsereignis bereits geschehen ist, wird der Rückruf sofort ausgeführt.If the initialize event has already happened, the callback runs immediately.

Hinweis

Selbst wenn Sie keine Startlogik verwenden, sollten Sie Office.initialize beim Laden Ihres Add-In-JavaScripts eine leere Funktion zuweisen, wie im folgenden Beispiel gezeigt.Even if you have no start-up logic, you should assign an empty function to Office.initialize when your add-in JavaScript loads, as shown in the following example. Bei einigen Kombinationen aus Office-Host und Plattform wird der Aufgabenbereich erst geladen, nachdem das Initialisierungsereignis ausgelöst und die angegebene Ereignishandlerfunktion ausgeführt wurde.Some Office host and platform combinations won't load the task pane until the initialize event fires and the specified event handler function runs.

Office.initialize = function () {};

Office JavaScript-API-ObjektmodellOffice JavaScript API object model

Nach der Initialisierung kann das Add-In mit dem Host (z. B. Excel, Outlook) interagieren.Once initialized, the add-in can interact with the host (e.g. Excel, Outlook). Die Seite Office JavaScript-API-Objektmodell enthält weitere Details zu bestimmten Nutzungsmustern.The Office JavaScript API object model page has more details on specific usage patterns. Darüber hinaus gibt es eine detaillierte Referenzdokumentation zu gemeinsam verwendeten APIs und bestimmten Hosts.There is also detailed reference documentation for both shared APIs and specific hosts.

Matrix der API-UnterstützungAPI support matrix

Diese Tabelle bietet eine Übersicht über die API und von verschiedenen Add-In-Typen unterstützten Features (Inhalt, Aufgabenbereich und Outlook) sowie über die Office-Anwendungen, die diese hosten können, wenn Sie Office-Hostanwendungen, die von Ihrem Add-in unterstützt werden mithilfe des 1.1-Add-in-Manifestschemas und Features angeben, die von der Version 1.1 JavaScript API für Office unterstützt werden.This table summarizes the API and features supported across add-in types (content, task pane, and Outlook) and the Office applications that can host them when you specify the Office host applications your add-in supports by using the 1.1 add-in manifest schema and features supported by v1.1 JavaScript API for Office.

HostnameHost name DatenbankDatabase ArbeitsmappeWorkbook PostfachMailbox PräsentationPresentation DokumentDocument ProjectProject
Unterstützte HostanwendungenSupported Host applications Access-Web-AppsAccess web apps Excel,Excel,
Excel OnlineExcel Online
Outlook,Outlook,
Outlook Web App,Outlook Web App,
OWA für GeräteOWA for Devices
PowerPoint,PowerPoint
PowerPoint OnlinePowerPoint Online
WordWord ProjectProject
Unterstützte Add-In-TypenSupported add-in types InhaltContent vY vY vY
AufgabenbereichTask Pane vY vY vY vY
OutlookOutlook vY
Unterstützte API-FeaturesSupported API features Text lesen/schreibenRead/Write Text vY vY vY vY
(Schreibgeschützt)(Read only)
Matrix lesen/schreibenRead/Write Matrix vY vY
Tabelle lesen/schreibenRead/Write Table vY vY
HTML lesen/schreibenRead/Write HTML vY
Lesen/SchreibenRead/Write
Office Open XMLOffice Open XML
vY
Eigenschaften von Aufgaben, Ressourcen,Ansichten und Feldern lesenRead task, resource, view, and field properties vY
SelectionChanged-EreignisseSelection changed events vY vY
Das gesamte Dokument abrufenGet whole document vY vY
Bindungen und BindungsereignisseBindings and binding events vY
(Nur vollständige und teilweise Tabellenbindungen)(Only full and partial table bindings)
vY vY
Benutzerdefinierte XML-Komponenten lesen/schreibenRead/Write Custom XML Parts vY
Add-In-Statusdaten beibehalten (Einstellungen)Persist add-in state data (settings) vY
(Pro Host-Add-In)(Per host add-in)
vY
(Pro Dokument)(Per document)
vY
(Pro Postfach)(Per mailbox)
vY
(Pro Dokument)(Per document)
vY
(Pro Dokument)(Per document)
SettingsChanged-EreignisseSettings changed events vY vY vY vY
Aktiver AnsichtsmodusGet active view mode
und ViewChanged-Ereignisseand view changed events
vY
Navigieren zu SpeicherortenNavigate to locations
im Dokumentin the document
vY vY vY
Aktivieren von kontextuellenActivate contextually
Verwendungsregeln und RegExusing rules and RegEx
vY
Elementeigenschaften lesenRead Item properties vY
Benutzerprofil lesenRead User profile vY
Anlagen abrufenGet attachments vY
Benutzeridentitätstoken abrufenGet User identity token vY
Exchange-Webdienste aufrufenCall Exchange Web Services vY