迁移 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.onKeyEventFocusNode.attach的onKey参数 =>onKeyEvent参数FocusNode.onKey=>FocusNode.onKeyEventFocusOnKeyCallback=>FocusOnKeyEventCallbackFocusScope.onKey=>FocusScope.onKeyEventFocusScopeNode.onKey=>FocusScopeNode.onKeyEventRawKeyboard=>HardwareKeyboardRawKeyboardListener=>KeyboardListenerRawKeyDownEvent=>KeyDownEventRawKeyEvent=>KeyEventRawKeyUpEvent=>KeyUpEvent
已停用的 API
#一旦只有一个按键事件系统,或者其功能不再提供,这些 API 就不再需要了。
debugKeyEventSimulatorTransitModeOverrideGLFWKeyHelperGtkKeyHelperKeyboardSideKeyDataTransitModeKeyEventManagerKeyHelperKeyMessageKeyMessageHandlerKeySimulatorTransitModeVariantModifierKeyRawKeyEventDataRawKeyEventDataAndroidRawKeyEventDataFuchsiaRawKeyEventDataIosRawKeyEventDataLinuxRawKeyEventDataMacOsRawKeyEventDataWebRawKeyEventDataWindowsRawKeyEventHandlerServicesBinding.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.onKeyEventFocusNode.onKeyEventFocusOnKeyEventCallbackFocusScope.onKeyEventFocusScopeNode.onKeyEventHardwareKeyboardKeyboardListenerKeyDownEventKeyRepeatEventKeyEventKeyEventHandlerKeyUpEvent
相关问题
相关 PR