QMK 语言特定键码（keymap_extras）与 Sendstring 布局支持完全指南

QMK 语言特定键码keymap_extras与 Sendstring 布局支持完全指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本指南讲解 QMK Firmware 如何通过quantum/keymap_extras/目录下的语言特定键码头文件让键盘固件支持全球数十种键盘布局——核心原理是键盘本身只发送 HID 数值码由操作系统依据用户设置的布局将其映射为对应字符。读完本文你将掌握在keymap.c中引入keymap_*.h头文件、在keymap.json中声明host_language、以及通过 Sendstring LUT 头文件让SEND_STRING()宏按非美式布局正确输出字符的完整方法。为什么需要语言特定键码键盘与操作系统的分工键盘硬件能够支持各种语言但这种支持并不在键盘内部实现。根据 HID 规范键盘默认发送的是 US ANSI 布局对应的数值码由操作系统根据用户配置的键盘布局把这些数值码映射成实际字符。QMK 官方文档给出了一个典型例子当瑞典用户按下印有å的按键时键盘实际上发送的是[的键码——只是操作系统在瑞典语布局下把它渲染成了å。这自然会带来认知上的混乱你在配列图里看到的键位标识与实际发送的键码不一致。为此QMK 为大量键盘布局提供了语言特定键码别名language-specific keycode aliases用来替代默认的KC_前缀键码。需要强调的是这些别名自身不会改变键盘行为——它们更像键帽标签真正完成字符映射的仍然是操作系统你依然要在系统设置中选择匹配的键盘布局两者缺一不可。所有语言特定键码别名都定义在 quantum/keymap_extras/ 目录下分别存放于keymap_*.h键码别名与sendstring_*.hSendstring 查找表两类头文件中。选择宿主键盘布局两种接入方式方式一在 keymap.c 中手动包含头文件在keymap.c顶部#include QMK_KEYBOARD_H之后加入对应语言的键码头文件即可。以日语为例#include QMK_KEYBOARD_H #include keymap_japanese.h // [!code focus]包含该头文件后键映射中即可直接使用JP_前缀的别名例如JP_YEN¥、JP_EISU英数、JP_ZKHK全半角切换等。在 keymap_japanese.h 中可以看到这些别名的真实定义例如#define JP_YEN KC_INT3、#define JP_EISU KC_CAPS——它们最终都落在基础键码上。方式二在 keymap.json 中声明 host_language如果你使用keymap.jsonQMK CLI 的推荐工作流只需添加host_language键QMK 的 Python 工具链会在生成keymap.c时自动注入对应的头文件包含。可用语言即下方头文件清单表格中拥有Sendstring LUT Header条目的那些语言{ keyboard: handwired/my_macropad, keymap: my_keymap, host_language: swedish, // [!code focus] layout: LAYOUT_all, layers: [ [SE_ARNG] ] }从源码看这一自动注入逻辑位于 lib/python/qmk/keymap.py当keymap_json中存在非空的host_language时工具会生成如下两行预处理代码拼入生成的 keymap 文件#include keymap_语言名.h #include sendstring_语言名.h也就是说声明host_language: swedish等价于同时包含keymap_swedish.h与sendstring_swedish.h键码别名与 Sendstring 查找表会被一并启用。Sendstring 支持让宏字符串按你的布局输出SEND_STRING()宏默认假设主机使用 US ANSI 布局因此当你在键映射中写下SEND_STRING(Hello)这类字符串时固件依据一张 ASCII 到键码的查找表逐字符翻译。若你使用其他布局可以通过包含对应语言的sendstring_*.h头文件来覆盖这些查找表。注意包含 Sendstring 头文件时不需要再单独包含对应的keymap_*.h因为它内部已经隐式包含了后者——这一点可以从 sendstring_swedish.h 开头看到它直接#include keymap_swedish.h。三张查找表与一张键码表以瑞典语为例sendstring_swedish.h中实际定义了四张 PROGMEM 常量表共同决定了每个 ASCII 字符如何输出表名作用ascii_to_shift_lut[16]标记哪些 ASCII 字符需要按住 Shift如!、?ascii_to_altgr_lut[16]标记哪些字符需要按下 AltGr如、$、€ascii_to_dead_lut[16]标记哪些字符属于死键dead key如重音符号´、变音符号¨ascii_to_keycode_lut[128]将 128 个 ASCII 码映射到具体键码别名如SE_1、SE_QUOT四张表都通过KCLUT_ENTRY(...)宏以每行 8 个字符的位图方式组织。正是因为有了ascii_to_shift_lut固件才知道输出!时要同时按住 Shift 和SE_1有了ascii_to_altgr_lut才知道输出€需要 AltGr SE_5有了ascii_to_dead_lut才知道´是一个必须先按下、等下一个字符的死键。使用限制仅支持 ASCII需要特别注意两个限制SEND_STRING()只能操作 ASCII 文本无法直接传入包含 Unicode 的字符串——这意味着你目标布局中的重音字符如å、é无法原样出现在宏字符串里。很多布局只以**死键dead key**形式提供 Grave或 Tilde~等字符。死键会与紧随其后的字符组合因此在要发送的字符串中死键字符之后必须紧跟一个空格防止它意外与下一个字符结合。例如在法语布局下发送SEND_STRING();。某些布局如希腊语、俄语没有 Sendstring 头文件因为它们不使用拉丁字母派生字母表大部分 ASCII 字符集根本无从输入——这也解释了为何下表中希腊语、俄语、韩语、波斯语等条目的 Sendstring 列为空。头文件清单语言与布局总表以下头文件均位于 quantum/keymap_extras/。两个表分别列出语言专用布局与非 QWERTY通用布局。语言专用布局布局键码头文件Sendstring LUT 头文件加拿大多语言 (CSA)keymap_canadian_multilingual.hsendstring_canadian_multilingual.h克罗地亚语keymap_croatian.hsendstring_croatian.h捷克语keymap_czech.hsendstring_czech.h捷克语 (macOS, ANSI)keymap_czech_mac_ansi.hsendstring_czech_mac_ansi.h捷克语 (macOS, ISO)keymap_czech_mac_iso.hsendstring_czech_mac_iso.h丹麦语keymap_danish.hsendstring_danish.h荷兰语比利时keymap_belgian.hsendstring_belgian.h英语爱尔兰keymap_irish.h英语英国keymap_uk.hsendstring_uk.h英语美式扩展keymap_us_extended.h英语美式国际keymap_us_international.hsendstring_us_international.h英语美式国际, Linuxkeymap_us_international_linux.h爱沙尼亚语keymap_estonian.hsendstring_estonian.hEurKEYkeymap_eurkey.h波斯语keymap_farsi.h芬兰语keymap_finnish.hsendstring_finnish.h法语keymap_french.hsendstring_french.h法语AFNORkeymap_french_afnor.hsendstring_french_afnor.h法语BÉPOkeymap_bepo.hsendstring_bepo.h法语比利时keymap_belgian.hsendstring_belgian.h法语加拿大keymap_canadian_french.hsendstring_canadian_french.h法语瑞士keymap_swiss_fr.hsendstring_swiss_fr.h法语macOS, ISOkeymap_french_mac_iso.hsendstring_french_mac_iso.h德语keymap_german.hsendstring_german.h德语瑞士keymap_swiss_de.hsendstring_swiss_de.h德语macOSkeymap_german_mac_iso.hsendstring_german_mac_iso.h德语Neo2keymap_neo2.h希腊语keymap_greek.h希伯来语keymap_hebrew.h匈牙利语keymap_hungarian.hsendstring_hungarian.h冰岛语keymap_icelandic.hsendstring_icelandic.h意大利语keymap_italian.hsendstring_italian.h意大利语macOS, ANSIkeymap_italian_mac_ansi.hsendstring_italian_mac_ansi.h意大利语macOS, ISOkeymap_italian_mac_iso.hsendstring_italian_mac_iso.h日语keymap_japanese.hsendstring_japanese.h韩语keymap_korean.h拉脱维亚语keymap_latvian.hsendstring_latvian.h立陶宛语ĄŽERTYkeymap_lithuanian_azerty.hsendstring_lithuanian_azerty.h立陶宛语QWERTYkeymap_lithuanian_qwerty.hsendstring_lithuanian_qwerty.h挪威语keymap_norwegian.hsendstring_norwegian.h波兰语keymap_polish.h葡萄牙语keymap_portuguese.hsendstring_portuguese.h葡萄牙语macOS, ISOkeymap_portuguese_mac_iso.hsendstring_portuguese_mac_iso.h葡萄牙语巴西keymap_brazilian_abnt2.hsendstring_brazilian_abnt2.h罗马尼亚语keymap_romanian.hsendstring_romanian.h俄语keymap_russian.h塞尔维亚语keymap_serbian.h塞尔维亚语拉丁keymap_serbian_latin.hsendstring_serbian_latin.h斯洛伐克语keymap_slovak.hsendstring_slovak.h斯洛文尼亚语keymap_slovenian.hsendstring_slovenian.h西班牙语keymap_spanish.hsendstring_spanish.h西班牙语Dvorakkeymap_spanish_dvorak.hsendstring_spanish_dvorak.h西班牙语拉丁美洲keymap_spanish_latin_america.hsendstring_spanish_latin_america.h瑞典语keymap_swedish.hsendstring_swedish.h瑞典语macOS, ANSIkeymap_swedish_mac_ansi.h瑞典语macOS, ISOkeymap_swedish_mac_iso.h瑞典语 PromacOS, ANSIkeymap_swedish_pro_mac_ansi.h瑞典语 PromacOS, ISOkeymap_swedish_pro_mac_iso.h土耳其语Fkeymap_turkish_f.hsendstring_turkish_f.h土耳其语Qkeymap_turkish_q.hsendstring_turkish_q.h乌克兰语keymap_ukrainian.h非 QWERTY 通用布局还有一批不严格属于某一种语言、但在非 QWERTY 配列下非常实用的布局布局键码头文件Sendstring LUT 头文件Colemakkeymap_colemak.hsendstring_colemak.hDvorakkeymap_dvorak.hsendstring_dvorak.hDvorak法语keymap_dvorak_fr.hsendstring_dvorak_fr.hDvorak程序员版keymap_dvorak_programmer.hsendstring_dvorak_programmer.hNormankeymap_norman.hsendstring_norman.hPloverkeymap_plover.hPloverDvorakkeymap_plover_dvorak.hWorkmankeymap_workman.hsendstring_workman.hWorkmanZXCVMkeymap_workman_zxcvm.hsendstring_workman_zxcvm.h提示仓库目录中还存在未列入上表的头文件例如keymap_nordic.h、keymap_russian_typewriter.h、keymap_steno.h、keymap_us.h说明布局支持仍在持续扩充编写键映射时可直接在目录中查找可用的头文件。源码视角键码别名的实际形态语言特定键码并非全新的键码值而是对基础键码的宏别名。打开 keymap_swedish.h 可以看到完整的定义模式#define SE_ARNG KC_LBRC // Å #define SE_ODIA KC_SCLN // Ö #define SE_ADIA KC_QUOT // Ä #define SE_HALF S(SE_SECT) // ½ #define SE_EXLM S(SE_1) // ! #define SE_AT ALGR(SE_2) // #define SE_EURO ALGR(SE_5) // € #define SE_LCBR ALGR(SE_7) // {从中可以总结出三条规律单键字符直接映射印在按键上的字符字母、数字、标点直接#define到对应基础键码如SE_ARNG → KC_LBRC。因此瑞典配列上印着Å的键实际发送的是美式布局[的键码与文档开头的例子完全吻合。上档字符用S()组合需要按住 Shift 的字符通过S(...)宏在别名基础上叠加如!定义为S(SE_1)。第三层字符用ALGR()组合需要 AltGr国际键盘的第三层的字符用ALGR(...)宏如、$、€、花括号、管道符等。正是这种别名叠加基础键码的设计让同一套 HID 协议在不同语言配列下都能以键帽标签般的直观方式书写键映射。使用时请记住这些别名不会替你修改操作系统的输入法设置host_language或头文件包含只是让键映射代码可读、可维护最终字符是否正确出现仍取决于主机端键盘布局是否与之一致。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考