鍵盤快速鍵

Blockly 會維護鍵盤快速鍵的登錄，將按鍵 (或按鍵組合，例如 ctrl-C) 對應至動作。登錄檔會預先填入許多快速鍵，例如 ctrl-C 和 meta-C (複製)。您可以在登錄檔中新增及刪除捷徑。

鍵盤快速鍵的運作方式

快速鍵登錄檔包含模擬鍵盤快速鍵的物件。使用者按下按鍵 (或按鍵組合) 時，Blockly 會執行下列動作：

  1. 檢查登錄檔，確認是否有任何快速鍵適用於該金鑰。如果多個快速鍵使用同一個按鍵，系統會依註冊順序反向嘗試使用快速鍵。也就是說，系統會先嘗試最近註冊的快速鍵。

  2. 呼叫快速指令的 preconditionFn 函式，判斷快速指令是否適用於目前情況。舉例來說，複製快速鍵適用於方塊，但不適用於工作區。如果捷徑不適用，Blockly 會嘗試清單中的下一個捷徑 (如有)。

  3. 呼叫捷徑的 callback 函式，執行捷徑的動作。舉例來說，複製快速鍵會複製目前聚焦的物件，例如區塊。如果這個函式傳回 true，處理作業就會停止。 如果傳回 false，Blockly 會嘗試清單中的下一個快速鍵 (如有)。

範圍

Scope 物件會識別目前為焦點的 Blockly 元件。範圍物件會傳遞至 preconditionFn 和 callback，這些物件會使用範圍物件判斷捷徑是否適用於特定元件，以及如何套用捷徑。

如要使用 Scope 物件，請使用其 focusedNode 屬性。這是實作 IFocusableNode 的物件。使用者可聚焦的所有 Blockly 元件都會實作這個介面，包括工作區、方塊、欄位、註解和自訂元件；詳情請參閱焦點系統。

舉例來說，preconditionFn 可能會使用 focusedNode，確保快速鍵只適用於區塊。

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

KeyboardShortcut 介面

捷徑登錄中的物件會實作 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
  // ...
};

Control 和 Meta

在 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/master/core/shortcut_items.ts 中找到這些項目。快速鍵是在 registerXxxx 函式中定義。

鍵盤瀏覽快速鍵

鍵盤瀏覽外掛程式包含快速鍵，可讓使用者透過鍵盤瀏覽 Blockly，例如使用方向鍵。對於無法使用滑鼠的使用者 (例如動作或視覺障礙者) 來說，鍵盤導覽功能至關重要。對於想使用鍵盤快速鍵提升效率的進階使用者來說，這項功能也相當實用。