Ajouter des raccourcis clavier personnalisés à vos compléments Office

Article
09/27/2024

Les raccourcis clavier, également appelés combinaisons de touches, permettent aux utilisateurs de votre complément de travailler plus efficacement. Les raccourcis clavier améliorent également l’accessibilité du complément pour les utilisateurs handicapés en fournissant une alternative à la souris.

Il existe trois étapes pour ajouter des raccourcis clavier à un complément.

Configurez le manifeste du complément.
Créez ou modifiez le fichier JSON des raccourcis pour définir les actions et leurs raccourcis clavier.
Mapper des actions personnalisées à leurs fonctions à l’aide de l’API Office.actions.associate .

Configuration requise

Les raccourcis clavier ne sont actuellement pris en charge que dans les plateformes suivantes et la build d’Excel et Word.

Office sur le web
Office pour Windows
- Excel : version 2102 (build 13801.20632) et versions ultérieures
- Word : version 2408 (build 17928.20114) et versions ultérieures
Office sur Mac
- Excel : version 16.55 (21111400) et versions ultérieures
- Word : version 16.88 (24081116) et versions ultérieures

En outre, les raccourcis clavier fonctionnent uniquement sur les plateformes qui prennent en charge les ensembles de conditions requises suivants. Pour plus d’informations sur les ensembles de conditions requises et leur utilisation, consultez Spécifier les applications Office et les exigences d’API.

SharedRuntime 1.1
KeyboardShortcuts 1.1 (obligatoire si le complément offre à ses utilisateurs la possibilité de personnaliser les raccourcis clavier)

Conseil

Pour commencer avec une version opérationnelle d’un complément avec des raccourcis clavier déjà configurés, clonez et exécutez l’exemple Utiliser les raccourcis clavier pour les actions de complément Office . Lorsque vous êtes prêt à ajouter des raccourcis clavier à votre propre complément, poursuivez avec cet article.

Configurer le manifeste

Deux petites modifications doivent être apportées au manifeste. L’une consiste à permettre au complément d’utiliser un runtime partagé et l’autre à pointer vers un fichier au format JSON où vous avez défini les raccourcis clavier.

Configurer le complément pour utiliser un runtime partagé

L’ajout de raccourcis clavier personnalisés nécessite que votre complément utilise le runtime partagé. Pour plus d’informations, consultez Configurer un complément pour utiliser un runtime partagé.

Lier le fichier de mappage au manifeste

Juste en dessous (pas à l’intérieur) de l’élément <VersionOverrides> dans le manifeste, ajoutez un élément ExtendedOverrides . Définissez l’attribut Url sur l’URL complète d’un fichier JSON dans votre projet que vous allez créer dans une étape ultérieure.

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

Créer ou modifier le fichier JSON des raccourcis

Les raccourcis clavier personnalisés sont définis dans un fichier JSON. Ce fichier décrit vos raccourcis clavier et les actions qu’ils appelleront. Le schéma complet du fichier JSON est à extended-manifest.schema.json.

Dans votre projet de complément, créez un fichier JSON. Assurez-vous que le chemin du fichier correspond à l’emplacement que vous avez spécifié pour l’attribut Url de l’élément ExtendedOverrides .
Ajoutez le code suivant au fichier. Notez ce qui suit à propos du code.
- Le tableau « actions » contient des objets qui définissent les actions à appeler. Les propriétés « actions.id » et « actions.name » sont requises.
- La propriété « actions.id » identifie de façon unique l’action à appeler à l’aide d’un raccourci clavier.
- La propriété « actions.name » doit décrire l’action d’un raccourci clavier. La description que vous fournissez s’affiche dans la boîte de dialogue qui s’affiche à un utilisateur en cas de conflit de raccourci entre plusieurs compléments ou avec Microsoft 365. Office ajoute le nom du complément entre parenthèses à la fin de la description. Pour plus d’informations sur la façon dont les conflits avec les raccourcis clavier sont gérés, consultez Éviter les combinaisons de touches utilisées par d’autres compléments.
- La propriété « type » est facultative. Actuellement, seul le type « ExecuteFunction » est pris en charge.
- Les actions spécifiées seront mappées à des fonctions que vous créerez à une étape ultérieure. Dans l’exemple, vous mapperez ultérieurement « ShowTaskpane » à une fonction qui appelle la Office.addin.showAsTaskpane méthode et « HideTaskpane » à une fonction qui appelle la Office.addin.hide méthode.
- Le tableau « raccourcis » contient des objets qui mappent des combinaisons de touches à des actions. Les propriétés « shortcuts.action », « shortcuts.key » et « shortcuts.key.default » sont requises.
- La valeur de la propriété « shortcuts.action » doit correspondre à la propriété « actions.id » de l’objet action applicable.
- Il est possible de personnaliser les raccourcis pour qu’ils soient spécifiques à la plateforme. Dans l’exemple, l’objet « raccourcis » personnalise les raccourcis pour chacune des plateformes suivantes : « windows », « mac » et « web ». Vous devez définir une touche de raccourci par défaut pour chaque raccourci. Elle est utilisée comme clé de secours si aucune combinaison de touches n’est spécifiée pour une plateforme particulière.
Conseil

Pour obtenir des conseils sur la création de combinaisons de touches personnalisées, consultez Recommandations pour les combinaisons de touches personnalisées.
```
{
    "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"
            }
        }
    ]
}
```

Mapper des actions personnalisées à leurs fonctions

Dans votre projet, ouvrez le fichier JavaScript chargé par votre page HTML dans l’élément <FunctionFile> .
Dans le fichier JavaScript, utilisez l’API Office.actions.associate pour mapper chaque action que vous avez spécifiée dans le fichier JSON à une fonction JavaScript. Ajoutez le code JavaScript suivant au fichier. Notez ce qui suit à propos du code.
- Le premier paramètre est l’une des actions du fichier JSON.
- Le deuxième paramètre est la fonction qui s’exécute lorsqu’un utilisateur appuie sur la combinaison de touches mappée à l’action dans le fichier JSON.
```
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;
        });
});
```

Recommandations pour les combinaisons de touches personnalisées

Utilisez les instructions suivantes pour créer des combinaisons de touches personnalisées pour vos compléments.

Un raccourci clavier doit inclure au moins une touche de modification (Alt/Option, Ctrl/Commande, Maj) et une seule autre touche. Ces clés doivent être jointes par un + caractère.
La clé de modification de commande est prise en charge sur la plateforme macOS.
Sur macOS, la touche Alt est mappée à la touche Option. Sur Windows, la touche Commande est mappée à la touche Ctrl.
La touche Maj ne peut pas être utilisée comme seule touche de modification. Il doit être combiné avec Alt/Option ou Ctrl/Commande.
Les combinaisons de touches peuvent inclure les caractères « A-Z », « a-z », « 0-9 » et les signes de ponctuation « - », « _ » et « + ». Par convention, les lettres minuscules ne sont pas utilisées dans les raccourcis clavier.
Lorsque deux caractères sont liés à la même touche physique sur un clavier standard, il s’agit de synonymes dans un raccourci clavier personnalisé. Par exemple, Alt+a et Alt+A sont le même raccourci, de même que Ctrl+- et Ctrl+_ (« - » et « _ » sont liés à la même touche physique).

Remarque

Les raccourcis clavier personnalisés doivent être enfoncés simultanément. Les touches d’accès, également appelées raccourcis de touches séquentielles (par exemple, Alt+H, H), ne sont pas prises en charge dans les compléments Office.

Raccourcis du navigateur qui ne peuvent pas être remplacés

Lorsque vous utilisez des raccourcis clavier personnalisés sur le web, certains raccourcis clavier utilisés par le navigateur ne peuvent pas être remplacés par des compléments. La liste suivante est un travail en cours. Si vous découvrez d’autres combinaisons qui ne peuvent pas être remplacées, faites-le nous savoir à l’aide de l’outil de commentaires au bas de cette page.

Ctrl+N
Ctrl+Maj+N
Ctrl+T
Ctrl+Maj+T
Ctrl+W
Ctrl+PgUp/PgDn

Éviter les combinaisons de touches utilisées par d’autres compléments

De nombreux raccourcis clavier sont déjà utilisés par Microsoft 365. Évitez d’inscrire des raccourcis clavier pour votre complément qui sont déjà utilisés. Toutefois, dans certains cas, il peut être nécessaire de remplacer les raccourcis clavier existants ou de gérer les conflits entre plusieurs compléments qui ont inscrit le même raccourci clavier.

En cas de conflit, l’utilisateur voit une boîte de dialogue la première fois qu’il tente d’utiliser un raccourci clavier en conflit. Notez que le texte de l’option de complément qui s’affiche dans cette boîte de dialogue provient de la propriété « actions.name » dans le fichier JSON des raccourcis.

Modal de conflit avec deux actions différentes pour un seul raccourci.

L’utilisateur peut sélectionner l’action que le raccourci clavier effectuera. Après avoir effectué la sélection, la préférence est enregistrée pour les utilisations futures du même raccourci. Les préférences de raccourci sont enregistrées par utilisateur, par plateforme. Si l’utilisateur souhaite modifier ses préférences, il peut appeler la commande de raccourci Réinitialiser les préférences des compléments Office à partir de la zone de recherche Rechercher . L’appel de la commande efface toutes les préférences de raccourci de complément de l’utilisateur et l’utilisateur sera à nouveau invité avec la boîte de dialogue de conflit la prochaine fois qu’il tentera d’utiliser un raccourci en conflit.

Zone de recherche Dites-moi dans Excel montrant l’action réinitialiser les préférences de raccourci du complément Office.

Pour une expérience utilisateur optimale, nous vous recommandons de réduire les conflits de raccourci clavier avec ces bonnes pratiques.

Utilisez uniquement les raccourcis clavier avec le modèle suivant : Ctrl+Maj+Alt+x, où x est une autre touche.
Évitez d’utiliser des raccourcis clavier établis dans Excel et Word. Pour obtenir une liste, consultez les rubriques suivantes :
- Raccourcis clavier dans Excel
- Raccourcis clavier dans Word
Lorsque le focus clavier est à l’intérieur de l’interface utilisateur du complément, Ctrl+Barre d’espace et Ctrl+Maj+F10 ne fonctionnent pas, car il s’agit de raccourcis d’accessibilité essentiels.
Sur un ordinateur Windows ou Mac, si la commande Réinitialiser les préférences de raccourci des compléments Office n’est pas disponible dans le menu de recherche, l’utilisateur peut ajouter manuellement la commande au ruban en personnalisant le ruban via le menu contextuel.

Localiser la description d’un raccourci clavier

Vous devrez peut-être localiser vos raccourcis clavier personnalisés dans les scénarios suivants.

Votre complément prend en charge plusieurs paramètres régionaux.
Votre complément prend en charge différents alphabets, systèmes d’écriture ou dispositions de clavier.

Pour plus d’informations sur la façon de localiser les raccourcis clavier JSON, consultez Localiser les remplacements étendus.

Activer la personnalisation des raccourcis pour des utilisateurs spécifiques

Remarque

Les API décrites dans cette section nécessitent l’ensemble de conditions requises KeyboardShortcuts 1.1 .

Les utilisateurs de votre complément peuvent réaffecter les actions du complément à d’autres combinaisons de clavier.

Utilisez la méthode Office.actions.replaceShortcuts pour affecter les combinaisons de clavier personnalisées d’un utilisateur à vos actions de compléments. La méthode accepte un paramètre de type {[actionId:string]: string|null}, où les actionIdsont un sous-ensemble des ID d’action qui doivent être définis dans le fichier JSON du manifeste étendu du complément. Les valeurs sont les combinaisons de touches préférées de l’utilisateur. La valeur peut également être null, ce qui supprimera toute personnalisation pour cela actionId et rétablira la combinaison de clavier par défaut spécifiée.

Si l’utilisateur est connecté à Microsoft 365, les combinaisons personnalisées sont enregistrées dans les paramètres d’itinérance de l’utilisateur par plateforme. La personnalisation des raccourcis n’est actuellement pas prise en charge pour les utilisateurs anonymes.

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

Pour savoir quels raccourcis sont déjà utilisés pour l’utilisateur, appelez la méthode Office.actions.getShortcuts . Cette méthode retourne un objet de type [actionId:string]:string|null}, où les valeurs représentent la combinaison de clavier actuelle que l’utilisateur doit utiliser pour appeler l’action spécifiée. Les valeurs peuvent provenir de trois sources différentes.

S’il y a eu un conflit avec le raccourci et que l’utilisateur a choisi d’utiliser une autre action (native ou autre complément) pour cette combinaison de claviers, la valeur retournée est null étant que le raccourci a été remplacé et qu’il n’existe aucune combinaison de clavier que l’utilisateur peut actuellement utiliser pour appeler cette action de complément.
Si le raccourci a été personnalisé à l’aide de la méthode Office.actions.replaceShortcuts , la valeur retournée est la combinaison de clavier personnalisée.
Si le raccourci n’a pas été remplacé ou personnalisé, il retourne la valeur à partir du fichier JSON du manifeste étendu du complément.

Voici un exemple.

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

Comme décrit dans Éviter les combinaisons de touches utilisées par d’autres compléments, il est recommandé d’éviter les conflits dans les raccourcis. Pour savoir si une ou plusieurs combinaisons de touches sont déjà utilisées, transmettez-les sous forme de tableau de chaînes à la méthode Office.actions.areShortcutsInUse . La méthode retourne un rapport contenant des combinaisons de touches déjà utilisées sous la forme d’un tableau d’objets de type {shortcut: string, inUse: boolean}. La shortcut propriété est une combinaison de touches, telle que « Ctrl+Maj+1 ». Si la combinaison est déjà inscrite dans une autre action, la inUse propriété a la truevaleur . Par exemple : [{shortcut: "Ctrl+Shift+1", inUse: true}, {shortcut: "Ctrl+Shift+2", inUse: false}]. L’extrait de code suivant est un exemple.

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

Implémenter des raccourcis clavier personnalisés entre les applications Microsoft 365 prises en charge

Vous pouvez implémenter un raccourci clavier personnalisé à utiliser dans les applications Microsoft 365 prises en charge, telles qu’Excel et Word. Si l’implémentation permettant d’effectuer la même tâche est différente sur chaque application, vous devez utiliser la Office.actions.associate méthode pour appeler une fonction de rappel différente pour chaque application. Voici un exemple de code.

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

Partager via