React Hotkeys Hook 键盘布局处理指南

理解键盘布局对热键的影响

在现代前端开发中，键盘快捷键(热键)是提升用户体验的重要手段。然而，开发者在实现热键功能时常常忽视一个关键因素：键盘布局差异。不同国家和地区的键盘布局会导致相同的物理按键产生不同的字符输出。

两种热键监听策略

1. 按键码监听（布局无关）

这是 react-hotkeys-hook 的默认行为，它监听的是物理按键的代码而非实际产生的字符。

function ExampleComponent() {
  const [count, setCount] = useState(0)
  useHotkeys('shift+1', () => setCount(prevCount => prevCount + 1))

  return (
    <span>按下了 'shift+1' 组合键 {count} 次</span>
  )
}

特点：

• 不受键盘布局影响
• 需要明确告知用户按下的物理按键组合
• 适用于需要统一物理按键行为的场景

2. 字符监听（布局相关）

当我们需要监听特定字符而非物理按键时，可以使用 useKey 选项。

function ExampleComponent() {
  const [count, setCount] = useState(0)
  useHotkeys('!', () => setCount(prevCount => prevCount + 1), { useKey: true })

  return (
    <span>按下了 '!' 键 {count} 次</span>
  )
}

特点：

• 监听实际产生的字符
• 不同布局下触发方式可能不同
• 适用于需要特定字符触发的场景

实际应用建议

1. 国际化应用：如果应用面向全球用户，推荐使用按键码监听方式，确保所有用户的操作体验一致。

2. 本地化应用：如果应用仅针对特定语言区域，可以考虑使用字符监听方式，提供更自然的用户体验。

3. 用户提示：无论采用哪种方式，都应该在UI中清晰标注用户需要按下的键位，避免混淆。

4. 组合键处理：对于组合键操作，按键码监听通常更可靠，因为字符监听可能因输入法状态而产生意外行为。

高级技巧

对于需要同时支持多种键盘布局的复杂应用，可以结合两种方式：

useHotkeys('!,shift+1', callback, { useKey: true })

这样无论用户使用何种布局，只要按下产生"!"的物理组合键或实际输入"!"字符都能触发回调。

通过合理选择热键监听策略，可以确保应用在不同键盘布局下都能提供一致且友好的快捷键体验。