useKeyModifier

跟踪按键是否被按下

useKeyModifier 使用 KeyboardEvent.getModifierState() 来响应式地跟踪特定修饰键（Shift、Control、Alt、CapsLock、Meta 等）是否正在被按下。它返回一个在 keydown、keyup、mousedown 和 mouseup 事件上更新的布尔值。你可以自定义触发更新的事件和设置初始值。

使用场景

  • 构建键盘快捷键指示器，当修饰键被按住时进行视觉高亮
  • 根据活动的修饰键显示不同的工具提示或光标样式
  • 实现修饰键感知的交互（例如 Ctrl+点击进行多选）

注意事项

  • SSR 安全：在服务端渲染期间返回 initial 值（默认 false）。服务端不会附加事件监听器。
  • 支持的修饰键：支持 Alt、AltGraph、CapsLock、Control、Fn、FnLock、Meta、NumLock、ScrollLock、Shift、Symbol 和 SymbolLock。并非所有修饰键在所有浏览器中都可用——参见 MDN 兼容性。
  • 事件自定义：默认事件（mousedown、mouseup、keydown、keyup）可通过 events 选项覆盖。

Usage

Live Editor

function Demo() {
  const Button = (props: { mode: boolean; name: string }) => {
    const { mode, name } = props;
    return (
      <button style={mode ? { background: "var(--c-input-border-focus)" } : {}}>
        {name}
      </button>
    );
  };

  const capsLock = useKeyModifier("CapsLock");
  const numLock = useKeyModifier("NumLock");
  const scrollLock = useKeyModifier("ScrollLock");
  const shift = useKeyModifier("Shift");
  const control = useKeyModifier("Control");
  const alt = useKeyModifier("Alt");

  return (
    <div>
      <div style={{ marginBottom: 10 }}>
        <Button mode={capsLock} name="CapsLock" />
        <Button mode={numLock} name="NumLock" />
        <Button mode={scrollLock} name="ScrollLock" />
      </div>
      <div>
        <Button mode={shift} name="Shift" />
        <Button mode={control} name="Control" />
        <Button mode={alt} name="Alt" />
      </div>
    </div>
  );
};
Result

API

useKeyModifier

Returns

boolean: 按键是否被按下

Arguments

参数名描述类型默认值
modifier键位KeyModifier (必填)-
options可选参数UseModifierOptions | undefined-

UseModifierOptions

参数名描述类型默认值
events更新按键状态的事件(keyof WindowEventMap)[]['mousedown', 'mouseup', 'keydown', 'keyup']
initial初始值booleanfalse

KeyModifier

export type KeyModifier = 'Alt' | 'AltGraph' | 'CapsLock' | 'Control' | 'Fn' | 'FnLock' | 'Meta' | 'NumLock' | 'ScrollLock' | 'Shift' | 'Symbol' | 'SymbolLock';