Add-In-Befehle

Add-In-Befehle sind Elemente der Benutzeroberfläche, die die Office-Benutzeroberfläche erweitern und Aktionen in Ihrem Add-In starten. Sie können Add-In-Befehle verwenden, um eine Schaltfläche zum Menüband oder ein Element zu einem Kontextmenü hinzuzufügen. Wenn Benutzer einen Add-In-Befehl auswählen, werden Aktionen, wie das Ausführen von JavaScript-Code oder das Anzeigen einer Add-In-Seite in einem Aufgabenbereich initiiert. Add-In-Befehle helfen Benutzer dabei, Ihr Add-In zu finden und zu verwenden; dies kann die Annahme und Wiederverwendung Ihres Add-Ins verbessern und die Kundenbindung stärken.

Hinweis

• SharePoint-Kataloge unterstützen keine Add-In-Befehle. Sie können Add-In-Befehle über das integrierte Apps-Portal oder Microsoft Marketplace bereitstellen oder das Querladen verwenden, um Ihren Add-In-Befehl zu Testzwecken bereitzustellen.
• Add-In-Befehle werden von Inhalts-Add-Ins derzeit nicht unterstützt.

Typen von Add-In-Befehlen

Es gibt zwei Arten von Add-In-Befehlen, je nach der Art der Aktion, die der Befehl auslöst.

• Aufgabenbereichbefehle: Die Schaltfläche oder das Menüelement öffnet den Aufgabenbereich des Add-Ins. Sie fügen diese Art von Add-In-Befehl mit Markup im Manifest hinzu. Der "CodeBehind" des Befehls wird von Office bereitgestellt.

• Funktionsbefehle: Die Schaltfläche oder der Menüpunkt führt ein beliebiges JavaScript aus. Der Code ruft fast immer APIs in der Office JavaScript Library auf, aber das muss nicht sein. Diese Art von Add-Ins zeigt in der Regel nur die Schaltfläche oder das Menüelement selbst an. Beachten Sie die folgenden Hinweise zu Funktionsbefehlen:

  • Die Runtime, in der der Funktionsbefehl ausgeführt wird, ist eine vollständige browserbasierte Laufzeit. Es kann HTML darstellen und das Internet aufrufen, um Daten zu senden oder abzurufen.

  • Die Laufzeit wird geschlossen, wenn entweder die Funktion abgeschlossen ist oder fünf Minuten vergangen sind, je nachdem, was früher ist.

  • Die ausgelöste Funktion kann die displayDialogAsync-Methode aufrufen, um einen Dialog anzuzeigen. Dies ist eine gute Möglichkeit, einen Fehler anzuzeigen, den Fortschritt anzuzeigen oder den Benutzer zur Eingabe aufzufordern.

    Hinweis

    Aufgrund des 5-Minuten-Timeouts sollte der Dialog so entworfen werden, dass Benutzer ihre Interaktion abschließen und innerhalb von 5 Minuten schließen können. Ihr Add-In sollte einen Aufgabenbereich für längere Interaktionen verwenden.

  • Wenn das Add-In für die Verwendung einer freigegebenen Runtime konfiguriert ist, kann die Funktion auch die showAsTaskpane-Methode aufrufen.

  Tipp

  Funktionsbefehle sind nicht die einzige Möglichkeit, beliebiges JavaScript in einem Add-In auszuführen. Ein Add-In kann auch Folgendes enthalten:

  • Benutzerdefinierte Handler für bestimmte Ereignisse, z. B. ein Benutzer, der einen neuen Nachrichtenbereich in Outlook öffnet.
  • Benutzerdefinierte Copilot-Agents , die Aktionen als Reaktion auf Anforderungen der Benutzer des Add-Ins in natürlicher Sprache ausführen.

Speicherort der Add-In-Befehle

Wenn ein Benutzer ein Add-In installiert, befinden sich die Befehle des Add-Ins im Menüband, in einer integrierten Office-Registerkarte oder auf einer benutzerdefinierten Registerkarte, die im Manifest angegeben ist. (Sie können auch Add-In-Befehle auf einer benutzerdefinierten kontextbezogenen Registerkarte platzieren, die ihr Add-In-Code zur Laufzeit definiert.) Sie werden auf der Benutzeroberfläche als Schaltfläche oder als Element in einem Dropdownmenü angezeigt.

Wenn das Menüband oder die Aktionsleiste immer überfüllter wird, werden Add-In-Befehle im Überlaufmenü angezeigt. Befehle für dasselbe Add-In werden in der Regel gruppiert.

Wenn Sie Office im Web das einzeilige oder vereinfachte Menübandlayout verwenden, wird der Add-In-Name nicht im Menüband angezeigt. Es wird nur das Befehlssymbol des Add-Ins angezeigt.

Excel, PowerPoint und Word

Im Folgenden sehen Sie ein Beispiel für Add-In-Befehle in einer benutzerdefinierten Gruppe auf der Registerkarte Daten des Excel-Menübands.

Outlook

Wenn Sie für Outlook einen Add-In-Befehl auf einer integrierten Menübandregisterkarte erstellen möchten, wird der Befehl auf der Standardregisterkarte basierend auf der Plattform und dem aktuellen Outlook-Modus angezeigt. Eine Anleitung finden Sie unter Verwenden von Add-Ins in Outlook.

Dropdownmenü

Ein Dropdownmenü-Add-In-Befehl definiert eine statische Liste von Elementen. Das Menü kann eine beliebige Mischung aus Elementen sein, die eine Funktion ausführen oder einen Aufgabenbereich öffnen. Untermenüs werden nicht unterstützt.

Gruppierte Add-In-Befehle im Menüband

Mehrere Add-In-Befehle können im Menüband gruppiert werden. Eine Gruppe muss mindestens einen Add-In-Befehl in Form einer Schaltfläche oder eines Dropdownmenüs enthalten. In Office unter Windows und auf Mac werden die Bezeichnung und das Symbol einer Schaltfläche oder eines Dropdownmenüs in der Regel für Add-In-Befehle in einer Gruppe angezeigt. Die Symbolgröße und die Sichtbarkeit der Bezeichnungen können jedoch aufgrund der folgenden Faktoren variieren, die den Platz einschränken.

• Die Anzahl der Add-In-Befehle in der Gruppe.
• Die Größe des Office-Clientfensters.

Wenn das Clientfenster maximiert ist und mehr als drei Steuerelemente in einer Gruppe vorhanden sind, wird die Bezeichnung jedes Steuerelements angezeigt, aber die Größe des Symbols kann variieren (einige werden als 16 x 16 Pixel angezeigt, während andere als 32 x 32 Pixel angezeigt werden).

Wenn zwei oder mehr Add-In-Befehle in einer Gruppe vorhanden sind und der Speicherplatz begrenzt wird, werden die folgenden Anpassungen an der Anzeige der Add-In-Befehle vorgenommen. Diese Änderungen werden in der folgenden Sequenz von rechts nach links auf die Gruppen von Add-In-Befehlen im Menüband angewendet.

1. Für jeden Add-In-Befehl in einer Gruppe werden kleine Symbole (16 x 16 Pixel) und Bezeichnungen angezeigt.
2. Es werden nur kleine Symbole angezeigt.
3. Die Gruppe wird als Dropdownmenü angezeigt, anstatt einzelne Add-In-Befehle im Menüband anzuzeigen. Ein Bildlaufschiebereglersymbol wird auch auf dem Menüband angezeigt, sodass Sie durch das Menüband scrollen können.

In Office im Web ändern sich die Symbolgröße und die Sichtbarkeit der Bezeichnung von Steuerelementen in Gruppen nicht, wenn die Größe des Browserfensters geändert wird. Das Bildlaufschiebereglersymbol wird einfach im Menüband angezeigt.

Befehlsfunktionen

Die folgenden Befehlsfunktionen werden derzeit unterstützt.

Erweiterungspunkte

• Menübandregisterkarten: Erweitern Sie integrierte Registerkarten, oder erstellen Sie eine neue benutzerdefinierte Kernregisterkarte. Ein Add-In kann nur über eine benutzerdefinierte Kernregisterkarte verfügen. (Sie können Add-In-Befehle auch auf einer benutzerdefinierten Kontextregisterkarte platzieren.)

  Hinweis

  Für Outlook werden benutzerdefinierte Registerkarten nur im klassischen Outlook unter Windows unterstützt. In Outlook im Web, unter Mac und im neuen Outlook unter Windows können Sie stattdessen benutzerdefinierte Gruppen von Steuerelementen auf einer der integrierten Menübandregisterkarten platzieren.

• Kontextmenüs - Erweitern Sie ausgewählte Kontextmenüs.

Steuerelementtypen

• Einfache Schaltflächen - Auslösen von bestimmten Aktionen.
• Menüs - Einfaches Dropdownmenü mit Schaltflächen, die Aktionen auslösen.

Standardverfügbarkeitsstatus

Sie können angeben, ob der Befehl verfügbar ist, wenn das Add-In gestartet wird, und die Einstellung programmgesteuert ändern.

Hinweis

Dieses Feature wird nicht in allen Office-Anwendungen oder -Szenarien unterstützt. Weitere Informationen finden Sie unter Ändern der Verfügbarkeit von Add-In-Befehlen.

Position auf dem Menüband

Sie können angeben, wo eine benutzerdefinierte Registerkarte im Menüband der Office-Anwendung angezeigt wird, z. B. "rechts neben der Start-Registerkarte".

Hinweis

Dieses Feature wird nicht in allen Office-Anwendungen oder -Szenarien unterstützt. Weitere Informationen finden Sie unter Positionieren einer benutzerdefinierten Registerkarte im Menüband.

Integration von eingebauten Office-Buttons

Sie können die integrierten Office-Menübandschaltflächen in Ihre benutzerdefinierten Befehlsgruppen und Ihre benutzerdefinierte Menüband-Registerkarte einfügen.

Hinweis

Dieses Feature wird nicht in allen Office-Anwendungen oder -Szenarien unterstützt. Weitere Informationen finden Sie unter Einfügen integrierter Office-Schaltflächen in benutzerdefinierte Registerkarten.

Kontextbezogene Registerkarten

Sie können eine benutzerdefinierte kontextbezogene Registerkarte angeben. d. h. eine Registerkarte, die nur in bestimmten Kontexten auf dem Menüband sichtbar ist, z. B. wenn ein Diagramm in Excel ausgewählt ist.

Hinweis

Dieses Feature wird nicht in allen Office-Anwendungen oder -Szenarien unterstützt. Weitere Informationen finden Sie unter Erstellen von benutzerdefinierten kontextbezogenen Registerkarten in Office-Add-Ins.

Unterstützte Plattformen

Add-In-Befehle werden derzeit auf den folgenden Plattformen unterstützt (mit Ausnahme der in den Unterabschnitten von Befehlsfunktionen angegeben Einschränkungen).

• Office im Web
• Office unter Windows, das mit einem Microsoft 365-Abonnement verbunden ist
• Office auf Mac, verbunden mit einem Microsoft 365-Abonnement
• Unbefristete Office 2021 oder höher unter Windows oder Mac

Hinweis

Informationen zur Unterstützung in Outlook finden Sie unter Outlook-Supporthinweise.

Debuggen

Zum Debuggen eines Add-In-Befehls müssen Sie ihn in Office im Web ausführen. Weitere Informationen finden Sie unter Debuggen von Add-Ins in Office im Web.

Bewährte Methoden

Wenden Sie beim Entwickeln von Add-In-Befehlen die folgenden bewährten Methoden an.

• Verwenden Sie Befehle, die eine bestimmte Aktion mit einem klaren Ergebnis für den Benutzer darstellen. Kombinieren Sie nicht mehrere Aktionen in einer einzigen Schaltfläche.
• Stellen Sie präzise Aktionen bereit, mit denen allgemeine Aufgaben im Add-In effizienter durchzuführen sind. Minimieren Sie die Anzahl der Schritte, die notwendig sind, um eine Aktion auszuführen.
• Befolgen Sie für alle Symbole die Entwurfsrichtlinien für Symbole.
• Stellen Sie eine Version Ihres Add-Ins bereit, die auf Office-Anwendungen oder -Plattformen (z. B. iPad) funktioniert, die keine Befehle unterstützen. Für diese Versionen kann ein einzelnes Add-In-Manifest verwendet werden.

Bewährte Methoden für Add-In-Befehle im Menüband

In der folgenden Tabelle werden die empfohlenen Grenzwerte für Objekte in einem Office-App-Menüband beschrieben.

Objekt	Empfohlenes Limit	Begründung der Benutzerfreundlichkeit
Registerkarten	Sieben sichtbare Registerkarten gleichzeitig	Verhindert, dass Benutzer mit zu vielen Optionen überwältigt werden, und hilft ihnen, sich zu merken, wo sich Befehle befinden. Es wird empfohlen, kontextbezogene Registerkarten zu verwenden, um Unübersichtlichkeit zu reduzieren.
Gruppen pro Registerkarte	Sechs Gruppen	Hilft Benutzern, Befehle schnell zu überprüfen und zu finden.
Befehle pro Gruppe	Sieben Befehle	Verringert die Entscheidungsmüdigkeit bei zu vielen Optionen.
Gesamtbefehle im Menüband	70 sichtbare Befehle	Hilft Benutzern, Aktionen effizient zu finden. Wenn Ihr Add-In über mehr als 70 Befehle verfügt, empfiehlt es sich, Kataloge, Dropdownmenüs oder Dialoge für den Überlauf zu implementieren.

Beachten Sie beim Konfigurieren von Add-In-Befehlen im Menüband zusätzlich zu den empfohlenen Objektgrenzwerten Folgendes.

• Platzieren Sie Befehle auf einer vorhandenen Registerkarte, z. B. auf den Registerkarten Einfügen und Überprüfen, wenn die bereitgestellte Funktionalität dazu passt. Wenn ihr Add-In benutzern beispielsweise das Einfügen von Medien ermöglicht, fügen Sie der Registerkarte Einfügen eine Gruppe hinzu. Beachten Sie, dass nicht alle Registerkarten in allen Office-Versionen verfügbar sind. Weitere Informationen finden Sie unter Office-Add-Ins-Manifest.
• Platzieren Sie Befehle auf der Registerkarte Start, wenn die Funktionalität nicht auf eine andere Registerkarte passt und Sie über weniger als sechs Befehle der obersten Ebene verfügen. Sie können auch Befehle zur Registerkarte Start hinzufügen, wenn Ihr Add-In für office-Versionen (z. B. Office im Web oder Desktop) verwendet werden muss und eine Registerkarte nicht in allen Versionen verfügbar ist.
• Platzieren Sie die Befehle in einer benutzerdefinierten Registerkarte, wenn Sie mehr als sechs Befehle der obersten Ebene haben.
• Benennen Sie Ihre Gruppe so, dass sie dem Namen Ihres Add-Ins entspricht. Wenn Sie über mehrere Gruppen verfügen, benennen Sie jede Gruppe basierend auf der Funktion, die die Befehle in dieser Gruppe bieten.
• Stellen Sie sicher, dass Gruppen ordnungsgemäß reduziert werden, wenn sich die Größe des Office-App-Fensters ändert. Während das Menüband eine dynamische Größenänderung bietet (siehe Gruppierte Add-In-Befehle im Menüband), müssen Sie auch Gruppenkombinationen für Ihr Add-In definieren.
• Fügen Sie keine unnötigen Schaltflächen hinzu, um den Immobilienbestand Ihres Add-Ins zu erhöhen.
• Positionieren Sie eine benutzerdefinierte Registerkarte nicht links von der Registerkarte Start, oder legen Sie sie beim Öffnen des Dokuments standardmäßig im Fokus, es sei denn, Ihr Add-In ist die primäre Art und Weise, wie Benutzer mit dem Dokument interagieren. Wenn Sie Ihrem Add-In übermäßige Bedeutung geben, könnte dies Benutzer und Administratoren stören und verärgern.
• Wenn Ihr Add-In die primäre Art und Weise ist, wie Benutzer mit dem Dokument interagieren, und Sie über eine benutzerdefinierte Menüband-Registerkarte verfügen, sollten Sie in Erwägung ziehen, die Schaltflächen für die Office-Funktionen, die Benutzer häufig benötigen, in die Registerkarte zu integrieren.
• Wenn die mit einer benutzerdefinierten Registerkarte bereitgestellte Funktionalität nur in bestimmten Kontexten verfügbar sein soll, verwenden Sie benutzerdefinierte Kontextregisterkarten. Wenn Sie benutzerdefinierte kontextbezogene Registerkarten verwenden, stellen Sie sicher, dass Sie eine Fallbackumgebung für den Fall implementieren, dass Ihr Add-In auf Plattformen ausgeführt wird, die keine benutzerdefinierten kontextbezogenen Registerkarten unterstützen.
• Implementieren Sie ein Dialogfeld, um Benutzern erweiterte Optionen zur Verfügung zu stellen. Dadurch wird verhindert, dass Ihr Add-In das Menüband mit selten verwendeten Befehlen überlädt. Informationen zum Implementieren eines Dialogfelds finden Sie unter Verwenden der Office-Dialog-API in Office-Add-Ins.

Hinweis

Add-Ins, die zu viel Speicherplatz belegen, bestehen möglicherweise die Microsoft Marketplace-Überprüfung nicht.

Nächste Schritte

Die beste Möglichkeit für den Einstieg in die Verwendung von Add-In-Befehlen ist die Erkundung der Office-Add-In-Befehle auf GitHub.

Weitere Informationen zum Angeben von Add-In-Befehlen in einem reinen Add-In-Manifest finden Sie unter Erstellen von Add-In-Befehlen mit dem reinen Add-In-Manifest und dem VersionOverrides-Verweisinhalt .

Weitere Informationen zum Angeben von Add-In-Befehlen im einheitlichen Manifest für Microsoft 365 finden Sie unter Erstellen von Add-In-Befehlen mit dem einheitlichen Manifest für Microsoft 365.