JS键盘事件中keyCode废弃后用什么替代

在现代Web标准中，KeyboardEvent.keyCode（以及伴随的 which 和 charCode）已被W3C规范标记为废弃（Deprecated）。它的标准替代方案是两个语义明确且各司其职的属性：event.key 和 event.code。如果需要获取按键产生的实际字符或业务功能（如按下回车提交、按下Esc关闭弹窗），使用 event.key；如果需要识别键盘上的物理键位（如游戏中控制走位的WASD、按键在物理布局中的相对坐标），使用 event.code。

图1：JS键盘事件核心属性演进示意图（keyCode向key与code分流）

一、为什么 keyCode 会被规范全面废弃

在早期的JavaScript代码中，开发者普遍依靠 e.keyCode === 13 来监听回车键，或者用 e.keyCode === 27 监听Esc键。然而，随着全球化操作系统和不同键盘硬件的普及，keyCode 的设计缺陷越来越明显：

• 缺乏语义，代码充斥“魔数”（Magic Numbers）： 数字 13 代表回车，27 代表取消，38 代表上箭头。直接阅读代码时必须在脑海中做查表转换，可读性极差且容易出现疏漏。
• 跨平台和跨浏览器不一致： 某些标点符号、特殊功能键在Windows、macOS、Linux系统下，甚至在同一系统的不同浏览器引擎中，返回的 keyCode 并不完全相同。
• 无法正确应对多语言键盘布局： keyCode 是一个混合产物，它试图同时表达物理按键和输出字符。在德语（QWERTZ）、法语（AZERTY）或虚拟软键盘上，同一个数字键码可能映射出截然不同的输入字符，导致业务逻辑出现偏差。

二、现代标准的双核心：event.key 与 event.code 的本质区别

为了解决上述混乱，W3C在 UI Events 规范中将按键的概念明确解耦为两个独立维度：

1. event.key（逻辑值 / 打印字符）： 代表用户当前按键所产生的结果或执行的逻辑功能。它是一个字符串。如果输入字母，它会准确反映大小写（如 "a" 或 "A"）；如果是控制键，它具有官方标准命名的语义字符串（如 "Enter"、"Escape"、"ArrowDown"、"Tab"）。
2. event.code（物理键 / 硬件槽位）： 代表被按下的物理键在键盘上的具体物理位置，不受当前操作系统语言、输入法状态以及Shift/CapsLock键切换的影响。例如，键盘左侧Q键下方的W键，无论当前系统切到哪国语言，其 event.code 永远是 "KeyW"。

图2：event.key 与 event.code 在不同按键状态下的行为对比

三、选型指南：如何选择 event.key 或 event.code

在实际业务开发中，选择哪个属性替换 keyCode 取决于具体的交互意图：

• 必须选用 event.key 的场景：
  • 表单与操作控制： 按回车提交（"Enter"）、按Esc取消或关闭抽屉（"Escape"）、按Tab切焦（"Tab"）。
  • 常规快捷键： 如按字母或标点触发的快捷键（例如按 "?" 呼出帮助菜单）。
  • 方向导航： 在下拉菜单、轮播图或表格中通过方向键移动光标（"ArrowUp"、"ArrowDown"、"ArrowLeft"、"ArrowRight"）。
• 必须选用 event.code 的场景：
  • 网页游戏角色移动： 例如经典 WASD 操作或方向摇杆。即使玩家使用法语键盘（对应键位印着 ZQSD），event.code 依然能够精确定位到键盘的上下左右物理槽位。
  • 物理按键绑定： 如视频剪辑软件的物理按键走带、键盘钢琴模拟器、或区分左Shift（"ShiftLeft"）与右Shift（"ShiftRight"）的特定专业软件。

图3：替代方案选型决策树与边界判断

四、常见按键的迁移对照表与现代代码实现

在实际替换已有项目中的 keyCode 时，可以直接查阅下述现代属性对照表：

1. 表单回车提交与Esc关闭弹窗的标准实现

// 监听输入框回车提交，并兼容中文输入法
const searchInput = document.getElementById('search-input');

searchInput.addEventListener('keydown', (event) => {
  // 重要防护：处于拼音/注音输入法选词过程中，按下 Enter 仅用于确认英文字符上屏，不应触发表单提交
  if (event.isComposing) {
    return;
  }

  if (event.key === 'Enter') {
    event.preventDefault();
    handleSearchSubmit(searchInput.value);
  }
});

// 全局监听 Esc 键关闭弹窗
window.addEventListener('keydown', (event) => {
  if (event.key === 'Escape') {
    closeActiveModal();
  }
});

2. 组合键监听的规范写法

监听类似 Ctrl + S 或 Command + K 的全局组合键时，不要使用旧的按键数字判断，直接使用 event.key 配合修饰键布尔属性：

window.addEventListener('keydown', (event) => {
  // 跨平台匹配 Ctrl(Windows/Linux) 或 Command(macOS)
  const isModifier = event.ctrlKey || event.metaKey;

  // 统一转为小写对比，防止用户在开启 CapsLock 或按 Shift 时匹配失败
  if (isModifier && event.key.toLowerCase() === 's') {
    event.preventDefault(); // 阻止浏览器默认保存网页行为
    saveDocument();
  }
});

五、从旧代码平滑迁移的实操四步法

将现有大型项目或组件库中的 keyCode 彻底清除，推荐按照以下四个明确步骤展开：

图4：平滑迁移四步操作流程与关键校验项

1. 步骤一：全局扫描定位。 使用正则 \.(keyCode|which|charCode) 全局检索现有工程，整理出所有还在读取数字键码的位置。
2. 步骤二：明确业务语义。 查看每一个监听器是用于“表单提交、弹窗关闭、字符判断”还是用于“物理游戏控制”。95%以上的网页交互属于前者。
3. 步骤三：替换为现代字符串。 将原本的数字对比替换为 event.key === 'Enter'、event.key === 'Escape' 等清晰自解释的代码。
4. 步骤四：补齐输入法合成检查。 在文本输入相关的 keydown 逻辑首行加入 if (event.isComposing) return;，避免在用户敲汉字拼音回车时触发意外逻辑。

六、浏览器兼容性与防护总结

event.key 与 event.code 已经在所有现代浏览器（Chrome、Firefox、Safari、Edge 以及移动端浏览器）中得到了全面支持，兼容性覆盖率超过99%。在目前的主流前端开发环境中，无需任何polyfill即可直接使用标准属性。

图5：现代键盘事件属性对照、标准命名与防御编程清单

总结而言，彻底告别 keyCode 不仅是顺应浏览器标准规范的必然要求，更能直接提高代码的可读性、可维护性与国际化鲁棒性。在日后的前端编码中，遇到键盘事件监听时，应当坚决弃用数字键码，直接选用 event.key（语义与字符）或 event.code（物理按键），并配合 event.isComposing 保障多语言输入法下的稳定体验。