Laden des DOM und der LaufzeitumgebungLoading the DOM and runtime environment

Für ein Add-In muss vor dem Ausführen der eigenen benutzerdefinierten Logik sichergestellt werden, dass sowohl das Dokumentobjektmodell (DOM) als auch die Office-Add-Ins-Laufzeitumgebung geladen wurden.An add-in must ensure that both the DOM and the Office Add-ins runtime environment are loaded before running its own custom logic.

Starten eines Inhalts- oder Aufgabenbereich-Add-insStartup of a content or task pane add-in

In der folgenden Abbildung wird der Ereignisablauf beim Starten eines Inhalts- oder Aufgabenbereich-Add-Ins in Excel, PowerPoint, Project, Word oder Access gezeigt.The following figure shows the flow of events involved in starting a content or task pane add-in in Excel, PowerPoint, Project, Word, or Access.

Ereignisablauf beim Starten eines Inhalts- oder Aufgabenbereich-Add-Ins

Die folgenden Ereignisse treten auf, wenn ein Inhalts- oder Aufgabenbereich-Add-In gestartet wird:The following events occur when a content or task pane add-in starts:

  1. Der Benutzer öffnet ein Dokument, das bereits ein Add-In enthält, oder fügt ein Add-In in das Dokument ein.The user opens a document that already contains an add-in or inserts an add-in in the document.

  2. Die Office-Hostanwendung liest das XML-Manifest des Add-ins aus AppSource, einem Add-In-Katalog in SharePoint oder dem freigegebenen Ordnerkatalog, aus dem das Add-In stammt.The Office host application reads the add-in's XML manifest from AppSource, an add-in catalog on SharePoint, or the shared folder catalog it originates from.

  3. Die Office-Hostanwendung öffnet die HTML-Seite des Add-Ins in einem Browsersteuerelement.The Office host application opens the add-in's HTML page in a browser control.

    Die nächsten beiden Schritte, 4 und 5, werden asynchron und parallel ausgeführt. Daher muss der Code des Add-ins sicherstellen, dass sowohl das Dokumentobjektmodell (DOM) als auch die Laufzeitumgebung geladen wurden, bevor fortgefahren werden kann.The next two steps, steps 4 and 5, occur asynchronously and in parallel. For this reason, your add-in's code must make sure that both the DOM and the add-in runtime environment have finished loading before proceeding.

  4. Das Browsersteuerelement lädt das DOM und den HTML-Textkörper und ruft den Ereignishandler für das window.onload-Ereignis auf.The browser control loads the DOM and HTML body, and calls the event handler for the window.onload event.

  5. Die Office-Hostanwendung lädt die Laufzeitumgebung, die wiederum die JavaScript-API für JavaScript-Bibliotheksdateien vom CDN-Server (Content Distribution Network) herunterlädt und zwischenspeichert und anschließend den Ereignishandler des Add-ins für das initialize-Ereignis des Office-Objekts aufruft, wenn ihm ein Handler zugewiesen wurde.The Office host application loads the runtime environment, which downloads and caches the JavaScript API for JavaScript library files from the content distribution network (CDN) server, and then calls the add-in's event handler for the initialize event of the Office object, if a handler has been assigned to it. Gleichzeitig wird auch überprüft, ob irgendwelche Rückrufe (oder verkettete then()-Funktionen) dem Office.onReady-Handler übergeben (oder mit ihm verkettet) wurden.At this time it also checks to see if any callbacks (or chained then() functions) have been passed (or chained) to the Office.onReady handler. Weitere Informationen zu den Unterschieden zwischen Office.initialize und Office.onReady finden Sie unter Initialisierung Ihres Add-in.For more information about the distinction between Office.initialize and Office.onReady, see Initializing your add-in.

  6. Wenn DOM und der HTML-Textkörper vollständig geladen wurden und das Add-in initialisiert ist, kann die Hauptfunktion des Add-ins fortgesetzt werden.When the DOM and HTML body finish loading and the add-in finishes initializing, the main function of the add-in can proceed.

Starten eines Outlook-Add-InsStartup of an Outlook add-in

In der folgenden Abbildung wird der Ereignisablauf beim Starten eines Outlook-Add-Ins auf dem Desktop, Tablet oder Smartphone gezeigt.The following figure shows the flow of events involved in starting an Outlook add-in running on the desktop, tablet, or smartphone.

Ereignisablauf beim Starten eines Outlook-Add-Ins

Die folgenden Ereignisse treten auf, wenn ein Outlook-Add-In gestartet wird:The following events occur when an Outlook add-in starts:

  1. Beim Starten von Outlook werden die XML-Manifeste für Outlook-Add-Ins gelesen, die für das E-Mail-Konto des Benutzers installiert wurden.When Outlook starts, Outlook reads the XML manifests for Outlook add-ins that have been installed for the user's email account.

  2. Der Benutzer wählt ein Element in Outlook aus.The user selects an item in Outlook.

  3. Falls das ausgewählte Element die Aktivierungsbedingungen eines Outlook-Add-Ins erfüllt, aktiviert Outlook das Add-In und zeigt die Schaltfläche in der Benutzeroberfläche an.If the selected item satisfies the activation conditions of an Outlook add-in, Outlook activates the add-in and makes its button visible in the UI.

  4. Falls der Benutzer auf die Schaltfläche klickt, um das Outlook-Add-In zu starten, öffnet Outlook die HTML-Seite in einem Browsersteuerelement. Die nächsten beiden Schritte, also Schritt 5 und 6, werden parallel ausgeführt.If the user clicks the button to start the Outlook add-in, Outlook opens the HTML page in a browser control. The next two steps, steps 5 and 6, occur in parallel.

  5. Das Browsersteuerelement lädt DOM sowie den HTML-Textkörper und ruft den Ereignishandler für das onload-Ereignis auf.The browser control loads the DOM and HTML body, and calls the event handler for the onload event.

  6. Outlook lädt die Laufzeitumgebung, welche wiederum die JavaScript-API für JavaScript-Bibliotheksdateien vom CDN-Server (Content Distribution Network) herunterlädt und zwischenspeichert und anschließend den Ereignishandler des Add-ins für das initialize-Ereignis des Office-Objekts aufruft, wenn ihm ein Handler zugewiesen wurde.Outlook loads the runtime environment, which downloads and caches the JavaScript API for JavaScript library files from the content distribution network (CDN) server, and then calls the event handler for the initialize event of the Office object of the add-in, if a handler has been assigned to it. Gleichzeitig wird auch überprüft, ob irgendwelche Rückrufe (oder verkettete then()-Funktionen) dem Office.onReady-Handler übergeben (oder mit ihm verkettet) wurden.At this time it also checks to see if any callbacks (or chained then() functions) have been passed (or chained) to the Office.onReady handler. Weitere Informationen zu den Unterschieden zwischen Office.initialize und Office.onReady finden Sie unter Initialisierung Ihres Add-in.For more information about the distinction between Office.initialize and Office.onReady, see Initializing your add-in.

  7. Wenn DOM und der HTML-Textkörper vollständig geladen wurden und das Add-in initialisiert ist, kann die Hauptfunktion des Add-ins fortgesetzt werden.When the DOM and HTML body finish loading and the add-in finishes initializing, the main function of the add-in can proceed.

Überprüfen des LadestatusChecking the load status

Eine Möglichkeit zu überprüfen, ob sowohl das DOM als auch die Laufzeitumgebung geladen wurden, ist mit der jQuery-Funktion .ready(): $(document).ready().One way to check that both the DOM and the runtime environment have finished loading is to use the jQuery .ready() function: $(document).ready(). Beispiel: Der folgende Ereignishandler OnReady stellt sicher, dass das DOM zuerst geladen wird, bevor der spezifische Code für das Initialisieren des Add-Ins ausgeführt wird.For example, the following onReady event handler makes sure the DOM is first loaded before the code specific to initializing the add-in runs. Anschließend verwendet der Handler OnReady die Eigenschaft mailbox.item, um das derzeit ausgewählte Element in Outlook zu erhalten, und ruft die Hauptfunktion initDialer des Add-ins auf.Subsequently, the onReady handler proceeds to use the mailbox.item property to obtain the currently selected item in Outlook, and calls the main function of the add-in, initDialer.

Office.onReady()
    .then(
        // Checks for the DOM to load.
        $(document).ready(function () {
            // After the DOM is loaded, add-in-specific code can run.
            var mailbox = Office.context.mailbox;
            _Item = mailbox.item;
            initDialer();
        });
);

Alternativ können Sie den gleichen Code in einem initialize-Ereignishandler verwenden, wie im folgenden Beispiel gezeigt.Alternatively, you can use the same code in an initialize event handler as shown in the following example.

Office.initialize = function () {
    // Checks for the DOM to load.
    $(document).ready(function () {
        // After the DOM is loaded, add-in-specific code can run.
        var mailbox = Office.context.mailbox;
        _Item = mailbox.item;
        initDialer();
    });
}

Dieselbe Vorgehensweise kann in den onReady- oder initialize-Handlern in jedem Office-Add-In verwendet werden.This same technique can be used in the onReady or initialize handlers of any Office Add-in.

Das Beispiel-Outlook-Add-In für die Telefonwählvorrichtung wählt einen geringfügig anderen Ansatz, wobei nur JavaScript zum Überprüfen derselben Bedingungen verwendet wird.The phone dialer sample Outlook add-in shows a slightly different approach using only JavaScript to check these same conditions.

Wichtig

Selbst wenn Ihr Add-In über keine auszuführenden Initialisierungsaufgaben verfügt, müssen Sie mindestens einen Aufruf von Office.onReady einschließen oder eine minimale Office.initialize-Ereignishandlerfunktion zuweisen, wie in den folgenden Beispielen gezeigt.Even if your add-in has no initialization tasks to perform, you must include at least a call of Office.onReady or assign minimal Office.initialize event handler function as shown in the following examples.

Office.onReady();
Office.initialize = function () {};

Wenn Sie Office.onReady nicht aufrufen oder keinen Office.initialize-Ereignishandler zuweisen, meldet das Add-in beim Start möglicherweise einen Fehler.If you do not call Office.onReady or assign an Office.initialize event handler, your add-in may raise an error when it starts. Auch wenn ein Benutzer versucht, das Add-In mit einem Office Online-Webclient wie Excel Online, PowerPoint Online oder Outlook Web App zu verwenden, wird beim Ausführen ein Fehler auftreten.Also, if a user attempts to use your add-in with an Office Online web client, such as Excel Online, PowerPoint Online, or Outlook Web App, it will fail to run.

Falls Ihr Add-in mehr als eine Seite enthält, muss bei jedem Laden einer neuen Seite immer Office.onReady von der entsprechenden Seite aufgerufen oder ein Office.initialize-Ereignishandler zugewiesen werden.If your add-in includes more than one page, whenever it loads a new page that page must either call Office.onReady or assign an Office.initialize event handler.

Siehe auchSee also