Flutter 键码生成器(gen_keycodes)深度解析:LogicalKeyboardKey / PhysicalKeyboardKey 的自动化生成与 Key ID 编址方案

原创2026-10-14 11:23:471,413 阅读
文章标签:跨平台移动开发OpenHarmony图形学开发工具UI组件构建工具

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 的多份代码文件。整体数据流为:

  1. 收集:在线拉取 Chromium、Android、Windows、GTK、GLFW 等上游头文件,结合仓库内的补充数据,解析合并;
  2. 沉淀:写入两份 JSON 主数据文件(可入库、可离线复用);
  3. 生成:基于主数据 + 模板,渲染出框架与引擎各平台的目标文件。

2.1 生成的两类框架文件

对 Flutter 框架(packages/flutter),生成器输出两份文件:

  • keyboard_key.g.dart:包含 LogicalKeyboardKey 与 PhysicalKeyboardKey 的全部静态常量定义、已知键的查找表(_knownLogicalKeys、_knownPhysicalKeys)、伪键同义词映射(_synonyms / _reverseSynonyms)、键标签映射(_keyLabels)以及各平面掩码常量;
  • keyboard_maps.g.dart:包含各平台特有的不可变映射表(如 kAndroidToLogicalKey、kMacOsToPhysicalKey、kWebToLogicalKey、kWindowsNumPadMap 等),供 RawKeyboard API 使用。

两个生成文件头部都带有明确的“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 的一致性,也把“新增键位”这类机械劳动从手工维护中解放出来。其核心设计可总结为三点:

  1. 单一数据源:所有平台、所有键位信息汇聚为两份 JSON 主数据,可离线重建、可入库审计;
  2. 平面化 Key ID:52 位整数 + 20 位平面前缀,让 Unicode 键、不可打印键、Flutter 私有键、平台私有键各得其所,且能稳定表达“自动生成”状态;
  3. 模板驱动的多目标输出:框架 Dart 文件、各平台 Engine 文件与测试文件共享同一数据,杜绝手工同步偏差。

如果你正准备为 Flutter 适配新平台,建议按以下顺序行动:先阅读 dev/tools/gen_keycodes/README.md 与 data/README.md 了解数据格式;参照 OpenHarmony 的 KeyboardMap.ets 与 KeyEmbedderResponder.ets 落地查表与平面兜底;对于官方平台,遇到未识别键请走 issue 流程补充到 keyboard_key.g.dart;对于自定义平台,请使用 0x20-0x2F 自定义平台平面,保持框架键表纯净。

登录后查看全文
flutter_flutter