迁移 RawKeyEvent/RawKeyboard 系统到 KeyEvent/HardwareKeyboard 系统
概述
#一段时间以来(数年),Flutter 一直实现了两个按键事件系统。新系统已与旧的平台特定原始按键事件系统达到同等水平,而原始系统已被弃用。
背景
#在最初的按键事件子系统中,在框架和客户端应用程序中处理每个平台的细微差别导致代码过于复杂,而且旧系统未能正确反映系统上按键事件的真实状态。
旧版 API RawKeyboard
已弃用,未来将被移除。HardwareKeyboard
和 KeyEvent
API 取代了此旧版 API。此更改的一个示例是 FocusNode.onKeyEvent
取代了 FocusNode.onKey
。
RawKeyboard
的行为比 HardwareKeyboard
提供的事件模型更不统一,也不如其规则。请考虑以下示例:
- 按下事件并不总是与释放事件匹配,反之亦然(已按键集合被静默更新)。
- 按下事件的逻辑键可能与释放事件的逻辑键不同。
- 按下事件和重复事件不易区分(需要手动跟踪)。
- 锁定模式(如大写锁定)仅记录了其“启用”状态。无法获取其按下状态。
因此,新的基于 KeyEvent
/HardwareKeyboard
的系统应运而生,为了尽量减少破坏性更改,它与旧系统并行实现,并打算最终弃用旧系统。现在是时候了,应用程序开发人员应迁移其代码,以避免在弃用 API 被移除时发生的破坏性更改。
变更说明
#以下是已弃用的 API。
已弃用但有同等功能的 API
#Focus.onKey
=>Focus.onKeyEvent
FocusNode.attach
的onKey
参数 =>onKeyEvent
参数FocusNode.onKey
=>FocusNode.onKeyEvent
FocusOnKeyCallback
=>FocusOnKeyEventCallback
FocusScope.onKey
=>FocusScope.onKeyEvent
FocusScopeNode.onKey
=>FocusScopeNode.onKeyEvent
RawKeyboard
=>HardwareKeyboard
RawKeyboardListener
=>KeyboardListener
RawKeyDownEvent
=>KeyDownEvent
RawKeyEvent
=>KeyEvent
RawKeyUpEvent
=>KeyUpEvent
已停用的 API
#一旦只有一个按键事件系统,或者其功能不再提供,这些 API 就不再需要了。
debugKeyEventSimulatorTransitModeOverride
GLFWKeyHelper
GtkKeyHelper
KeyboardSide
KeyDataTransitMode
KeyEventManager
KeyHelper
KeyMessage
KeyMessageHandler
KeySimulatorTransitModeVariant
ModifierKey
RawKeyEventData
RawKeyEventDataAndroid
RawKeyEventDataFuchsia
RawKeyEventDataIos
RawKeyEventDataLinux
RawKeyEventDataMacOs
RawKeyEventDataWeb
RawKeyEventDataWindows
RawKeyEventHandler
ServicesBinding.keyEventManager
迁移指南
#Flutter 框架库已完成迁移。如果您的代码使用了上一节中列出的任何类或方法,请迁移到这些新 API。
迁移使用 RawKeyEvent
的代码
#对于大多数情况,所有 RawKeyEvent
API 都有相应的 KeyEvent
API 可用。
RawKeyEventData
对象或其子类中包含的与平台特定信息相关的某些 API 已被移除,不再受支持。一个例外是,RawKeyEventDataAndroid.eventSource
信息现在可以作为 KeyEvent.deviceType
以更独立于平台的形式访问。
迁移 isKeyPressed
和相关函数
#如果旧代码使用了 RawKeyEvent.isKeyPressed
、RawKeyEvent.isControlPressed
、RawKeyEvent.isShiftPressed
、RawKeyEvent.isAltPressed
或 RawKeyEvent.isMetaPressed
API,现在 HardwareKeyboard
单例实例上也有等效的函数,但 [KeyEvent] 上不可用。RawKeyEvent.isKeyPressed
可作为 HardwareKeyboard.isLogicalKeyPressed
使用。
之前
KeyEventResult _handleKeyEvent(RawKeyEvent keyEvent) {
if (keyEvent.isControlPressed ||
keyEvent.isShiftPressed ||
keyEvent.isAltPressed ||
keyEvent.isMetaPressed) {
print('Modifier pressed: $keyEvent');
}
if (keyEvent.isKeyPressed(LogicalKeyboardKey.keyA)) {
print('Key A pressed.');
}
return KeyEventResult.ignored;
}
之后
KeyEventResult _handleKeyEvent(KeyEvent _) {
if (HardwareKeyboard.instance.isControlPressed ||
HardwareKeyboard.instance.isShiftPressed ||
HardwareKeyboard.instance.isAltPressed ||
HardwareKeyboard.instance.isMetaPressed) {
print('Modifier pressed: $keyEvent');
}
if (HardwareKeyboard.instance.isLogicalKeyPressed(LogicalKeyboardKey.keyA)) {
print('Key A pressed.');
}
return KeyEventResult.ignored;
}
为焦点设置 onKey
#如果旧代码使用了 Focus.onKey
、FocusScope.onKey
、FocusNode.onKey
或 FocusScopeNode.onKey
参数,那么现在有等效的 Focus.onKeyEvent
、FocusScope.onKeyEvent
、FocusNode.onKeyEvent
或 FocusScopeNode.onKeyEvent
参数,它们提供 KeyEvent
而不是 RawKeyEvent
。
之前
Widget build(BuildContext context) {
return Focus(
onKey: (RawKeyEvent keyEvent) {
print('Key event: $keyEvent');
return KeyEventResult.ignored;
}
child: child,
);
}
之后
Widget build(BuildContext context) {
return Focus(
onKeyEvent: (KeyEvent keyEvent) {
print('Key event: $keyEvent');
return KeyEventResult.ignored;
}
child: child,
);
}
重复按键事件处理
#如果您之前依赖 RawKeyEvent.repeat
属性来确定一个按键是否为重复按键事件,现在这已被分离到一个单独的 KeyRepeatEvent
类型。
之前
KeyEventResult _handleKeyEvent(RawKeyEvent keyEvent) {
if (keyEvent is RawKeyDownEvent) {
print('Key down: ${keyEvent.data.logicalKey.keyLabel}(${keyEvent.repeat ? ' (repeated)' : ''})');
}
return KeyEventResult.ignored;
}
之后
KeyEventResult _handleKeyEvent(KeyEvent _) {
if (keyEvent is KeyDownEvent || keyEvent is KeyRepeatEvent) {
print('Key down: ${keyEvent.logicalKey.keyLabel}(${keyEvent is KeyRepeatEvent ? ' (repeated)' : ''})');
}
return KeyEventResult.ignored;
}
虽然 KeyRepeatEvent
不是 KeyDownEvent
的子类,但它也是一个按键按下事件。不要假定 keyEvent is! KeyDownEvent
只允许按键释放事件。同时检查 KeyDownEvent
和 KeyRepeatEvent
。
时间线
#已发布版本:3.18.0-7.0.pre
稳定版本:3.19.0
参考资料
#替换 API 文档
Focus.onKeyEvent
FocusNode.onKeyEvent
FocusOnKeyEventCallback
FocusScope.onKeyEvent
FocusScopeNode.onKeyEvent
HardwareKeyboard
KeyboardListener
KeyDownEvent
KeyRepeatEvent
KeyEvent
KeyEventHandler
KeyUpEvent
相关问题
相关 PR