Skip to content

Commit 9d3ca78

Browse files
committed
fix: 完善快捷键录入与全局注册 #406
1 parent 084b54a commit 9d3ca78

9 files changed

Lines changed: 265 additions & 26 deletions

File tree

‎electron/main/ipc/hotkey.ts‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,3 @@
1-
/**
2-
* 快捷键 IPC
3-
*/
4-
51
import { ipcMain } from "electron";
62
import {
73
getHotkeyConfig,
@@ -10,23 +6,34 @@ import {
106
setGlobalEnabled,
117
probeAccelerator,
128
getConflicts,
9+
setRecording,
1310
} from "@main/services/globalHotkey";
1411
import type { HotkeyActionId, HotkeyBinding } from "@shared/types/hotkey";
1512

13+
/** 快捷键 IPC */
1614
export const registerHotkeyIpc = (): void => {
15+
// 拉取完整绑定配置
1716
ipcMain.handle("hotkey:getAll", () => getHotkeyConfig());
1817

18+
// 更新单个动作的绑定,并同步重注册全局快捷键
1919
ipcMain.handle("hotkey:set", (_event, id: HotkeyActionId, binding: HotkeyBinding) =>
2020
setBinding(id, binding),
2121
);
2222

23+
// 重置单项或全部绑定
2324
ipcMain.handle("hotkey:reset", (_event, id?: HotkeyActionId) => resetBindings(id));
2425

26+
// 切换全局快捷键总开关
2527
ipcMain.handle("hotkey:setGlobalEnabled", (_event, enabled: boolean) =>
2628
setGlobalEnabled(enabled),
2729
);
2830

31+
// 探测组合键能否在系统层注册
2932
ipcMain.handle("hotkey:probe", (_event, accel: string) => probeAccelerator(accel));
3033

34+
// 录入期间暂停/恢复全局注册
35+
ipcMain.handle("hotkey:setRecording", (_event, recording: boolean) => setRecording(recording));
36+
37+
// 拉取当前冲突列表
3138
ipcMain.handle("hotkey:getConflicts", () => getConflicts());
3239
};

‎electron/main/services/globalHotkey.ts‎

Lines changed: 34 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,14 @@ import type {
1818
HotkeyBinding,
1919
HotkeyConfig,
2020
HotkeyConflict,
21+
HotkeyProbeResult,
2122
} from "@shared/types/hotkey";
2223
import { defaultHotkeyConfig, HOTKEY_ACTIONS } from "@shared/defaults/hotkeys";
23-
import { normalizeAccelerator } from "@shared/utils/accelerator";
24+
import { isSupportedAccelerator, normalizeAccelerator } from "@shared/utils/accelerator";
2425

2526
let conflicts: HotkeyConflict[] = [];
27+
/** 录入期间暂停注册,避免已被占用的组合被系统吞掉 */
28+
let suspended = false;
2629

2730
/** 取当前完整配置(store 兜底默认) */
2831
const readConfig = (): HotkeyConfig => {
@@ -55,6 +58,7 @@ const unregisterAll = (): void => {
5558
* globalEnabled = false 时只 unregisterAll 不注册新的
5659
*/
5760
const applyAll = (): void => {
61+
if (suspended) return;
5862
unregisterAll();
5963
const config = readConfig();
6064
if (!config.globalEnabled) {
@@ -69,7 +73,7 @@ const applyAll = (): void => {
6973
if (!accel) continue;
7074

7175
const norm = normalizeAccelerator(accel);
72-
if (!norm) {
76+
if (!norm || !isSupportedAccelerator(norm)) {
7377
conflicts.push({ id, scope: "global", reason: "invalid" });
7478
continue;
7579
}
@@ -159,23 +163,44 @@ export const setGlobalEnabled = (enabled: boolean): HotkeyConfig => {
159163
/**
160164
* 探测某 accelerator 是否能在系统层注册成功
161165
* 用于录入新 global 时给 UI 实时反馈
166+
* @param accelerator - 待探测的加速键
167+
* @returns ok 可注册;invalid 格式或平台不支持;occupied 已被系统或其他程序占用
162168
*/
163-
export const probeAccelerator = (accelerator: string): boolean => {
169+
export const probeAccelerator = (accelerator: string): HotkeyProbeResult => {
164170
const norm = normalizeAccelerator(accelerator);
165-
if (!norm) return false;
171+
if (!norm || !isSupportedAccelerator(norm)) return "invalid";
166172
const wasRegistered = globalShortcut.isRegistered(norm);
167173
if (wasRegistered) {
168174
globalShortcut.unregister(norm);
169175
}
170-
let ok = false;
176+
let result: HotkeyProbeResult = "invalid";
171177
try {
172-
ok = globalShortcut.register(norm, () => {});
173-
if (ok) globalShortcut.unregister(norm);
178+
if (globalShortcut.register(norm, () => {})) {
179+
globalShortcut.unregister(norm);
180+
result = "ok";
181+
} else {
182+
result = "occupied";
183+
}
174184
} catch {
175-
ok = false;
185+
result = "invalid";
176186
}
177187
if (wasRegistered) {
178188
applyAll();
179189
}
180-
return ok;
190+
return result;
191+
};
192+
193+
/**
194+
* 录入期间暂停/恢复全局快捷键
195+
* 暂停时释放系统占用,保证已被注册的组合也能被录入
196+
* @param recording - 是否处于录入态
197+
*/
198+
export const setRecording = (recording: boolean): void => {
199+
if (recording === suspended) return;
200+
suspended = recording;
201+
if (suspended) {
202+
globalShortcut.unregisterAll();
203+
return;
204+
}
205+
applyAll();
181206
};

‎electron/preload/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -867,6 +867,7 @@ const api = {
867867
reset: (id?: HotkeyActionId) => ipcRenderer.invoke("hotkey:reset", id),
868868
setGlobalEnabled: (enabled: boolean) => ipcRenderer.invoke("hotkey:setGlobalEnabled", enabled),
869869
probe: (accelerator: string) => ipcRenderer.invoke("hotkey:probe", accelerator),
870+
setRecording: (recording: boolean) => ipcRenderer.invoke("hotkey:setRecording", recording),
870871
getConflicts: () => ipcRenderer.invoke("hotkey:getConflicts"),
871872
onTrigger: (callback: (id: HotkeyActionId) => void) =>
872873
subscribe<HotkeyActionId>("hotkey:trigger", callback),

‎shared/types/hotkey.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,9 @@ export interface HotkeyConflict {
6262
conflictWith?: HotkeyActionId;
6363
}
6464

65+
/** 全局快捷键探测结果 */
66+
export type HotkeyProbeResult = "ok" | "invalid" | "occupied";
67+
6568
export interface HotkeyApi {
6669
/** 拉取完整配置 */
6770
getAll: () => Promise<HotkeyConfig>;
@@ -72,7 +75,9 @@ export interface HotkeyApi {
7275
/** 切换全局快捷键总开关 */
7376
setGlobalEnabled: (enabled: boolean) => Promise<HotkeyConfig>;
7477
/** 探测某 accelerator 在系统层是否可注册(仅 global 录入预校验用) */
75-
probe: (accelerator: string) => Promise<boolean>;
78+
probe: (accelerator: string) => Promise<HotkeyProbeResult>;
79+
/** 录入期间暂停全局快捷键注册 */
80+
setRecording: (recording: boolean) => Promise<void>;
7681
/** 拉取当前冲突快照(init 时使用,避免错过启动时已 broadcast 的事件) */
7782
getConflicts: () => Promise<HotkeyConflict[]>;
7883
/** 主进程触发某动作(global 命中后转回渲染端 dispatch) */

‎shared/utils/accelerator.ts‎

Lines changed: 157 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,110 @@ const MODIFIER_TOKENS = new Set([
2828
"cmdorctrl",
2929
]);
3030

31+
/** Electron 支持的具名按键 token(不区分大小写) */
32+
const NAMED_KEY_TOKENS = new Set([
33+
"space",
34+
"spacebar",
35+
"tab",
36+
"capslock",
37+
"numlock",
38+
"scrolllock",
39+
"backspace",
40+
"delete",
41+
"del",
42+
"insert",
43+
"return",
44+
"enter",
45+
"up",
46+
"down",
47+
"left",
48+
"right",
49+
"home",
50+
"end",
51+
"pageup",
52+
"pagedown",
53+
"escape",
54+
"esc",
55+
"volumeup",
56+
"volumedown",
57+
"volumemute",
58+
"medianexttrack",
59+
"mediaprevioustrack",
60+
"mediastop",
61+
"mediaplaypause",
62+
"printscreen",
63+
"plus",
64+
]);
65+
66+
/** Electron 支持的符号按键 token */
67+
const PUNCTUATION_TOKENS = new Set([
68+
")",
69+
"!",
70+
"@",
71+
"#",
72+
"$",
73+
"%",
74+
"^",
75+
"&",
76+
"*",
77+
"(",
78+
":",
79+
";",
80+
"+",
81+
"=",
82+
"<",
83+
",",
84+
"_",
85+
"-",
86+
">",
87+
".",
88+
"?",
89+
"/",
90+
"~",
91+
"`",
92+
"{",
93+
"]",
94+
"[",
95+
"|",
96+
"\\",
97+
"}",
98+
'"',
99+
"'",
100+
]);
101+
102+
/** 小键盘 Accelerator token → event.code */
103+
const NUMPAD_TO_CODE: Record<string, string> = {
104+
num0: "Numpad0",
105+
num1: "Numpad1",
106+
num2: "Numpad2",
107+
num3: "Numpad3",
108+
num4: "Numpad4",
109+
num5: "Numpad5",
110+
num6: "Numpad6",
111+
num7: "Numpad7",
112+
num8: "Numpad8",
113+
num9: "Numpad9",
114+
numdec: "NumpadDecimal",
115+
numadd: "NumpadAdd",
116+
numsub: "NumpadSubtract",
117+
nummult: "NumpadMultiply",
118+
numdiv: "NumpadDivide",
119+
};
120+
121+
/** event.code → 小键盘 Accelerator token */
122+
const CODE_TO_NUMPAD: Record<string, string> = Object.fromEntries(
123+
Object.entries(NUMPAD_TO_CODE).map(([token, code]) => [code, token]),
124+
);
125+
126+
/** 小键盘符号键的展示文案 */
127+
const NUMPAD_LABELS: Record<string, string> = {
128+
numdec: "Num.",
129+
numadd: "Num+",
130+
numsub: "Num-",
131+
nummult: "Num*",
132+
numdiv: "Num/",
133+
};
134+
31135
/**
32136
* 把 Accelerator 中的 key token(最后一段非 modifier)规范成 KeyboardEvent.code 形式
33137
* Electron Accelerator 用的是 key 字符(如 "A"、"Right"),需要映射到 code
@@ -39,6 +143,9 @@ const keyToCode = (token: string): string => {
39143
if (/^[A-Za-z]$/.test(t)) return `Key${t.toUpperCase()}`;
40144
// 数字
41145
if (/^[0-9]$/.test(t)) return `Digit${t}`;
146+
// 小键盘
147+
const numpad = NUMPAD_TO_CODE[t.toLowerCase()];
148+
if (numpad) return numpad;
42149
// 方向键
43150
const arrow: Record<string, string> = {
44151
left: "ArrowLeft",
@@ -155,13 +262,20 @@ export const normalizeAccelerator = (accel: string): string => {
155262
.split("+")
156263
.map((t) => t.trim())
157264
.filter(Boolean);
158-
const mods = { cmdOrCtrl: false, cmd: false, ctrl: false, alt: false, shift: false };
265+
const mods = {
266+
cmdOrCtrl: false,
267+
cmd: false,
268+
super: false,
269+
ctrl: false,
270+
alt: false,
271+
shift: false,
272+
};
159273
let key = "";
160274
for (const t of tokens) {
161275
const lower = t.toLowerCase();
162276
if (lower === "commandorcontrol" || lower === "cmdorctrl") mods.cmdOrCtrl = true;
163-
else if (lower === "cmd" || lower === "command" || lower === "meta" || lower === "super")
164-
mods.cmd = true;
277+
else if (lower === "cmd" || lower === "command") mods.cmd = true;
278+
else if (lower === "meta" || lower === "super") mods.super = true;
165279
else if (lower === "ctrl" || lower === "control") mods.ctrl = true;
166280
else if (lower === "alt" || lower === "option") mods.alt = true;
167281
else if (lower === "shift") mods.shift = true;
@@ -173,20 +287,51 @@ export const normalizeAccelerator = (accel: string): string => {
173287
const parts: string[] = [];
174288
if (mods.cmdOrCtrl) parts.push("CommandOrControl");
175289
if (mods.cmd) parts.push("Cmd");
290+
if (mods.super) parts.push("Super");
176291
if (mods.ctrl) parts.push("Ctrl");
177292
if (mods.alt) parts.push("Alt");
178293
if (mods.shift) parts.push("Shift");
179294
parts.push(key);
180295
return parts.join("+");
181296
};
182297

298+
/**
299+
* 判断 accelerator 是否在 Electron 支持的按键集合内
300+
* @param accel - 加速键字符串
301+
* @returns 是否受支持
302+
*/
303+
export const isSupportedAccelerator = (accel: string): boolean => {
304+
if (!accel) return false;
305+
const tokens = accel
306+
.split("+")
307+
.map((t) => t.trim())
308+
.filter(Boolean);
309+
if (tokens.length === 0) return false;
310+
311+
let key = "";
312+
for (const token of tokens) {
313+
if (MODIFIER_TOKENS.has(token.toLowerCase())) continue;
314+
key = token;
315+
}
316+
if (!key) return false;
317+
318+
const lower = key.toLowerCase();
319+
if (/^[a-z0-9]$/.test(lower)) return true;
320+
if (/^f([1-9]|1[0-9]|2[0-4])$/.test(lower)) return true;
321+
if (/^num[0-9]$/.test(lower)) return true;
322+
if (["numdec", "numadd", "numsub", "nummult", "numdiv"].includes(lower)) return true;
323+
if (NAMED_KEY_TOKENS.has(lower)) return true;
324+
return PUNCTUATION_TOKENS.has(key);
325+
};
326+
183327
/** 直接对已解析结构与事件比较,避免热路径重复解析字符串 */
184328
export const matchParsed = (event: KeyboardEvent, parsed: ParsedAccelerator): boolean => {
185329
if (event.ctrlKey !== parsed.ctrl) return false;
186330
if (event.metaKey !== parsed.meta) return false;
187331
if (event.altKey !== parsed.alt) return false;
188332
if (event.shiftKey !== parsed.shift) return false;
189-
return event.code === parsed.code;
333+
// 小键盘回车与主回车共用 Return,避免全局与应用内行为不一致
334+
return event.code === parsed.code || (parsed.code === "Enter" && event.code === "NumpadEnter");
190335
};
191336

192337
/**
@@ -220,6 +365,10 @@ export const formatAccelerator = (accel: string | null, isMac: boolean): string
220365
out.push(isMac ? "↵" : "Enter");
221366
} else if (lower === "space" || lower === "spacebar") {
222367
out.push("Space");
368+
} else if (/^num[0-9]$/.test(lower)) {
369+
out.push(`Num${lower.slice(3)}`);
370+
} else if (lower in NUMPAD_LABELS) {
371+
out.push(NUMPAD_LABELS[lower]);
223372
} else if (/^[a-z]$/.test(lower)) {
224373
out.push(lower.toUpperCase());
225374
} else {
@@ -256,6 +405,9 @@ export const eventToAccelerator = (event: KeyboardEvent, isMac: boolean): string
256405
if (code.startsWith("Digit")) return code.slice(5);
257406
if (code.startsWith("Arrow")) return code.slice(5); // ArrowLeft → Left
258407
if (code.startsWith("F") && /^F[0-9]+$/.test(code)) return code; // F1
408+
const numpad = CODE_TO_NUMPAD[code];
409+
if (numpad) return numpad;
410+
if (code === "NumpadEnter") return "Return";
259411
const map: Record<string, string> = {
260412
Space: "Space",
261413
Enter: "Return",
@@ -289,7 +441,7 @@ export const eventToAccelerator = (event: KeyboardEvent, isMac: boolean): string
289441
const cmdOrCtrl = isMac ? event.metaKey : event.ctrlKey;
290442
const otherCmdLike = isMac ? event.ctrlKey : event.metaKey;
291443
if (cmdOrCtrl) parts.push("CommandOrControl");
292-
if (otherCmdLike) parts.push(isMac ? "Ctrl" : "Cmd");
444+
if (otherCmdLike) parts.push(isMac ? "Ctrl" : "Super");
293445
if (event.altKey) parts.push("Alt");
294446
if (event.shiftKey) parts.push("Shift");
295447
parts.push(codeToToken(event.code));

0 commit comments

Comments
 (0)