Freigeben über

Ändern der Verfügbarkeit von Add-In-Befehlen

  • Artikel

Wenn einige Funktionen in Ihrem Add-In nur in bestimmten Kontexten verfügbar sein sollten, können Sie Ihre benutzerdefinierten Add-In-Befehle programmgesteuert so konfigurieren, dass sie nur in diesen Kontexten verfügbar sind. Beispielsweise sollte eine Funktion, die den Header einer Tabelle ändert, nur verfügbar sein, wenn sich der Cursor in einer Tabelle befindet.

Hinweis

  • In diesem Artikel wird davon ausgegangen, dass Sie mit den grundlegenden Konzepten für Add-In-Befehle vertraut sind. Überprüfen Sie es, wenn Sie in letzter Zeit nicht mit Add-In-Befehlen (benutzerdefinierte Menüelemente und Menübandschaltflächen) gearbeitet haben.

Unterstützte Funktionen

Sie können die Verfügbarkeit eines Add-In-Befehls für die folgenden Funktionen programmgesteuert ändern.

  • Menübandschaltflächen, Menüs und Registerkarten.
  • Kontextmenüelemente.

Unterstützung für Office-Anwendungen und Anforderungssätze

In der folgenden Tabelle werden die Office-Anwendungen beschrieben, die das Konfigurieren der Verfügbarkeit von Add-In-Befehlen unterstützen. Außerdem werden die erforderlichen Anforderungssätze für die Verwendung der API aufgelistet.

Add-In-Befehlsfunktion Anforderungssatz Unterstützte Office-Anwendungen
Menübandschaltflächen, Menüs und Registerkarten RibbonApi 1.1
  • Excel
  • PowerPoint
  • Word
Kontextmenüelemente ContextMenuApi 1.1
  • Excel
  • PowerPoint
  • Word

Tipp

Informationen zum Testen der Plattformunterstützung mit Anforderungssätzen finden Sie unter Office-Versionen und Anforderungssätze.

Konfigurieren einer freigegebenen Runtime

Um die Verfügbarkeit eines Menüband- oder Kontextmenüsteuerelements oder -elements zu ändern, muss das Manifest Ihres Add-Ins zunächst für die Verwendung einer freigegebenen Runtime konfiguriert werden. Eine Anleitung zum Einrichten einer freigegebenen Runtime finden Sie unter Konfigurieren Ihres Office-Add-Ins für die Verwendung einer freigegebenen Runtime.

Programmgesteuertes Ändern der Verfügbarkeit eines Add-In-Befehls

Deaktivieren von Menübandsteuerelementen beim Start

Hinweis

Nur die Steuerelemente im Menüband können deaktiviert werden, wenn die Office-Anwendung gestartet wird. Benutzerdefinierte Steuerelemente, die einem Kontextmenü beim Start hinzugefügt wurden, können nicht deaktiviert werden.

Standardmäßig ist eine benutzerdefinierte Schaltfläche oder ein benutzerdefiniertes Menüelement im Menüband für die Verwendung verfügbar, wenn die Office-Anwendung gestartet wird. Um es beim Starten von Office zu deaktivieren, müssen Sie dies im Manifest angeben. Der Prozess hängt davon ab, welche Art von Manifest Ihr Add-In verwendet.

Einheitliches Manifest für Microsoft 365

Hinweis

Das einheitliche Manifest für Microsoft 365 kann in Outlook-Produktions-Add-Ins verwendet werden. Es ist nur als Vorschau für Excel-, PowerPoint- und Word-Add-Ins verfügbar.

Fügen Sie einfach dem Steuerelement- oder Menüelementobjekt eine "enabled"-Eigenschaft mit dem Wert false hinzu. Im Folgenden wird die grundlegende Struktur veranschaulicht.

"extensions": [
    ...
    {
        ...
        "ribbons": [
            ...
            {
                ...
                "tabs": [
                    {
                        "id": "MyTab",
                        "groups": [
                            {
                                ...
                                "controls": [
                                    {
                                        "id": "Contoso.MyButton1",
                                        ...
                                        "enabled": false
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    }
]

Manifest nur für Add-Ins

Fügen Sie einfach ein Enabled-Element direkt unterhalb (nicht innerhalb) des Action-Elements des Steuerelementelements hinzu. Legen Sie dann den Wert auf fest false.

Im Folgenden wird die grundlegende Struktur eines Manifests veranschaulicht, das das <Enabled-Element> konfiguriert.

<OfficeApp ...>
  ...
  <VersionOverrides ...>
    ...
    <Hosts>
      <Host ...>
        ...
        <DesktopFormFactor>
          <ExtensionPoint ...>
            <CustomTab ...>
              ...
              <Group ...>
                ...
                <Control ... id="Contoso.MyButton3">
                  ...
                  <Action ...>
                  <Enabled>false</Enabled>
...
</OfficeApp>

Ändern der Verfügbarkeit eines Menübandsteuerelements

Führen Sie die folgenden Schritte aus, um die Verfügbarkeit einer Schaltfläche oder eines Menüelements auf dem Menüband zu aktualisieren.

  1. Erstellen Sie ein RibbonUpdaterData-Objekt , das Folgendes angibt:
    • Die IDs des Befehls, einschließlich der übergeordneten Gruppe und Registerkarte. Die IDs müssen mit den im Manifest deklarierten IDs übereinstimmen.
    • Die Verfügbarkeit status des Befehls.
  2. Übergeben Sie das Objekt RibbonUpdaterData an die Methode Office.ribbon.requestUpdate().

Nachfolgend sehen Sie ein einfaches Beispiel. Beachten Sie, dass "MyButton", "OfficeAddinTab1" und "CustomGroup111" aus dem Manifest kopiert werden.

function enableButton() {
    const ribbonUpdaterData = {
        tabs: [
            {
                id: "OfficeAppTab1",
                groups: [
                    {
                      id: "CustomGroup111",
                      controls: [
                        {
                            id: "MyButton",
                            enabled: true
                        }
                      ]
                    }
                ]
            }
        ]
    };

    Office.ribbon.requestUpdate(ribbonUpdaterData);
}

Es gibt mehrere Schnittstellen (Typen), um das Erstellen des RibbonUpdateData-Objekts zu vereinfachen.

Das folgende Beispiel ist das entsprechende Beispiel in TypeScript und verwendet diese Typen.

const enableButton = async () => {
    const button: Control = { id: "MyButton", enabled: true };
    const parentGroup: Group = { id: "CustomGroup111", controls: [button] };
    const parentTab: Tab = { id: "OfficeAddinTab1", groups: [parentGroup] };
    const ribbonUpdater: RibbonUpdaterData = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);
}

Tipp

Sie können awaitrequestUpdate() aufrufen, wenn die übergeordnete Funktion asynchron ist. Beachten Sie jedoch, dass die Office-Anwendung steuert, wann sie den Status des Menübands aktualisiert. Die Methode requestUpdate() stellt eine Anforderung zur Aktualisierung in eine Warteschlange. Die -Methode löst das Zusageobjekt auf, sobald die Anforderung in die Warteschlange gestellt wurde, und nicht, wenn das Menüband tatsächlich aktualisiert wird.

Gleichzeitiges Umschalten der Registerkartensichtbarkeit und aktivierter status einer Schaltfläche

Die requestUpdate-Methode wird auch verwendet, um die Sichtbarkeit einer benutzerdefinierten kontextbezogenen Registerkarte umzuschalten. Ausführliche Informationen zu diesem Code und Beispielcode finden Sie unter Erstellen benutzerdefinierter kontextbezogener Registerkarten in Office-Add-Ins.

Ändern des Status als Reaktion auf ein Ereignis

Ein häufiges Szenario, in dem sich der Status eines Menübands oder Kontextmenüsteuerelements ändern sollte, ist, wenn ein vom Benutzer initiiertes Ereignis den Add-In-Kontext ändert. Stellen Sie sich ein Szenario vor, in dem eine Schaltfläche verfügbar sein sollte, wenn und nur dann, wenn ein Diagramm aktiviert wird. Obwohl im folgenden Beispiel Menübandsteuerelemente verwendet werden, kann eine ähnliche Implementierung auf benutzerdefinierte Elemente in einem Kontextmenü angewendet werden.

  1. Legen Sie zunächst das <Enabled-Element> für die Schaltfläche im Manifest auf fest false. Eine Anleitung zur Konfiguration finden Sie unter Deaktivieren von Menübandsteuerelementen beim Start.

  2. Weisen Sie dann Handler zu. Dies erfolgt in der Regel in der Office.onReady-Funktion wie im folgenden Beispiel. Im Beispiel werden Handler (die in einem späteren Schritt erstellt wurden) den OnActivated - und onDeactivated-Ereignissen aller Diagramme in einem Excel-Arbeitsblatt zugewiesen.

    Office.onReady(async () => {
    await Excel.run((context) => {
        const charts = context.workbook.worksheets
            .getActiveWorksheet()
            .charts;
        charts.onActivated.add(enableChartFormat);
        charts.onDeactivated.add(disableChartFormat);
        return context.sync();
    });
});

  3. Definieren Sie den enableChartFormat Handler. Nachfolgend sehen Sie ein einfaches Beispiel. Eine stabilere Möglichkeit zum Ändern der status eines Steuerelements finden Sie unter Bewährte Methode: Testen auf Fehler bei der Steuerung status.

    function enableChartFormat() {
    const button =
        {
            id: "ChartFormatButton",
            enabled: true
        };
    const parentGroup =
        {
            id: "MyGroup",
            controls: [button]
        };
    const parentTab =
        {
            id: "CustomChartTab",
            groups: [parentGroup]
        };
    const ribbonUpdater = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);
}

  4. Definieren Sie den disableChartFormat Handler. Sie ist identisch mit dem enableChartFormat Handler, mit der Ausnahme, dass die enabled-Eigenschaft des Schaltflächenobjekts auf falsefestgelegt ist.

Bewährte Methode: Testen auf Steuerelement-Statusfehler

In einigen Fällen wird das Menüband oder Kontextmenü nach requestUpdate dem Aufruf nicht neu gezeichnet, sodass sich die klickbare status des Steuerelements nicht ändert. Aus diesem Grund ist es eine bewährte Methode für das Add-In, die status seiner Steuerelemente nachzuverfolgen. Das Add-In sollte den folgenden Regeln entsprechen.

  • Wann immer requestUpdate aufgerufen wird, sollte der Code den beabsichtigten Status der benutzerdefinierten Schaltflächen und Menüelemente aufzeichnen.
  • Wenn ein benutzerdefiniertes Steuerelement ausgewählt wird, sollte der erste Code im Handler überprüfen, ob die Schaltfläche verfügbar sein sollte. Wenn es nicht verfügbar sein sollte, sollte der Code einen Fehler melden oder protokollieren und erneut versuchen, die Schaltflächen auf den beabsichtigten Zustand festzulegen.

Das folgende Beispiel zeigt eine Funktion, die eine Schaltfläche im Menüband deaktiviert und die status der Schaltfläche aufzeichnet. In diesem Beispiel ist eine globale boolesche Variable, chartFormatButtonEnabled die mit demselben Wert wie das Enabled-Element für die Schaltfläche im Manifest des Add-Ins initialisiert wird. Obwohl im Beispiel eine Menübandschaltfläche verwendet wird, kann eine ähnliche Implementierung auf benutzerdefinierte Elemente in einem Kontextmenü angewendet werden.

function disableChartFormat() {
    const button =
    {
        id: "ChartFormatButton",
        enabled: false
    };
    const parentGroup =
    {
        id: "MyGroup",
        controls: [button]
    };
    const parentTab =
    {
        id: "CustomChartTab",
        groups: [parentGroup]
    };
    const ribbonUpdater = { tabs: [parentTab] };
    Office.ribbon.requestUpdate(ribbonUpdater);

    chartFormatButtonEnabled = false;
}

Das folgende Beispiel zeigt, wie der Handler der Schaltfläche diese auf einen fehlerhaften Status überprüft. Beachten Sie, dass reportError eine Funktion ist, die einen Fehler anzeigt oder protokolliert.

function chartFormatButtonHandler() {
    if (chartFormatButtonEnabled) {

        // Do work here.

    } else {
        // Report the error and try to make the button unavailable again.
        reportError("That action is not possible at this time.");
        disableChartFormat();
    }
}

Fehlerbehandlung

In einigen Szenarien kann Office das Menüband oder Kontextmenü nicht aktualisieren und gibt einen Fehler zurück. Wenn das Add-In beispielsweise aktualisiert wird und das aktualisierte Add-In einen anderen Satz von benutzerdefinierten Add-In-Befehlen enthält, muss die Office-Anwendung geschlossen und erneut geöffnet werden. Bis dahin gibt die Methode requestUpdate den Fehler HostRestartNeeded zurück. Nachfolgend sehen Sie ein Beispiel dafür, wie dieser Fehler behoben wird. In diesem Fall zeigt die Methode reportError dem Benutzer den Fehler an. Obwohl im Beispiel eine Menübandschaltfläche verwendet wird, kann eine ähnliche Implementierung auf benutzerdefinierte Elemente in einem Kontextmenü angewendet werden.

function disableChartFormat() {
    try {
        const button =
        {
            id: "ChartFormatButton",
            enabled: false
        };
        const parentGroup =
        {
            id: "MyGroup",
            controls: [button]
        };
        const parentTab =
        {
            id: "CustomChartTab",
            groups: [parentGroup]
        };
        const ribbonUpdater = { tabs: [parentTab] };
        Office.ribbon.requestUpdate(ribbonUpdater);

        chartFormatButtonEnabled = false;
    }
    catch(error) {
        if (error.code == "HostRestartNeeded"){
            reportError("Contoso Awesome Add-in has been upgraded. Please save your work, close the Office application, and restart it.");
        }
    }
}

Siehe auch