Aktivieren und Deaktivieren von Add-In-Befehlen
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
In diesem Artikel wird davon ausgegangen, dass Sie mit den grundlegenden Konzepten für Add-In-Befehle 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 in Excel, PowerPoint und Word als Teil des RibbonApi 1.1-Anforderungssatzes verfügbar. Informationen zum Testen der Plattformunterstützung mit Anforderungssätzen finden Sie unter Office-Versionen und Anforderungssätze.
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.
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> .)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" />.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
residAttribut der Aktion fest.SourceLocation-Element für genau die gleiche Zeichenfolge, die Sie für dasresid<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 dasresid<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
residAttribut des FunctionFile-Elements auf genau die gleiche Zeichenfolge fest, die Sie für dasresid<Runtime-Element> in Schritt 1 verwendet haben,Contoso.SharedRuntime.Urlz. B. . Das Element sollte wie folgt aussehen:<FunctionFile resid="Contoso.SharedRuntime.Url"/>
- Wenn das Add-In einen Aufgabenbereich enthält, legen Sie das
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:
- 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.
- Ü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 des aktivierten 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.
- Wann immer
requestUpdateaufgerufen wird, sollte der Code den beabsichtigten Status der benutzerdefinierten Schaltflächen und Menüelemente aufzeichnen. - 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.");
}
}
}
Office Add-ins