Flutter 键码生成器(gen_keycodes)深度解析:LogicalKeyboardKey / PhysicalKeyboardKey 的自动化生成与 Key ID 编址方案
Flutter 键码生成器(gen_keycodes)深度解析:LogicalKeyboardKey / PhysicalKeyboardKey 的自动化生成与 Key ID 编址方案
本文围绕 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 路径) | 生成器实现 |
|---|---|---|
| Android | engine/src/flutter/shell/platform/android/io/flutter/embedding/android/KeyboardMap.java |
android_code_gen.dart |
| macOS | engine/src/flutter/shell/platform/darwin/macos/framework/Source/KeyCodeMap.g.mm |
macos_code_gen.dart |
| iOS | engine/src/flutter/shell/platform/darwin/ios/framework/Source/KeyCodeMap.g.mm |
ios_code_gen.dart |
| Windows | engine/src/flutter/shell/platform/windows/flutter_key_map.g.cc |
windows_code_gen.dart |
| Linux (GTK) | engine/src/flutter/shell/platform/linux/key_mapping.g.cc |
gtk_code_gen.dart |
| Web | engine/src/flutter/lib/web_ui/lib/src/engine/key_map.g.dart |
web_code_gen.dart |
| Engine 工具 | engine/src/flutter/shell/platform/embedder/test_utils/key_codes.g.h、engine/src/flutter/shell/platform/android/test/io/flutter/util/KeyCodes.java |
testing_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 主数据文件,且已入库:
只要这两份文件存在,就无需联网。日常重建目标文件只需执行:
/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.dart):
- Chromium
dom_code_data.inc(物理键 USB HID 码)与dom_key_data.inc(逻辑键列表); - Android
keycodes.h(键码)与Generic.kl(扫描码布局); - Windows
WinUser.h(虚拟键码); - GTK
gdkkeysyms.h(keyval 定义); - GLFW
glfw3.h(GLFW 键码)。
刷新后的 physical_key_data.g.json 与 logical_key_data.g.json 应当提交入库,以便后续离线生成与审计。
3.3 其他命令行选项
--help 可查看全部参数。除 --collect 外,核心参数包括(默认值见 gen_keycodes.dart):
| 参数 | 默认值 | 作用 |
|---|---|---|
--physical-data |
dev/tools/gen_keycodes/data/physical_key_data.g.json |
收集时写入、生成时读取的物理键主数据路径 |
--logical-data |
dev/tools/gen_keycodes/data/logical_key_data.g.json |
收集时写入、生成时读取的逻辑键主数据路径 |
--code |
packages/flutter/lib/src/services/keyboard_key.g.dart |
keyboard_key.g.dart 输出路径 |
--maps |
packages/flutter/lib/src/services/keyboard_maps.g.dart |
keyboard_maps.g.dart 输出路径 |
四、Key ID 编址方案:52 位整数与平面划分
为了让每个键拥有全局唯一 ID,Flutter 采用了一套“平面(plane)”编址方案,避免自行铸造新编码。该方案同时适用于逻辑键与物理键。
4.1 编码结构
键码是一个 52 位整数(上限受 JavaScript 安全整数 2^53-1 限制)。整个命名空间划分为多个 32 位宽度的 平面:
- 高 20 位:平面 ID(plane ID);
- 低 32 位:该平面内的值(value)。
例如平面 0x1 对应范围 0x1 0000 0000 - 0x1 FFFF FFFF。平面内部如何分配值由该平面自行决定。
4.2 平面规划总表
| 平面 | 名称 | 内容与取值规则 |
|---|---|---|
0x00 |
Unicode 平面 | 逻辑键:按下会生成 Unicode 字符的键(含死键,不含功能键、Shift 等修饰键),取值为对应字符的 Unicode 码点(尽量取小写、忽略修饰键),如 Key A(0x61)、Digit 1(0x31)、Colon(0x3A)、Key Ù(0xD9)。物理键:USB HID usage 键 |
0x01 |
不可打印平面 | 逻辑键:Chromium key 列表中不生成 Unicode 字符的键,取值为 Chromium 宏值,如 CapsLock(0x105)、ArrowUp(0x304)、F1(0x801)、Hiragata(0x716)、TVPower(0xD4B)。注意:Chromium 中的修饰键(如 Shift)不在此平面,见 Flutter 平面 |
0x02 |
Flutter 平面 | Flutter 自行定义的键。修饰键放于此,因为 Flutter 区分左右侧修饰键(ShiftLeft / ShiftRight),而 Web 只有统一的 Shift;其他如小键盘键、手柄键也在此 |
0x03-0x0F |
保留 | 未分配 |
0x10-0x1F |
平台平面 | 由 Flutter 管理的官方平台平面(见下表) |
0x20-0x2F |
自定义平台平面 | 供自定义平台私用,规则与 Flutter 平台平面类似 |
4.3 官方平台平面编号
| Code | Platform |
|---|---|
0x11 |
Android |
0x12 |
Fuchsia |
0x13 |
iOS |
0x14 |
macOS |
0x15 |
Gtk |
0x16 |
Windows |
0x17 |
Web |
0x18 |
GLFW |
平台平面存放该平台 embedder 私有的键(通常是 Flutter 尚未官方认可的键)。平面内值的分配规则由平台自行决定,典型做法是直接使用平台原生按键事件中的其他字段。
4.4 掩码常量与运行时实现
上述平面划分在生成文件中体现为一组掩码/平面常量。生成器的常量定义见 constants.dart:
kValueMask = 0x00FFFFFFFF:提取低 32 位值;kPlaneMask = 0xFF00000000:提取平面前缀;kUnicodePlane = 0x0000000000、kUnprintablePlane = 0x0100000000、kFlutterPlane = 0x0200000000;kStartOfPlatformPlanes = 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.tmpl):
synonyms:从具体键取伪键,如shiftLeft.synonyms返回{ shift };collapseSynonyms:将一组键折叠为伪键集合,回答“是否有任意 Ctrl 键按下”;expandSynonyms:将伪键展开为具体键集合(control→controlLeft+controlRight)。
5.2 各平台辅助数据
| 平台 | 文件 | 说明 |
|---|---|---|
| Android | android_keyboard_map_java.tmpl | KeyboardMap.java 的模板 |
| Android | android_key_name_to_name.json | 逻辑键名到对应 keycode 常量名的映射 |
| iOS | ios_logical_to_physical.json | 逻辑键名到对应物理键名的映射,用于从 keyCode 推导无法(或不应)从 characterIgnoringModifiers 推导的逻辑键 |
| iOS | ios_key_code_map_mm.tmpl | KeyCodeMap.mm 的模板 |
| Web | web_key_map_dart.tmpl | key_map.dart 的模板 |
| Web | web_logical_location_mapping.json | Web 的 key + location 二元组到逻辑键名的映射,用于区分相同 key 不同 location 的逻辑键 |
| Windows | windows_flutter_key_map_cc.tmpl | flutter_key_map.cc 的模板 |
| Windows | windows_logical_to_window_vk.json | 逻辑键名到 Win32 虚拟键名的映射 |
| Windows | windows_scancode_logical_map.json | 物理键名到逻辑键名的映射,用于 keycode 为 0 或一个 keycode 对应多个键、只能靠扫描码区分的情形 |
| GTK | gtk_key_mapping_cc.tmpl | key_mapping.cc 的模板 |
| GTK | gtk_lock_bit_mapping.json | GTK 修饰位宏名到 Flutter 逻辑键名(元素 #0)与物理键名(元素 #1)的映射,用于生成 GTK 需保持锁定状态同步的键 |
| GTK | gtk_logical_name_mapping.json | 逻辑键名到对应 keyval 宏名的映射 |
| GTK | gtk_modifier_bit_mapping.json | GTK 修饰位宏名到 Flutter 物理键名(元素 #0)、逻辑键名(元素 #1)及配对键逻辑键名(元素 #2)的映射,用于生成 GTK 需保持按下状态同步的键 |
| GTK | gtk_numpad_shift.json | 小键盘键 keyval 宏名到 NumLock 开启时对应键的映射。GTK 对 NumLock 开/关使用不同 keyval,而 Flutter 逻辑键模型视为同一键 |
| GLFW | glfw_key_name_to_name.json、glfw_keyboard_map_cc.tmpl | 逻辑键名到 GLFW 宏名的映射与 keyboard_map.cc 模板(当前均标记为 Unused for now) |
| macOS | macos_key_code_map_cc.tmpl、macos_logical_to_physical.json | 模板与逻辑键到物理键的映射(用于从 keyCode 推导逻辑键) |
| Fuchsia | fuchsia_keyboard_map_cc.tmpl | keyboard_map.cc 的模板(当前标记为 Unused for now) |
5.3 各平台映射的生成要点
不同平台映射的生成逻辑体现了各平台键事件模型的差异(实现见 keyboard_maps_code_gen.dart):
- Android:同时生成 key code → 逻辑键、扫描码 → 物理键、以及小键盘专用映射(
kAndroidNumPadMap),用于区分KEY_EQUALS与NUMPAD_EQUALS这类可打印键; - Windows:字母键不在
logical_key_data.g.json中记录(embedder 不使用它们),生成器会按 ASCII 字母/数字键标签手动补入;同时生成扫描码 → 物理键映射,以及 keycode 为 0 或歧义时使用的扫描码 → 逻辑键映射(数据源 windows_scancode_logical_map.json); - macOS / iOS:无扫描码概念,用虚拟 keycode 表示物理键,且逻辑键大多从
characterIgnoringModifiers推导,映射表只负责无法或不应这样推导的键; - Web:同时生成
key→ 逻辑键、key→ 物理键(含otherWebCodes别名)以及key+location联合判定的kWebLocationMap; - GTK:除 keyval → 逻辑键映射外,还生成 XKB 扫描码 → 物理键映射,并利用修饰位/锁定位映射生成需同步状态的“checked keys”。
六、数据解析与合并的内部原理
6.1 物理键数据(PhysicalKeyData)
physical_key_data.dart 负责把 Chromium dom_code_data.inc(格式如 DOM_CODE(0x000010, 0x0000, 0x0000, 0x0000, 0xffff, "Hyper", HYPER))与 Android Generic.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 逻辑键数据(LogicalKeyData)
logical_key_data.dart 把 Chromium dom_key_data.inc、GTK gdkkeysyms.h、Windows WinUser.h、Android keycodes.h、GLFW glfw3.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等代表性常量(checkCommonOutput); - Android 输出须包含
class KeyboardMap、scanCodeToPhysical、keyCodeToLogical; - macOS / iOS 输出须包含
kValueMask、keyCodeToPhysicalKey、keyCodeToLogicalKey、keyCodeToModifierFlag、modifierFlagToKeyCode等; - Windows 输出须包含
KeyboardKeyEmbedderHandler::windowsToPhysicalMap_等三张映射; - Linux 输出须包含
initialize_modifier_bit_to_checked_keys、initialize_lock_bit_to_checked_keys; - Web 输出须包含
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 ID:52 位整数 + 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 自定义平台平面,保持框架键表纯净。