React 版 keymaster 快速开始
这里介绍如何在 React 项目中使用 @keekuun/keymaster-react 注册键盘快捷键，并给出基础示例。
安装
💡 版本提示：文档显示的是最新版本（v0.5.0）。如果你需要使用特定版本，请查看 版本管理文档 或 npm 上的所有版本。
安装最新版本
npm install @keekuun/keymaster-react
# 或者
pnpm add @keekuun/keymaster-react安装特定版本
如果你需要使用特定版本（例如 0.1.0），可以指定版本号：
npm install @keekuun/keymaster-react@0.1.0
# 或者
pnpm add @keekuun/keymaster-react@0.1.0⚠️ 注意：如果使用旧版本，文档中的某些 API 可能不可用。建议查看对应版本的 README（在 npm 包页面）或 版本管理文档。
基础示例：保存快捷键 Ctrl+S
下面的示例展示如何在编辑器组件中为 Ctrl+S 绑定保存逻辑：
import React from 'react';
import { useKeyBinding } from '@keekuun/keymaster-react';
function Editor() {
useKeyBinding(
'ctrl+s',
() => {
// 在这里执行保存逻辑，例如：调接口 / 更新本地状态
console.log('保存成功');
},
{ preventDefault: true }, // 阻止浏览器默认的保存页面行为
);
return <textarea placeholder="在这里输入内容，然后按 Ctrl+S 触发保存"></textarea>;
}
export default Editor;要在你的应用中验证行为，只需要把 Editor 组件挂载到页面上，然后在浏览器中按下 Ctrl+S，观察控制台输出或你的实际保存逻辑是否被触发。
试试看：
多个快捷键示例
你也可以在同一个组件中多次调用 useKeyBinding，为不同快捷键绑定不同行为：
useKeyBinding('ctrl+s', onSave, { preventDefault: true });
useKeyBinding('ctrl+z', onUndo);
useKeyBinding('ctrl+shift+z', onRedo);交互演示：
高级 API
作用域快捷键（scopedElement）
当你需要在特定元素范围内绑定快捷键时（例如编辑器、对话框），可以使用 scopedElement 选项：
import React, { useRef } from 'react';
import { useKeyBinding } from '@keekuun/keymaster-react';
function Editor() {
const editorRef = useRef<HTMLTextAreaElement>(null);
// 只在编辑器区域内生效
useKeyBinding(
'ctrl+s',
() => {
console.log('保存编辑器内容');
},
{
scopedElement: editorRef.current,
preventDefault: true,
},
);
return <textarea ref={editorRef} placeholder="按 Ctrl+S 保存" />;
}或者使用便捷的 useScopedKeyBinding Hook：
import { useScopedKeyBinding } from '@keekuun/keymaster-react';
const containerRef = useRef<HTMLDivElement>(null);
useScopedKeyBinding(
'ctrl+k',
() => {
console.log('只在容器内生效');
},
containerRef,
);交互演示：
编辑器模式
编辑器模式会自动处理常见的快捷键冲突，特别适合代码编辑器、富文本编辑器等场景：
import { useEditorKeyBinding } from '@keekuun/keymaster-react';
function CodeEditor() {
const editorRef = useRef<HTMLTextAreaElement>(null);
// 编辑器模式会自动阻止默认行为
useEditorKeyBinding(
'ctrl+s',
() => {
saveCode();
},
editorRef.current,
);
useEditorKeyBinding(
'ctrl+z',
() => {
undo();
},
editorRef.current,
);
return <textarea ref={editorRef} />;
}交互演示：
Electron 模式
在 Electron 应用中，可以使用 useElectronKeyBinding 来适配主进程与渲染进程的快捷键协调：
import { useElectronKeyBinding } from '@keekuun/keymaster-react';
function ElectronApp() {
useElectronKeyBinding(
'ctrl+alt+r',
() => {
// 通过 bridge / ipc 通知主进程
window.electron?.ipcRenderer?.send('shortcut:reload');
},
{
electronHook: ({ parsed, processInfo, versions }) => {
console.log('[electron shortcut]', parsed, processInfo, versions);
// 返回 false 可以中断后续处理
return true;
},
},
);
return <div>Electron App</div>;
}Electron 钩子（electronHook）
在 Electron 模式下，你可以通过 electronHook 收集环境信息或做统一拦截：
useElectronKeyBinding('ctrl+alt+r', handler, {
electronHook: ({ event, parsed, processInfo, versions }) => {
// 统一日志 / 监控
if (!versions?.electron) return false; // 环境异常时直接中断
return true;
},
});交互演示：
Electron 模式演示
Electron 模式适配桌面应用场景，可以通过 electronHook 扩展或拦截 Electron 特定的行为。
当前环境：浏览器环境（仅演示）
尝试以下快捷键（在 Electron 环境中会触发 hook）：
最近触发：暂无
快捷键组合管理
使用 KeyBindingManager 管理一组相关的快捷键绑定：
import { useEffect } from 'react';
import { createKeyBindingManager, isValidShortcut, formatShortcut } from '@keekuun/keymaster-react';
function Editor() {
useEffect(() => {
const manager = createKeyBindingManager();
// 链式注册多个快捷键
manager
.register('ctrl+s', () => save(), { preventDefault: true })
.register('ctrl+z', () => undo())
.register('ctrl+shift+z', () => redo());
// 组件卸载时自动清理所有绑定
return () => manager.dispose();
}, []);
return <textarea />;
}工具函数：
isValidShortcut(shortcut): 检查快捷键格式是否有效formatShortcut(shortcut): 格式化快捷键字符串（统一大小写）
交互演示：