將 ShortcutActivator 和 ShortcutManager 遷移到 KeyEvent 系統

一段時間以來（多年），Flutter 已經實現了兩個關鍵事件系統。新系統已與舊的平臺特定原始按鍵事件系統達到同等水平，而舊的原始系統將被移除。為了做好準備，Flutter 中使用舊系統的 API 正在被修改，對於其中少數 API，我們已決定進行 API 的破壞性更改，以維護 API 的質量。

在原始按鍵事件子系統中，處理框架和客戶端應用程式中的每個平臺的怪癖導致程式碼過於複雜，而舊系統未能正確表示系統中按鍵事件的真實狀態。

因此，新的 KeyEvent 基於的系統應運而生，為了最大限度地減少破壞性更改，它與舊系統並行實現，目的是最終棄用原始系統。現在這一時刻即將來臨，為了做好準備，我們進行了一些必要的最小破壞性更改，以維護 API 的質量。

受影響的 API 摘要

• ShortcutActivator.accepts 現在接收 KeyEvent 和 HardwareKeyboard。
• ShortcutActivator.isActivatedBy 已被棄用。只需呼叫 accepts 即可。
• ShortcutActivator.triggers 現在是可選的，如果未實現則返回 null。
• ShortcutManager.handleKeypress 現在接收 KeyEvent。

此更改將 ShortcutActivator.accepts 方法修改為接收 KeyEvent 和 HardwareKeyboard，而不是之前的 RawKeyEvent 和 RawKeyboard。

ShortcutActivator.accepts 的含義已略有改變。在更改之前，假定 accepts 僅在 ShortcutActivator.triggers 返回 null 時呼叫，或者傳送到 accepts 的按鍵事件的邏輯鍵存在於 triggers 列表中時呼叫。現在它總是被呼叫，並且可能將 triggers 列表用作效能改進，但不是必需的。Flutter 子類，如 SingleActivator 和 CharacterActivator，已經這樣做了。

此更改還將 ShortcutManager.handleKeypress 方法修改為接收 KeyEvent 而不是 RawKeyEvent。

Flutter 框架提供的 API 已遷移。僅當您使用上一節中列出的任何方法時，才需要遷移。

將 KeyEvent 傳遞給 ShortcutActivator.accepts，而不是 RawKeyEvent。這可能意味著需要更改獲取按鍵事件的來源。根據您的獲取方式，這可能意味著切換到使用 Focus.onKeyEvent 而不是 Focus.onKey，或者如果您使用 FocusScope、FocusNode 或 FocusScopeNode，則進行類似的更改。

如果您正在使用 RawKeyboardListener，請切換到使用 KeyboardListener。如果您直接訪問 RawKeyboard，請使用 HardwareKeyboard。您會發現所有按鍵事件源都有非原始的等效項。

ShortcutActivator.accepts 方法已修改為接收 KeyEvent 和 HardwareKeyboard，而不是 RawKeyEvent 和 RawKeyboard。

之前

class MyActivator extends ShortcutActivator {
  @override
  bool accepts(RawKeyEvent event, RawKeyboard state) {
    // ... (your implementation here)
    returns false;
  }
  // ...
}

之後

class MyActivator extends ShortcutActivator {
  @override
  bool accepts(KeyEvent event, HardwareKeyboard state) {
    // ... (your implementation here)
    returns false;
  }
  // ...
}

ShortcutManager 類已修改為在 handleKeypress 中接收 KeyEvent 而不是 RawKeyEvent。這兩個 API 的一個區別是重複按鍵的確定方式不同。在 RawKeyEvent 的情況下，repeat 成員表示重複，但在 RawKeyEvent 程式碼中，該事件的型別不同（KeyRepeatEvent）。

之前

class _MyShortcutManager extends ShortcutManager {
  @override
  KeyEventResult handleKeypress(BuildContext context, RawKeyEvent event) {
    if (event is! RawKeyDownEvent) {
      return KeyEventResult.ignored;
    }
    if (event.repeat) {
      // (Do something with repeated keys.)
    }
    // ... (your implementation here)
    return KeyEventResult.handled;
  }
}

之後

class _MyShortcutManager extends ShortcutManager {
  @override
  KeyEventResult handleKeypress(BuildContext context, KeyEvent event) {
    if (event is! KeyDownEvent && event is! KeyRepeatEvent) {
      return KeyEventResult.ignored;
    }
    if (event is KeyRepeatEvent) {
      // (Do something with repeated keys.)
    }
    // ... (your implementation here)
    return KeyEventResult.handled;
  }
}

已釋出到版本：3.17.0-5.0.pre
穩定版本：3.19.0

API 文件

• KeyEvent
• HardwareKeyboard
• ShortcutActivator
• ShortcutManager

相關問題

• RawKeyEvent 和 RawKeyboard 等應被棄用並移除（Issue 136419）

相關 PR

• 為 ShortcutActivator 和 ShortcutManager 遷移到 KeyEvent 而非 RawKeyEvent 做準備