Hinzufügen benutzerdefinierter Tastenkombinationen zu Ihren Office-Add-Ins

Tastenkombinationen, auch als Tastenkombinationen bezeichnet, ermöglichen es den Benutzern Ihres Add-Ins, effizienter zu arbeiten. Tastenkombinationen verbessern auch die Barrierefreiheit des Add-Ins für Benutzer mit Behinderungen, indem sie eine Alternative zur Maus bereitstellen.

Es gibt drei Schritte zum Hinzufügen von Tastenkombinationen zu einem Add-In.

1. Konfigurieren Sie das Manifest des Add-Ins.
2. Erstellen oder bearbeiten Sie die JSON-Verknüpfungsdatei , um Aktionen und deren Tastenkombinationen zu definieren.
3. Ordnen Sie ihren Funktionen mithilfe der Office.actions.associate-API benutzerdefinierte Aktionen zu.

Voraussetzungen

Tastenkombinationen werden derzeit nur auf den folgenden Plattformen und in excel- undWord unterstützt.

• Office im Web
• Office unter Windows
  • Excel: Version 2102 (Build 13801.20632) und höher
  • Word: Version 2408 (Build 17928.20114) und höher
• Office für Mac
  • Excel: Version 16.55 (21111400) und höher
  • Word: Version 16.88 (24081116) und höher

Darüber hinaus funktionieren Tastenkombinationen nur auf Plattformen, die die folgenden Anforderungssätze unterstützen. Informationen zu Anforderungssätzen und deren Verwendung finden Sie unter Angeben von Office-Anwendungen und API-Anforderungen.

• SharedRuntime 1.1
• KeyboardShortcuts 1.1 (erforderlich, wenn das Add-In benutzern die Option zum Anpassen von Tastenkombinationen bietet)

Konfigurieren des Manifests

Es müssen zwei kleine Änderungen am Manifest vorgenommen werden. Eine besteht darin, dem Add-In die Verwendung einer freigegebenen Runtime zu ermöglichen, und die andere besteht darin, auf eine Datei im JSON-Format zu verweisen, in der Sie die Tastenkombinationen definiert haben.

Konfigurieren des Add-Ins für die Verwendung einer freigegebenen Runtime

Das Hinzufügen benutzerdefinierter Tastenkombinationen erfordert, dass Ihr Add-In die freigegebene Runtime verwendet. Weitere Informationen finden Sie unter Konfigurieren eines Add-Ins für die Verwendung einer freigegebenen Runtime.

Verknüpfen der Zuordnungsdatei mit dem Manifest

Fügen Sie unmittelbar unterhalb (nicht innerhalb) des <VersionOverrides-Elements> im Manifest ein ExtendedOverrides-Element hinzu. Legen Sie das Url Attribut auf die vollständige URL einer JSON-Datei in Ihrem Projekt fest, die Sie in einem späteren Schritt erstellen werden.

    ...
    </VersionOverrides>  
    <ExtendedOverrides Url="https://contoso.com/addin/shortcuts.json"></ExtendedOverrides>
</OfficeApp>

Erstellen oder Bearbeiten der JSON-Verknüpfungsdatei

Benutzerdefinierte Tastenkombinationen werden in einer JSON-Datei definiert. Diese Datei beschreibt Ihre Tastenkombinationen und die Aktionen, die sie aufrufen. Das vollständige Schema für die JSON-Datei befindet sich extended-manifest.schema.json.

1. Erstellen Sie in Ihrem Add-In-Projekt eine JSON-Datei. Stellen Sie sicher, dass der Pfad der Datei mit dem Speicherort übereinstimmt, den Sie für das Url Attribut des ExtendedOverrides-Elements angegeben haben .

2. Fügen Sie der Datei das folgende Markup hinzu. Beachten Sie Folgendes zum Code.

   • Das Array "actions" enthält Objekte, die die aufzurufenden Aktionen definieren. Die Eigenschaften "actions.id" und "actions.name" sind erforderlich.
   • Die Eigenschaft "actions.id" identifiziert eindeutig die Aktion, die mithilfe einer Tastenkombination aufgerufen werden soll.
   • Die Eigenschaft "actions.name" muss die Aktion einer Tastenkombination beschreiben. Die von Ihnen bereitgestellte Beschreibung wird im Dialogfeld angezeigt, das einem Benutzer angezeigt wird, wenn es einen Verknüpfungskonflikt zwischen mehreren Add-Ins oder mit Microsoft 365 gibt. Office fügt den Namen des Add-Ins in Klammern am Ende der Beschreibung an. Weitere Informationen zum Umgang mit Konflikten mit Tastenkombinationen finden Sie unter Vermeiden von Tastenkombinationen, die von anderen Add-Ins verwendet werden.
   • Die Eigenschaft "type" ist optional. Derzeit wird nur der Typ "ExecuteFunction" unterstützt.
   • Die angegebenen Aktionen werden Funktionen zugeordnet, die Sie in einem späteren Schritt erstellen. Im Beispiel ordnen Sie "ShowTaskpane" später einer Funktion zu, die die Office.addin.showAsTaskpane -Methode aufruft, und "HideTaskpane" einer Funktion, die die Office.addin.hide -Methode aufruft.
   • Das Array "Shortcuts" enthält Objekte, die Tastenkombinationen Aktionen zuordnen. Die Eigenschaften "shortcuts.action", "shortcuts.key" und "shortcuts.key.default" sind erforderlich.
   • Der Wert der Eigenschaft "shortcuts.action" muss mit der Eigenschaft "actions.id" des entsprechenden Aktionsobjekts übereinstimmen.
   • Es ist möglich, Verknüpfungen so anzupassen, dass sie plattformspezifisch sind. Im Beispiel passt das Objekt "shortcuts" Verknüpfungen für jede der folgenden Plattformen an: "windows", "mac" und "web". Sie müssen für jede Verknüpfung eine Standardtaste definieren. Dies wird als Fallbackschlüssel verwendet, wenn keine Tastenkombination für eine bestimmte Plattform angegeben ist.

   Tipp

   Eine Anleitung zum Erstellen benutzerdefinierter Tastenkombinationen finden Sie unter Richtlinien für benutzerdefinierte Tastenkombinationen.

   {
       "actions": [
           {
               "id": "ShowTaskpane",
               "type": "ExecuteFunction",
               "name": "Show task pane"
           },
           {
               "id": "HideTaskpane",
               "type": "ExecuteFunction",
               "name": "Hide task pane"
           }
       ],
       "shortcuts": [
           {
               "action": "ShowTaskpane",
               "key": {
                   "default": "Ctrl+Alt+Up",
                   "mac": "Command+Shift+Up",
                   "web": "Ctrl+Alt+1",
                   "windows": "Ctrl+Alt+Up"
               }
           },
           {
               "action": "HideTaskpane",
               "key": {
                   "default": "Ctrl+Alt+Down",
                   "mac": "Command+Shift+Down",
                   "web": "Ctrl+Alt+2",
                   "windows": "Ctrl+Alt+Up"
               }
           }
       ]
   }
   

Zuordnen benutzerdefinierter Aktionen zu ihren Funktionen

1. Öffnen Sie in Ihrem Projekt die von Ihrer HTML-Seite geladene JavaScript-Datei im <FunctionFile-Element> .

2. Verwenden Sie in der JavaScript-Datei die Office.actions.associate-API , um jede Aktion, die Sie in der JSON-Datei angegeben haben, einer JavaScript-Funktion zuzuordnen. Fügen Sie der Datei den folgenden JavaScript-Code hinzu. Beachten Sie Folgendes zum Code.

   • Der erste Parameter ist eine der Aktionen aus der JSON-Datei.
   • Der zweite Parameter ist die Funktion, die ausgeführt wird, wenn ein Benutzer die Tastenkombination drückt, die der Aktion in der JSON-Datei zugeordnet ist.

   Office.actions.associate("ShowTaskpane", () => {
       return Office.addin.showAsTaskpane()
           .then(() => {
               return;
           })
           .catch((error) => {
               return error.code;
           });
   });
   

   Office.actions.associate("HideTaskpane", () => {
       return Office.addin.hide()
           .then(() => {
               return;
           })
           .catch((error) => {
               return error.code;
           });
   });
   

Richtlinien für benutzerdefinierte Tastenkombinationen

Verwenden Sie die folgenden Richtlinien, um benutzerdefinierte Tastenkombinationen für Ihre Add-Ins zu erstellen.

• Eine Tastenkombination muss mindestens eine Modifizierertaste (ALT/WAHL, STRG/BEFEHL, UMSCHALT) und nur eine weitere Taste enthalten. Diese Schlüssel müssen mit einem + Zeichen verknüpft werden.
• Die Befehlsmodifizierertaste wird auf der macOS-Plattform unterstützt.
• Unter macOS wird die ALT-TASTE der Wahltaste zugeordnet. Unter Windows wird die Befehlstaste der STRG-TASTE zugeordnet.
• Die UMSCHALTTASTE kann nicht als einzige Modifizierertaste verwendet werden. Sie muss entweder mit ALT/WAHL oder STRG/BEFEHL kombiniert werden.
• Tastenkombinationen können die Zeichen "A-Z", "a-z", "0-9" und die Satzzeichen "-", "_" und "+" enthalten. In Tastenkombinationen werden standardmäßig keine Kleinbuchstaben verwendet.
• Wenn zwei Zeichen mit derselben physischen Taste auf einer Standardtastatur verknüpft sind, handelt es sich um Synonyme in einer benutzerdefinierten Tastenkombination. Beispielsweise sind ALT+a und ALT+A die gleiche Tastenkombination sowie STRG+- und STRG+_ ("-" und "_" sind mit derselben physischen Taste verknüpft).

Browserverknüpfungen, die nicht überschrieben werden können

Wenn Sie benutzerdefinierte Tastenkombinationen im Web verwenden, können einige Tastenkombinationen, die vom Browser verwendet werden, nicht von Add-Ins überschrieben werden. Die folgende Liste enthält eine laufende Arbeit. Wenn Sie andere Kombinationen entdecken, die nicht überschrieben werden können, teilen Sie uns dies bitte mit, indem Sie das Feedbacktool unten auf dieser Seite verwenden.

• STRG+N
• STRG+UMSCHALT+N
• STRG+T
• STRG+UMSCHALT+T
• STRG+W
• STRG+PgUp/PgDn

Vermeiden von Tastenkombinationen, die von anderen Add-Ins verwendet werden

Es gibt viele Tastenkombinationen, die bereits von Microsoft 365 verwendet werden. Vermeiden Sie das Registrieren von Tastenkombinationen für Ihr Add-In, die bereits verwendet werden. Es kann jedoch einige Fälle geben, in denen es erforderlich ist, vorhandene Tastenkombinationen zu überschreiben oder Konflikte zwischen mehreren Add-Ins zu behandeln, die dieselbe Tastenkombination registriert haben.

Im Falle eines Konflikts wird dem Benutzer ein Dialogfeld angezeigt, wenn er zum ersten Mal versucht, eine in Konflikt stehende Tastenkombination zu verwenden. Beachten Sie, dass der Text für die Add-In-Option, der in diesem Dialogfeld angezeigt wird, aus der Eigenschaft "actions.name" in der JSON-Datei für Verknüpfungen stammt.

Der Benutzer kann auswählen, welche Aktion die Tastenkombination ausführen soll. Nachdem Sie die Auswahl getroffen haben, wird die Einstellung für zukünftige Verwendungen derselben Verknüpfung gespeichert. Die Tastenkombinationseinstellungen werden pro Benutzer und Plattform gespeichert. Wenn der Benutzer seine Einstellungen ändern möchte, kann er den Befehl Tastenkombinationen für Office-Add-Ins zurücksetzen über das Suchfeld "Bitte wissen" aufrufen. Durch das Aufrufen des Befehls werden alle Add-In-Tastenkombinationseinstellungen des Benutzers gelöscht, und der Benutzer wird erneut mit dem Konfliktdialogfeld aufgefordert, wenn er das nächste Mal versucht, eine in Konflikt stehende Verknüpfung zu verwenden.

Um eine optimale Benutzererfahrung zu erzielen, wird empfohlen, dass Sie Konflikte mit Tastenkombinationen mit diesen bewährten Methoden minimieren.

• Verwenden Sie nur Tastenkombinationen mit folgendem Muster: STRG+UMSCHALT+ALT+x, wobei x eine andere Taste ist.
• Vermeiden Sie die Verwendung etablierter Tastenkombinationen in Excel und Word. Eine Liste finden Sie in den folgenden Artikeln:
  • Tastenkombinationen in Excel
  • Tastenkombinationen in Word
• Wenn sich der Tastaturfokus auf der Add-In-Benutzeroberfläche befindet, funktionieren STRG+LEERTASTE und STRG+UMSCHALT+F10 nicht, da dies wichtige Tastenkombinationen für die Barrierefreiheit sind.
• Wenn auf einem Windows - oder Mac-Computer der Befehl Tastenkombinationseinstellungen für Office-Add-Ins zurücksetzen im Suchmenü nicht verfügbar ist, kann der Benutzer den Befehl manuell zum Menüband hinzufügen, indem er das Menüband über das Kontextmenü anpassen.

Lokalisieren der Beschreibung einer Tastenkombination

Möglicherweise müssen Sie Ihre benutzerdefinierten Tastenkombinationen in den folgenden Szenarien lokalisieren.

• Ihr Add-In unterstützt mehrere Gebietsschemas.
• Ihr Add-In unterstützt verschiedene Alphabete, Schreibsysteme oder Tastaturlayouts.

Informationen zum Lokalisieren der JSON-Tastenkombinationen finden Sie unter Lokalisieren erweiterter Außerkraftsetzungen.

Aktivieren der Verknüpfungsanpassung für bestimmte Benutzer

Benutzer Ihres Add-Ins können die Aktionen des Add-Ins alternativen Tastaturkombinationen neu zuweisen.

Verwenden Sie die Office.actions.replaceShortcuts-Methode , um den Add-Ins-Aktionen benutzerdefinierte Tastaturkombinationen eines Benutzers zuzuweisen. Die -Methode akzeptiert einen Parameter vom Typ {[actionId:string]: string|null}, wobei die actionIds eine Teilmenge der Aktions-IDs sind, die im JSON-Code des erweiterten Manifests des Add-Ins definiert werden müssen. Die Werte sind die bevorzugten Tastenkombinationen des Benutzers. Der Wert kann auch seinnull, wodurch jegliche Anpassungen für diese actionId und rückgängig machen an die angegebene Standardtastaturkombination entfernt werden.

Wenn der Benutzer bei Microsoft 365 angemeldet ist, werden die benutzerdefinierten Kombinationen in den Roamingeinstellungen des Benutzers pro Plattform gespeichert. Das Anpassen von Tastenkombinationen wird für anonyme Benutzer derzeit nicht unterstützt.

const userCustomShortcuts = {
    ShowTaskpane: "Ctrl+Shift+1",
    HideTaskpane: "Ctrl+Shift+2"
};

Office.actions.replaceShortcuts(userCustomShortcuts)
    .then(() => {
        console.log("Successfully registered shortcut.");
    })
    .catch((error) => {
        if (error.code == "InvalidOperation") {
            console.log("ActionId doesn't exist or shortcut combination is invalid.");
        }
    });

Um herauszufinden, welche Tastenkombinationen für den Benutzer bereits verwendet werden, rufen Sie die Office.actions.getShortcuts-Methode auf. Diese Methode gibt ein Objekt vom Typ [actionId:string]:string|null}zurück, wobei die Werte die aktuelle Tastaturkombination darstellen, die der Benutzer zum Aufrufen der angegebenen Aktion verwenden muss. Die Werte können aus drei verschiedenen Quellen stammen.

• Wenn ein Konflikt mit der Verknüpfung aufgetreten ist und der Benutzer eine andere Aktion (entweder nativ oder ein anderes Add-In) für diese Tastenkombination verwendet hat, wird null der zurückgegebene Wert zurückgegeben, da die Verknüpfung überschrieben wurde und es keine Tastaturkombination gibt, die der Benutzer derzeit verwenden kann, um diese Add-In-Aktion aufzurufen.
• Wenn die Verknüpfung mithilfe der Office.actions.replaceShortcuts-Methode angepasst wurde, wird als Wert die angepasste Tastaturkombination zurückgegeben.
• Wenn die Verknüpfung nicht überschrieben oder angepasst wurde, wird der Wert aus dem JSON-Code des erweiterten Manifests des Add-Ins zurückgegeben.

Es folgt ein Beispiel.

Office.actions.getShortcuts()
    .then(function (userShortcuts) {
       for (const action in userShortcuts) {
           let shortcut = userShortcuts[action];
           console.log(action + ": " + shortcut);
       }
    });

Wie unter Vermeiden von Tastenkombinationen in anderen Add-Ins beschrieben, empfiehlt es sich, Konflikte in Tastenkombinationen zu vermeiden. Um zu ermitteln, ob eine oder mehrere Tastenkombinationen bereits verwendet werden, übergeben Sie sie als Array von Zeichenfolgen an die Office.actions.areShortcutsInUse-Methode . Die -Methode gibt einen Bericht zurück, der Schlüsselkombinationen enthält, die bereits in Form eines Arrays von Objekten vom Typ {shortcut: string, inUse: boolean}verwendet werden. Die shortcut -Eigenschaft ist eine Tastenkombination, z. B. "STRG+UMSCHALT+1". Wenn die Kombination bereits bei einer anderen Aktion registriert ist, wird die inUse -Eigenschaft auf truefestgelegt. Beispiel: [{shortcut: "Ctrl+Shift+1", inUse: true}, {shortcut: "Ctrl+Shift+2", inUse: false}]. Der folgende Codeausschnitt ist ein Beispiel.

const shortcuts = ["Ctrl+Shift+1", "Ctrl+Shift+2"];
Office.actions.areShortcutsInUse(shortcuts)
    .then((inUseArray) => {
        const availableShortcuts = inUseArray.filter((shortcut) => {
            return !shortcut.inUse;
        });
        console.log(availableShortcuts);
        const usedShortcuts = inUseArray.filter((shortcut) => {
            return shortcut.inUse;
        });
        console.log(usedShortcuts);
    });

Implementieren von benutzerdefinierten Tastenkombinationen für unterstützte Microsoft 365-Apps

Sie können eine benutzerdefinierte Tastenkombination für unterstützte Microsoft 365-Apps wie Excel und Word implementieren. Wenn die Implementierung zum Ausführen derselben Aufgabe für jede App unterschiedlich ist, müssen Sie die Office.actions.associate -Methode verwenden, um eine andere Rückruffunktion für jede App aufzurufen. Hier ein Beispielcode:

const host = Office.context.host;
if (host === Office.HostType.Excel) {
    Office.actions.associate("ChangeFormat", changeFormatExcel);
} else if (host === Office.HostType.Word) {
    Office.actions.associate("ChangeFormat", changeFormatWord);
}
...

Siehe auch

• Office-Add-In-Beispiel: Verwenden von Tastenkombinationen für Office-Add-In-Aktionen
• Freigegebene Laufzeitanforderungssätze
• Anforderungssätze für Tastenkombinationen