Skróty klawiszowe

Blockly prowadzi rejestr skrótów klawiszowych, które mapują klawisze (lub kombinacje klawiszy, np. ctrl-C) na działania. Rejestr jest wstępnie wypełniony wieloma skrótami, takimi jak ctrl-C i meta-C do kopiowania. Możesz dodawać skróty do rejestru i usuwać je z niego.

Jak działają skróty klawiszowe

Rejestr skrótów zawiera obiekty modelujące skróty klawiszowe. Gdy użytkownik naciśnie klawisz (lub kombinację klawiszy), Blockly:

  1. Sprawdza rejestr, aby zobaczyć, czy do klucza mają zastosowanie jakieś skróty. Jeśli klawisz jest używany w więcej niż jednym skrócie, skróty są wypróbowywane w odwrotnej kolejności rejestracji. Oznacza to, że najpierw wypróbowywany jest ostatnio zarejestrowany skrót.

  2. Wywołuje funkcję preconditionFn skrótu, która określa, czy skrót ma zastosowanie w bieżącej sytuacji. Na przykład skrót kopiowania dotyczy bloków, ale nie obszaru roboczego. Jeśli skrót nie ma zastosowania, Blockly próbuje użyć kolejnego skrótu na liście (jeśli taki istnieje).

  3. Wywołuje funkcję callback skrótu, która wykonuje działanie skrótu. Na przykład skrót kopiowania tworzy kopię aktualnie zaznaczonego obiektu, np. bloku. Jeśli ta funkcja zwróci wartość true, przetwarzanie zostanie zatrzymane. Jeśli zwróci wartość false, Blockly spróbuje użyć kolejnego skrótu z listy (jeśli taki istnieje).

Zakres

A Scope obiekt identyfikuje komponent Blockly, który jest obecnie zaznaczony. Obiekty zakresu są przekazywane do funkcji preconditionFn i callback, które używają ich do określania, czy skrót ma zastosowanie do danego komponentu, a jeśli tak, to w jaki sposób.

Aby użyć obiektu Scope, użyj jego właściwości focusedNode. Jest to obiekt, który implementuje interfejs IFocusableNode. Ten interfejs jest implementowany przez wszystkie komponenty Blockly, na których użytkownik może się skupić, w tym obszary robocze, bloki, pola, komentarze i własne komponenty niestandardowe. Więcej informacji znajdziesz w artykule System fokusowania.

Na przykład preconditionFn może używać focusedNode, aby mieć pewność, że skrót dotyczy tylko bloków.

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

Interfejs KeyboardShortcut

Obiekty w rejestrze skrótów implementują interfejs KeyboardShortcut. Zawiera te właściwości:

name (wymagane)

Unikalna nazwa skrótu. Nie jest ona widoczna dla użytkowników i nie musi być czytelna dla człowieka. Nie należy go tłumaczyć.

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

preconditionFn (opcjonalnie)

Blockly wywołuje tę funkcję, aby określić, czy skrót ma zastosowanie w bieżącej sytuacji. Jeśli zwróci wartość true, Blockly wywoła funkcję callback. Jeśli zwróci wartość false, Blockly zignoruje ten skrót. Na przykład:

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

Skrót może pominąć tę funkcję, jeśli zawsze ma zastosowanie (rzadko). Skróty nie powinny pomijać tej funkcji, a następnie podejmować działań warunkowo w callback. Zapobiega to wykonywaniu przez Blockly takich czynności jak tworzenie menu pomocy kontekstowej, które wyświetlają odpowiednie skróty.

callback (opcjonalnie)

Ta funkcja wykonuje działanie powiązane ze skrótem. Jest wywoływana tylko wtedy, gdy preconditionFn zwraca true lub nie istnieje. Jego parametry to:

  • workspace: bieżąca WorkspaceSvg.
  • e: Event, która zainicjowała skrót.
  • shortcut: KeyboardShortcut.
  • scope: Scope, do którego odnosi się skrót.

Zwraca true, jeśli operacja się uda, i false, jeśli się nie uda.

Na przykład:

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

Chociaż parametr callback jest opcjonalny, zwykle nie ma powodu, aby go nie wdrażać.

keyCodes (opcjonalnie)

Tablica klawiszy (lub kombinacji klawiszy), które aktywują ten skrót. Aby zidentyfikować klucze, użyj kodów klawiszy w Blockly.utils.KeyCodes. Na przykład:

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

Jeśli chcesz zmapować dodatkowe klawisze na istniejący skrót – na przykład chcesz dodać klawisze do domyślnego skrótu – możesz wywołać Blockly.ShortcutRegistry.registry.addKeyMapping. Nie jest to częste zjawisko.

Kombinacje klawiszy

Jeśli skrót klawiszowy jest aktywowany przez kombinację klawiszy, np. przez jednoczesne przytrzymanie klawiszy Control i C, utwórz serializowany kod klawisza, wywołując funkcję 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
  // ...
};

Control i Meta

W systemie Windows wiele skrótów jest aktywowanych za pomocą klawisza Control. Na komputerze Mac te skróty klawiszowe używają klawisza Command, który jest rozpoznawany jako kod klawisza META. Aby obsługiwać oba systemy operacyjne, zarejestruj skróty za pomocą CTRL i 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],
  // ...
};

Uwaga dotycząca implementacji

Moduły obsługi zdarzeń klawiatury w Blockly używają właściwości keycodeKeyboardEvent, mimo że jest ona wycofana.

allowCollision (opcjonalnie)

Domyślnie możesz zarejestrować tylko jeden skrót dla danego klawisza lub kombinacji klawiszy. Ustawienie tej właściwości na true umożliwia zarejestrowanie klucza (lub kombinacji kluczy) nawet wtedy, gdy skrót z tym samym kluczem (lub kombinacją kluczy) został już zarejestrowany.

Pamiętaj, że ta właściwość ma zastosowanie tylko podczas próby zarejestrowania tego skrótu. Nie uniemożliwia to używania tego samego klawisza (lub kombinacji klawiszy) przez inne skróty. To, czy można je zarejestrować, zależy od wartości właściwości allowCollision.

Niezależnie od liczby skrótów zarejestrowanych dla danego klawisza lub kombinacji klawiszy zostanie wykonany co najwyżej jeden z nich. Skróty są testowane w odwrotnej kolejności rejestracji (od ostatniego zarejestrowanego do pierwszego zarejestrowanego). Gdy jedna z nich zwróci wartość true z wywołania zwrotnego, nie są wypróbowywane żadne inne skróty.

metadane (opcjonalne);

Jest to dowolny obiekt zawierający dodatkowe informacje. Jest on dostępny dla callback za pomocą parametru shortcut.

Dodawanie, usuwanie i modyfikowanie skrótów

Aby dodać nowy skrót klawiszowy, wywołaj:Blockly.ShortcutRegistry.registry.register

Blockly.ShortcutRegistry.registry.register(logFieldsShortcut);

Ta funkcja ma drugi parametr (allowOverrides), który umożliwia zastąpienie istniejącego skrótu skrótem o tej samej nazwie. Pamiętaj, że różni się to od opcji KeyboardShortcut.allowCollision, która umożliwia dodanie skrótu o innej nazwie, ale z użyciem tego samego klawisza lub kombinacji klawiszy co istniejący skrót.

Aby usunąć skrót klawiszowy, wywołaj funkcję Blockly.ShortcutRegistry.registry.unregister i przekaż nazwę skrótu:

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

Nie możesz modyfikować skrótu klawiszowego w miejscu. Zamiast tego musisz usunąć istniejący skrót i dodać nowy. Na przykład:

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

Skróty domyślne

Rejestr skrótów jest wstępnie wypełniony wieloma skrótami. Znajdziesz je na stronie https://github.com/google/blockly/blob/master/core/shortcut_items.ts. Skróty są zdefiniowane w funkcjach registerXxxx.

Skróty nawigacji za pomocą klawiatury

Wtyczka do nawigacji za pomocą klawiatury zawiera skróty, które umożliwiają użytkownikom poruszanie się po Blockly za pomocą klawiatury, np. przy użyciu klawiszy strzałek. Nawigacja za pomocą klawiatury jest niezbędna dla użytkowników, którzy nie mogą korzystać z myszy, np. osób z upośledzeniem ruchowym lub wzrokowym. Jest to również przydatne dla zaawansowanych użytkowników, którzy mogą chcieć używać skrótów klawiszowych, aby zwiększyć wydajność.