From 9080c3af21464ca7fc4eb46618d5180ea5739954 Mon Sep 17 00:00:00 2001
From: gaoziman <2942894660@qq.com>
Date: Sat, 27 Dec 2025 23:55:55 +0800
Subject: [PATCH] =?UTF-8?q?feat(=E7=B1=BB=E5=9E=8B):=20=E6=B7=BB=E5=8A=A0?=
 =?UTF-8?q?=E5=BF=AB=E6=8D=B7=E9=94=AE=E7=B3=BB=E7=BB=9F=E7=B1=BB=E5=9E=8B?=
 =?UTF-8?q?=E5=AE=9A=E4=B9=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 定义 ModifierKey、HotkeyScope、HotkeyCategory 类型
- 定义 HotkeyConfig 快捷键配置接口
- 定义 HotkeysContextType Context 类型
- 实现 formatHotkey 格式化显示函数
---
 src/types/hotkeys.ts | 120 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 src/types/hotkeys.ts

diff --git a/src/types/hotkeys.ts b/src/types/hotkeys.ts
new file mode 100644
index 0000000..e39cfb6
--- /dev/null
+++ b/src/types/hotkeys.ts
@@ -0,0 +1,120 @@
+/**
+ * 快捷键系统类型定义
+ */
+
+/** 修饰键类型 */
+export type ModifierKey = 'ctrl' | 'meta' | 'alt' | 'shift';
+
+/** 快捷键作用域 */
+export type HotkeyScope = 'global' | 'modal' | 'input';
+
+/** 快捷键分类 */
+export type HotkeyCategory = '导航' | '编辑' | '通用';
+
+/**
+ * 快捷键配置
+ */
+export interface HotkeyConfig {
+  /** 主键（如 'n', '/', 'k', 'Escape'） */
+  key: string;
+  /** 修饰键组合 */
+  modifiers?: ModifierKey[];
+  /** 快捷键描述 */
+  description: string;
+  /** 分类 */
+  category?: HotkeyCategory;
+  /** 触发回调 */
+  action: () => void;
+  /** 是否启用（可以是布尔值或函数） */
+  enabled?: boolean | (() => boolean);
+  /** 是否阻止默认行为（默认 true） */
+  preventDefault?: boolean;
+  /** 作用域：global-全局, modal-仅弹窗, input-包括输入框 */
+  scope?: HotkeyScope;
+  /** 是否允许在输入框中触发（默认 false，仅对有修饰键的快捷键生效） */
+  allowInInput?: boolean;
+}
+
+/**
+ * 已注册的快捷键信息（用于显示帮助面板）
+ */
+export interface RegisteredHotkey {
+  id: string;
+  config: HotkeyConfig;
+}
+
+/**
+ * 快捷键 Context 类型
+ */
+export interface HotkeysContextType {
+  /** 注册快捷键 */
+  register: (id: string, config: HotkeyConfig) => void;
+  /** 注销快捷键 */
+  unregister: (id: string) => void;
+  /** 设置快捷键启用状态 */
+  setEnabled: (id: string, enabled: boolean) => void;
+  /** 获取所有已注册的快捷键 */
+  getAll: () => RegisteredHotkey[];
+  /** 帮助面板是否打开 */
+  isHelperOpen: boolean;
+  /** 切换帮助面板 */
+  toggleHelper: () => void;
+  /** 关闭帮助面板 */
+  closeHelper: () => void;
+  /** 打开帮助面板 */
+  openHelper: () => void;
+  /** 全局禁用状态（用于弹窗打开时暂停快捷键） */
+  isDisabled: boolean;
+  /** 设置全局禁用状态 */
+  setDisabled: (disabled: boolean) => void;
+}
+
+/**
+ * 格式化快捷键显示
+ * @param config 快捷键配置
+ * @param isMac 是否为 Mac 系统
+ * @returns 格式化的快捷键字符串
+ */
+export function formatHotkey(config: HotkeyConfig, isMac: boolean = true): string {
+  const parts: string[] = [];
+
+  if (config.modifiers?.includes('ctrl')) {
+    parts.push(isMac ? '⌃' : 'Ctrl');
+  }
+  if (config.modifiers?.includes('meta')) {
+    parts.push(isMac ? '⌘' : 'Ctrl');
+  }
+  if (config.modifiers?.includes('alt')) {
+    parts.push(isMac ? '⌥' : 'Alt');
+  }
+  if (config.modifiers?.includes('shift')) {
+    parts.push(isMac ? '⇧' : 'Shift');
+  }
+
+  // 格式化主键显示
+  const keyDisplay = formatKeyDisplay(config.key);
+  parts.push(keyDisplay);
+
+  return isMac ? parts.join(' ') : parts.join('+');
+}
+
+/**
+ * 格式化单个按键显示
+ */
+function formatKeyDisplay(key: string): string {
+  const keyMap: Record<string, string> = {
+    'Escape': 'Esc',
+    'ArrowUp': '↑',
+    'ArrowDown': '↓',
+    'ArrowLeft': '←',
+    'ArrowRight': '→',
+    'Enter': '↵',
+    ' ': 'Space',
+    '/': '/',
+    ',': ',',
+    '.': '.',
+    '?': '?',
+  };
+
+  return keyMap[key] || key.toUpperCase();
+}