Raccourcis clavier

Blockly tient à jour un registre de raccourcis clavier qui associent des touches (ou des combinaisons de touches comme ctrl-C) à des actions. Le registre est prérempli avec un certain nombre de raccourcis, tels que ctrl-C et meta-C pour copier. Vous pouvez ajouter et supprimer des raccourcis dans le registre.

Fonctionnement des raccourcis clavier

Le registre des raccourcis contient des objets qui modélisent les raccourcis clavier. Lorsque l'utilisateur appuie sur une touche (ou une combinaison de touches), Blockly :

  1. Vérifie le registre pour voir si des raccourcis s'appliquent à la clé. Si plusieurs raccourcis utilisent la même touche, ils sont essayés dans l'ordre inverse de leur enregistrement. Autrement dit, le raccourci enregistré le plus récemment est essayé en premier.

  2. Appelle la fonction preconditionFn du raccourci, qui détermine si le raccourci s'applique à la situation actuelle. Par exemple, le raccourci de copie s'applique aux blocs, mais pas à l'espace de travail. Si le raccourci ne s'applique pas, Blockly essaie le raccourci suivant de la liste, le cas échéant.

  3. Appelle la fonction callback du raccourci, qui exécute l'action du raccourci. Par exemple, le raccourci de copie crée une copie de l'objet actuellement sélectionné, tel qu'un bloc. Si cette fonction renvoie true, le traitement s'arrête. Si la méthode renvoie false, Blockly essaie le raccourci suivant de la liste, le cas échéant.

Champ d'application

Un objet Scope identifie le composant Blockly actuellement sélectionné. Les objets de portée sont transmis à preconditionFn et callback, qui les utilisent pour déterminer si un raccourci s'applique à un composant particulier et, le cas échéant, comment l'appliquer.

Pour utiliser un objet Scope, utilisez sa propriété focusedNode. Il s'agit d'un objet qui implémente IFocusableNode. Cette interface est implémentée par tous les composants Blockly sur lesquels l'utilisateur peut se concentrer, y compris les espaces de travail, les blocs, les champs, les commentaires et vos propres composants personnalisés. Pour en savoir plus, consultez Système de sélection.

Par exemple, un preconditionFn peut utiliser focusedNode pour s'assurer qu'un raccourci ne s'applique qu'aux blocs.

preconditionFn(workspace, scope) {
  return (scope.focusedNode instanceof Blockly.BlockSvg);
}

Interface KeyboardShortcut

Les objets du registre de raccourcis implémentent l'interface KeyboardShortcut. Il contient les propriétés suivantes.

Nom (obligatoire)

Nom unique du raccourci. Les utilisateurs ne le verront pas et il n'a pas besoin d'être lisible par un humain. Il ne doit pas être traduit.

const logFieldsShortcut = {
  name: 'logFields',
  // ...
};

preconditionFn (facultatif)

Blockly appelle cette fonction pour déterminer si un raccourci s'applique à la situation actuelle. S'il renvoie true, Blockly appelle callback. Si la méthode renvoie false, Blockly ignore ce raccourci. Exemple :

const logFieldsShortcut = {
  // ...
  preconditionFn(workspace, scope) {
    // This shortcut only applies to blocks.
    return (scope.focusedNode instanceof Blockly.BlockSvg);
  },
  // ...
};

Un raccourci peut omettre cette fonction s'il s'applique toujours (ce qui est rare). Les raccourcis ne doivent pas omettre cette fonction et effectuer ensuite une action conditionnelle dans callback. Cela empêche Blockly d'effectuer des actions telles que la création de menus d'aide contextuels affichant les raccourcis applicables.

callback (facultatif)

Cette fonction exécute l'action associée au raccourci. Elle n'est appelée que si preconditionFn renvoie true ou n'existe pas. Ses paramètres sont les suivants :

  • workspace : la valeur WorkspaceSvg actuelle.
  • e : Event qui a lancé le raccourci.
  • shortcut : le KeyboardShortcut lui-même.
  • scope : Scope auquel s'applique le raccourci.

Elle renvoie true en cas de réussite et false en cas d'échec.

Exemple :

const logFieldsShortcut = {
  // ...
  callback(workspace, event, shortcut, scope) {
    // preconditionFn required focusedNode to be a BlockSvg.
    for (input of scope.focusedNode.inputList) {
      // Log the values of all named fields. (Label fields usually don't have names.)
      for (field of input.fieldRow) {
        if (field.name) {
          console.log(field.name + ': ' + field.getText());
        }
      }
    }
    return true;
  },
  // ...
};

Bien que callback soit facultatif, il n'y a généralement aucune raison de ne pas l'implémenter.

keyCodes (facultatif)

Tableau de clés (ou de combinaisons de touches) qui activent ce raccourci. Pour identifier les touches, utilisez les codes de touches dans Blockly.utils.KeyCodes. Exemple :

const logFieldsShortcut = {
  // ...
  keyCodes: [Blockly.utils.KeyCodes.L],
  // ...
};

Si vous souhaitez mapper des touches supplémentaires à un raccourci existant (par exemple, si vous souhaitez ajouter des touches à un raccourci par défaut), vous pouvez appeler Blockly.ShortcutRegistry.registry.addKeyMapping. Ce n'est pas courant.

Combinaisons de touches

Si votre raccourci clavier est activé par une combinaison de touches, par exemple en appuyant simultanément sur Control et C, créez un code de touche sérialisé en appelant Blockly.ShortcutRegistry.registry.createSerializedKey :

const ctrlC = Blockly.ShortcutRegistry.registry.createSerializedKey(
  Blockly.utils.KeyCodes.C,       // Keycode of main key
  [Blockly.utils.KeyCodes.CTRL],  // Array of modifier keys
);

const copyShortcut = {
  // ...
  keyCodes: [ctrlC], // Use the serialized keycode
  // ...
};

Ctrl et Meta

Sous Windows, de nombreux raccourcis sont activés avec la touche Control. Sur Mac, ces raccourcis clavier utilisent plutôt la touche Command, qui est reconnue comme le code de touche META. Pour prendre en charge les deux systèmes d'exploitation, enregistrez vos raccourcis avec le code de touche CTRL et le code de touche META.

const ctrlC = Blockly.ShortcutRegistry.registry.createSerializedKey(
  Blockly.utils.KeyCodes.C,
  [Blockly.utils.KeyCodes.CTRL],
);
const metaC = Blockly.ShortcutRegistry.registry.createSerializedKey(
  Blockly.utils.KeyCodes.C,
  [Blockly.utils.KeyCodes.META],
);

const copyShortcut = {
  // ...
  keyCodes: [ctrlC, metaC],
  // ...
};

Remarque sur l'implémentation

Les gestionnaires d'événements clavier de Blockly utilisent la propriété keycode de KeyboardEvent, même si elle est obsolète.

allowCollision (facultatif)

Par défaut, vous ne pouvez enregistrer qu'un seul raccourci pour une touche ou une combinaison de touches donnée. Si vous définissez cette propriété sur true, vous pouvez enregistrer une touche (ou une combinaison de touches) même si un raccourci avec la même touche (ou combinaison de touches) a déjà été enregistré.

Notez que cette propriété ne s'applique que lorsque vous tentez d'enregistrer ce raccourci. Il n'empêche pas d'autres raccourcis d'utiliser la même touche (ou combinaison de touches). Leur enregistrement dépend de la valeur de leur propriété allowCollision.

Quel que soit le nombre de raccourcis enregistrés pour une touche ou une combinaison de touches donnée, un seul sera exécuté. Les raccourcis sont testés dans l'ordre inverse de leur enregistrement (du dernier enregistré au premier enregistré). Une fois que l'un d'eux renvoie true à partir de son rappel, aucun autre raccourci n'est essayé.

métadonnées (facultatif)

Il s'agit d'un objet arbitraire contenant des informations supplémentaires. Il est disponible pour callback via le paramètre shortcut.

Ajouter, supprimer et modifier des raccourcis

Pour ajouter un raccourci clavier, appelez Blockly.ShortcutRegistry.registry.register :

Blockly.ShortcutRegistry.registry.register(logFieldsShortcut);

Cette fonction comporte un deuxième paramètre (allowOverrides) qui vous permet de remplacer un raccourci existant portant le même nom que votre raccourci. Notez que cette option est différente de KeyboardShortcut.allowCollision, qui vous permet d'ajouter un raccourci avec un nom différent, mais qui utilise la même touche ou combinaison de touches qu'un raccourci existant.

Pour supprimer un raccourci clavier, appelez Blockly.ShortcutRegistry.registry.unregister et transmettez le nom du raccourci :

Blockly.ShortcutRegistry.registry.unregister('logFields');

Vous ne pouvez pas modifier un raccourci clavier sur place. Au lieu de cela, vous devez supprimer le raccourci existant et en ajouter un autre. Exemple :

// Get the existing shortcut. getRegistry returns an object keyed by shortcut name.
const allShortcuts = Blockly.ShortcutRegistry.registry.getRegistry();
const modLogFieldsShortcut = allShortcuts[logFieldsShortcut.name];
// Apply the shortcut only to math blocks,
modLogFieldsShortcut.preconditionFn = function (workspace, scope) {
  return (scope.focusedNode instanceof Blockly.BlockSvg &&
          scope.focusedNode.type.startsWith('math_'));
}
// Delete the existing shortcut and add the modified shortcut.
Blockly.ShortcutRegistry.registry.unregister(logFieldsShortcut.name);
Blockly.ShortcutRegistry.registry.register(modLogFieldsShortcut);

Raccourcis par défaut

Le registre des raccourcis est prérempli avec un certain nombre de raccourcis. Vous les trouverez sur la page https://github.com/google/blockly/blob/master/core/shortcut_items.ts. Les raccourcis sont définis dans les fonctions registerXxxx.

Raccourcis de navigation au clavier

Le plug-in de navigation au clavier contient des raccourcis qui permettent aux utilisateurs de naviguer dans Blockly à l'aide du clavier, par exemple en utilisant les touches fléchées. La navigation au clavier est essentielle pour les utilisateurs qui ne peuvent pas utiliser de souris, par exemple ceux qui souffrent d'un handicap moteur ou visuel. Il est également utile pour les utilisateurs expérimentés qui souhaitent utiliser des raccourcis clavier pour gagner en efficacité.