调一个快捷键功能按下去没反应加个日志一看e.keyCode打出来是 229。换一个键变成 0。再换一个明明按的是同一个物理位置切换输入法之后又变成了别的数字。这种事我第一次碰到的时候盯着控制台看了半小时一度怀疑是自己事件监听写错了。后来才想明白keyCode这个数字根本不是浏览器随手给的它背后有一条从键盘电路板一直通到 JS 事件对象的完整翻译链链条上任何一环动了这个数字就可能跟着变。keyCode是键盘事件对象上的一个数字属性历史上用来标识哪个键被按下了。它曾经是判断按键的唯一手段如今在规范里已经被标记为遗留属性但你在任何一家公司的前端代码、游戏引擎、自动化测试脚本、远程控制工具里都还能翻出它的身影。搞明白它为什么存在、为什么每个键会对应一个值、这套值在什么场景下仍然不可替代、又在什么场景下必须绕开是每个要去碰键盘交互的人绕不过去的一课。这篇文章就按这条链路往下挖先讲概念分层再讲从矩阵扫描到虚拟键码的底层原理然后是真实使用场景的拆解接着给一套能直接抄的键位探针和快捷键管理器的完整实现最后把那些让人怀疑人生的异常情况整理成速查表。不管你是刚学事件监听的新手还是已经写过几套快捷键系统的老手应该都能从里面捡到点东西。1. 先把概念捋直keyCode 到底属于哪一层1.1 一次按键要穿过四层每层都有自己的编号很多人对keyCode的困惑根源在于把它当成了键盘的固有属性。实际上从手指按下键帽到 JS 收到事件对象中间至少存在四层彼此独立的编码体系每一层都有自己的坐标系。第一层是硬件层。键盘内部是一张行列交叉的矩阵控制芯片扫描出第几行第几列被导通了再把它翻译成一个扫描码。这一层描述的是纯粹的物理位置跟键盘上印的是什么字符毫无关系。第二层是协议层。键盘通过接口上报数据时用的是一套标准化的人机接口设备用法编号可以理解为一种通用语言让不同厂商的键盘能被同一套驱动识别。这一层描述的仍然是物理按键的位置但编号被标准化了。第三层是系统层。操作系统拿到扫描码或者用法编号后会去查当前的键盘布局表把它翻译成一个虚拟键码。这一层开始引入语义同一个物理位置在这套字母排列布局下是字母在另一套布局下就是符号。虚拟键码是操作系统内部的概念普通应用接触不到原始值。第四层是运行时层。浏览器或应用框架把系统事件再包装一次塞进事件对象于是你才拿到keyCode、key、code这一堆属性。这一层的编码在早期规范里大量复用了 ASCII 和虚拟键码的数值所以你会看到字母键的keyCode恰好是 65 到 90。把这条链想清楚了很多疑惑自然就解开了为什么keyCode对字母键返回大写字母的码值不管你是不是按了 Shift为什么换个输入法这个数字会变成 229为什么同一个物理键在另一套布局的机器上keyCode不一样。因为它们本来就分属不同的层。记住一句话code说的是你按了键盘上的哪个位置key说的是这次按键产生了什么字符keyCode是这两者混在一起的历史遗留物大部分时候更接近前者偶尔会滑向后者。1.2 keyCode、key、code、which 四兄弟的对照与踩坑史这几个属性经常被混用我在代码评审里见过太多次把它们当同义词的情况。下面这张表是我自己整理的一张对照建议直接存下来。属性类型典型值描述的是受 Shift 影响受键盘布局影响状态keyCode数字65、13、37逻辑按键历史映射字母键不受影响部分符号键会变已标记遗留key字符串a、A、Enter本次按键产生的字符或语义名受影响受影响现行标准code字符串KeyA、Enter、ShiftLeft物理位置不受影响不受影响现行标准which数字同 keyCode 或 charCode早期兼容属性视情况视情况已废弃举一组具体的例子会更直观。按下主键盘区左边那个字母 A 键不按 Shiftkey是acode是KeyAkeyCode是 65按住 Shift 再按key变成Acode还是KeyAkeyCode还是 65。再看数字键区最上面那一排。按下主键盘区的数字 1 键code是Digit1key是1keyCode是 49而按下小键盘区的 1code是Numpad1keyCode同样是 97 而不是 49。这个差异在需要区分小键盘的场景里非常关键判断依据就是location属性或者直接用code的前缀。which更麻烦一点它在键盘事件里通常等于keyCode在字符事件里又等于charCode属于历史遗留的模糊地带。现代代码里完全可以不碰它。我个人的取舍很明确需要知道物理位置就用code需要知道用户实际打出了什么字符就用key两者都不满足、必须跟老系统对接时才去读keyCode。这个原则定下来之后快捷键相关的 bug 至少少了一半。2. 唯一性的底层原理从矩阵扫描到虚拟键码2.1 硬件层键盘矩阵、行列扫描与扫描码想理解每个键有一个编号得先看键盘是怎么知道哪个键被按下了的。最朴素的想法是一个键接一根线按下导通控制器读引脚电平。但一把 104 键的键盘如果这么做需要一百多根线排线粗得像小臂成本和可靠性都不现实。实际的方案是矩阵扫描。把按键排列成行列交叉的网格每个按键放在一根行线和一根列线的交叉点上行线和列线之间平时不导通按下键帽才接通。控制器逐列输出低电平同时读取所有行线的状态就能反推出是哪一行哪一列被短接了。一个 8 行 16 列的矩阵只要 24 根线就能覆盖 128 个位置线数从线性关系变成加法关系。这就是为什么键盘控制芯片能做得那么小。矩阵带来一个经典副作用鬼键。当三个键同时按下且它们在矩阵上恰好构成一个矩形的三个角时第四个角对应的行线和列线之间会形成一条经另外两个按键绕过去的回路控制器读出来就像第四个键也被按下了。传统的解决办法是在每个交叉点上串一个二极管只允许电流单向流动把回路切断。所谓N 键无冲说的就是这把键盘在硬件上把这个问题处理干净了能同时正确识别任意多个按键。这一层的输出就是扫描码。不同厂商、不同代际的键盘扫描码的具体取值可能不同但本质都是某个行列位置被触发了这样一个物理事实。键盘固件在这里还会做去抖处理因为机械触点在闭合瞬间会有几毫秒的抖动实测常见的去抖窗口在 5 毫秒到 15 毫秒之间设太短会重复触发设太长快速连击会丢键。2.2 系统层键盘布局表把扫描码翻译成虚拟键码扫描码描述的是位置可系统和应用需要的是这个键代表什么。中间这层翻译由键盘布局表完成。这一层的关键设计是位置和语义被彻底解耦。同一份硬件上报的位置序列在不同布局表里会翻译成完全不同的字符。主键盘区左上角那个位置在一套布局下产出字母在另一套布局下可能产出另一个字母在第三套布局下甚至可能是一个符号。操作系统切换输入法布局时改的就是这张表硬件一点没变。这解释了为什么每个键有唯一编号这个说法需要加个限定在给定的布局表内部每个位置有且只有一个虚拟键码这是保证正确性的基础但跨布局时同一个位置可能对应不同的虚拟键码同一个虚拟键码也可能来自不同的物理位置。唯一性是在一个坐标系内成立的换坐标系就不成立了。虚拟键码的取值各家有各家的设计思路大致分成两派一派按位置编码好处是物理位置和码值一一对应做游戏和快捷键特别顺手坏处是想知道用户打出了什么字符还得再查一次表另一派按语义编码直接把 ASCII 或 Unicode 的字符编码当成键码用好处是拿字符方便坏处是布局一换码值就跟着变。浏览器事件里的keyCode就是这两派的混血产物字母和数字区间老老实实复用了 ASCII标点符号区间又自己造了一套。2.3 运行时层事件对象是怎么拿到那个数字的系统把虚拟键码交给应用之后运行时会把它包装成事件对象。早期的事件规范在定义这部分时直接规定了字母键的keyCode应等于对应大写字母的 ASCII 值于是就有了 65 到 90 这一段。数字键沿用 48 到 57。回车是 13制表符是 9退格是 8空格是 32这些都是 ASCII 里的控制字符顺手就复用了。功能键和导航键没有 ASCII 对应值规范就自己编了一套方向键四个值依次是 37 到 40功能键从 112 排到 123Insert是 45Delete是 46Home是 36End是 35。修饰键给了 16、17、18 三个值分别对应 Shift、Control、Alt。下面这张表是我手头常用的一份对照覆盖了绝大多数日常会碰到的键。按键keyCodecodekey字母 A65KeyAa或A字母 Z90KeyZz或Z主键盘数字 048Digit00或)小键盘数字 096Numpad00回车13EnterEnter制表9TabTab空格32Space 退格8BackspaceBackspace左上角 Esc27EscapeEscape左方向键37ArrowLeftArrowLeft左 Shift16ShiftLeftShift左 Control17ControlLeftControl左 Alt18AltLeftAltF1112F1F1看这张表就能明白一件事keyCode里没有任何哪个厂商的键盘的痕迹它是一套纯软件层面的约定。所以它在不同硬件之间能通用这是它当年能一统天下的原因。2.4 唯一其实是相对的哪些键会撞车标题里的唯一两个字如果严格抠是要打折扣的。我至少遇到过四类例外做快捷键功能时全都踩过。第一类是输入法组合态。当用户用中文输入法正在拼一个词的时候keydown事件的keyCode可能返回 229key返回Process。这时候你根本无从判断他按了哪个键因为系统把按键交给了输入法处理。正确做法是先检查isComposing为真就直接放行不要拦。这一条是所有中文场景快捷键功能的第一铁律。第二类是多媒体键和厂商自定义键。音量加减、播放暂停、计算器、邮件这些键很多情况下根本不产生标准的键盘事件或者产生的事件里keyCode是 0。指望用一套统一的数字表覆盖所有键盘的所有键是不现实的。第三类是同一物理位置在不同布局下码值不同。标点符号区尤其明显同一个位置在一套布局下是分号在另一套布局下可能是别的符号keyCode会跟着变。这也是为什么游戏和快捷键系统倾向于用code而不是keyCode。第四类是小键盘的数字区和主键盘的数字区。虽然keyCode分开了48 到 57 对 96 到 105但如果你只判断keyCode不判断location某些映射表里仍然会出现歧义尤其在老旧环境里。所以更准确的说法是在一套固定的映射约定下每个逻辑按键都有一个稳定的数字标识。这个稳定是相对稳定不是绝对不变。理解了这一点你才不会在某个下午突然发现某个键的keyCode变了的时候抓狂。3. 场景拆解这套编码到现在为什么还离不开3.1 快捷键引擎组合键判定为什么偏爱数字码做快捷键功能的时候我需要判断用户按下的这一组键是不是注册表里的某个组合。这件事听起来简单实现起来有几个隐藏的坑。第一个坑是修饰键的左右不区分。用户注册了CtrlS他心里想的是随便按哪个 Ctrl 都行。但事件里的code是ControlLeft或ControlRight是两个不同的字符串。如果用code做键就得在规范化阶段把左右归并成一个虚拟的名字。第二个坑是顺序不确定。用户按下 Ctrl 和 S 的时候物理上可能先按下 Ctrl 再按 S也可能两个几乎同时事件里修饰键只体现在布尔标志位上不体现在主键的码值里。所以组合键的表示必须是修饰键集合 主键这样的结构而不是一串按键序列。第三个坑是大小写和 Shift 的冲突。用户注册了CtrlS同时按住 Shift 再按key会变成S如果按key比较就会匹配失败。而keyCode对字母键不区分大小写天然就把这个问题绕过去了这也是它当年在快捷键场景里如此流行的实际原因。我的做法是用code做主键、用布尔标志位做修饰键、在规范化阶段统一排序并归并左右修饰键。这样既保留了物理位置的准确性又避免了大小写干扰。后面第 4 节会给出完整实现。3.2 游戏与实时输入低延迟路径上的原始码游戏对键盘输入的要求和普通网页完全是两个世界。普通网页可以容忍几十毫秒的事件延迟游戏不行玩家按下移动键到角色响应超过两三帧就会被感知为卡。在这种场景下原始码的价值就凸显出来了。游戏需要的是物理位置的稳定映射玩家把跳跃绑在空格上他换一套字母布局的键盘空格还是空格跳跃还得能用。如果用key做判断碰到布局切换就会出问题如果用keyCode大部分情况下能用但标点键会飘。还有一个隐性需求是多键同时按下的正确识别。格斗游戏里同时按三个键出招如果键盘矩阵有鬼键问题第三个键可能检测不到这时候玩家会觉得是游戏的问题。这就是为什么游戏玩家愿意为全键无冲的键盘多花钱。软件层面能做的是在事件处理里避免不必要的同步阻塞不要在按键回调里做重活。游戏场景的经验按键状态表用code做键按下和抬起分别置位和清零渲染循环里读这张表而不是在事件回调里直接驱动逻辑。这样能把输入采样和渲染解耦避免事件密集触发时掉帧。3.3 自动化测试与远程控制回放需要可序列化的按键自动化测试要做的事情是录制一串操作然后重放。录制下来的东西必须能序列化成文本或者 JSON存进文件下次读出来还能准确还原。数字码在这个场景里的优势非常明显一个整数几十个字节就能表示整个按键序列比对和索引都极快。字符串虽然可读性更好但存储和比较的开销更大。所以很多老的自动化脚本格式里按键记录就是一堆数字。不过这里有个陷阱录制环境和回放环境的键盘布局可能不一致。在一台机器上录的分号在另一台机器上回放可能变成别的符号。解决办法是在录制时同时记录物理位置和字符语义两份信息回放时优先用物理位置遇到不支持的键再退回语义。远程控制类的协议也是类似的思路。传输层更倾向于直接转发底层的位置码让接收端用自己的布局表去翻译。这样做的好处是链路两端不需要约定同一套字符编码代价是接收端必须有对应的布局信息否则翻译出来的字符会是错的。3.4 无障碍与自定义键位物理位置和字符语义必须分开这是一块很多人容易忽略但实际需求很刚性的领域。有些用户因为手部条件限制需要把常用的操作重新映射到少数几个容易按到的键上有些用户使用单键开关、头部指针、口含棒之类的替代输入设备这些设备上报的往往只是某个开关被触发了需要软件层做一层映射。这种场景下物理位置和字符语义必须彻底分开。用户把保存映射到他习惯按的那个键这个映射关系绑定的是位置不是字符。如果绑定字符用户一换布局就全乱了。这也是code属性存在的核心理由之一。自定义键盘固件领域更是把这套思想用到了极致。支持多层键位映射的固件本质就是维护一张物理位置到行为的查找表按一下层切换键整张表换一套内容同一个物理键在基础层是字母、在功能层是方向键。这种设计的底层前提就是硬件层上报的是位置而不是字符。3.5 表单与输入法什么时候必须绕开 keyCode反过来有些场景是坚决不能用keyCode的最典型的就是表单输入控制。假设你要做一个输入框只允许输入数字。用keyCode判断 48 到 57 看起来能拦住字母但用户用输入法输入中文、用粘贴输入内容、用语音输入、用拖拽文本这一套判断全都会漏。而且不同布局下数字键的keyCode也可能不同。正确的思路是不要试图在按键阶段阻止非法字符而是在输入完成后校验和过滤。监听input事件拿到的已经是最终值直接做正则清洗。如果确实需要在按键阶段拦截比如防止回车提交表单那也应该判断key而不是keyCode同时跳过isComposing为真的情况。再比如富文本编辑器里处理光标移动需要区分用户是按了方向键还是输入了字符这时候key是ArrowLeft这样明确的语义名比数字可读得多也更不容易出错。4. 动手做键位探针加快捷键管理器4.1 第一步写一个键位探针页面排查任何键盘相关的问题第一步永远是看清楚到底发生了什么。我手边常备一个探针页面二十几行代码任何环境打开就能用。!DOCTYPE html html langzh-CN head meta charsetutf-8 title键位探针/title style body { font: 14px/1.7 system-ui, sans-serif; padding: 24px; } table { border-collapse: collapse; width: 100%; } th, td { border: 1px solid #ddd; padding: 6px 10px; text-align: left; } tr.active { background: #eef6ff; transition: background .2s; } /style /head body p在页面任意位置按键按 Esc 清空记录。/p table thead tr thkey/ththcode/ththkeyCode/th thlocation/ththrepeat/ththisComposing/th /tr /thead tbody idlog/tbody /table script const log document.getElementById(log); const seen new Map(); window.addEventListener(keydown, (e) { if (e.code Escape !e.isComposing) { log.innerHTML ; seen.clear(); return; } const id ${e.code}|${e.location}; const row seen.get(id) || log.insertRow(); seen.set(id, row); row.innerHTML td${e.key}/td td${e.code}/td td${e.keyCode}/td td${e.location}/td td${e.repeat}/td td${e.isComposing}/td; row.className active; setTimeout(() { row.className ; }, 150); }); /script /body /html这个探针的关键设计点有三个。用code|location做去重键是因为同一个code在小键盘和主键盘上location不同能区分开。按 Esc 清空而不是按某个功能键是因为 Esc 在几乎所有环境里都能稳定触发且不会被输入法吃掉。高亮用setTimeout复位而不是用动画是因为按键是高频事件CSS 动画在密集触发时会排队看起来反而卡。实测下来这个页面能覆盖我 90% 的排查需求。剩下的 10% 需要看更底层的东西那就得上系统级的按键监测工具了。4.2 第二步用 code 做组合键注册与冲突检测探针看清楚了接下来搭一个能用的快捷键管理器。核心是三件事组合键字符串规范化、事件到组合键的转换、冲突检测。const MOD_ALIAS { ControlLeft: Control, ControlRight: Control, ShiftLeft: Shift, ShiftRight: Shift, AltLeft: Alt, AltRight: Alt, MetaLeft: Meta, MetaRight: Meta, }; const MOD_ORDER [Control, Alt, Shift, Meta]; const MOD_CODES new Set(Object.keys(MOD_ALIAS)); // 把 ctrls、ShiftKeyA 这类写法统一成 ControlShiftKeyA function normalize(combo) { const tokens combo.split().map(s s.trim()).filter(Boolean); const mods new Set(); const keys []; for (const token of tokens) { const upper token[0].toUpperCase() token.slice(1).toLowerCase(); const mod MOD_ALIAS[token] || MOD_ALIAS[${upper}Left]; if (mod) { mods.add(mod); continue; } keys.push(token.length 1 ? Key${token.toUpperCase()} : token); } keys.sort(); return [...MOD_ORDER.filter(m mods.has(m)), ...keys].join(); } function comboFromEvent(e) { const mods new Set(); if (e.ctrlKey) mods.add(Control); if (e.altKey) mods.add(Alt); if (e.shiftKey) mods.add(Shift); if (e.metaKey) mods.add(Meta); const keys []; if (!MOD_CODES.has(e.code) e.code) keys.push(e.code); return { id: [...MOD_ORDER.filter(m mods.has(m)), ...keys].join(), bare: keys.length 0, }; }规范化函数里有个细节值得说token.length 1的时候补Key前缀。原因是用户写配置时习惯写ctrls而不是ctrlKeyS但如果只写单字符又没法区分主键盘字母区和别的区域。统一补成KeyX是最省事的约定代价是数字键需要写成Digit1或者单独加一条映射规则。注册表用Map而不是普通对象是因为Map的键可以是任意字符串且不会有原型链污染问题注册表里被塞进一个__proto__这种键名的时候不会出事。const registry new Map(); function register(combo, handler, options {}) { const id normalize(combo); if (registry.has(id)) { console.warn(快捷键冲突已存在: ${id}); return false; } registry.set(id, { handler, ...options }); return true; } function handleKeydown(e) { if (e.isComposing || e.key Process) return; // 输入法态直接放行 const { id, bare } comboFromEvent(e); const entry registry.get(id); if (!entry) return; if (bare entry.requireMainKey ! false) return; // 纯修饰键不触发 e.preventDefault(); e.stopPropagation(); entry.handler(e); } window.addEventListener(keydown, handleKeydown);这段代码里有两条防线是针对中文环境的。第一道是isComposing和key Process的双重检查因为部分环境下这两个标志不一定同时出现双保险更稳。第二道是bare检查防止用户只按下 Ctrl 没按主键的时候误触发。4.3 第三步跨布局兼容与降级策略再好的方案也得考虑老环境。如果目标环境里code属性可能为空比如某些非常老的内嵌浏览器内核就得准备一条降级路径。const KEYCODE_TO_CODE new Map([ [65, KeyA], [66, KeyB], [67, KeyC], [13, Enter], [32, Space], [27, Escape], [37, ArrowLeft], [38, ArrowUp], [39, ArrowRight], [40, ArrowDown], ]); function safeCode(e) { if (e.code) return e.code; if (KEYCODE_TO_CODE.has(e.keyCode)) return KEYCODE_TO_CODE.get(e.keyCode); // 最后的兜底用 key 的语义名 return e.key || Unidentified; }这个映射表只覆盖高频键没有必要把一百多个键全列出来因为降级路径本身就是为了兜底覆盖率不需要 100%。真到了连code都没有的环境用户对功能完备度的预期本来也会降低。还有一条兼容性经验不要假设同一台机器上布局永远不变。用户可能在会话过程中切换键盘布局这时候同一个物理键的key会变code不变。如果你的逻辑依赖key就得监听布局变化事件或者干脆改用code。4.4 长按、重复与触发阈值的取值repeat属性标记的是这个事件是不是长按产生的重复事件。默认情况下按住一个键不放系统会以固定的初始延迟和后续间隔持续产生keydown不同系统的取值略有差异常见的初始延迟在 400 到 500 毫秒之间后续间隔在 30 到 50 毫秒之间。如果要做长按触发的功能比如按住空格开始录音、松开停止就必须自己管理状态不能依赖repeatconst HOLD_MS 420; // 长按判定阈值 const HOLD_REPEAT 0; // 长按期间允许的重复触发次数0 表示不重复 const holdTimers new Map(); function onKeyDown(e) { if (e.isComposing || e.repeat) return; const { id } comboFromEvent(e); const entry registry.get(id); if (!entry || entry.hold undefined) return; e.preventDefault(); const timer setTimeout(() { entry.hold(e); holdTimers.delete(id); }, HOLD_MS); holdTimers.set(id, { timer, entry }); } function onKeyUp(e) { const { id } comboFromEvent(e); const held holdTimers.get(id); if (!held) return; clearTimeout(held.timer); holdTimers.delete(id); // 没到长按阈值就松手走短按逻辑 if (held.entry.tap) held.entry.tap(e); } window.addEventListener(keydown, onKeyDown); window.addEventListener(keyup, onKeyUp);阈值设 420 毫秒是个经验值。设太短正常打字会被误判成长按设太长用户会觉得要按很久才响应。400 到 500 这个区间跟系统自身的重复触发延迟基本对齐手感上最自然。如果功能本身有明确的使用场景比如按住说话可以适当放宽到 600 毫秒因为用户心理上已经准备好要按久一点了。一个容易忽略的点长按功能必须在keyup里清理计时器而且要考虑按住期间窗口失焦的情况。用户按住键切走了窗口keyup可能永远不会到达计时器就一直挂着。稳妥做法是监听窗口失焦事件把holdTimers全部清空。5. 排坑实录那些让人怀疑人生的异常5.1 常见异常速查表下面这张表是我这些年攒下来的基本覆盖了 95% 的键盘事件异常。现象最常见原因排查动作处理方式keyCode恒为 229输入法正在组合打印isComposing和key组合态直接放行不拦截keyCode为 0多媒体键或特殊键检查key是否为Unidentified单独维护白名单或不处理快捷键在切换布局后失效判断依据用了key对比code和key的差异改用code做判断小键盘数字和主键盘混淆只看了keyCode打印location用code或location区分按住键重复触发没检查repeat打印repeat逻辑里过滤repeat为真的事件CtrlS 触发浏览器保存没调preventDefault看事件是否被消费匹配成功后立即阻止默认行为中文输入框里方向键失灵事件被快捷键系统吞掉检查isComposing组合态下不拦截任何键长按功能松手后还在跑keyup未到达记录keydown/keyup配对窗口失焦时清空所有计时器5.2 三个典型排查案例的还原案例一快捷键在部分同事机器上不生效。现象很奇怪同一个页面大部分人的机器上Ctrl;能触发少数人不行。一开始怀疑是浏览器版本差异试了几台发现版本一样。后来用探针页面一对比发现那几台机器的键盘布局配置不同分号那个位置的keyCode果然不一样。根因是判定逻辑用了keyCode加硬编码的数字。改法很简单把注册逻辑换成code版本问题消失。这件事让我彻底放弃了在快捷键里用keyCode。案例二输入框里打拼音光标乱跳。现象是用户用中文输入法打拼音的时候按下方向键想调整光标位置结果整个输入框失焦了。排查发现是快捷键系统监听在捕获阶段把所有方向键都拦下来了还调了preventDefault。修复方法是监听函数最开头加一句if (e.isComposing) return;让组合态下的事件畅通无阻。这一条后来被我写进了团队所有快捷键相关代码的模板里。案例三游戏角色按住前进键切窗口回来后角色一直往前走。原因是按住键的时候窗口失焦keyup事件没触发按键状态表里前进键一直是按下状态。修复方法是监听窗口失焦事件把整张按键状态表清零。这个思路后来被我推广到了所有需要维护按键按下状态的场景包括自定义的拖拽、连续滚动等等。5.3 几条我自己的经验规则写到最后分享几条这几年攒下来的、文档里不会写的东西。规则一永远区分判断按键和判断字符。需要知道物理位置用code需要知道用户输入了什么用key。不要在脑子里把这两件事混成一件事混了之后架构会越来越乱最后没法维护。规则二输入法状态是一等公民不是边缘情况。做面向中文用户的产品isComposing检查必须在第一行。我见过太多快捷键 bug 都是因为开发者自己在英文环境测试根本没意识到输入法组合态的存在。规则三不要在按键事件的回调里做重活。按键事件可能以每秒几十次的频率触发回调里做 DOM 查询、布局计算、网络请求必然掉帧。正确做法是回调里只更新状态真正的逻辑放到下一帧或者下一个渲染周期去跑。规则四keyCode可以读但不要新建依赖。维护老代码的时候读keyCode是必要的指望全面重构一遍不现实。但新写的代码里除非有明确的外部约定要求否则不要主动引入它。规范层面已经把它标记为遗留未来某一天某个环境把它移除了你也不会意外。规则五给自己的快捷键系统留一个关闭所有快捷键的开关。用户在用输入法、用屏幕阅读器、用辅助设备的时候全局快捷键可能造成严重干扰。给一个能一键关掉的入口成本很低体验提升很大。这个开关我一般做成两态通过键盘组合或者界面按钮切换都行关键是让用户有退路。
调一个快捷键功能按下去没反应加个日志一看e.keyCode打出来是 229。换一个键变成 0。再换一个明明按的是同一个物理位置切换输入法之后又变成了别的数字。这种事我第一次碰到的时候盯着控制台看了半小时一度怀疑是自己事件监听写错了。后来才想明白keyCode这个数字根本不是浏览器随手给的它背后有一条从键盘电路板一直通到 JS 事件对象的完整翻译链链条上任何一环动了这个数字就可能跟着变。keyCode是键盘事件对象上的一个数字属性历史上用来标识哪个键被按下了。它曾经是判断按键的唯一手段如今在规范里已经被标记为遗留属性但你在任何一家公司的前端代码、游戏引擎、自动化测试脚本、远程控制工具里都还能翻出它的身影。搞明白它为什么存在、为什么每个键会对应一个值、这套值在什么场景下仍然不可替代、又在什么场景下必须绕开是每个要去碰键盘交互的人绕不过去的一课。这篇文章就按这条链路往下挖先讲概念分层再讲从矩阵扫描到虚拟键码的底层原理然后是真实使用场景的拆解接着给一套能直接抄的键位探针和快捷键管理器的完整实现最后把那些让人怀疑人生的异常情况整理成速查表。不管你是刚学事件监听的新手还是已经写过几套快捷键系统的老手应该都能从里面捡到点东西。1. 先把概念捋直keyCode 到底属于哪一层1.1 一次按键要穿过四层每层都有自己的编号很多人对keyCode的困惑根源在于把它当成了键盘的固有属性。实际上从手指按下键帽到 JS 收到事件对象中间至少存在四层彼此独立的编码体系每一层都有自己的坐标系。第一层是硬件层。键盘内部是一张行列交叉的矩阵控制芯片扫描出第几行第几列被导通了再把它翻译成一个扫描码。这一层描述的是纯粹的物理位置跟键盘上印的是什么字符毫无关系。第二层是协议层。键盘通过接口上报数据时用的是一套标准化的人机接口设备用法编号可以理解为一种通用语言让不同厂商的键盘能被同一套驱动识别。这一层描述的仍然是物理按键的位置但编号被标准化了。第三层是系统层。操作系统拿到扫描码或者用法编号后会去查当前的键盘布局表把它翻译成一个虚拟键码。这一层开始引入语义同一个物理位置在这套字母排列布局下是字母在另一套布局下就是符号。虚拟键码是操作系统内部的概念普通应用接触不到原始值。第四层是运行时层。浏览器或应用框架把系统事件再包装一次塞进事件对象于是你才拿到keyCode、key、code这一堆属性。这一层的编码在早期规范里大量复用了 ASCII 和虚拟键码的数值所以你会看到字母键的keyCode恰好是 65 到 90。把这条链想清楚了很多疑惑自然就解开了为什么keyCode对字母键返回大写字母的码值不管你是不是按了 Shift为什么换个输入法这个数字会变成 229为什么同一个物理键在另一套布局的机器上keyCode不一样。因为它们本来就分属不同的层。记住一句话code说的是你按了键盘上的哪个位置key说的是这次按键产生了什么字符keyCode是这两者混在一起的历史遗留物大部分时候更接近前者偶尔会滑向后者。1.2 keyCode、key、code、which 四兄弟的对照与踩坑史这几个属性经常被混用我在代码评审里见过太多次把它们当同义词的情况。下面这张表是我自己整理的一张对照建议直接存下来。属性类型典型值描述的是受 Shift 影响受键盘布局影响状态keyCode数字65、13、37逻辑按键历史映射字母键不受影响部分符号键会变已标记遗留key字符串a、A、Enter本次按键产生的字符或语义名受影响受影响现行标准code字符串KeyA、Enter、ShiftLeft物理位置不受影响不受影响现行标准which数字同 keyCode 或 charCode早期兼容属性视情况视情况已废弃举一组具体的例子会更直观。按下主键盘区左边那个字母 A 键不按 Shiftkey是acode是KeyAkeyCode是 65按住 Shift 再按key变成Acode还是KeyAkeyCode还是 65。再看数字键区最上面那一排。按下主键盘区的数字 1 键code是Digit1key是1keyCode是 49而按下小键盘区的 1code是Numpad1keyCode同样是 97 而不是 49。这个差异在需要区分小键盘的场景里非常关键判断依据就是location属性或者直接用code的前缀。which更麻烦一点它在键盘事件里通常等于keyCode在字符事件里又等于charCode属于历史遗留的模糊地带。现代代码里完全可以不碰它。我个人的取舍很明确需要知道物理位置就用code需要知道用户实际打出了什么字符就用key两者都不满足、必须跟老系统对接时才去读keyCode。这个原则定下来之后快捷键相关的 bug 至少少了一半。2. 唯一性的底层原理从矩阵扫描到虚拟键码2.1 硬件层键盘矩阵、行列扫描与扫描码想理解每个键有一个编号得先看键盘是怎么知道哪个键被按下了的。最朴素的想法是一个键接一根线按下导通控制器读引脚电平。但一把 104 键的键盘如果这么做需要一百多根线排线粗得像小臂成本和可靠性都不现实。实际的方案是矩阵扫描。把按键排列成行列交叉的网格每个按键放在一根行线和一根列线的交叉点上行线和列线之间平时不导通按下键帽才接通。控制器逐列输出低电平同时读取所有行线的状态就能反推出是哪一行哪一列被短接了。一个 8 行 16 列的矩阵只要 24 根线就能覆盖 128 个位置线数从线性关系变成加法关系。这就是为什么键盘控制芯片能做得那么小。矩阵带来一个经典副作用鬼键。当三个键同时按下且它们在矩阵上恰好构成一个矩形的三个角时第四个角对应的行线和列线之间会形成一条经另外两个按键绕过去的回路控制器读出来就像第四个键也被按下了。传统的解决办法是在每个交叉点上串一个二极管只允许电流单向流动把回路切断。所谓N 键无冲说的就是这把键盘在硬件上把这个问题处理干净了能同时正确识别任意多个按键。这一层的输出就是扫描码。不同厂商、不同代际的键盘扫描码的具体取值可能不同但本质都是某个行列位置被触发了这样一个物理事实。键盘固件在这里还会做去抖处理因为机械触点在闭合瞬间会有几毫秒的抖动实测常见的去抖窗口在 5 毫秒到 15 毫秒之间设太短会重复触发设太长快速连击会丢键。2.2 系统层键盘布局表把扫描码翻译成虚拟键码扫描码描述的是位置可系统和应用需要的是这个键代表什么。中间这层翻译由键盘布局表完成。这一层的关键设计是位置和语义被彻底解耦。同一份硬件上报的位置序列在不同布局表里会翻译成完全不同的字符。主键盘区左上角那个位置在一套布局下产出字母在另一套布局下可能产出另一个字母在第三套布局下甚至可能是一个符号。操作系统切换输入法布局时改的就是这张表硬件一点没变。这解释了为什么每个键有唯一编号这个说法需要加个限定在给定的布局表内部每个位置有且只有一个虚拟键码这是保证正确性的基础但跨布局时同一个位置可能对应不同的虚拟键码同一个虚拟键码也可能来自不同的物理位置。唯一性是在一个坐标系内成立的换坐标系就不成立了。虚拟键码的取值各家有各家的设计思路大致分成两派一派按位置编码好处是物理位置和码值一一对应做游戏和快捷键特别顺手坏处是想知道用户打出了什么字符还得再查一次表另一派按语义编码直接把 ASCII 或 Unicode 的字符编码当成键码用好处是拿字符方便坏处是布局一换码值就跟着变。浏览器事件里的keyCode就是这两派的混血产物字母和数字区间老老实实复用了 ASCII标点符号区间又自己造了一套。2.3 运行时层事件对象是怎么拿到那个数字的系统把虚拟键码交给应用之后运行时会把它包装成事件对象。早期的事件规范在定义这部分时直接规定了字母键的keyCode应等于对应大写字母的 ASCII 值于是就有了 65 到 90 这一段。数字键沿用 48 到 57。回车是 13制表符是 9退格是 8空格是 32这些都是 ASCII 里的控制字符顺手就复用了。功能键和导航键没有 ASCII 对应值规范就自己编了一套方向键四个值依次是 37 到 40功能键从 112 排到 123Insert是 45Delete是 46Home是 36End是 35。修饰键给了 16、17、18 三个值分别对应 Shift、Control、Alt。下面这张表是我手头常用的一份对照覆盖了绝大多数日常会碰到的键。按键keyCodecodekey字母 A65KeyAa或A字母 Z90KeyZz或Z主键盘数字 048Digit00或)小键盘数字 096Numpad00回车13EnterEnter制表9TabTab空格32Space 退格8BackspaceBackspace左上角 Esc27EscapeEscape左方向键37ArrowLeftArrowLeft左 Shift16ShiftLeftShift左 Control17ControlLeftControl左 Alt18AltLeftAltF1112F1F1看这张表就能明白一件事keyCode里没有任何哪个厂商的键盘的痕迹它是一套纯软件层面的约定。所以它在不同硬件之间能通用这是它当年能一统天下的原因。2.4 唯一其实是相对的哪些键会撞车标题里的唯一两个字如果严格抠是要打折扣的。我至少遇到过四类例外做快捷键功能时全都踩过。第一类是输入法组合态。当用户用中文输入法正在拼一个词的时候keydown事件的keyCode可能返回 229key返回Process。这时候你根本无从判断他按了哪个键因为系统把按键交给了输入法处理。正确做法是先检查isComposing为真就直接放行不要拦。这一条是所有中文场景快捷键功能的第一铁律。第二类是多媒体键和厂商自定义键。音量加减、播放暂停、计算器、邮件这些键很多情况下根本不产生标准的键盘事件或者产生的事件里keyCode是 0。指望用一套统一的数字表覆盖所有键盘的所有键是不现实的。第三类是同一物理位置在不同布局下码值不同。标点符号区尤其明显同一个位置在一套布局下是分号在另一套布局下可能是别的符号keyCode会跟着变。这也是为什么游戏和快捷键系统倾向于用code而不是keyCode。第四类是小键盘的数字区和主键盘的数字区。虽然keyCode分开了48 到 57 对 96 到 105但如果你只判断keyCode不判断location某些映射表里仍然会出现歧义尤其在老旧环境里。所以更准确的说法是在一套固定的映射约定下每个逻辑按键都有一个稳定的数字标识。这个稳定是相对稳定不是绝对不变。理解了这一点你才不会在某个下午突然发现某个键的keyCode变了的时候抓狂。3. 场景拆解这套编码到现在为什么还离不开3.1 快捷键引擎组合键判定为什么偏爱数字码做快捷键功能的时候我需要判断用户按下的这一组键是不是注册表里的某个组合。这件事听起来简单实现起来有几个隐藏的坑。第一个坑是修饰键的左右不区分。用户注册了CtrlS他心里想的是随便按哪个 Ctrl 都行。但事件里的code是ControlLeft或ControlRight是两个不同的字符串。如果用code做键就得在规范化阶段把左右归并成一个虚拟的名字。第二个坑是顺序不确定。用户按下 Ctrl 和 S 的时候物理上可能先按下 Ctrl 再按 S也可能两个几乎同时事件里修饰键只体现在布尔标志位上不体现在主键的码值里。所以组合键的表示必须是修饰键集合 主键这样的结构而不是一串按键序列。第三个坑是大小写和 Shift 的冲突。用户注册了CtrlS同时按住 Shift 再按key会变成S如果按key比较就会匹配失败。而keyCode对字母键不区分大小写天然就把这个问题绕过去了这也是它当年在快捷键场景里如此流行的实际原因。我的做法是用code做主键、用布尔标志位做修饰键、在规范化阶段统一排序并归并左右修饰键。这样既保留了物理位置的准确性又避免了大小写干扰。后面第 4 节会给出完整实现。3.2 游戏与实时输入低延迟路径上的原始码游戏对键盘输入的要求和普通网页完全是两个世界。普通网页可以容忍几十毫秒的事件延迟游戏不行玩家按下移动键到角色响应超过两三帧就会被感知为卡。在这种场景下原始码的价值就凸显出来了。游戏需要的是物理位置的稳定映射玩家把跳跃绑在空格上他换一套字母布局的键盘空格还是空格跳跃还得能用。如果用key做判断碰到布局切换就会出问题如果用keyCode大部分情况下能用但标点键会飘。还有一个隐性需求是多键同时按下的正确识别。格斗游戏里同时按三个键出招如果键盘矩阵有鬼键问题第三个键可能检测不到这时候玩家会觉得是游戏的问题。这就是为什么游戏玩家愿意为全键无冲的键盘多花钱。软件层面能做的是在事件处理里避免不必要的同步阻塞不要在按键回调里做重活。游戏场景的经验按键状态表用code做键按下和抬起分别置位和清零渲染循环里读这张表而不是在事件回调里直接驱动逻辑。这样能把输入采样和渲染解耦避免事件密集触发时掉帧。3.3 自动化测试与远程控制回放需要可序列化的按键自动化测试要做的事情是录制一串操作然后重放。录制下来的东西必须能序列化成文本或者 JSON存进文件下次读出来还能准确还原。数字码在这个场景里的优势非常明显一个整数几十个字节就能表示整个按键序列比对和索引都极快。字符串虽然可读性更好但存储和比较的开销更大。所以很多老的自动化脚本格式里按键记录就是一堆数字。不过这里有个陷阱录制环境和回放环境的键盘布局可能不一致。在一台机器上录的分号在另一台机器上回放可能变成别的符号。解决办法是在录制时同时记录物理位置和字符语义两份信息回放时优先用物理位置遇到不支持的键再退回语义。远程控制类的协议也是类似的思路。传输层更倾向于直接转发底层的位置码让接收端用自己的布局表去翻译。这样做的好处是链路两端不需要约定同一套字符编码代价是接收端必须有对应的布局信息否则翻译出来的字符会是错的。3.4 无障碍与自定义键位物理位置和字符语义必须分开这是一块很多人容易忽略但实际需求很刚性的领域。有些用户因为手部条件限制需要把常用的操作重新映射到少数几个容易按到的键上有些用户使用单键开关、头部指针、口含棒之类的替代输入设备这些设备上报的往往只是某个开关被触发了需要软件层做一层映射。这种场景下物理位置和字符语义必须彻底分开。用户把保存映射到他习惯按的那个键这个映射关系绑定的是位置不是字符。如果绑定字符用户一换布局就全乱了。这也是code属性存在的核心理由之一。自定义键盘固件领域更是把这套思想用到了极致。支持多层键位映射的固件本质就是维护一张物理位置到行为的查找表按一下层切换键整张表换一套内容同一个物理键在基础层是字母、在功能层是方向键。这种设计的底层前提就是硬件层上报的是位置而不是字符。3.5 表单与输入法什么时候必须绕开 keyCode反过来有些场景是坚决不能用keyCode的最典型的就是表单输入控制。假设你要做一个输入框只允许输入数字。用keyCode判断 48 到 57 看起来能拦住字母但用户用输入法输入中文、用粘贴输入内容、用语音输入、用拖拽文本这一套判断全都会漏。而且不同布局下数字键的keyCode也可能不同。正确的思路是不要试图在按键阶段阻止非法字符而是在输入完成后校验和过滤。监听input事件拿到的已经是最终值直接做正则清洗。如果确实需要在按键阶段拦截比如防止回车提交表单那也应该判断key而不是keyCode同时跳过isComposing为真的情况。再比如富文本编辑器里处理光标移动需要区分用户是按了方向键还是输入了字符这时候key是ArrowLeft这样明确的语义名比数字可读得多也更不容易出错。4. 动手做键位探针加快捷键管理器4.1 第一步写一个键位探针页面排查任何键盘相关的问题第一步永远是看清楚到底发生了什么。我手边常备一个探针页面二十几行代码任何环境打开就能用。!DOCTYPE html html langzh-CN head meta charsetutf-8 title键位探针/title style body { font: 14px/1.7 system-ui, sans-serif; padding: 24px; } table { border-collapse: collapse; width: 100%; } th, td { border: 1px solid #ddd; padding: 6px 10px; text-align: left; } tr.active { background: #eef6ff; transition: background .2s; } /style /head body p在页面任意位置按键按 Esc 清空记录。/p table thead tr thkey/ththcode/ththkeyCode/th thlocation/ththrepeat/ththisComposing/th /tr /thead tbody idlog/tbody /table script const log document.getElementById(log); const seen new Map(); window.addEventListener(keydown, (e) { if (e.code Escape !e.isComposing) { log.innerHTML ; seen.clear(); return; } const id ${e.code}|${e.location}; const row seen.get(id) || log.insertRow(); seen.set(id, row); row.innerHTML td${e.key}/td td${e.code}/td td${e.keyCode}/td td${e.location}/td td${e.repeat}/td td${e.isComposing}/td; row.className active; setTimeout(() { row.className ; }, 150); }); /script /body /html这个探针的关键设计点有三个。用code|location做去重键是因为同一个code在小键盘和主键盘上location不同能区分开。按 Esc 清空而不是按某个功能键是因为 Esc 在几乎所有环境里都能稳定触发且不会被输入法吃掉。高亮用setTimeout复位而不是用动画是因为按键是高频事件CSS 动画在密集触发时会排队看起来反而卡。实测下来这个页面能覆盖我 90% 的排查需求。剩下的 10% 需要看更底层的东西那就得上系统级的按键监测工具了。4.2 第二步用 code 做组合键注册与冲突检测探针看清楚了接下来搭一个能用的快捷键管理器。核心是三件事组合键字符串规范化、事件到组合键的转换、冲突检测。const MOD_ALIAS { ControlLeft: Control, ControlRight: Control, ShiftLeft: Shift, ShiftRight: Shift, AltLeft: Alt, AltRight: Alt, MetaLeft: Meta, MetaRight: Meta, }; const MOD_ORDER [Control, Alt, Shift, Meta]; const MOD_CODES new Set(Object.keys(MOD_ALIAS)); // 把 ctrls、ShiftKeyA 这类写法统一成 ControlShiftKeyA function normalize(combo) { const tokens combo.split().map(s s.trim()).filter(Boolean); const mods new Set(); const keys []; for (const token of tokens) { const upper token[0].toUpperCase() token.slice(1).toLowerCase(); const mod MOD_ALIAS[token] || MOD_ALIAS[${upper}Left]; if (mod) { mods.add(mod); continue; } keys.push(token.length 1 ? Key${token.toUpperCase()} : token); } keys.sort(); return [...MOD_ORDER.filter(m mods.has(m)), ...keys].join(); } function comboFromEvent(e) { const mods new Set(); if (e.ctrlKey) mods.add(Control); if (e.altKey) mods.add(Alt); if (e.shiftKey) mods.add(Shift); if (e.metaKey) mods.add(Meta); const keys []; if (!MOD_CODES.has(e.code) e.code) keys.push(e.code); return { id: [...MOD_ORDER.filter(m mods.has(m)), ...keys].join(), bare: keys.length 0, }; }规范化函数里有个细节值得说token.length 1的时候补Key前缀。原因是用户写配置时习惯写ctrls而不是ctrlKeyS但如果只写单字符又没法区分主键盘字母区和别的区域。统一补成KeyX是最省事的约定代价是数字键需要写成Digit1或者单独加一条映射规则。注册表用Map而不是普通对象是因为Map的键可以是任意字符串且不会有原型链污染问题注册表里被塞进一个__proto__这种键名的时候不会出事。const registry new Map(); function register(combo, handler, options {}) { const id normalize(combo); if (registry.has(id)) { console.warn(快捷键冲突已存在: ${id}); return false; } registry.set(id, { handler, ...options }); return true; } function handleKeydown(e) { if (e.isComposing || e.key Process) return; // 输入法态直接放行 const { id, bare } comboFromEvent(e); const entry registry.get(id); if (!entry) return; if (bare entry.requireMainKey ! false) return; // 纯修饰键不触发 e.preventDefault(); e.stopPropagation(); entry.handler(e); } window.addEventListener(keydown, handleKeydown);这段代码里有两条防线是针对中文环境的。第一道是isComposing和key Process的双重检查因为部分环境下这两个标志不一定同时出现双保险更稳。第二道是bare检查防止用户只按下 Ctrl 没按主键的时候误触发。4.3 第三步跨布局兼容与降级策略再好的方案也得考虑老环境。如果目标环境里code属性可能为空比如某些非常老的内嵌浏览器内核就得准备一条降级路径。const KEYCODE_TO_CODE new Map([ [65, KeyA], [66, KeyB], [67, KeyC], [13, Enter], [32, Space], [27, Escape], [37, ArrowLeft], [38, ArrowUp], [39, ArrowRight], [40, ArrowDown], ]); function safeCode(e) { if (e.code) return e.code; if (KEYCODE_TO_CODE.has(e.keyCode)) return KEYCODE_TO_CODE.get(e.keyCode); // 最后的兜底用 key 的语义名 return e.key || Unidentified; }这个映射表只覆盖高频键没有必要把一百多个键全列出来因为降级路径本身就是为了兜底覆盖率不需要 100%。真到了连code都没有的环境用户对功能完备度的预期本来也会降低。还有一条兼容性经验不要假设同一台机器上布局永远不变。用户可能在会话过程中切换键盘布局这时候同一个物理键的key会变code不变。如果你的逻辑依赖key就得监听布局变化事件或者干脆改用code。4.4 长按、重复与触发阈值的取值repeat属性标记的是这个事件是不是长按产生的重复事件。默认情况下按住一个键不放系统会以固定的初始延迟和后续间隔持续产生keydown不同系统的取值略有差异常见的初始延迟在 400 到 500 毫秒之间后续间隔在 30 到 50 毫秒之间。如果要做长按触发的功能比如按住空格开始录音、松开停止就必须自己管理状态不能依赖repeatconst HOLD_MS 420; // 长按判定阈值 const HOLD_REPEAT 0; // 长按期间允许的重复触发次数0 表示不重复 const holdTimers new Map(); function onKeyDown(e) { if (e.isComposing || e.repeat) return; const { id } comboFromEvent(e); const entry registry.get(id); if (!entry || entry.hold undefined) return; e.preventDefault(); const timer setTimeout(() { entry.hold(e); holdTimers.delete(id); }, HOLD_MS); holdTimers.set(id, { timer, entry }); } function onKeyUp(e) { const { id } comboFromEvent(e); const held holdTimers.get(id); if (!held) return; clearTimeout(held.timer); holdTimers.delete(id); // 没到长按阈值就松手走短按逻辑 if (held.entry.tap) held.entry.tap(e); } window.addEventListener(keydown, onKeyDown); window.addEventListener(keyup, onKeyUp);阈值设 420 毫秒是个经验值。设太短正常打字会被误判成长按设太长用户会觉得要按很久才响应。400 到 500 这个区间跟系统自身的重复触发延迟基本对齐手感上最自然。如果功能本身有明确的使用场景比如按住说话可以适当放宽到 600 毫秒因为用户心理上已经准备好要按久一点了。一个容易忽略的点长按功能必须在keyup里清理计时器而且要考虑按住期间窗口失焦的情况。用户按住键切走了窗口keyup可能永远不会到达计时器就一直挂着。稳妥做法是监听窗口失焦事件把holdTimers全部清空。5. 排坑实录那些让人怀疑人生的异常5.1 常见异常速查表下面这张表是我这些年攒下来的基本覆盖了 95% 的键盘事件异常。现象最常见原因排查动作处理方式keyCode恒为 229输入法正在组合打印isComposing和key组合态直接放行不拦截keyCode为 0多媒体键或特殊键检查key是否为Unidentified单独维护白名单或不处理快捷键在切换布局后失效判断依据用了key对比code和key的差异改用code做判断小键盘数字和主键盘混淆只看了keyCode打印location用code或location区分按住键重复触发没检查repeat打印repeat逻辑里过滤repeat为真的事件CtrlS 触发浏览器保存没调preventDefault看事件是否被消费匹配成功后立即阻止默认行为中文输入框里方向键失灵事件被快捷键系统吞掉检查isComposing组合态下不拦截任何键长按功能松手后还在跑keyup未到达记录keydown/keyup配对窗口失焦时清空所有计时器5.2 三个典型排查案例的还原案例一快捷键在部分同事机器上不生效。现象很奇怪同一个页面大部分人的机器上Ctrl;能触发少数人不行。一开始怀疑是浏览器版本差异试了几台发现版本一样。后来用探针页面一对比发现那几台机器的键盘布局配置不同分号那个位置的keyCode果然不一样。根因是判定逻辑用了keyCode加硬编码的数字。改法很简单把注册逻辑换成code版本问题消失。这件事让我彻底放弃了在快捷键里用keyCode。案例二输入框里打拼音光标乱跳。现象是用户用中文输入法打拼音的时候按下方向键想调整光标位置结果整个输入框失焦了。排查发现是快捷键系统监听在捕获阶段把所有方向键都拦下来了还调了preventDefault。修复方法是监听函数最开头加一句if (e.isComposing) return;让组合态下的事件畅通无阻。这一条后来被我写进了团队所有快捷键相关代码的模板里。案例三游戏角色按住前进键切窗口回来后角色一直往前走。原因是按住键的时候窗口失焦keyup事件没触发按键状态表里前进键一直是按下状态。修复方法是监听窗口失焦事件把整张按键状态表清零。这个思路后来被我推广到了所有需要维护按键按下状态的场景包括自定义的拖拽、连续滚动等等。5.3 几条我自己的经验规则写到最后分享几条这几年攒下来的、文档里不会写的东西。规则一永远区分判断按键和判断字符。需要知道物理位置用code需要知道用户输入了什么用key。不要在脑子里把这两件事混成一件事混了之后架构会越来越乱最后没法维护。规则二输入法状态是一等公民不是边缘情况。做面向中文用户的产品isComposing检查必须在第一行。我见过太多快捷键 bug 都是因为开发者自己在英文环境测试根本没意识到输入法组合态的存在。规则三不要在按键事件的回调里做重活。按键事件可能以每秒几十次的频率触发回调里做 DOM 查询、布局计算、网络请求必然掉帧。正确做法是回调里只更新状态真正的逻辑放到下一帧或者下一个渲染周期去跑。规则四keyCode可以读但不要新建依赖。维护老代码的时候读keyCode是必要的指望全面重构一遍不现实。但新写的代码里除非有明确的外部约定要求否则不要主动引入它。规范层面已经把它标记为遗留未来某一天某个环境把它移除了你也不会意外。规则五给自己的快捷键系统留一个关闭所有快捷键的开关。用户在用输入法、用屏幕阅读器、用辅助设备的时候全局快捷键可能造成严重干扰。给一个能一键关掉的入口成本很低体验提升很大。这个开关我一般做成两态通过键盘组合或者界面按钮切换都行关键是让用户有退路。
