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

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, на которых пользователь может сфокусироваться, включая рабочие области, блоки, поля, комментарии и ваши собственные компоненты; подробнее см. в разделе Система Focus .

Например, 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 необязателен, обычно нет причин не реализовывать его.

Коды клавиш (необязательно)

Массив клавиш (или их комбинаций), активирующих эту комбинацию. Для идентификации клавиш используйте коды клавиш из 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/google/blockly/blob/master/core/shortcut_items.ts . Ярлыки определяются в функциях registerXxxx .

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

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