应使用 wh_keyboard_ll 低级钩子捕获原始按键，结合 getkeyboardlayout 和 mapvirtualkeyex 动态映射字符，避免 toascii 等过时 api，并通过后台线程异步处理以保证响应性。
要异步捕获并处理非标准键盘布局下的原始按键映射，不能依赖控件级事件（如 KeyDown）或简单轮询（如 GetAsyncKeyState），而需结合操作系统底层输入机制与布局感知能力。核心在于：获取原始扫描码/虚拟键码 → 关联当前活跃键盘布局 → 映射为实际字符或语义键名 → 异步分发处理。
用低级钩子捕获原始按键流
在 Windows 上，必须使用 WH_KEYBOARD_LL 类型的全局钩子（SetWindowsHookEx），它在消息进入目标线程消息队列前触发，不依赖焦点，能稳定捕获所有物理按键动作（包括 Alt+Tab、Win 键等）。回调函数需为 static，且所在类实例须防止被 GC 回收（例如用 static readonly 字段持有引用）。钩子返回值决定是否继续传递该按键——若仅需监听不拦截，直接 CallNextHookEx 即可。
- 回调中通过 KBDLLHOOKSTRUCT 结构体获取扫描码（scanCode）、虚拟键码（vkCode）、标志位（flags，含重复、扩展键等信息）
- 注意区分 WM_KEYDOWN / WM_SYSKEYDOWN：前者是普通按键，后者对应 Alt、F10 等系统键，处理逻辑应分开
- 避免在回调中执行耗时操作（如 I/O、UI 更新），应将数据投递到后台线程或 Task 队列异步处理
动态适配当前键盘布局
同一物理按键在不同布局下输出不同字符（如德语键盘的 'ö' 键在美式键盘上是 ';’）。不能硬编码 vkCode→字符映射，而应实时查询系统布局：
- 调用 GetKeyboardLayout(GetCurrentThreadId()) 获取当前线程激活的 HKL（键盘布局句柄）
- 用 MapVirtualKeyEx 将 vkCode + scanCode + HKL 转为 Unicode 字符（MAPVK_VK_TO_CHAR）或扫描码（MAPVK_VK_TO_VSC）
- 对组合键（Shift/Ctrl/Alt），需先用 GetKeyboardState 获取当前修饰键状态，再传入 MapVirtualKeyEx 的 fUnicode 参数控制大小写和符号变体
跨平台统一处理建议（Node.js 场景）
若面向 Electron 或桌面 Node 应用，推荐使用 native-keymap 模块。它封装了各平台差异（Windows 的 IMM/KBD、macOS 的 TIS、Linux 的 XKB），提供一致 API：
- 调用 getKeyMap() 得到完整键位表，含每个键在不同修饰状态下的输出字符、vkey、位置码（USB HID usage code）
- 配合 raw-keyboard 或 robotjs 监听原始事件，再用 native-keymap 查表还原语义——这样既保有原始输入精度，又规避了手动解析布局的复杂性
- 特别适合快捷键管理器、远程输入工具、无障碍辅助软件等需精确响应“用户本意”的场景
避开常见陷阱
很多实现卡在“为什么 Shift+A 有时是 a 有时是 A”这类问题上，根源常是状态同步缺失：
- 不要只靠一次 GetKeyboardState 判断修饰键——它反映的是调用瞬间快照，而按键事件可能跨越多个消息周期；应结合钩子中的 flags（如 LLKHF_INJECTED、LLKHF_ALTDOWN）做上下文推断
- 避免用 ToAscii / ToUnicode：它们依赖线程键盘布局且行为不稳定，已被 MapVirtualKeyEx 取代
- 非标准布局（如 Colemak、Dvorak、带额外宏键的游戏键盘）需测试真实设备，模拟器或软键盘可能不触发低级钩子
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
