aria-keyshortcuts仅声明快捷键语义,不触发行为;必须作用于可聚焦交互元素,配合keydown监听与视觉提示(如)才能实现完整功能。

aria-keyshortcuts只声明语义,不触发任何行为
写了 aria-keyshortcuts="Ctrl+S",按下 Ctrl+S 却没反应?这不是 bug,是设计如此。aria-keyshortcuts 仅用于向屏幕阅读器“播报”该元素支持的快捷键组合,它本身不监听、不拦截、不执行。你必须额外写 keydown 监听逻辑,否则键盘用户按了也白按。
常见错误包括:
- 只加属性不写 JS,导致视障用户听到“按 Ctrl+S 保存”,但实际一按就触发浏览器默认保存页面
- 监听全局
keydown却没做e.target判断,结果在输入框里按 Ctrl+S 也触发了保存(应禁用) - 用了
e.preventDefault()却忘了手动调用保存函数,页面静默无响应
必须作用在可聚焦的交互元素上
aria-keyshortcuts 对 <div>、<code><span></span> 或纯文本节点无效——即使加了,屏幕阅读器会读出来,但用户 Tab 不到、空格/回车点不了、键盘根本激活不了它。
可用元素包括:
-
<button></button>、<input>、<textarea></textarea>(原生可聚焦) - 带
role="button"或role="menuitem"的元素,且必须显式加tabindex="0" - 自定义组件需确保能被 Tab 导航到,并有明确激活逻辑(如监听
keydown+click)
错误写法:<div aria-keyshortcuts="Ctrl+S">保存</div> —— 语义脱节,功能断裂。
键名必须严格符合 W3C Key Names 规范
大小写、连接符、拼写全错不得:辅助技术解析时直接忽略整个属性,等于没写。
正确示例:
-
aria-keyshortcuts="Ctrl+S"(首字母大写,+ 连接) -
aria-keyshortcuts="Escape"(不是Esc,也不是esc) -
aria-keyshortcuts="Meta+Shift+T"(Mac 上用Meta,不用Cmd)
错误示例:
-
aria-keyshortcuts="ctrl+s"(小写) -
aria-keyshortcuts="Ctrl S"(空格代替 +) -
aria-keyshortcuts="Cmd+S"(Cmd是非标准别名,部分读屏器不识别)
视觉提示必须同步提供,否则快捷键不可发现
仅靠 aria-keyshortcuts, sighted 键盘用户完全不知道快捷键存在。屏幕阅读器用户下次换设备或换浏览器也可能找不到它。
可靠做法:
- 在按钮文本中嵌入
<kbd>Ctrl+S</kbd>,例如:<button>保存<kbd>Ctrl+S</kbd></button> - 确保
<kbd></kbd>内容包含在无障碍名称中(不要只靠title,因鼠标悬停才显示,键盘用户看不到) - 若需区分平台,可补充说明,如「保存
<kbd>Ctrl+S</kbd>(macOS 上为 <code><kbd>Meta+S</kbd>)」</code>
最常被忽略的一点:快捷键的可访问性 = 声明(aria-keyshortcuts) + 行为(<code>keydown 监听) + 可见性(视觉提示),三者缺一不可。漏掉任意一环,对某类用户就是不可用。











