Aktivieren und Deaktivieren von Add-In-Befehlen

  • Artikel

Wenn bestimmte Funktionen des Add-Ins nur in bestimmten Kontexten verfügbar sein sollen, können Sie die benutzerdefinierten Add-In-Befehle programmgesteuert aktivieren oder deaktivieren. Beispielsweise sollte eine Funktion, die die Kopfzeile einer Tabelle ändert, nur aktiviert sein, wenn sich der Cursor in einer Tabelle befindet.

Sie können auch angeben, ob der Befehl aktiviert oder deaktiviert ist, wenn die Office-Clientanwendung geöffnet wird.

Hinweis

Dieser Artikel geht von der Annahme aus, dass Sie der folgenden Dokumentation vertraut sind. Lesen Sie diese Dokumentation, wenn Sie in der letzten Zeit nicht mit Add-In-Befehlen (benutzerdefinierten Menüelementen und Schaltflächen des Menübands) gearbeitet haben.

Unterstützung für Office-Anwendungen und -Plattformen

Die in diesem Artikel beschriebenen APIs sind nur in Excel verfügbar. Vorschauunterstützung ist jedoch derzeit in PowerPoint und Word verfügbar. Vollständige Supportdetails finden Sie im RibbonApi 1.1-Anforderungssatz .

Prüfen der Plattformunterstützung mit Anforderungssätzen

Anforderungssätze sind benannte Gruppen von API-Mitgliedern. Office-Add-Ins verwenden im Manifest angegebene Anforderungssätze oder verwenden eine Laufzeitüberprüfung, um zu bestimmen, ob eine Kombination aus Office-Anwendung und Plattform APIs unterstützt, die ein Add-In benötigt. Weitere Informationen finden Sie unter Office-Versionen und Anforderungssätze.

Die ApIs zum Aktivieren/Deaktivieren gehören zum RibbonApi 1.1-Anforderungssatz .

Hinweis

Der RibbonApi 1.1-Anforderungssatz wird im Manifest noch nicht unterstützt, sodass Sie ihn nicht im Abschnitt Anforderungen> des Manifests< angeben können. Um die Unterstützung zu testen, sollte Ihr Code aufrufen Office.context.requirements.isSetSupported('RibbonApi', '1.1'). Wenn und nur wenn dieser Aufruf zurückgibt true, kann Ihr Code die APIs zum Aktivieren/Deaktivieren aufrufen. Wenn der Aufruf von isSetSupported zurückgibt false, sind alle benutzerdefinierten Add-In-Befehle die ganze Zeit aktiviert. Sie müssen Ihr Produktions-Add-In und alle In-App-Anweisungen entwerfen, um zu berücksichtigen, wie es funktioniert, wenn der RibbonApi 1.1-Anforderungssatz nicht unterstützt wird. Weitere Informationen und Beispiele für die Verwendung isSetSupportedvon finden Sie unter Angeben von Office-Anwendungen und API-Anforderungen, insbesondere Laufzeitüberprüfungen für Methoden- und Anforderungssatzunterstützung. (Der Abschnitt Angeben, welche Office-Versionen und Plattformen Ihr Add-In dieses Artikels hosten können , gilt nicht für Menüband 1.1.)

Freigegebene Laufzeit erforderlich

Die in diesem Artikel beschriebenen APIs und Manifestmarkup erfordern, dass das Manifest des Add-Ins angibt, dass eine freigegebene Runtime verwendet werden soll. Führen Sie dazu die folgenden Schritte aus.

  1. Fügen Sie im Element Runtimes des Manifests das folgende untergeordnete Element hinzu: <Runtime resid="Contoso.SharedRuntime.Url" lifetime="long" />. (Wenn noch kein <Runtimes-Element im Manifest vorhanden ist, erstellen Sie es als erstes untergeordnetes> Element unter dem <Host-Element> im <Abschnitt VersionOverrides> .)

  2. Fügen Sie im Abschnitt Resources.Urls des Manifests das folgende untergeordnete Element hinzu: <bt:Url id="Contoso.SharedRuntime.Url" DefaultValue="https://{MyDomain}/{path-to-start-page}" />, wobei {MyDomain} die Domäne des Add-Ins ist und {path-to-start-page} der Pfad für die Startseite des Add-Ins. Beispiel: <bt:Url id="Contoso.SharedRuntime.Url" DefaultValue="https://localhost:3000/index.html" />.

  3. Je nachdem, ob Das Add-In einen Aufgabenbereich, eine Funktionsdatei oder eine benutzerdefinierte Excel-Funktion enthält, müssen Sie einen oder mehrere der folgenden drei Schritte ausführen.

    • Wenn das Add-In einen Aufgabenbereich enthält, legen Sie das resid Attribut der Aktion fest.SourceLocation-Element für genau die gleiche Zeichenfolge, die Sie für das resid<Runtime-Element> in Schritt 1 verwendet haben, Contoso.SharedRuntime.Urlz. B. . Das Element sollte wie folgt aussehen: <SourceLocation resid="Contoso.SharedRuntime.Url"/>
    • Wenn das Add-In eine benutzerdefinierte Excel-Funktion enthält, legen Sie das resid -Attribut der Seite fest.SourceLocation-Element genau die gleiche Zeichenfolge, die Sie für das resid<Runtime-Element> in Schritt 1 verwendet haben, Contoso.SharedRuntime.Urlz. B. . Das Element sollte wie folgt aussehen: <SourceLocation resid="Contoso.SharedRuntime.Url"/>
    • Wenn das Add-In eine Funktionsdatei enthält, legen Sie das resid Attribut des FunctionFile-Elements auf genau die gleiche Zeichenfolge fest, die Sie für das resid<Runtime-Element> in Schritt 1 verwendet haben, Contoso.SharedRuntime.Urlz. B. . Das Element sollte wie folgt aussehen: <FunctionFile resid="Contoso.SharedRuntime.Url"/>

Festlegen des Standardwerts für den Status auf "Disabled" (Deaktiviert)

Standardmäßig ist jeder Add-In-Befehl beim Start der Office-Anwendung aktiviert. Wenn eine benutzerdefinierte Schaltfläche oder ein benutzerdefiniertes Menüelement beim Start der Office-Anwendung deaktiviert sein soll, geben Sie dies im Manifest an. Fügen Sie einfach ein Enabled-Element (mit dem Wert false) direkt unter (nicht in) dem Action-Element in der Deklaration des Steuerelements ein. Im Folgenden wird die grundlegende Struktur veranschaulicht.

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

Programmgesteuertes Ändern des Status

Die wesentlichen Schritte zum Ändern des Aktivierungsstatus eines Add-In-Befehls sind:

  1. Erstellen Sie ein RibbonUpdaterData-Objekt , das (1) den Befehl und seine übergeordnete Gruppe und Registerkarte durch ihre im Manifest deklarierten IDs angibt. und (2) gibt den aktivierten oder deaktivierten Status des Befehls an.
  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() {
    Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "OfficeAppTab1", 
                groups: [
                    {
                      id: "CustomGroup111",
                      controls: [
                        {
                            id: "MyButton", 
                            enabled: true
                        }
                      ]
                    }
                ]
            }
        ]
    });
}

Wir stellen auch mehrere Schnittstellen (Typen) zur Verfügung, um die Konstruktion des RibbonUpdateData-Objekts zu erleichtern. 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);
}

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.

Ändern des Status als Reaktion auf ein Ereignis

Ein häufiges Szenario, in dem sich der Menübandstatus ändern sollte, ist die Änderung des Add-In-Kontexts durch ein vom Benutzer initiiertes Ereignis.

Angenommen, in einem Szenario soll eine Schaltfläche nur dann aktiviert werden, wenn ein Diagramm aktiviert ist. Der erste Schritt besteht darin, das Enabled-Element für die Schaltfläche im Manifest auf false festzulegen. Ein Beispiel sehen Sie oben.

Zweitens, weisen Sie Handler zu. Dies erfolgt in der Regel in der Office.onReady-Funktion wie im folgenden Beispiel, die Handler (die in einem späteren Schritt erstellt wurden) den onActivated - und onDeactivated-Ereignissen aller Diagramme im Arbeitsblatt zuweist.

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();
    });
});

Drittens: Definieren Sie den enableChartFormat-Handler. Das folgende Beispiel ist recht einfach. Unter Bewährte Methoden: Testen auf Steuerelement-Statusfehler weiter unten finden Sie jedoch eine robustere Art und Weise, den Status eines Steuerelements zu ändern.

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);
}

Viertens: Definieren Sie den disableChartFormat-Handler. Dies entspricht der Vorgehensweise bei enableChartFormat, außer dass die Eigenschaft Enabled des Schaltflächenobjekts auf false gesetzt 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.

Bewährte Methode: Testen auf Steuerelement-Statusfehler

Unter bestimmten Umständen wird das Menüband nach dem Aufruf von requestUpdate nicht aktualisiert, sodass sich der Status des anklickbaren Steuerelements nicht ändert. Aus diesem Grund ist es eine bewährtes Methode, den Status der Steuerelemente des Add-Ins nachzuverfolgen. Das Add-In sollte den folgenden Regeln entsprechen.

  1. Wann immer requestUpdate aufgerufen wird, sollte der Code den beabsichtigten Status der benutzerdefinierten Schaltflächen und Menüelemente aufzeichnen.
  2. Wenn auf ein benutzerdefiniertes Steuerelement geklickt wird, sollte der erste Code im Handler prüfen, ob die Schaltfläche hätte anklickbar sein sollen. Ist dies nicht der Fall, sollte der Code einen Fehler melden oder protokollieren und erneut versuchen, die Schaltflächen in den beabsichtigten Zustand zu versetzen.

Das folgende Beispiel zeigt eine Funktion, die eine Schaltfläche deaktiviert und den Status der Schaltfläche aufzeichnet. Beachten Sie, dass chartFormatButtonEnabled eine globale boolesche Variable ist, die auf denselben Wert initialisiert wird wie das Enabled-Element für die Schaltfläche im Manifest.

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 again to disable.
        reportError("That action is not possible at this time.");
        disableChartFormat();
    }
}

Fehlerbehandlung

In einigen Szenarien ist Office nicht in der Lage, das Menüband zu 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.

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.");
        }
    }
}