Горячие клавиши

Blockly ведет реестр сочетаний клавиш, которые сопоставляют клавиши (или комбинации клавиш, например, ctrl-C ) с действиями. Реестр предварительно заполнен рядом сочетаний клавиш, например, ctrl-C и meta-C для копирования. Вы можете добавлять и удалять сочетания клавиш из реестра.

Как работают сочетания клавиш

Реестр сочетаний клавиш содержит объекты, моделирующие сочетания клавиш. Когда пользователь нажимает клавишу (или комбинацию клавиш), Blockly:

  1. Проверяет реестр, чтобы узнать, есть ли какие-либо сочетания клавиш, применимые к данному ключу. Если ключ используется несколькими сочетаниями клавиш, они пробуются в обратном порядке регистрации. То есть, сначала пробуется наиболее недавно зарегистрированное сочетание клавиш.

  2. Вызывает функцию preconditionFn ярлыка, которая определяет, применим ли ярлык к текущей ситуации. Например, ярлык копирования применяется к блокам, но не к рабочей области. Если ярлык не применим, Blockly пытается использовать следующий ярлык в списке, если таковой имеется.

  3. Вызывает функцию callback клавиш, которая выполняет действие сочетания клавиш. Например, сочетание клавиш «Копировать» создает копию текущего сфокусированного объекта, такого как блок. Если эта функция возвращает true , обработка останавливается. Если она возвращает false , Blockly пытается использовать следующее сочетание клавиш в списке, если таковое имеется.

Объем

Объект Scope идентифицирует компонент Blockly, который в данный момент находится в фокусе. Объекты Scope передаются в функции preconditionFn и callback , которые используют их для определения того, применяется ли сочетание клавиш к конкретному компоненту и, если да, то как его применить.

Для использования объекта Scope воспользуйтесь его свойством focusedNode . Это объект, реализующий интерфейс IFocusableNode . Этот интерфейс реализован всеми компонентами Blockly, на которых пользователь может сосредоточиться, включая рабочие области, блоки, поля, комментарии и ваши собственные пользовательские компоненты; для получения дополнительной информации см. раздел «Система фокусировки» .

Например, preconditionFn может использовать focusedNode , чтобы гарантировать, что сочетание клавиш применяется только к блокам.

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

Интерфейс сочетаний клавиш

Объекты в реестре сочетаний клавиш реализуют интерфейс KeyboardShortcut . Он содержит следующие свойства.

имя (обязательно)

Уникальное имя для ярлыка. Оно не отображается пользователям и не обязательно должно быть удобочитаемым. Переводить его не следует.

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

preconditionFn (необязательно)

Blockly вызывает эту функцию, чтобы определить, применима ли данная комбинация клавиш к текущей ситуации. Если она возвращает true , Blockly вызывает функцию callback . Если она возвращает false , Blockly игнорирует эту комбинацию клавиш. Например:

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

В случае, если сочетание клавиш применяется всегда (что встречается редко), эта функция может быть опущена. Сочетания клавиш не должны опускать эту функцию, а затем выполнять действия условно в callback . Это предотвратит создание Blockly контекстных меню справки, отображающих применимые сочетания клавиш.

обратный вызов (необязательно)

Эта функция выполняет действие, связанное с ярлыком. Она вызывается только в том случае, если preconditionFn возвращает true или отсутствует. Её параметры:

  • workspace : текущий WorkspaceSvg .
  • e : Event , инициировавшее создание ярлыка.
  • shortcut : само KeyboardShortcut .
  • scope : Scope , к которой применяется данный ярлык.

Функция возвращает true в случае успеха и false в случае неудачи.

Например:

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;
  },
  // ...
};

Хотя callback является необязательной, как правило, нет причин её не реализовывать.

keyCodes (необязательно)

Массив клавиш (или комбинаций клавиш), активирующих это сочетание клавиш. Для идентификации клавиш используйте коды клавиш из Blockly.utils.KeyCodes . Например:

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

Если вы хотите назначить дополнительные клавиши существующему сочетанию клавиш — например, добавить клавиши к сочетанию клавиш по умолчанию — вы можете вызвать Blockly.ShortcutRegistry.registry.addKeyMapping . Это не распространенная практика.

Комбинации клавиш

Если ваша комбинация клавиш активируется сочетанием клавиш, например, одновременным удержанием Control и C , создайте сериализованный код клавиши, вызвав метод 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
  // ...
};

Контроль и Мета

В Windows многие сочетания клавиш активируются клавишей Control . На Mac эти сочетания клавиш используют клавишу Command , которая распознается как META -код. Для поддержки обеих операционных систем зарегистрируйте свои сочетания клавиш как с помощью CTRL -кода, так и с помощью 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],
  // ...
};

Примечание по реализации

Обработчики событий клавиатуры в Blockly используют свойство keycode объекта KeyboardEvent , несмотря на то, что оно устарело.

allowCollision (необязательно)

По умолчанию для данной клавиши или комбинации клавиш можно зарегистрировать только одно сочетание клавиш. Установка этого параметра в true позволяет зарегистрировать клавишу (или комбинацию клавиш), даже если сочетание клавиш с той же клавишей (или комбинацией клавиш) уже зарегистрировано.

Обратите внимание, что это свойство применяется только при попытке зарегистрировать данное сочетание клавиш. Оно не препятствует использованию той же клавиши (или комбинации клавиш) другими сочетаниями клавиш. Возможность их регистрации зависит от значения свойства allowCollision .

Независимо от того, сколько сочетаний клавиш зарегистрировано для данной клавиши или комбинации клавиш, будет успешно выполнено не более одного. Сочетания клавиш проверяются в обратном порядке регистрации (от последнего зарегистрированного к первому). После того, как одно из них вернет true из своей функции обратного вызова, другие сочетания клавиш не проверяются.

метаданные (необязательно)

Это произвольный объект, содержащий дополнительную информацию. Его можно callback через параметр- shortcut .

Добавление, удаление и изменение ярлыков.

Чтобы добавить новое сочетание клавиш, вызовите метод Blockly.ShortcutRegistry.registry.register :

Blockly.ShortcutRegistry.registry.register(logFieldsShortcut);

Эта функция имеет второй параметр ( allowOverrides ), который позволяет заменить существующую комбинацию клавиш на ту же, что и ваша. Обратите внимание, что это отличается от KeyboardShortcut.allowCollision , которая позволяет добавить комбинацию клавиш с другим именем, но использующую ту же клавишу или комбинацию клавиш, что и существующая комбинация.

Чтобы удалить сочетание клавиш, вызовите метод Blockly.ShortcutRegistry.registry.unregister и передайте имя сочетания клавиш:

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

Изменить сочетание клавиш на месте невозможно. Вместо этого необходимо удалить существующее сочетание клавиш и добавить новое. Например: 

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

Сочетания клавиш по умолчанию

Реестр ярлыков предварительно заполнен рядом ярлыков. Вы можете найти их в файле https://github.com/RaspberryPiFoundation/blockly/blob/main/core/shortcut_items.ts . Ярлыки определены в функциях registerXxxx .

Сочетания клавиш навигации

Плагин для навигации с помощью клавиатуры содержит сочетания клавиш, позволяющие пользователям перемещаться по Blockly с помощью клавиатуры, например, используя клавиши со стрелками. Навигация с помощью клавиатуры необходима пользователям, которые не могут использовать мышь, например, людям с нарушениями моторики или зрения. Она также полезна для опытных пользователей, которым может потребоваться использовать сочетания клавиш для повышения эффективности.