Privacy boundary
We do not need to see what you translate.
- The private waitlist form collects the qualification and contact details needed for the beta plus coarse source and landing-page language metadata, never selected text, documents, API keys, or full model requests. Local-model content stays on your Mac; cloud mode sends content only to the provider you choose.
+ The private waitlist form collects the qualification and contact details needed for the beta plus coarse source and landing-page language metadata, never selected text, documents, API keys, or full model requests. On-device model content stays on your Mac; a remote Ollama URL or cloud model sends content only to the service you choose.
Read the public validation rules
diff --git a/site/index.html b/site/index.html
index f005bb9..df06a03 100644
--- a/site/index.html
+++ b/site/index.html
@@ -40,7 +40,7 @@
立即从源码试用
加入签名版候补
@@ -106,7 +106,7 @@
签名版未就绪，先从源码验证价值。
隐私边界
我们不需要看到你翻译了什么。
- 私密候补表单收集资格判断和联系所需的信息，以及粗粒度来源和落地页语言元数据；不收集选中文字、文档、API Key 或完整模型请求。本地模型内容留在电脑；云端模式只发送给你选择的模型服务。
+ 私密候补表单收集资格判断和联系所需的信息，以及粗粒度来源和落地页语言元数据；不收集选中文字、文档、API Key 或完整模型请求。使用本机模型时内容留在电脑；配置远程 Ollama 或云端模型时，内容只发送给你选择的服务。
查看公开验证规则
diff --git a/src-tauri/src/selection.rs b/src-tauri/src/selection.rs
index 41a7f29..629caa3 100644
--- a/src-tauri/src/selection.rs
+++ b/src-tauri/src/selection.rs
@@ -102,7 +102,7 @@ end try
if !output.status.success() {
return Err(
- "无法读取选中文字。请在“系统设置 → 隐私与安全性 → 辅助功能”中允许逐词。".into(),
+ "无法通过复制读取选中文字。请在“系统设置 → 隐私与安全性”中检查逐词的“辅助功能”和“自动化 → System Events”权限。".into(),
);
}
diff --git a/src/App.tsx b/src/App.tsx
index 435378c..c5f5f22 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -13,14 +13,23 @@ import {
X,
Zap,
} from "lucide-react";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { extractFileText } from "./documents";
import {
getEngineStatus,
isDesktopApp,
- registerSelectionShortcut,
+ configureSelectionShortcut,
requestTranslation,
+ SelectionShortcutConfigurationError,
} from "./platform";
+import {
+ DEFAULT_SELECTION_SHORTCUT,
+ formatSelectionShortcut,
+ readSelectionShortcutSettings,
+ saveSelectionShortcutSettings,
+ shortcutFromKeyboardEvent,
+} from "./shortcut";
+import type { SelectionShortcutSettings } from "./shortcut";
import type {
EngineSettings,
Provider,
@@ -41,11 +50,13 @@ const DEFAULT_SETTINGS: EngineSettings = {
const PROVIDER_LABELS: Record
= {
auto: "自动选择",
- ollama: "Ollama 本地",
+ ollama: "Ollama",
openai: "云端模型",
dictionary: "极速词典",
};
+type ShortcutRegistrationStatus = "registering" | "registered" | "disabled" | "failed";
+
function readSavedSettings(): EngineSettings {
try {
const saved = JSON.parse(localStorage.getItem("wordwise-settings") ?? "{}") as Partial;
@@ -76,6 +87,9 @@ export default function App() {
const [text, setText] = useState(SAMPLE);
const [result, setResult] = useState(null);
const [settings, setSettings] = useState(readSavedSettings);
+ const [selectionShortcut, setSelectionShortcut] = useState(
+ readSelectionShortcutSettings,
+ );
const [status, setStatus] = useState(null);
const [settingsOpen, setSettingsOpen] = useState(false);
const [loading, setLoading] = useState(false);
@@ -84,8 +98,17 @@ export default function App() {
const [fileName, setFileName] = useState("");
const [error, setError] = useState("");
const [copied, setCopied] = useState(false);
+ const [shortcutBusy, setShortcutBusy] = useState(false);
+ const [shortcutError, setShortcutError] = useState("");
+ const [shortcutRegistrationStatus, setShortcutRegistrationStatus] = useState(
+ selectionShortcut.enabled ? "registering" : "disabled",
+ );
const fileInputRef = useRef(null);
const settingsRef = useRef(settings);
+ const statusRef = useRef(status);
+ const selectionRequestInFlight = useRef(false);
+ const shortcutOperationInFlight = useRef(false);
+ const shortcutGlobalError = useRef("");
const tokenCount = useMemo(
() => text.match(/\p{L}+(?:['’]\p{L}+)*|\p{N}+(?:[.,]\p{N}+)*|[^\s]/gu)?.length ?? 0,
@@ -116,28 +139,63 @@ export default function App() {
}, [settings]);
useEffect(() => {
- let removeShortcut: () => void = () => undefined;
+ statusRef.current = status;
+ }, [status]);
+
+ const handleSelectedText = useCallback(async (selectedText: string) => {
+ if (selectionRequestInFlight.current) return;
+ selectionRequestInFlight.current = true;
+ setText(selectedText);
+ setFileName("");
+ setResult(null);
+
+ try {
+ const activeSettings = settingsRef.current;
+ if (needsModelConfiguration(activeSettings, statusRef.current)) {
+ setSettingsOpen(true);
+ return;
+ }
+ await translateValue(selectedText, activeSettings);
+ } finally {
+ selectionRequestInFlight.current = false;
+ }
+ }, []);
+
+ const handleSelectionError = useCallback((message: string) => {
+ shortcutGlobalError.current = "";
+ setError(message);
+ }, []);
+
+ useEffect(() => {
let cancelled = false;
- void registerSelectionShortcut(
- async (selectedText) => {
- if (cancelled) return;
- setText(selectedText);
- setFileName("");
- setResult(null);
- await translateValue(selectedText, settingsRef.current);
- },
- (message) => setError(message),
- ).then((remove) => {
- if (cancelled) remove();
- else removeShortcut = remove;
- }).catch((caught) => {
- setError(caught instanceof Error ? caught.message : "全局快捷键注册失败");
+ void configureSelectionShortcut(
+ selectionShortcut.enabled ? selectionShortcut.accelerator : null,
+ handleSelectedText,
+ handleSelectionError,
+ ).then(() => {
+ if (!cancelled) {
+ setShortcutRegistrationStatus(selectionShortcut.enabled ? "registered" : "disabled");
+ }
+ }).catch(() => {
+ if (!cancelled) {
+ setShortcutRegistrationStatus("failed");
+ const message = selectionShortcut.enabled
+ ? `无法注册 ${formatSelectionShortcut(selectionShortcut.accelerator)}，可能已被其他应用占用`
+ : "无法关闭选区快捷键";
+ shortcutGlobalError.current = message;
+ setShortcutError(message);
+ setError(message);
+ }
});
return () => {
cancelled = true;
- removeShortcut();
+ void configureSelectionShortcut(
+ null,
+ handleSelectedText,
+ handleSelectionError,
+ ).catch(() => undefined);
};
}, []);
@@ -214,6 +272,69 @@ export default function App() {
setSettings((current) => ({ ...current, [key]: value }));
}
+ async function applySelectionShortcut(next: SelectionShortcutSettings) {
+ if (shortcutOperationInFlight.current) return;
+ shortcutOperationInFlight.current = true;
+ setShortcutBusy(true);
+ setShortcutError("");
+ setShortcutRegistrationStatus("registering");
+ try {
+ await configureSelectionShortcut(
+ next.enabled ? next.accelerator : null,
+ handleSelectedText,
+ handleSelectionError,
+ );
+ setSelectionShortcut(next);
+ setShortcutRegistrationStatus(next.enabled ? "registered" : "disabled");
+
+ const previousGlobalError = shortcutGlobalError.current;
+ shortcutGlobalError.current = "";
+ if (previousGlobalError) {
+ setError((current) => current === previousGlobalError ? "" : current);
+ }
+
+ try {
+ saveSelectionShortcutSettings(next);
+ } catch {
+ setShortcutError("快捷键已应用，但无法保存；下次启动将恢复原设置");
+ }
+ } catch (caught) {
+ const activeAccelerator = caught instanceof SelectionShortcutConfigurationError
+ ? caught.activeAccelerator
+ : selectionShortcut.enabled
+ ? selectionShortcut.accelerator
+ : null;
+ const previousStillActive = selectionShortcut.enabled
+ && activeAccelerator === selectionShortcut.accelerator;
+
+ setShortcutRegistrationStatus(
+ previousStillActive ? "registered" : activeAccelerator ? "failed" : selectionShortcut.enabled ? "failed" : "disabled",
+ );
+
+ let message: string;
+ if (previousStillActive) {
+ message = next.enabled
+ ? `无法注册 ${formatSelectionShortcut(next.accelerator)}，已保留 ${formatSelectionShortcut(selectionShortcut.accelerator)}`
+ : `无法关闭 ${formatSelectionShortcut(selectionShortcut.accelerator)}，原快捷键仍有效`;
+ } else if (!activeAccelerator) {
+ message = selectionShortcut.enabled
+ ? `无法注册 ${formatSelectionShortcut(next.accelerator)}，原快捷键也未能恢复；请重新启用或更换`
+ : `无法注册 ${formatSelectionShortcut(next.accelerator)}，选区快捷键仍为关闭状态`;
+ } else {
+ message = `快捷键配置未完成；当前仍为 ${formatSelectionShortcut(activeAccelerator)}`;
+ }
+ setShortcutError(message);
+
+ if (!previousStillActive && selectionShortcut.enabled) {
+ shortcutGlobalError.current = message;
+ setError(message);
+ }
+ } finally {
+ shortcutOperationInFlight.current = false;
+ setShortcutBusy(false);
+ }
+ }
+
function resetText() {
setText("");
setResult(null);
@@ -225,20 +346,23 @@ export default function App() {
const currentProviderStatus = (() => {
if (settings.provider === "dictionary") return "仅逐词查义";
- if (settings.provider === "ollama") return status?.ollama.available ? "本地已连接" : "等待本地模型";
+ if (settings.provider === "ollama") return status?.ollama.available ? "Ollama 可用" : "等待 Ollama";
if (settings.provider === "openai") {
return hasEnteredApiKey || status?.openaiConfigured ? "API 已配置" : "需要 API Key";
}
- if (status?.ollama.available) return "将使用本地模型";
+ if (status?.ollama.available) return "将使用 Ollama";
if (hasEnteredApiKey || status?.openaiConfigured) return "将使用云端模型";
return "需要配置引擎";
})();
- const needsModelSetup = status !== null
- && settings.provider === "auto"
- && !status.ollama.available
- && !hasEnteredApiKey
- && !status.openaiConfigured;
+ const needsModelSetup = needsModelConfiguration(settings, status);
+ const shortcutStatusLabel = shortcutRegistrationStatus === "registered"
+ ? "已注册"
+ : shortcutRegistrationStatus === "disabled"
+ ? "已关闭"
+ : shortcutRegistrationStatus === "registering"
+ ? "配置中"
+ : "注册失败";
return (
@@ -250,7 +374,7 @@ export default function App() {
setSettingsOpen(true)}>
+ setSettingsOpen(true)}>
@@ -282,7 +406,7 @@ export default function App() {
先连接一个语境翻译引擎
- Ollama 内容留在本机；云端 API 适合立即开始。极速词典只做逐词查义，不会冒充整句翻译。
+ 本机 Ollama 内容留在电脑；远程服务适合立即开始。极速词典只做逐词查义，不会冒充整句翻译。
setSettingsOpen(true)}>
{isDesktopApp ? "桌面客户端" : "本地优先"}
- {isDesktopApp && ⌥ + T 翻译选中文字 }
+ {isDesktopApp && (
+
+ {shortcutRegistrationStatus === "failed"
+ ? "选区快捷键配置失败"
+ : selectionShortcut.enabled
+ ? `${formatSelectionShortcut(selectionShortcut.accelerator)} 翻译选中文字`
+ : "选区快捷键已关闭"}
+
+ )}
Ctrl / ⌘ + Enter 翻译
单次上限 20,000 字符
@@ -444,12 +576,82 @@ export default function App() {
event.stopPropagation()}>
-
翻译引擎
-
自动模式使用已配置的 Ollama 或云端 API，不会静默降级为基础词典。
+
设置
+
配置选区快捷键和翻译引擎。自动模式不会静默降级为基础词典。
setSettingsOpen(false)}>
+ {isDesktopApp && (
+
+
+ 选区快捷键
+
+ {shortcutStatusLabel}
+
+
+
+
+ 选中文字后用快捷键翻译
+ 关闭后不会注册任何选区翻译快捷键。
+
+
+
+
+ 快捷键
+ 点按输入框后按新组合键；文字键和 F1-F12 需搭配 ⌘、⌃ 或 ⌥。
+
+ void applySelectionShortcut({
+ ...DEFAULT_SELECTION_SHORTCUT,
+ enabled: selectionShortcut.enabled,
+ })}
+ >
+
+
+ {shortcutError &&
{shortcutError}
}
+
运行方式
{(Object.keys(PROVIDER_LABELS) as Provider[]).map((provider) => (
@@ -470,8 +672,8 @@ export default function App() {
{(settings.provider === "auto" || settings.provider === "ollama") && (
- Ollama 本地模型
- {status?.ollama.available ? "已连接" : "未连接"}
+ Ollama 模型
+ {status?.ollama.available ? "默认地址可用" : "默认地址未连接"}
服务地址
@@ -517,7 +719,7 @@ export default function App() {
)}
- API Key 不会写入浏览器存储
+ 设置保存在本机；API Key 不会写入浏览器存储
setSettingsOpen(false)}>
@@ -530,8 +732,16 @@ export default function App() {
function providerDescription(provider: Provider, status: ServerStatus | null) {
switch (provider) {
case "auto": return "按可用性选择最佳引擎";
- case "ollama": return status?.ollama.available ? `${status.ollama.models.length} 个本地模型可用` : "数据不离开本机";
+ case "ollama": return status?.ollama.available ? `${status.ollama.models.length} 个默认地址模型可用` : "默认连接本机服务，可修改地址";
case "openai": return "语境质量高，按 API 用量计费";
case "dictionary": return "离线逐词查义，不提供可靠整句翻译";
}
}
+
+function needsModelConfiguration(settings: EngineSettings, status: ServerStatus | null) {
+ return status !== null
+ && settings.provider === "auto"
+ && !status.ollama.available
+ && !settings.openaiApiKey.trim()
+ && !status.openaiConfigured;
+}
diff --git a/src/platform.test.ts b/src/platform.test.ts
new file mode 100644
index 0000000..d8dd253
--- /dev/null
+++ b/src/platform.test.ts
@@ -0,0 +1,200 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ handlers: new Map Promise>(),
+ invoke: vi.fn(),
+ register: vi.fn(),
+ unregister: vi.fn(),
+ show: vi.fn(),
+ setFocus: vi.fn(),
+}));
+
+vi.mock("@tauri-apps/api/core", () => ({
+ invoke: mocks.invoke,
+ isTauri: () => true,
+}));
+
+vi.mock("@tauri-apps/api/window", () => ({
+ getCurrentWindow: () => ({ show: mocks.show, setFocus: mocks.setFocus }),
+}));
+
+vi.mock("@tauri-apps/plugin-global-shortcut", () => ({
+ register: mocks.register,
+ unregister: mocks.unregister,
+}));
+
+beforeEach(() => {
+ vi.resetModules();
+ mocks.handlers.clear();
+ mocks.invoke.mockReset();
+ mocks.register.mockReset();
+ mocks.unregister.mockReset();
+ mocks.show.mockReset().mockResolvedValue(undefined);
+ mocks.setFocus.mockReset().mockResolvedValue(undefined);
+ mocks.unregister.mockImplementation(async (shortcut: string) => {
+ mocks.handlers.delete(shortcut);
+ });
+ mocks.register.mockImplementation(async (
+ shortcut: string,
+ handler: (event: { state: "Released" | "Pressed" }) => Promise,
+ ) => {
+ mocks.handlers.set(shortcut, handler);
+ });
+});
+
+describe("selection shortcut registration", () => {
+ it("serially replaces and disables the active shortcut", async () => {
+ const { configureSelectionShortcut } = await import("./platform");
+ const onSelection = vi.fn();
+ const onError = vi.fn();
+
+ await configureSelectionShortcut("Alt+K", onSelection, onError);
+ await configureSelectionShortcut("Alt+J", onSelection, onError);
+ await configureSelectionShortcut(null, onSelection, onError);
+
+ expect(mocks.register.mock.calls.map(([shortcut]) => shortcut)).toEqual([
+ "Alt+K",
+ "Alt+J",
+ ]);
+ expect(mocks.unregister.mock.calls.map(([shortcut]) => shortcut)).toEqual([
+ "Alt+K",
+ "Alt+J",
+ ]);
+ });
+
+ it("restores the previous shortcut when a replacement fails", async () => {
+ const { configureSelectionShortcut } = await import("./platform");
+ const onSelection = vi.fn();
+ const onError = vi.fn();
+ mocks.register.mockImplementation(async (
+ shortcut: string,
+ handler: (event: { state: "Released" | "Pressed" }) => Promise,
+ ) => {
+ if (shortcut === "Alt+J") throw new Error("occupied");
+ mocks.handlers.set(shortcut, handler);
+ });
+
+ await configureSelectionShortcut("Alt+K", onSelection, onError);
+ await expect(
+ configureSelectionShortcut("Alt+J", onSelection, onError),
+ ).rejects.toThrow("occupied");
+
+ expect(mocks.register.mock.calls.map(([shortcut]) => shortcut)).toEqual([
+ "Alt+K",
+ "Alt+J",
+ "Alt+K",
+ ]);
+
+ mocks.invoke.mockResolvedValue("restored shortcut");
+ await mocks.handlers.get("Alt+K")?.({ state: "Pressed" });
+ expect(onSelection).toHaveBeenCalledWith("restored shortcut");
+ });
+
+ it("reports when both replacement and rollback registration fail", async () => {
+ const {
+ configureSelectionShortcut,
+ SelectionShortcutConfigurationError,
+ } = await import("./platform");
+ const onSelection = vi.fn();
+ const onError = vi.fn();
+ let initialRegistrationDone = false;
+ mocks.register.mockImplementation(async (
+ shortcut: string,
+ handler: (event: { state: "Released" | "Pressed" }) => Promise,
+ ) => {
+ if (shortcut === "Alt+K" && !initialRegistrationDone) {
+ initialRegistrationDone = true;
+ mocks.handlers.set(shortcut, handler);
+ return;
+ }
+ throw new Error("registration unavailable");
+ });
+
+ await configureSelectionShortcut("Alt+K", onSelection, onError);
+ const replacement = configureSelectionShortcut("Alt+J", onSelection, onError);
+
+ await expect(replacement).rejects.toBeInstanceOf(SelectionShortcutConfigurationError);
+ await expect(replacement).rejects.toMatchObject({ activeAccelerator: null });
+ });
+
+ it("captures selected text only for the pressed event", async () => {
+ const { configureSelectionShortcut } = await import("./platform");
+ const onSelection = vi.fn();
+ const onError = vi.fn();
+ mocks.invoke.mockResolvedValue("Selected API documentation");
+
+ await configureSelectionShortcut("Alt+K", onSelection, onError);
+ const handler = mocks.handlers.get("Alt+K");
+ await handler?.({ state: "Released" });
+ await handler?.({ state: "Pressed" });
+
+ expect(mocks.invoke).toHaveBeenCalledOnce();
+ expect(mocks.show).toHaveBeenCalledOnce();
+ expect(mocks.setFocus).toHaveBeenCalledOnce();
+ expect(onSelection).toHaveBeenCalledWith("Selected API documentation");
+ expect(onError).not.toHaveBeenCalled();
+ });
+
+ it("shows the app before reporting a selection error", async () => {
+ const { configureSelectionShortcut } = await import("./platform");
+ const onSelection = vi.fn();
+ const onError = vi.fn();
+ mocks.invoke.mockRejectedValue("没有检测到选中的文字");
+
+ await configureSelectionShortcut("Alt+K", onSelection, onError);
+ await mocks.handlers.get("Alt+K")?.({ state: "Pressed" });
+
+ expect(mocks.show).toHaveBeenCalledOnce();
+ expect(mocks.setFocus).toHaveBeenCalledOnce();
+ expect(onError).toHaveBeenCalledWith("没有检测到选中的文字");
+ expect(onSelection).not.toHaveBeenCalled();
+ });
+
+ it("prevents concurrent selection capture and translation", async () => {
+ const { configureSelectionShortcut } = await import("./platform");
+ const onSelection = vi.fn();
+ const onError = vi.fn();
+ let resolveCapture: (text: string) => void = () => undefined;
+ mocks.invoke.mockImplementation(() => new Promise((resolve) => {
+ resolveCapture = resolve;
+ }));
+
+ await configureSelectionShortcut("Alt+K", onSelection, onError);
+ const handler = mocks.handlers.get("Alt+K");
+ const firstPress = handler?.({ state: "Pressed" });
+ const secondPress = handler?.({ state: "Pressed" });
+
+ expect(mocks.invoke).toHaveBeenCalledOnce();
+ resolveCapture("one selection");
+ await Promise.all([firstPress, secondPress]);
+ expect(onSelection).toHaveBeenCalledOnce();
+ expect(onSelection).toHaveBeenCalledWith("one selection");
+ });
+
+ it("continues translation and reports when the app window cannot open", async () => {
+ const { configureSelectionShortcut } = await import("./platform");
+ const onSelection = vi.fn();
+ const onError = vi.fn();
+ mocks.invoke.mockResolvedValue("Selected API documentation");
+ mocks.show.mockRejectedValue(new Error("window unavailable"));
+
+ await configureSelectionShortcut("Alt+K", onSelection, onError);
+ await mocks.handlers.get("Alt+K")?.({ state: "Pressed" });
+
+ expect(mocks.setFocus).toHaveBeenCalledOnce();
+ expect(onSelection).toHaveBeenCalledWith("Selected API documentation");
+ expect(onError).toHaveBeenCalledWith("已读取选中文字，但无法打开逐词窗口");
+ });
+
+ it("converts selection callback failures into a visible error", async () => {
+ const { configureSelectionShortcut } = await import("./platform");
+ const onSelection = vi.fn().mockRejectedValue(new Error("render failed"));
+ const onError = vi.fn();
+ mocks.invoke.mockResolvedValue("Selected API documentation");
+
+ await configureSelectionShortcut("Alt+K", onSelection, onError);
+ await mocks.handlers.get("Alt+K")?.({ state: "Pressed" });
+
+ expect(onError).toHaveBeenCalledWith("无法处理选中的文字");
+ });
+});
diff --git a/src/platform.ts b/src/platform.ts
index 41886d4..f0a95e9 100644
--- a/src/platform.ts
+++ b/src/platform.ts
@@ -3,10 +3,33 @@ import { getCurrentWindow } from "@tauri-apps/api/window";
import { register, unregister } from "@tauri-apps/plugin-global-shortcut";
import type { EngineSettings, ServerStatus, TranslationResult } from "./types";
-const SELECTION_SHORTCUT = "Alt+T";
-
export const isDesktopApp = isTauri();
+type SelectionShortcutRegistration = {
+ accelerator: string;
+ onSelection: (text: string) => void | Promise;
+ onError: (message: string) => void;
+};
+
+export class SelectionShortcutConfigurationError extends Error {
+ readonly activeAccelerator: string | null;
+
+ constructor(activeAccelerator: string | null, cause: unknown) {
+ const message = cause instanceof Error
+ ? cause.message
+ : typeof cause === "string"
+ ? cause
+ : "全局快捷键配置失败";
+ super(message, { cause });
+ this.name = "SelectionShortcutConfigurationError";
+ this.activeAccelerator = activeAccelerator;
+ }
+}
+
+let activeSelectionShortcut: SelectionShortcutRegistration | null = null;
+let selectionShortcutQueue = Promise.resolve();
+let selectionCaptureInFlight = false;
+
async function parseResponse(response: Response): Promise {
const body = (await response.json()) as T & { error?: string };
if (!response.ok) throw new Error(body.error || "请求失败");
@@ -33,28 +56,106 @@ export async function requestTranslation(text: string, settings: EngineSettings)
return parseResponse(response);
}
-export async function registerSelectionShortcut(
+export function configureSelectionShortcut(
+ accelerator: string | null,
onSelection: (text: string) => void | Promise,
onError: (message: string) => void,
) {
- if (!isDesktopApp) return () => undefined;
+ if (!isDesktopApp) return Promise.resolve();
+
+ const next = accelerator ? { accelerator, onSelection, onError } : null;
+ const operation = selectionShortcutQueue.then(async () => {
+ const previous = activeSelectionShortcut;
+ if (previous?.accelerator === next?.accelerator) {
+ activeSelectionShortcut = next;
+ return;
+ }
- await unregister(SELECTION_SHORTCUT).catch(() => undefined);
- await register(SELECTION_SHORTCUT, async (event) => {
- if (event.state !== "Pressed") return;
try {
- const selectedText = await invoke("capture_selected_text");
- const appWindow = getCurrentWindow();
- await appWindow.show();
- await appWindow.setFocus();
- await onSelection(selectedText);
- } catch (error) {
- const message = typeof error === "string" ? error : "无法读取选中的文字";
- onError(message);
+ if (previous) {
+ await unregister(previous.accelerator);
+ activeSelectionShortcut = null;
+ }
+ if (!next) return;
+
+ await register(next.accelerator, createSelectionShortcutHandler(next.accelerator));
+ activeSelectionShortcut = next;
+ } catch (cause) {
+ if (previous && activeSelectionShortcut === null) {
+ try {
+ await register(
+ previous.accelerator,
+ createSelectionShortcutHandler(previous.accelerator),
+ );
+ activeSelectionShortcut = previous;
+ } catch {
+ activeSelectionShortcut = null;
+ }
+ }
+ throw new SelectionShortcutConfigurationError(
+ activeSelectionShortcut?.accelerator ?? null,
+ cause,
+ );
}
});
- return () => {
- void unregister(SELECTION_SHORTCUT).catch(() => undefined);
+ selectionShortcutQueue = operation.catch(() => undefined);
+ return operation;
+}
+
+function createSelectionShortcutHandler(accelerator: string) {
+ return async (event: { state: "Released" | "Pressed" }) => {
+ if (event.state !== "Pressed" || selectionCaptureInFlight) return;
+ const registration = activeSelectionShortcut;
+ if (!registration || registration.accelerator !== accelerator) return;
+
+ selectionCaptureInFlight = true;
+ try {
+ let selectedText: string;
+ try {
+ selectedText = await invoke("capture_selected_text");
+ } catch (error) {
+ await showAndFocusAppWindow();
+ reportSelectionError(
+ registration,
+ typeof error === "string" ? error : "无法读取选中的文字",
+ );
+ return;
+ }
+
+ const windowReady = await showAndFocusAppWindow();
+ try {
+ await registration.onSelection(selectedText);
+ } catch {
+ reportSelectionError(registration, "无法处理选中的文字");
+ }
+ if (!windowReady) {
+ reportSelectionError(registration, "已读取选中文字，但无法打开逐词窗口");
+ }
+ } finally {
+ selectionCaptureInFlight = false;
+ }
};
}
+
+async function showAndFocusAppWindow() {
+ try {
+ const appWindow = getCurrentWindow();
+ const shown = await appWindow.show().then(() => true).catch(() => false);
+ const focused = await appWindow.setFocus().then(() => true).catch(() => false);
+ return shown && focused;
+ } catch {
+ return false;
+ }
+}
+
+function reportSelectionError(
+ registration: SelectionShortcutRegistration,
+ message: string,
+) {
+ try {
+ registration.onError(message);
+ } catch {
+ // A UI callback must not leave the global shortcut channel rejected.
+ }
+}
diff --git a/src/shortcut.test.ts b/src/shortcut.test.ts
new file mode 100644
index 0000000..9c83f23
--- /dev/null
+++ b/src/shortcut.test.ts
@@ -0,0 +1,102 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+ DEFAULT_SELECTION_SHORTCUT,
+ formatSelectionShortcut,
+ readSelectionShortcutSettings,
+ saveSelectionShortcutSettings,
+ SELECTION_SHORTCUT_STORAGE_KEY,
+ shortcutFromKeyboardEvent,
+ validateSelectionShortcut,
+} from "./shortcut";
+
+describe("selection shortcut settings", () => {
+ it("uses the safe default when no preference is stored", () => {
+ expect(readSelectionShortcutSettings({ getItem: () => null })).toEqual(
+ DEFAULT_SELECTION_SHORTCUT,
+ );
+ });
+
+ it("uses the safe default when storage cannot be read", () => {
+ expect(readSelectionShortcutSettings({
+ getItem: () => { throw new DOMException("blocked", "SecurityError"); },
+ })).toEqual(DEFAULT_SELECTION_SHORTCUT);
+ });
+
+ it("keeps the enabled preference but rejects an unsafe stored key", () => {
+ const storage = {
+ getItem: () => JSON.stringify({ enabled: false, accelerator: "K" }),
+ };
+
+ expect(readSelectionShortcutSettings(storage)).toEqual({
+ enabled: false,
+ accelerator: "Alt+K",
+ });
+ });
+
+ it("persists only the shortcut preference", () => {
+ const setItem = vi.fn();
+ saveSelectionShortcutSettings(
+ { enabled: true, accelerator: "Command+Shift+J" },
+ { setItem },
+ );
+
+ expect(setItem).toHaveBeenCalledWith(
+ SELECTION_SHORTCUT_STORAGE_KEY,
+ JSON.stringify({ enabled: true, accelerator: "Command+Shift+J" }),
+ );
+ });
+});
+
+describe("shortcut capture", () => {
+ it("captures Option+K using the physical key code", () => {
+ expect(shortcutFromKeyboardEvent({
+ code: "KeyK",
+ metaKey: false,
+ ctrlKey: false,
+ altKey: true,
+ shiftKey: false,
+ })).toEqual({ accelerator: "Alt+K" });
+ });
+
+ it("waits while the user is holding only a modifier", () => {
+ expect(shortcutFromKeyboardEvent({
+ code: "AltLeft",
+ metaKey: false,
+ ctrlKey: false,
+ altKey: true,
+ shiftKey: false,
+ })).toEqual({});
+ });
+
+ it("rejects bare and Shift-only printable keys", () => {
+ expect(validateSelectionShortcut("K").error).toContain("Option");
+ expect(validateSelectionShortcut("Shift+K").error).toContain("Option");
+ });
+
+ it("rejects copy and other high-risk system shortcuts", () => {
+ expect(validateSelectionShortcut("Command+C").error).toContain("系统");
+ expect(validateSelectionShortcut("Alt+Command+C").error).toContain("系统");
+ expect(validateSelectionShortcut("Command+Q").error).toContain("系统");
+ expect(validateSelectionShortcut("Control+Space").error).toContain("系统");
+ });
+
+ it("normalizes modifier order", () => {
+ expect(validateSelectionShortcut("Shift+Alt+J")).toEqual({
+ accelerator: "Alt+Shift+J",
+ });
+ });
+
+ it("allows a bare function key", () => {
+ expect(validateSelectionShortcut("F13")).toEqual({ accelerator: "F13" });
+ });
+
+ it("requires a primary modifier for standard Mac function keys", () => {
+ expect(validateSelectionShortcut("F5").error).toContain("F1-F12");
+ expect(validateSelectionShortcut("Shift+F5").error).toContain("F1-F12");
+ expect(validateSelectionShortcut("Alt+F5")).toEqual({ accelerator: "Alt+F5" });
+ });
+
+ it("formats macOS modifiers for display", () => {
+ expect(formatSelectionShortcut("Command+Control+Alt+Shift+K")).toBe("⌘ ⌃ ⌥ ⇧ K");
+ });
+});
diff --git a/src/shortcut.ts b/src/shortcut.ts
new file mode 100644
index 0000000..7f3d9fd
--- /dev/null
+++ b/src/shortcut.ts
@@ -0,0 +1,204 @@
+export type SelectionShortcutSettings = {
+ enabled: boolean;
+ accelerator: string;
+};
+
+export type ShortcutKeyEvent = {
+ code: string;
+ metaKey: boolean;
+ ctrlKey: boolean;
+ altKey: boolean;
+ shiftKey: boolean;
+};
+
+export type ShortcutCapture = {
+ accelerator?: string;
+ error?: string;
+};
+
+type StorageReader = Pick;
+type StorageWriter = Pick;
+
+export const SELECTION_SHORTCUT_STORAGE_KEY = "wordwise-selection-shortcut";
+export const DEFAULT_SELECTION_SHORTCUT: SelectionShortcutSettings = {
+ enabled: true,
+ accelerator: "Alt+K",
+};
+
+const MODIFIER_CODES = new Set([
+ "AltLeft",
+ "AltRight",
+ "ControlLeft",
+ "ControlRight",
+ "MetaLeft",
+ "MetaRight",
+ "ShiftLeft",
+ "ShiftRight",
+]);
+
+const MODIFIER_ORDER = ["Command", "Control", "Alt", "Shift"] as const;
+const RESERVED_SHORTCUTS = new Set([
+ "Command+A",
+ "Command+F",
+ "Command+H",
+ "Command+M",
+ "Command+N",
+ "Command+O",
+ "Command+P",
+ "Command+Q",
+ "Command+S",
+ "Command+V",
+ "Command+W",
+ "Command+X",
+ "Command+Z",
+ "Command+Shift+Z",
+ "Command+Space",
+ "Control+C",
+ "Control+Space",
+]);
+
+const SPECIAL_KEYS: Record = {
+ Backquote: "Backquote",
+ Backslash: "Backslash",
+ BracketLeft: "BracketLeft",
+ BracketRight: "BracketRight",
+ Comma: "Comma",
+ Equal: "Equal",
+ Minus: "Minus",
+ Period: "Period",
+ Quote: "Quote",
+ Semicolon: "Semicolon",
+ Slash: "Slash",
+ Space: "Space",
+};
+
+const DISPLAY_KEYS: Record = {
+ Backquote: "`",
+ Backslash: "\\",
+ BracketLeft: "[",
+ BracketRight: "]",
+ Comma: ",",
+ Equal: "=",
+ Minus: "-",
+ Period: ".",
+ Quote: "'",
+ Semicolon: ";",
+ Slash: "/",
+ Space: "Space",
+};
+
+export function readSelectionShortcutSettings(
+ storage?: StorageReader,
+): SelectionShortcutSettings {
+ try {
+ const target = storage ?? localStorage;
+ const saved = JSON.parse(
+ target.getItem(SELECTION_SHORTCUT_STORAGE_KEY) ?? "{}",
+ ) as Partial;
+ const accelerator = typeof saved.accelerator === "string"
+ ? validateSelectionShortcut(saved.accelerator).accelerator
+ : undefined;
+
+ return {
+ enabled: typeof saved.enabled === "boolean"
+ ? saved.enabled
+ : DEFAULT_SELECTION_SHORTCUT.enabled,
+ accelerator: accelerator ?? DEFAULT_SELECTION_SHORTCUT.accelerator,
+ };
+ } catch {
+ return { ...DEFAULT_SELECTION_SHORTCUT };
+ }
+}
+
+export function saveSelectionShortcutSettings(
+ settings: SelectionShortcutSettings,
+ storage?: StorageWriter,
+) {
+ (storage ?? localStorage).setItem(
+ SELECTION_SHORTCUT_STORAGE_KEY,
+ JSON.stringify(settings),
+ );
+}
+
+export function shortcutFromKeyboardEvent(event: ShortcutKeyEvent): ShortcutCapture {
+ if (MODIFIER_CODES.has(event.code)) return {};
+
+ const key = keyFromCode(event.code);
+ if (!key) return { error: "这个按键不能用于全局快捷键" };
+
+ const modifiers = [
+ event.metaKey ? "Command" : "",
+ event.ctrlKey ? "Control" : "",
+ event.altKey ? "Alt" : "",
+ event.shiftKey ? "Shift" : "",
+ ].filter(Boolean);
+
+ return validateSelectionShortcut([...modifiers, key].join("+"));
+}
+
+export function validateSelectionShortcut(accelerator: string): ShortcutCapture {
+ const tokens = accelerator.split("+").map((token) => token.trim()).filter(Boolean);
+ if (tokens.length === 0) return { error: "请按下一个快捷键" };
+
+ const key = tokens.at(-1) ?? "";
+ const modifiers = tokens.slice(0, -1);
+ const allowedModifiers = new Set(MODIFIER_ORDER);
+ const uniqueModifiers = new Set(modifiers);
+ const normalizedKey = normalizeKey(key);
+
+ if (
+ uniqueModifiers.size !== modifiers.length
+ || modifiers.some((modifier) => !allowedModifiers.has(modifier))
+ || !normalizedKey
+ ) {
+ return { error: "这个快捷键格式无效" };
+ }
+
+ const allowsBareFunctionKey = /^F(?:1[3-9]|20)$/.test(normalizedKey);
+ const hasPrimaryModifier = modifiers.some((modifier) => (
+ modifier === "Command" || modifier === "Control" || modifier === "Alt"
+ ));
+ if (!allowsBareFunctionKey && !hasPrimaryModifier) {
+ return { error: "文字键和 F1-F12 必须搭配 Command、Control 或 Option" };
+ }
+
+ const normalizedModifiers = MODIFIER_ORDER.filter((modifier) => (
+ uniqueModifiers.has(modifier)
+ ));
+ const normalizedAccelerator = [...normalizedModifiers, normalizedKey].join("+");
+ if (
+ (normalizedKey === "C" && uniqueModifiers.has("Command"))
+ || RESERVED_SHORTCUTS.has(normalizedAccelerator)
+ ) {
+ return { error: "这个组合键用于系统或常用操作，请选择其他快捷键" };
+ }
+
+ return { accelerator: normalizedAccelerator };
+}
+
+export function formatSelectionShortcut(accelerator: string) {
+ const symbols: Record = {
+ Command: "⌘",
+ Control: "⌃",
+ Alt: "⌥",
+ Shift: "⇧",
+ };
+ return accelerator
+ .split("+")
+ .map((token) => symbols[token] ?? DISPLAY_KEYS[token] ?? token)
+ .join(" ");
+}
+
+function keyFromCode(code: string) {
+ if (/^Key[A-Z]$/.test(code)) return code.slice(3);
+ if (/^Digit[0-9]$/.test(code)) return code.slice(5);
+ if (/^F(?:[1-9]|1\d|20)$/.test(code)) return code;
+ return SPECIAL_KEYS[code];
+}
+
+function normalizeKey(key: string) {
+ if (/^[A-Za-z]$/.test(key)) return key.toUpperCase();
+ if (/^[0-9]$/.test(key)) return key;
+ if (/^F(?:[1-9]|1\d|20)$/.test(key.toUpperCase())) return key.toUpperCase();
+ return Object.hasOwn(SPECIAL_KEYS, key) ? key : undefined;
+}
diff --git a/src/styles.css b/src/styles.css
index c34f64c..cb28067 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -397,6 +397,17 @@ textarea::placeholder { color: #a1a8a3; }
.settings-group label:has(input[type="password"]) { grid-column: 1 / -1; }
.settings-group input { width: 100%; height: 36px; padding: 0 10px; border: 1px solid var(--line-strong); border-radius: 6px; background: #fff; color: var(--ink); font-size: 12px; }
+.shortcut-settings { grid-template-columns: 1fr; }
+.settings-group .shortcut-toggle { flex-direction: row; align-items: center; gap: 10px; color: var(--ink); }
+.settings-group .shortcut-toggle input { width: 16px; height: 16px; flex: 0 0 auto; padding: 0; accent-color: var(--green); }
+.shortcut-toggle > span { display: flex; flex-direction: column; gap: 3px; }
+.shortcut-toggle strong { font-size: 12px; }
+.shortcut-toggle small, .shortcut-recorder small { color: var(--muted); font-size: 10px; line-height: 1.4; }
+.shortcut-recorder { display: grid; grid-template-columns: minmax(0, 1fr) 36px; align-items: end; gap: 8px; }
+.shortcut-input { cursor: text; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+.shortcut-input:disabled { cursor: not-allowed; background: var(--surface); color: var(--muted); }
+.shortcut-error { margin: 0; color: var(--red); font-size: 10px; line-height: 1.4; }
+
.dialog-footer { min-height: 64px; justify-content: space-between; gap: 16px; padding: 10px 22px; color: var(--muted); font-size: 10px; }
.dialog-footer .primary-button { min-width: 92px; }
diff --git a/tests/smoke/translation.spec.ts b/tests/smoke/translation.spec.ts
index 3ce86ee..cc240c3 100644
--- a/tests/smoke/translation.spec.ts
+++ b/tests/smoke/translation.spec.ts
@@ -21,7 +21,7 @@ test("translates every sample token and opens settings", async ({ page }) => {
await expect(page.getByText("先连接一个语境翻译引擎")).toBeVisible();
await expect(page.getByRole("button", { name: "配置引擎" })).toBeVisible();
await page.getByRole("button", { name: "配置后翻译" }).click();
- await expect(page.getByRole("dialog", { name: "翻译引擎" })).toBeVisible();
+ await expect(page.getByRole("dialog", { name: "设置" })).toBeVisible();
await page.getByRole("button", { name: "关闭设置" }).click();
await page.getByLabel("翻译引擎").selectOption("dictionary");
await page.getByRole("button", { name: "逐词翻译", exact: true }).click();
@@ -31,10 +31,10 @@ test("translates every sample token and opens settings", async ({ page }) => {
await expect(page.locator(".segment-row")).toHaveCount(52);
await expect(page.locator(".segment-row").filter({ hasText: "hood" })).toContainText("内部机制");
- await page.getByRole("button", { name: "翻译引擎设置" }).click();
- const dialog = page.getByRole("dialog", { name: "翻译引擎" });
+ await page.getByRole("button", { name: "设置" }).click();
+ const dialog = page.getByRole("dialog", { name: "设置" });
await expect(dialog).toBeVisible();
- await expect(dialog.getByRole("radio", { name: /Ollama 本地/ })).toBeVisible();
+ await expect(dialog.getByRole("radio", { name: /Ollama/ })).toBeVisible();
await expect(dialog.getByText("离线逐词查义，不提供可靠整句翻译")).toBeVisible();
});
diff --git a/vitest.config.ts b/vitest.config.ts
index 1b8d7f4..c9eecdf 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -2,6 +2,6 @@ import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
- include: ["server/**/*.test.ts"],
+ include: ["server/**/*.test.ts", "src/**/*.test.ts"],
},
});