快捷键自定义

WinCode 的快捷键系统基于作用域(Scope)模型,由 KeyboardTab 展示、keyboardStore 管理、useRegisterShortcut Hook 在各组件中注册。用户在设置页可直接按键重绑任意快捷键。

作用域(Scope)

快捷键只在对应的 active scope 中生效,作用域随界面动态 push/pop:

// useKeyboardScope.ts
export function useKeyboardScope(scope: string, active: boolean = true) {
  const pushScope = useKeyboardStore((s) => s.pushScope);
  const popScope  = useKeyboardStore((s) => s.popScope);
  useEffect(() => {
    if (active) {
      pushScope(scope);
      return () => popScope(scope);
    }
  }, [scope, active, pushScope, popScope]);
}

当多个作用域同时激活时,优先级更高的 scope 内的绑定胜出;同 scope 内按 priority 字段比较。

默认快捷键表

从源码中提取的默认绑定:

自定义快捷键

KeyboardTab 按 scope 分组展示所有已注册绑定,每项右侧是 KeyboardShortcutInput 录入控件:

1. 点击输入框进入录制模式(setRecording(true))
2. 按下目标键,Hook 将其写入 userOverrides 并持久化到 localStorage['keyboard-shortcuts-overrides']
3. 下次 dispatch 时,effectiveKey = userOverrides[id] ?? binding.key 优先使用用户覆盖

右上角 恢复默认 按钮调用 resetToDefaults(),清空 localStorage 中的覆盖记录。

注册新快捷键

功能组件中使用 useRegisterShortcut:

useRegisterShortcut({
  id: 'settings.open',
  defaultKey: 'cmd+,',
  scope: 'global',
  description: '打开设置',
  handler: toggleSettings,
});

配置字段:id(唯一标识)、defaultKey(默认键)、scope、description(显示在设置页)、handler(回调)、priority(可选)、targetFilter(过滤触发元素)、when(条件)、preventDefault(默认 true)。

派发与优先级

Layout.tsx 在窗口挂载全局 keydown 监听,事件交给 keyboardStore.dispatch:

1. 过滤:若 isRecording 或 event.isComposing(中文输入法)直接返回
2. 匹配:检查 key / scope / targetFilter / when
3. 排序:优先 scope 深度,再按 priority
4. 命中首个后 preventDefault() 并执行 handler

相关文档

• 设置概览