Anzeigen oder Ausblenden des Aufgabenbereichs Ihres Office-Add-In

  • Artikel

Wichtig

Die freigegebene Runtime wird nur in einigen Office-Anwendungen unterstützt. Weitere Informationen finden Sie unter Gemeinsame Laufzeitanforderungsgruppen.

Sie können den Aufgabenbereich Ihres Office-Add-Ins anzeigen, indem Sie die Office.addin.showAsTaskpane() -Methode aufrufen.

function onCurrentQuarter() {
    Office.addin.showAsTaskpane()
    .then(function() {
        // Code that enables task pane UI elements for
        // working with the current quarter.
    });
}

Der vorherige Code geht von einem Szenario aus, in dem ein Excel-Arbeitsblatt mit dem Namen CurrentQuarterSales vorhanden ist. Das Add-In macht den Aufgabenbereich sichtbar, wenn dieses Arbeitsblatt aktiviert wird. Die -Methode onCurrentQuarter ist ein Handler für das Office.Worksheet.onActivated-Ereignis , das für das Arbeitsblatt registriert wurde.

Sie können den Aufgabenbereich auch ausblenden, indem Sie die Office.addin.hide() -Methode aufrufen.

function onCurrentQuarterDeactivated() {
    Office.addin.hide();
}

Der vorherige Code ist ein Handler, der für das Office.Worksheet.onDeactivated-Ereignis registriert ist.

Zusätzliche Details zum Anzeigen des Aufgabenbereichs

Wenn Sie aufrufen Office.addin.showAsTaskpane(), zeigt Office in einem Aufgabenbereich die Datei an, die Sie als Ressourcen-ID (resid) des Aufgabenbereichs zugewiesen haben. Dieser resid Wert kann zugewiesen oder geändert werden, indem Sie Ihre manifest.xml Datei öffnen und SourceLocation> im -Element suchen<.<Action xsi:type="ShowTaskpane"> (Weitere Informationen finden Sie unter Konfigurieren Ihres Office-Add-Ins für die Verwendung einer freigegebenen Runtime .)

Da Office.addin.showAsTaskpane() eine asynchrone Methode ist, wird Ihr Code weiterhin ausgeführt, bis die Methode abgeschlossen ist. Warten Sie auf diesen Abschluss entweder mit dem await Schlüsselwort oder einer then() Methode, je nachdem, welche JavaScript-Syntax Sie verwenden.

Konfigurieren Ihres Add-Ins für die Verwendung der freigegebenen Runtime

Um die showAsTaskpane() Methoden und hide() verwenden zu können, muss Ihr Add-In die freigegebene Runtime verwenden. Weitere Informationen finden Sie unter Konfigurieren Ihres Office-Add-Ins für die Verwendung einer freigegebenen Runtime.

Beibehalten von Zustands- und Ereignislistenern

Die hide() Methoden und showAsTaskpane() ändern nur die Sichtbarkeit des Aufgabenbereichs. Sie werden nicht entladen oder neu laden (oder ihren Zustand erneut initialisieren).

Betrachten Sie das folgende Szenario: Ein Aufgabenbereich ist mit Registerkarten konzipiert. Die Registerkarte Start ist geöffnet, wenn das Add-In zum ersten Mal gestartet wird. Angenommen, ein Benutzer öffnet die Registerkarte Einstellungen , und später wird code im Aufgabenbereich als Reaktion auf ein Ereignis aufgerufen hide() . Noch spätere Codeaufrufe showAsTaskpane() als Reaktion auf ein anderes Ereignis. Der Aufgabenbereich wird wieder angezeigt, und die Registerkarte Einstellungen ist weiterhin ausgewählt.

Ein Aufgabenbereich mit vier Registerkarten mit den Bezeichnungen Start, Einstellungen, Favoriten und Konten.

Darüber hinaus werden alle im Aufgabenbereich registrierten Ereignislistener weiterhin ausgeführt, auch wenn der Aufgabenbereich ausgeblendet ist.

Betrachten Sie das folgende Szenario: Der Aufgabenbereich verfügt über einen registrierten Handler für Excel Worksheet.onActivated und Worksheet.onDeactivated Ereignisse für ein Blatt mit dem Namen Sheet1. Der aktivierte Handler bewirkt, dass im Aufgabenbereich ein grüner Punkt angezeigt wird. Der deaktivierte Handler zeigt den Punkt rot (der Standardzustand). Angenommen, dieser Code ruft auf hide() , wenn Sheet1 nicht aktiviert ist und der Punkt rot ist. Während der Aufgabenbereich ausgeblendet ist, wird Sheet1 aktiviert. Spätere Codeaufrufe showAsTaskpane() als Reaktion auf ein Ereignis. Wenn der Aufgabenbereich geöffnet wird, ist der Punkt grün, da die Ereignislistener und -handler ausgeführt wurden, obwohl der Aufgabenbereich ausgeblendet war.

Behandeln des Sichtbarkeitsänderungsereignisses

Wenn Ihr Code die Sichtbarkeit des Aufgabenbereichs mit showAsTaskpane() oder hide()ändert, löst Office das VisibilityModeChanged -Ereignis aus. Es kann nützlich sein, dieses Ereignis zu behandeln. Angenommen, der Aufgabenbereich zeigt eine Liste aller Blätter in einer Arbeitsmappe an. Wenn ein neues Arbeitsblatt hinzugefügt wird, während der Aufgabenbereich ausgeblendet ist, würde das Anzeigen des Aufgabenbereichs nicht den namen des neuen Arbeitsblatts zur Liste hinzufügen. Ihr Code kann jedoch auf das VisibilityModeChanged -Ereignis reagieren, um die Worksheet.name-Eigenschaft aller Arbeitsblätter in der Workbook.worksheets-Auflistung neu zu laden, wie im folgenden Beispielcode gezeigt.

Um einen Handler für das Ereignis zu registrieren, verwenden Sie keine "Handler hinzufügen"-Methode wie in den meisten Office JavaScript-Kontexten. Stattdessen gibt es eine spezielle Funktion, an die Sie Ihren Handler übergeben: Office.addin.onVisibilityModeChanged. Es folgt ein Beispiel. Beachten Sie, dass die Eigenschaft den args.visibilityMode Typ VisibilityMode hat.

Office.addin.onVisibilityModeChanged(function(args) {
    if (args.visibilityMode == "Taskpane") {
        // Code that runs whenever the task pane is made visible.
        // For example, an Excel.run() that loads the names of
        // all worksheets and passes them to the task pane UI.
    }
});

Die Funktion gibt eine weitere Funktion zurück, die die Registrierung des Handlers auf hebt . Hier ist ein einfaches, aber nicht robustes Beispiel.

const removeVisibilityModeHandler =
    Office.addin.onVisibilityModeChanged(function(args) {
        if (args.visibilityMode == "Taskpane") {
            // Code that runs whenever the task pane is made visible.
        }
    });


// In some later code path, deregister with:
removeVisibilityModeHandler();

Die onVisibilityModeChanged -Methode ist asynchron und gibt eine Zusage zurück. Dies bedeutet, dass Ihr Code auf die Erfüllung der Zusage warten muss, bevor er den Handler für die Aufhebung der Registrierung aufrufen kann.

// await the promise from onVisibilityModeChanged and assign
// the returned deregister handler to removeVisibilityModeHandler.
const removeVisibilityModeHandler =
    await Office.addin.onVisibilityModeChanged(function(args) {
        if (args.visibilityMode == "Taskpane") {
            // Code that runs whenever the task pane is made visible.
        }
    });

Die Funktion zum Aufheben der Registrierung ist ebenfalls asynchron und gibt eine Zusage zurück. Wenn Sie also über Code verfügen, der erst nach Abschluss der Aufhebung der Registrierung ausgeführt werden soll, sollten Sie auf die von der Funktion zum Aufheben der Registrierung zurückgegebene Zusage warten.

// await the promise from the deregister handler before continuing
await removeVisibilityModeHandler();
// subsequent code here

Siehe auch