跨平台前端移动开发OpenHarmony【免费下载链接】flutter_flutter本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。项目地址https://gitcode.com/CPF-Flutter/flutter_flutter点击查看免费下载本文围绕 Flutter 开源仓库中dev/tools/gen_keycodes工具目录完整讲解其如何从多平台数据源汇总键位信息、生成 Dart 框架代码与各平台引擎映射文件并深入剖析支撑这一切的 52 位 Key ID 平面plane编址方案。读完本文你将掌握该生成器的运行方式、数据流走向、各数据文件的职责以及新增平台含 OpenHarmony 自定义平台时的键码规范与扩展要点。一、工具定位为什么要“生成”而不是“手写”键盘键码在 Flutter 中键盘键位通过两个公开类对外暴露LogicalKeyboardKey表示“逻辑键”即结合修饰键、模式与键盘布局解释后的键。例如按键帽上印有“Q”的那个键在法语布局下位于 TAB 键旁边却印着“A”PhysicalKeyboardKey表示“物理键”即键盘上某个固定物理位置QWERTY 键盘上的相对位置与修饰键状态、输入模式、键盘布局无关。以典型场景为例实现“按 Q 退出”时应该监听逻辑键无论布局如何都匹配印有 Q 的键实现“CAPS LOCK 右侧按键左移角色”的游戏时应该监听物理键无论按键产生什么字符都锁定该键位。两类键的定义散落于 Dart 框架、各平台 embedder 与测试代码中条目数以千计若手工维护将极易出错且难以同步。因此 Flutter 维护了一个专门的代码生成器gen_keycodes。该工具位于dev/tools/gen_keycodes/以 Dart 编写职责是集中管理所有键盘键位信息并自动生成各目标文件而不是让开发者手写常量。二、整体架构一份数据多处输出生成器将多来源的键位信息汇聚成两份“主数据”文件再据此渲染各类模板输出横跨 Flutter 框架与 Flutter Engine 的多份代码文件。整体数据流为收集在线拉取 Chromium、Android、Windows、GTK、GLFW 等上游头文件结合仓库内的补充数据解析合并沉淀写入两份 JSON 主数据文件可入库、可离线复用生成基于主数据 模板渲染出框架与引擎各平台的目标文件。2.1 生成的两类框架文件对 Flutter 框架packages/flutter生成器输出两份文件keyboard_key.g.dart包含LogicalKeyboardKey与PhysicalKeyboardKey的全部静态常量定义、已知键的查找表_knownLogicalKeys、_knownPhysicalKeys、伪键同义词映射_synonyms/_reverseSynonyms、键标签映射_keyLabels以及各平面掩码常量keyboard_maps.g.dart包含各平台特有的不可变映射表如kAndroidToLogicalKey、kMacOsToPhysicalKey、kWebToLogicalKey、kWindowsNumPadMap等供RawKeyboardAPI 使用。两个生成文件头部都带有明确的“DO NOT EDIT”警告并指引编辑模板dev/tools/gen_keycodes/data/keyboard_key.tmpl与keyboard_maps.tmpl见 keyboard_key.tmpl 第 14-19 行。2.2 引擎侧与测试侧的输出除框架外生成器还输出 Engine 侧每平台一份键映射文件以及若干测试辅助文件完整调用清单见 gen_keycodes.dart 的main函数平台输出文件Engine 路径生成器实现Androidengine/src/flutter/shell/platform/android/io/flutter/embedding/android/KeyboardMap.javaandroid_code_gen.dartmacOSengine/src/flutter/shell/platform/darwin/macos/framework/Source/KeyCodeMap.g.mmmacos_code_gen.dartiOSengine/src/flutter/shell/platform/darwin/ios/framework/Source/KeyCodeMap.g.mmios_code_gen.dartWindowsengine/src/flutter/shell/platform/windows/flutter_key_map.g.ccwindows_code_gen.dartLinux (GTK)engine/src/flutter/shell/platform/linux/key_mapping.g.ccgtk_code_gen.dartWebengine/src/flutter/lib/web_ui/lib/src/engine/key_map.g.dartweb_code_gen.dartEngine 工具engine/src/flutter/shell/platform/embedder/test_utils/key_codes.g.h、engine/src/flutter/shell/platform/android/test/io/flutter/util/KeyCodes.javatesting_key_codes_cc_gen.dart、testing_key_codes_java_gen.dart各输出路径由每个生成器类中的outputPath(platform)方法定义如 android_code_gen.dart。2.3 模板渲染机制所有生成器共享基类 BaseCodeGenerator它读取模板文件查找形如TOKEN的占位符并通过子类实现的mappings()字典做字符串替换。例如keyboard_key.g.dart中的LOGICAL_KEY_DEFINITIONS、PHYSICAL_KEY_MAP、MASK_CONSTANTS等占位符分别由 keyboard_keys_code_gen.dart 中对应的_logicalDefinitions、_predefinedHidCodeMap、_maskConstantVariables填充。平台映射文件同理如keyboard_maps.tmpl中的ANDROID_KEY_CODE_MAP等见 keyboard_maps_code_gen.dart。生成的键常量命名还有一层保护若结果命中 Dart 保留字会自动追加Key后缀如newKey相关逻辑位于 utils.dart 的kDartReservedWords列表与 logical_key_data.dart 的computeName方法中。三、运行方式离线生成与在线重建3.1 基于已入库数据离线生成推荐日常使用生成器将解析后的数据沉淀为两份 JSON 主数据文件且已入库physical_key_data.g.jsonlogical_key_data.g.json只要这两份文件存在就无需联网。日常重建目标文件只需执行/PATH/TO/ROOT/bin/gen_keycodes其中/PATH/TO/ROOT指本仓库根目录。仓库内的启动脚本 bin/gen_keycodes 会自动解析出仓库根目录并以--enable-asserts启动 Dart 运行bin/gen_keycodes.dart该脚本严格要求在断言开启模式下运行详见 gen_keycodes.dart。3.2 在线重建数据--collect若上游键位数据有更新可在线重新收集全部数据源并刷新 JSON 主数据/PATH/TO/ROOT/bin/gen_keycodes --collect执行后--collect分支会依次拉取并解析以下上游数据见 gen_keycodes.dartChromiumdom_code_data.inc物理键 USB HID 码与dom_key_data.inc逻辑键列表Androidkeycodes.h键码与Generic.kl扫描码布局WindowsWinUser.h虚拟键码GTKgdkkeysyms.hkeyval 定义GLFWglfw3.hGLFW 键码。刷新后的physical_key_data.g.json与logical_key_data.g.json应当提交入库以便后续离线生成与审计。3.3 其他命令行选项--help可查看全部参数。除--collect外核心参数包括默认值见 gen_keycodes.dart参数默认值作用--physical-datadev/tools/gen_keycodes/data/physical_key_data.g.json收集时写入、生成时读取的物理键主数据路径--logical-datadev/tools/gen_keycodes/data/logical_key_data.g.json收集时写入、生成时读取的逻辑键主数据路径--codepackages/flutter/lib/src/services/keyboard_key.g.dartkeyboard_key.g.dart输出路径--mapspackages/flutter/lib/src/services/keyboard_maps.g.dartkeyboard_maps.g.dart输出路径四、Key ID 编址方案52 位整数与平面划分为了让每个键拥有全局唯一 IDFlutter 采用了一套“平面plane”编址方案避免自行铸造新编码。该方案同时适用于逻辑键与物理键。4.1 编码结构键码是一个52 位整数上限受 JavaScript 安全整数2^53-1限制。整个命名空间划分为多个 32 位宽度的平面高 20 位平面 IDplane ID低 32 位该平面内的值value。例如平面0x1对应范围0x1 0000 0000 - 0x1 FFFF FFFF。平面内部如何分配值由该平面自行决定。4.2 平面规划总表平面名称内容与取值规则0x00Unicode 平面逻辑键按下会生成 Unicode 字符的键含死键不含功能键、Shift 等修饰键取值为对应字符的 Unicode 码点尽量取小写、忽略修饰键如 Key A0x61、Digit 10x31、Colon0x3A、Key Ù0xD9。物理键USB HID usage 键0x01不可打印平面逻辑键Chromium key 列表中不生成 Unicode 字符的键取值为 Chromium 宏值如 CapsLock0x105、ArrowUp0x304、F10x801、Hiragata0x716、TVPower0xD4B。注意Chromium 中的修饰键如 Shift不在此平面见 Flutter 平面0x02Flutter 平面Flutter 自行定义的键。修饰键放于此因为 Flutter 区分左右侧修饰键ShiftLeft / ShiftRight而 Web 只有统一的 Shift其他如小键盘键、手柄键也在此0x03-0x0F保留未分配0x10-0x1F平台平面由 Flutter 管理的官方平台平面见下表0x20-0x2F自定义平台平面供自定义平台私用规则与 Flutter 平台平面类似4.3 官方平台平面编号CodePlatform0x11Android0x12Fuchsia0x13iOS0x14macOS0x15Gtk0x16Windows0x17Web0x18GLFW平台平面存放该平台 embedder 私有的键通常是 Flutter 尚未官方认可的键。平面内值的分配规则由平台自行决定典型做法是直接使用平台原生按键事件中的其他字段。4.4 掩码常量与运行时实现上述平面划分在生成文件中体现为一组掩码/平面常量。生成器的常量定义见 constants.dartkValueMask 0x00FFFFFFFF提取低 32 位值kPlaneMask 0xFF00000000提取平面前缀kUnicodePlane 0x0000000000、kUnprintablePlane 0x0100000000、kFlutterPlane 0x0200000000kStartOfPlatformPlanes 0x1100000000平台平面起始值kAndroidPlane 0x1100000000…kGlfwPlane 0x1800000000各平台平面。这些常量在生成后的 keyboard_key.g.dart 中同样可见如valueMask 0x000ffffffff、planeMask 0x0ff00000000、startOfPlatformPlanes 0x01100000000并被各平台raw_keyboard_*.dart用于运行时拼接 ID——例如raw_keyboard_android.dart中LogicalKeyboardKey.unicodePlane | (combinedCodePoint LogicalKeyboardKey.valueMask)的用法。生成后的实际常量示例见 keyboard_key.g.dart逻辑键digit1 LogicalKeyboardKey(0x00000000031)Unicode 平面f1 LogicalKeyboardKey(0x00100000801)不可打印平面shiftLeft LogicalKeyboardKey(0x00200000102)Flutter 平面左右修饰键区分numpad1 LogicalKeyboardKey(0x00200000231)Flutter 平面物理键常量则直接以 USB HID usage 编号如keyA。4.5 自动生成的键autogenerated运行时若遇到平台上报、但 Flutter 尚未识别的键码embedder 会将其放入对应平台平面得到“自动生成”的键 ID。判断依据是bool get isAutogenerated (keyId planeMask) startOfPlatformPlanes;自动生成的 ID 不应被持久化使用。需要注意的是能生成 Unicode 字符的未知键不会进入平台平面它们会被赋予基于 Unicode 的稳定 ID。一旦 Flutter 后续正式支持某个此前未知的键码该键 ID 会发生变化如0x1020000ffff变为0x0020000ffff但这属于有计划的一次性变更。4.6 面向移植者的使用建议键码对用户是不透明的不应被拆解来“读取含义”——编码方案随时可能改变从 API 获取含义更可靠、更正确。如果正在把 Flutter 移植到新平台请遵循以下建议Flutter 官方管理的平台当遇到未识别键时建议提交 issue 把该值加入keyboard_key.g.dart而不是使用平台平面值。因为一旦多个平台共用该键且被 Flutter 认领其值会被改到 Flutter 平面所有受管平台将开始发送新值——这是一次破坏性变更自定义平台由于平台作者对键映射拥有完全控制权此类变更不会造成破坏因此建议直接使用自定义平台平面0x20-0x2F的值避免向框架添加平台独占键值。五、数据文件全景主数据与各平台辅助数据data/README.md 对data目录下的每个文件作了清单式说明按用途可归纳如下。5.1 通用数据文件说明physical_key_data.g.json合并后的物理键主数据--collect时重新生成否则作为输入源logical_key_data.g.json合并后的逻辑键主数据--collect时重新生成否则作为输入源supplemental_hid_codes.inc在 Chromium HID 列表基础上补充的额外物理键某些条目可覆盖 Chromium 对应项supplemental_key_data.inc在 Chromium 键列表基础上补充的额外逻辑键chromium_modifiers.json将 Web 的key修饰键映射到左右变体的逻辑键名。Web 对左右修饰键使用同一key而 Flutter 逻辑键模型视为不同键因此需要独立取值printable.json将 Flutter 键名映射到其可打印字符用于生成键标签synonyms.json将代表其他键的伪键映射到其所代表的键集合例如Shift表示ShiftLeft或ShiftRight实际内容为 Shift / Meta / Alt / Control 四组左右配对layout_goals.json布局目标清单平台键盘管理器应为这些键找到映射。每个键名同时对应逻辑键与物理键布尔值表示是否强制mandatory。强制目标必须满足找不到映射时使用该文件中的默认值非强制目标仅作提示仅在映射信息异常如不含 ASCII 字符时使用以 synonyms.json 为例其完整内容为{ Shift: [ShiftLeft, ShiftRight], Meta: [MetaLeft, MetaRight], Alt: [AltLeft, AltRight], Control: [ControlLeft, ControlRight] }伪键机制在框架侧有两套配套 API由模板生成见 keyboard_key.tmplsynonyms从具体键取伪键如shiftLeft.synonyms返回{ shift }collapseSynonyms将一组键折叠为伪键集合回答“是否有任意 Ctrl 键按下”expandSynonyms将伪键展开为具体键集合control→controlLeftcontrolRight。5.2 各平台辅助数据平台文件说明Androidandroid_keyboard_map_java.tmplKeyboardMap.java的模板Androidandroid_key_name_to_name.json逻辑键名到对应 keycode 常量名的映射iOSios_logical_to_physical.json逻辑键名到对应物理键名的映射用于从keyCode推导无法或不应从characterIgnoringModifiers推导的逻辑键iOSios_key_code_map_mm.tmplKeyCodeMap.mm的模板Webweb_key_map_dart.tmplkey_map.dart的模板Webweb_logical_location_mapping.jsonWeb 的keylocation二元组到逻辑键名的映射用于区分相同key不同location的逻辑键Windowswindows_flutter_key_map_cc.tmplflutter_key_map.cc的模板Windowswindows_logical_to_window_vk.json逻辑键名到 Win32 虚拟键名的映射Windowswindows_scancode_logical_map.json物理键名到逻辑键名的映射用于 keycode 为 0 或一个 keycode 对应多个键、只能靠扫描码区分的情形GTKgtk_key_mapping_cc.tmplkey_mapping.cc的模板GTKgtk_lock_bit_mapping.jsonGTK 修饰位宏名到 Flutter 逻辑键名元素 #0与物理键名元素 #1的映射用于生成 GTK 需保持锁定状态同步的键GTKgtk_logical_name_mapping.json逻辑键名到对应keyval宏名的映射GTKgtk_modifier_bit_mapping.jsonGTK 修饰位宏名到 Flutter 物理键名元素 #0、逻辑键名元素 #1及配对键逻辑键名元素 #2的映射用于生成 GTK 需保持按下状态同步的键GTKgtk_numpad_shift.json小键盘键keyval宏名到 NumLock 开启时对应键的映射。GTK 对 NumLock 开/关使用不同keyval而 Flutter 逻辑键模型视为同一键GLFWglfw_key_name_to_name.json、glfw_keyboard_map_cc.tmpl逻辑键名到 GLFW 宏名的映射与keyboard_map.cc模板当前均标记为 Unused for nowmacOSmacos_key_code_map_cc.tmpl、macos_logical_to_physical.json模板与逻辑键到物理键的映射用于从keyCode推导逻辑键Fuchsiafuchsia_keyboard_map_cc.tmplkeyboard_map.cc的模板当前标记为 Unused for now5.3 各平台映射的生成要点不同平台映射的生成逻辑体现了各平台键事件模型的差异实现见 keyboard_maps_code_gen.dartAndroid同时生成 key code → 逻辑键、扫描码 → 物理键、以及小键盘专用映射kAndroidNumPadMap用于区分KEY_EQUALS与NUMPAD_EQUALS这类可打印键Windows字母键不在logical_key_data.g.json中记录embedder 不使用它们生成器会按 ASCII 字母/数字键标签手动补入同时生成扫描码 → 物理键映射以及 keycode 为 0 或歧义时使用的扫描码 → 逻辑键映射数据源 windows_scancode_logical_map.jsonmacOS / iOS无扫描码概念用虚拟 keycode 表示物理键且逻辑键大多从characterIgnoringModifiers推导映射表只负责无法或不应这样推导的键Web同时生成key→ 逻辑键、key→ 物理键含otherWebCodes别名以及keylocation联合判定的kWebLocationMapGTK除 keyval → 逻辑键映射外还生成 XKB 扫描码 → 物理键映射并利用修饰位/锁定位映射生成需同步状态的“checked keys”。六、数据解析与合并的内部原理6.1 物理键数据PhysicalKeyDataphysical_key_data.dart 负责把 Chromiumdom_code_data.inc格式如DOM_CODE(0x000010, 0x0000, 0x0000, 0x0000, 0xffff, Hyper, HYPER)与 AndroidGeneric.kl扫描码文件合并产出PhysicalKeyEntry。每个条目携带USB HID 码、evdev 扫描码、XKB 扫描码、Windows 扫描码、macOS 扫描码、iOS 扫描码、Android 扫描码列表、Chromium 事件码及额外 Web 别名。其中 iOS 扫描码由 USB HID 码推导当(usbHidCode 0x070000) 0x070000时取usbHidCode ^ 0x070000。解析时还会处理上游数据的特例跳过IntlHash、None等不会实际产生的键Fn 键允许重复条目并覆盖同一 USB HID 码的重复条目仅支持追加额外 DOM 键otherWebCodes。6.2 逻辑键数据LogicalKeyDatalogical_key_data.dart 把 Chromiumdom_key_data.inc、GTKgdkkeysyms.h、WindowsWinUser.h、Androidkeycodes.h、GLFWglfw3.h以及 macOS/iOS 的逻辑-物理映射合并为LogicalKeyEntry。每个逻辑键条目记录Flutter ID含平面、Web 名、各平台键码名与键码值列表、键标签等。关键处理规则包括Chromium 的修饰键Shift 等从 DOM 源中跳过由补充数据在 Flutter 平面生成左右变体可打印键放入 Unicode 平面其余按来源放入不可打印平面或 Flutter 平面Web 名仅记录非可打印键可打印键的 Web 名不加入macOS/iOS 通过“逻辑键 → 物理键”映射反向推导键码值Fuchsia 无独立头文件其值由逻辑键的 Unicode 码点或物理键的 USB HID 码换算得出GLFW 定义可能引用其他宏如GLFW_KEY_LAST GLFW_KEY_MENU解析时需二次解引用。6.3 命名规范键的常量名由工具统一推导computeName/computeCommentName/computeConstantName见 logical_key_data.dart驼峰命名拆分为注释名如wakeUp→ “Wake Up”、首词小写后去除空格得到常量名同时规避 Dart 保留字。物理键若没有 DOM 名则回退到 Chromium 符号名仍为空则以Key{hex}兜底见 physical_key_data.dart。七、测试保障生成结果的可验证性工具自带单元测试 gen_keycodes_test.dart以入库 JSON 为输入为每个平台执行一次生成并断言产物特征所有平台输出均须包含版权头、DO NOT EDIT标记以及KeyA、Digit1、F1、Numpad1、ShiftLeft等代表性常量checkCommonOutputAndroid 输出须包含class KeyboardMap、scanCodeToPhysical、keyCodeToLogicalmacOS / iOS 输出须包含kValueMask、keyCodeToPhysicalKey、keyCodeToLogicalKey、keyCodeToModifierFlag、modifierFlagToKeyCode等Windows 输出须包含KeyboardKeyEmbedderHandler::windowsToPhysicalMap_等三张映射Linux 输出须包含initialize_modifier_bit_to_checked_keys、initialize_lock_bit_to_checked_keysWeb 输出须包含kWebToLogicalKey、kWebToPhysicalKey、kWebLogicalLocationMap另有针对 flutter/flutter#87098 的回归断言ShiftLeft必须存在但不得以ShiftLeft或Shift作为 Web 名可打印键不得使用自身名字作为 Web 名。八、OpenHarmony 平台实践自定义平台的落地方案本仓库是 Flutter SDK 的 OpenHarmony 适配版本。虽然gen_keycodes工具本身只覆盖官方平台Android / Fuchsia / iOS / macOS / GTK / Windows / Web / GLFW但 OpenHarmony embedder 在工程实践中正是沿着“自定义平台平面”的思路落地键映射。在 Engine 侧shell/platform/ohos目录下实现了完整的键盘事件链路KeyboardMap.ets声明 OpenHarmony KeyCode → Flutter 逻辑键/物理键的静态映射表如0x7E1 → 0x61对应 keyA并定义了kValueMask 0x000FFFFFFFF与kOhosPlane 0x01900000000即0x19号平面处于 Flutter 平台平面区0x10-0x1F内为 OpenHarmony embedder 私用同时以ModifierGoal声明 Ctrl / Shift / Alt 的左右键 KeyPair 同步目标KeyEmbedderResponder.ets将 OpenHarmony 键事件转换为 Flutter 键数据。查表命中则返回映射值未命中则执行keyOfPlane(keyCode, KeyboardMap.kOhosPlane)把原始 keyCode 归入 OpenHarmony 平面——这正是“自动生成键”机制在自定义平台上的实际落地KeyboardManager.ets协调KeyEventChannel/KeyboardChannel/KeyEmbedderResponder/KeyEventHandler管理键盘状态与事件分发。这个实现示例恰好印证了 README 中“自定义平台建议使用平台平面值以避免向框架添加平台独占键”的设计指导——OpenHarmony 的未知键被映射到0x19平面而非 Flutter 平面从而不会污染官方框架键表。九、小结与移植建议gen_keycodes是 Flutter 键盘体系的中枢一份统一键位数据经模板渲染分发到框架与各平台引擎既保证了多平台键 ID 的一致性也把“新增键位”这类机械劳动从手工维护中解放出来。其核心设计可总结为三点单一数据源所有平台、所有键位信息汇聚为两份 JSON 主数据可离线重建、可入库审计平面化 Key ID52 位整数 20 位平面前缀让 Unicode 键、不可打印键、Flutter 私有键、平台私有键各得其所且能稳定表达“自动生成”状态模板驱动的多目标输出框架 Dart 文件、各平台 Engine 文件与测试文件共享同一数据杜绝手工同步偏差。如果你正准备为 Flutter 适配新平台建议按以下顺序行动先阅读 dev/tools/gen_keycodes/README.md 与 data/README.md 了解数据格式参照 OpenHarmony 的 KeyboardMap.ets 与 KeyEmbedderResponder.ets 落地查表与平面兜底对于官方平台遇到未识别键请走 issue 流程补充到keyboard_key.g.dart对于自定义平台请使用0x20-0x2F自定义平台平面保持框架键表纯净。赞分享跨平台前端移动开发OpenHarmony【免费下载链接】flutter_flutter本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。项目地址https://gitcode.com/CPF-Flutter/flutter_flutter点击查看免费下载相关推荐Flutter 键盘事件体系揭秘gen_keycodes 代码生成工具与 52 位键码平面方案Flutter 键盘事件体系揭秘gen_keycodes 代码生成工具与 52 位键码平面方案 本文深入讲解 Flutter 仓库中 dev/tools/ge跨平台移动开发前端UI组件桌面应用Isaac Lab 机器人学习仿真框架从零到首个训练任务完整指南Isaac Lab 机器人学习仿真框架从零到首个训练任务完整指南 Isaac Lab 是 NVIDIA 开源的 GPU 加速机器人学习仿真框架构建在 Isa人工智能强化学习机器人具身智能深度学习Flutter gen_keycodes 数据目录详解一组 JSON 与模板文件如何驱动跨平台键盘键码生成Flutter gen_keycodes 数据目录详解一组 JSON 与模板文件如何驱动跨平台键盘键码生成 本篇围绕 dev/tools/gen_keycod跨平台移动开发前端UI组件桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考