Freigeben über

Initialisieren Ihres Office-Add-Ins

  • Artikel

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.

Tipp

Sie sollten Office.onReady() anstelle von Office.initialize verwenden. Obwohl Office.initialize weiterhin unterstützt wird, Office.onReady() bietet sie mehr Flexibilität. Sie können nur einen Handler Office.initialize zuweisen, der von der Office-Infrastruktur nur einmal aufgerufen wird. Sie können an verschiedenen Stellen im Code aufrufen Office.onReady() und verschiedene Rückrufe verwenden.

Informationen zu den Unterschieden zwischen diesen beiden Techniken finden Sie unter Hauptunterschiede zwischen Office.initialize und Office.onReady().

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.

Hinweis

Selbst wenn Sie keine Startlogik verwenden, sollten Sie Office.onReady() aufrufen oder Office.initialize beim Laden Ihres Add-In-JavaScripts eine leere Funktion zuweisen. Einige Kombinationen aus Office-Anwendungen und -Plattformen laden den Aufgabenbereich erst, wenn eine dieser Optionen eintritt. Die folgenden Beispiele veranschaulichen diese beiden Verfahren.

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