Initialisieren Ihres Office-Add-Ins

Office-Add-Ins weisen häufig eine Startlogik für Vorgänge wie diese auf:

• Überprüfen Sie, ob die Office-Version des Benutzers alle Office-APIs unterstützt, die Ihr Code aufruft.

• Stellen Sie sicher, dass bestimmte Artefakte vorhanden sind, z. B. ein Arbeitsblatt mit einem bestimmten Namen.

• Fordern Sie den Benutzer auf, einige Zellen in Excel auszuwählen, und fügen Sie dann ein Diagramm ein, das mit diesen ausgewählten Werten initialisiert wurde.

• Einrichten von Bindungen.

• Verwenden Sie die Office-Dialog-API, um den Benutzer zur Eingabe von Add-In-Standardeinstellungswerten aufzufordern.

Ein Office-Add-In kann jedoch keine Office-JavaScript-APIs aufrufen, bis die Bibliothek geladen wurde. In diesem Artikel werden die beiden Möglichkeiten beschrieben, mit denen Ihr Code sicherstellen kann, dass die Bibliothek geladen wurde.

• Initialisieren Sie mit Office.onReady().
• Initialisieren Sie mit Office.initialize.

Weitere Details zur Ereignisabfolge beim Initialisieren eines Add-Ins finden Sie unter Laden des DOM und der Laufzeitumgebung.

Initialisieren mit Office.onReady()

Office.onReady() ist eine asynchrone Funktion, die ein Promise-Objekt zurückgibt, während überprüft wird, ob die Office.js Bibliothek geladen ist. Wenn die Bibliothek geladen wird, löst sie die Zusage als Objekt auf, das die Office-Clientanwendung mit einem Office.HostType Enumerationswert (Excel, Wordusw.) und die Plattform mit einem Office.PlatformType Enumerationswert (PC, , MacOfficeOnlineusw.) angibt. Die Zusage wird sofort aufgelöst, wenn die Bibliothek beim Aufruf von Office.onReady() bereits geladen ist.

Eine Möglichkeit zum Aufrufen Office.onReady() besteht darin, eine Rückruffunktion zu übergeben. Im Folgenden sehen Sie ein Beispiel.

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. Beispielsweise überprüft der folgende Code, ob die Excel-Version des Benutzers alle APIs unterstützt, die möglicherweise vom Add-In aufgerufen werden.

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 sehen Sie das gleiche Beispiel mit den async Schlüsselwörtern und await 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 einen eigenen Initialisierungshandler oder -tests enthalten, sollten diese in der Regel in der Antwort auf Office.onReady()platziert werden. Auf die JQuery-Methode$(document).ready() wird beispielsweise wie folgt verwiesen:

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

Es gibt jedoch Ausnahmen von dieser Vorgehensweise. Angenommen, Sie möchten Ihr Add-In in einem Browser öffnen (anstatt es in einer Office-Anwendung querladen), um Ihre Benutzeroberfläche mit Browsertools zu debuggen. Sobald Office.js in diesem Szenario feststellt, dass er außerhalb einer Office-Hostanwendung ausgeführt wird, wird der Rückruf aufgerufen und die Zusage sowohl für den Host als auch für die Plattform mit null aufgelöst.

Eine weitere Ausnahme wäre, wenn eine Statusanzeige im Aufgabenbereich angezeigt werden soll, während das Add-In geladen wird. In diesem Szenario sollte Ihr Code jQuery ready aufrufen und dessen Rückruf verwenden, um die Statusanzeige zu rendern. Anschließend kann der Office.onReady Rückruf die Statusanzeige durch die endgültige Benutzeroberfläche ersetzen.

Initialisieren mit Office.initialize

Ein Initialisierungsereignis wird ausgelöst, wenn die Office.js-Bibliothek geladen und für die Benutzerinteraktion bereit ist. Sie können Office.initialize einen Handler zuweisen, der Ihre Initialisierungslogik implementiert. 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.

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 einen eigenen Initialisierungshandler oder eigene Tests enthalten, sollten diese in der Regel innerhalb des Office.initialize Ereignisses platziert werden (die ausnahmen, die zuvor im Abschnitt Initialize with Office.onReady() beschrieben wurden, gelten auch in diesem Fall). Auf die JQuery-Methode$(document).ready() wird beispielsweise wie folgt verwiesen:

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. Dieser Parameter gibt an, wie ein Add-In zum aktuellen Dokument hinzugefügt wurde. 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.

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.

Hauptunterschiede zwischen Office.initialize und 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. 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. In diesem Fall wird der zweite Rückruf ausgeführt, wenn auf die Schaltfläche geklickt wird.

• Das Office.initialize-Ereignis wird am Ende des internen Prozesses ausgelöst, bei dem Office.js sich selbst initialisiert. Und die Auslösung erfolgt unmittelbar nach dem Ende des internen Prozesses. 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. 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. Zu dem Zeitpunkt, da Ihr Skript geladen wird und den Handler zuweist, ist das Initialisierungsereignis bereits geschehen. Es ist jedoch nie "zu spät", um aufzurufen Office.onReady(). Wenn das Initialisierungsereignis bereits geschehen ist, wird der Rückruf sofort ausgeführt.

Office.onReady();

Office.initialize = function () {};

Debuginitialisierung

Informationen zum Debuggen der Office.initialize Funktionen und Office.onReady() finden Sie unter Debuggen der Funktionen initialize und onReady.

Siehe auch

• Grundlegendes zur JavaScript-API für Office
• Laden des DOM und der Laufzeitumgebung