QMK 固件 2025-02-23 重大变更解析社区模块、Chordal Hold 与 DEFAULT_FOLDER 弃用【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文基于 QMK 官方变更记录 20250223 展开解读 2025 年 2 月 23 日发布的 QMK 固件周期中最重要的三项内容面向第三方开发者的社区模块Community Modules机制、基于对侧手规则的 Chordal Hold tap-hold 变体以及构建系统中DEFAULT_FOLDER的正式弃用。读完本文你将了解如何在新版 QMK 中消费与贡献社区模块、如何通过布局矩阵启用 Chordal Hold、在哪些键盘上需要更新构建目标名称以及keyboard.json与keyboard_aliases.hjson如何逐步取代rules.mk中的DEFAULT_FOLDER。社区模块Community Modules本周期引入的核心功能是社区模块允许第三方实现代码并以可导入的形式提供给其他键盘构建使用。这些模块可以提供覆盖或增强常规 QMK 处理的实现QMK 提供了一组 hooks钩子模块目前可以实现的包括初始化、按键处理、挂起suspend和关机shutdown等阶段。完整的 hooks 列表见 社区模块文档。仓库内的模块示例QMK 仓库自带的 hello_world 模块 是理解该机制的最佳起点。其 hello_world.c 展示了模块的两个典型 hook 用法void keyboard_post_init_hello_world(void) { keyboard_post_init_hello_world_kb(); // 先让 keyboard 层有机会处理 defer_exec(10000, delayed_hello_world, NULL); } bool process_record_hello_world(uint16_t keycode, keyrecord_t *record) { if (!process_record_hello_world_kb(keycode, record)) { return false; } switch (keycode) { case COMMUNITY_MODULE_HELLO: if (record-event.pressed) { SEND_STRING(Hello there.); break; } } return true; }两个值得注意的实现细节API 版本断言源文件头部调用ASSERT_COMMUNITY_MODULES_MIN_API_VERSION(1, 0, 0);在编译期检查当前 QMK 提供的模块 API 是否满足模块要求的最低版本这是模块与核心解耦的关键保障。_kb转发约定每个 hook 实现keyboard_post_init_hello_world、process_record_hello_world都会先调用对应的_kb变体再执行模块自身逻辑保证键盘/键位映射层的覆盖链不被模块截断。模块的元数据由 qmk_module.json 描述其中features声明了模块依赖的 QMK 功能示例声明了console与deferred_execkeycodes则为模块注入自定义键码示例定义了COMMUNITY_MODULE_HELLO别名CM_HELO。仓库中其他内置模块如 super_alt_tab 采用同样的结构。模块的构建接入由 lib/python/qmk/community_modules.py 及 build_keyboard.mk 在构建时完成解析与链接并提供qmk generate community_modules生成流程见 lib/python/qmk/cli/generate/community_modules.py。此外本次更新带来了对外部用户空间External Userspace的一等支持——也就是说社区模块可以直接从 userspace 仓库导入这是将键位映射构建迁移到 userspace 仓库的又一理由详见 External Userspace 文档。Chordal Hold基于对侧手规则的 tap-hold 变体Chordal Hold 默认实现一个对侧手opposite hands规则当一个 tap-hold 键被按下后在 tap 判定窗口tapping term结束前又按下了另一个键时若这两个键位于同一只手则 tap-hold 键将被判定为轻击tap。该特性尤其适合配合 home row mods 使用可以避免滚键rolled keypresses时 mod-tap 误触发修饰键。从源码结构看该机制实现在 quantum/action_tapping.c 中核心是弱定义函数get_chordal_hold()其默认实现get_chordal_hold_default()通过读取 PROGMEM 中的布局矩阵chordal_hold_layout[MATRIX_ROWS][MATRIX_COLS]判断两个按键的左右手归属由弱函数chordal_hold_handedness()提供可被键盘侧覆盖。在 waiting buffer 处理路径中当检测到 tap-hold 键与其他键同侧时会将其结算为 tapwaiting_buffer_chordal_hold_taps_until()会连续将之前的 tap-hold 判定为 tap。完整用法与配置项见 tap-hold 文档的 Chordal Hold 章节。本周期还附带修复了一个 Chordal Hold 的缺陷在快速连击序列中同时按下多个 mod-tap 时出现修饰键卡住的问题修复于同期 changelist 的 Bugs 部分。需要用户操作的变更键盘构建目标改名以下键盘的代码基座在本周期发生了路径迁移旧构建目标将失效需要按下表更新旧键盘名称新键盘名称cxt_studiocxt_studio/12e4ergodox_stm32handwired/ergodox_stm32ploopyco/mouseploopyco/mouse/rev1_002ploopyco/trackball/rev1ploopyco/trackball/rev1_004ymdk/id75ymdk/id75/f103对应的目录结构在仓库中均已就位例如 cxt_studio、handwired、ploopyco 与 ymdk 下的子目录。迁移动机在 changelist 的 Keyboards 部分可以印证ymdk/id75 按 revision 拆分、cxt_studio 移入独立文件夹并新增 12E3 变体、Ergodox STM32 移入 handwired 目录、Ploopy 系列适配 RP2040 硬件升级。弃用公告DEFAULT_FOLDER 移除按照 QMK 的弃用通知政策本周期对较大范围的改动给出弃用预告。DEFAULT_FOLDER最初是为绕过构建系统的限制而引入的当父目录中包含公共配置时会产生无效的构建目标。随着keyboard.json作为配置文件的引入该机制于 2024-05-26 周期落地构建系统已具备一致的方法来识别构建目标DEFAULT_FOLDER的功能因此变得冗余后续意图是让rules.mk回归纯配置。本周期围绕该弃用做的工作包括正式弃用DEFAULT_FOLDERchangelist Others 部分将部分键盘的DEFAULT_FOLDER迁移到keyboard_aliases.hjson并在已有 keyboard aliases 的情况下移除DEFAULT_FOLDERKeyboards 部分多条记录修复因DEFAULT_FOLDER引起的 CI 问题并移除无效构建目标Keyboard fixes 部分。构建目标的后向兼容在可行的范围内得以保留对于已存在 aliases 的键盘旧名称仍可解析。完整变更清单以下为原文档 Full changelist 的完整继承按类别组织。Core核心OSL 与 MO 的链式组合支持为 EurKEY 布局添加额外键位映射新增leader_add_user回调ARM 平台始终将 audio pin 复位为 0更新 Starlight 矩阵灯光效果使用 runner 重构 Hue Breathing 矩阵灯光效果确保 ARM 平台timer_read()可在中断处理程序中安全调用Raindrops 效果遵循 LED 范围限制新增 Chordal Hold——一种类似 Achordion / Bilateral Combinations 的对侧手规则 tap-hold 选项Azoteq 传感器改善轮询期间的 I2C 行为macOS 安装移除损坏的 ARM 工具链TIMER_DIFF小型重构修正希伯来语子音符号subscript alef为 quantum painter 新增 SH1107 显示屏驱动[CI] 重新生成文件修复 Backlight 反向互补输出的问题修复使用 APA102 驱动编译时的编译问题合并各处send_string实现合并各处timer_elapsed实现i2c_master移除弃用函数处理键盘 make 目标时解析 keyboard_aliasesLED 驱动移除弃用宏定义ferris/0_1更新 I2C API 用法统一 i2c_master 头文件社区模块Community modules迁移基础 WS2812 代码统一 UART 头文件统一 spi_master 头文件在_user/_kb层获得处理机会之后再调用process_record_viaCLI命令行扩展 lint拒绝空白的 blank 文件qmk docs恢复--port与--browser参数更新 via2json 的布局宏搜索逻辑修改new-keymap的键位映射命名提示default_keyboard.h生成逻辑调整确保qmk flash对 UF2 兼容 bootloader 拒绝非法文件拒绝 readme 占位dummy内容Submodule updates子模块更新chibios: usb_main 移除 OTG sof workaround更新 ChibiOS 至最新稳定分支更新 ChibiOSstable_21.11.x更新 ChibiOS-ContribKeyboards键盘重构将 ymdk/id75 迁移至 revision 目录skyloong/gk61移除对核心键码行为的覆盖moky/moky88移除弃用宏的使用更新 Promenade 键盘补齐矩阵中缺失的键及其他键位映射小改动将 cxt_studio 键盘移入独立文件夹新增 CXT Studio 12E3 键盘新增 Silakka54 键盘为 skiller_sgk50_s4 增加布局为 RGBKB Sol 3 增加看门狗服务将部分DEFAULT_FOLDER迁移到 keyboard_aliases.hjson多条移除已有 keyboard aliases 的DEFAULT_FOLDER多条更新 A-JAZZ AKC084A-JAZZ AKP846handwired/xealous 移除DEFAULT_FOLDERPloopy Classic、Mouse、Thumb 适配 RP2040 硬件升级将 Ergodox STM32 移入 handwired 目录移除 readme 占位内容Keyboard fixes键盘修复修复涉及DEFAULT_FOLDER的 CI 问题rgbkb/pan移除无效构建目标Others其他正式弃用DEFAULT_FOLDER更正 I2C API 文档引用Bugs缺陷修复Retro Tapping 重写修复键码滚键Key Roll问题修复 Quantum Painter 在高优化等级下的编译问题AT32F415 的修复与更新Chordal Hold 修复mod-tap 快速连击序列下修饰键卡住的问题修复 STM32L0/1 cat.1 设备的 EEPROM 驱动小结与升级建议本次变更周期的三条主线对用户的实际影响如下构建目标迁移如果你使用 cxt_studio、ergodox_stm32、ploopyco/mouse、ploopyco/trackball/rev1 或 ymdk/id75请立即更新构建命令中的键盘名改为表格中的新路径。rules.mk清理如果你的键盘或外部仓库仍在使用DEFAULT_FOLDER建议将其迁移到keyboard_aliases.hjson键盘级或依赖keyboard.json的目标发现机制为后续rules.mk纯配置化做准备。尝试新特性启用 Chordal Hold参考 tap_hold 文档可显著改善 home row mods 的滚键体验有开发能力的用户可以从 hello_world 模块 起步按 社区模块文档 描述的流程开发并导入自己的模块并结合 外部用户空间 管理跨键盘复用的代码。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考