标题栏双击最大化/还原和拖拽功能问题

一、需求描述

在标题栏空白区域实现：

• 双击最大化：双击标题栏空白区域，窗口最大化
• 双击还原：窗口已最大化时，再次双击还原到原始大小
• 窗口拖拽：按住标题栏空白区域可拖拽移动窗口
• 按钮排除：双击/拖拽按钮区域时不触发上述行为
• 平台支持：Windows 和 macOS 均需支持

二、技术背景

2.1 项目架构

• Electron + Vite + React TypeScript 桌面应用
• 标题栏组件：src/renderer/src/components/layout/title-bar.tsx
• 主进程窗口控制：src/main/ipc/menu.ipc.ts
• Preload API：src/preload/api/window.api.ts

2.2 窗口配置

typescript

// src/main/window.ts
const windowConfig = {
  // Windows: 无边框透明窗口
  frame: false,
  transparent: true,
  // macOS: 隐藏标题栏但保留红绿灯
  titleBarStyle: "hidden",
};

由于 frame: false，没有原生标题栏，所有标题栏行为都需要自行实现。

2.3 -webkit-app-region: drag 简介

• webkit-app-region: drag 是 Electron 里做自定义标题栏拖拽区域用的 CSS
• 用于窗口设置成无边框（ frame: false ），设置自定义标题的拖拽区域
• 设置了 drag 的区域，里面的按钮、输入框、链接会无法点击，如果需要点击，需要单独设置 no-drag

这是 Electron/Chromium 提供的 CSS 属性，用于标记窗口可拖拽区域。设置后：

• 鼠标拖拽该区域可移动窗口
• 双击该区域可最大化/还原窗口（原生行为）
• 代价：所有鼠标事件在 Chromium 合成器层面被拦截，不会到达 DOM

css

-webkit-app-region: drag;     /* 这个区域可以拖动窗口 */
-webkit-app-region: no-drag;  /* 这个区域不参与拖动，可以正常点击 */

三、问题定位过程

3.1 初始方案：React onDoubleClick + webkitAppRegion: drag

思路：保留原生拖拽能力，用 React 的 onDoubleClick 处理双击。

结果：拖拽正常，双击无效。

原因：-webkit-app-region: drag 在 Chromium 合成器层面拦截事件，React 的合成事件系统收不到 dblclick。

3.2 尝试：原生 addEventListener + webkitAppRegion: drag

思路：用原生 addEventListener("dblclick") 替代 React 事件。

结果：拖拽正常，双击无效。

原因：同上，事件在合成器层面被吞掉，原生 DOM 事件也收不到。

3.3 尝试：capture 阶段监听

思路：window.addEventListener("dblclick", handler, true) 在 capture 阶段抢先捕获事件。

结果：拖拽正常，双击无效。

原因：-webkit-app-region: drag 的拦截发生在 Chromium 合成器层，比 DOM 事件系统的 capture 阶段更早，任何 DOM 层面的监听都无法绕过。

3.4 尝试：主进程 before-input-event 监听

思路：在主进程的 webContents 上监听 before-input-event，检测双击。

结果：拖拽正常，双击无效。

原因：-webkit-app-region: drag 区域的事件不经过 Electron 的输入事件管道，before-input-event 不会触发。

3.5 尝试：透明覆盖层分离

思路：在标题栏上叠加两个透明层，一个负责拖拽（有 drag 属性），一个负责双击（无 drag 属性）。

结果：无论哪个层在上面，都无法同时工作。

原因：

• 双击层在上 → 双击正常，但覆盖了拖拽层导致拖拽失效
• 拖拽层在上 → 拖拽正常，但覆盖了双击层导致双击失效

3.6 尝试：移除 drag，React onDoubleClick

思路：彻底移除 -webkit-app-region: drag，用 React onDoubleClick 处理双击。

结果：双击正常，拖拽失效。

原因：移除了原生拖拽能力，需要手动实现拖拽。

3.7 尝试：移除 drag，手动拖拽 + 原生 dblclick 监听

思路：用 JavaScript 手动实现拖拽（mousedown/mousemove/mouseup + IPC），同时用原生 addEventListener("dblclick") 处理双击。

结果：拖拽正常，双击无效。

原因：关键发现 — 手动拖拽的 mousemove 处理器在双击时会被微小的鼠标位移触发，导致窗口立即移动，浏览器因此无法将两次快速点击识别为 dblclick 事件。

3.8 最终方案：移除 drag，React onDoubleClick + 阈值拖拽

• 需要手动实现拖拽、双击事件，不要依赖electron的drag的css属性

思路：用 React onDoubleClick 处理双击，手动拖拽添加 5px 激活阈值。

结果：✅ 双击和拖拽都正常。

关键修复：拖拽阈值（DRAG_THRESHOLD = 5）。双击时鼠标位移通常小于 5px，不会激活拖拽，dblclick 事件正常触发。只有鼠标移动超过 5px 后才开始拖拽。

四、最终实现方案

4.1 核心代码

typescript

// title-bar.tsx

// 双击：React onDoubleClick
<div
  ref={titleBarRef}
  onDoubleClick={(e) => {
    if ((e.target as HTMLElement).closest("button")) return;
    window.electronAPI.maximizeWindow();
  }}
>

// 拖拽：JavaScript 手动实现 + 5px 阈值
useEffect(() => {
  const DRAG_THRESHOLD = 5;
  let dragging = false;
  let pendingDrag = false;
  let startMouseX = 0, startMouseY = 0;
  let startWinX = 0, startWinY = 0;

  const onMouseDown = (e: MouseEvent) => {
    if (e.button !== 0) return;
    if ((e.target as HTMLElement).closest("button")) return;
    pendingDrag = true;
    dragging = false;
    startMouseX = e.screenX;
    startMouseY = e.screenY;
    window.electronAPI.getWindowPosition().then(([wx, wy]) => {
      startWinX = wx;
      startWinY = wy;
    });
  };

  const onMouseMove = (e: MouseEvent) => {
    if (!pendingDrag) return;
    const dx = e.screenX - startMouseX;
    const dy = e.screenY - startMouseY;
    if (!dragging) {
      if (Math.abs(dx) < DRAG_THRESHOLD && Math.abs(dy) < DRAG_THRESHOLD) return;
      dragging = true;
    }
    window.electronAPI.setWindowPosition(startWinX + dx, startWinY + dy);
  };

  const onMouseUp = () => {
    pendingDrag = false;
    dragging = false;
  };

  el.addEventListener("mousedown", onMouseDown);
  window.addEventListener("mousemove", onMouseMove);
  window.addEventListener("mouseup", onMouseUp);
}, []);

4.2 新增 IPC 通道

通道	方向	用途
WINDOW.GET_POSITION	renderer → main	获取窗口当前位置
WINDOW.SET_POSITION	renderer → main	设置窗口位置（拖拽时调用）
WINDOW.IS_MAXIMIZED	renderer → main	判断窗口是否最大化

4.3 涉及文件变更

文件	变更内容
src/renderer/src/components/layout/title-bar.tsx	双击处理 + 手动拖拽逻辑
src/main/ipc/menu.ipc.ts	新增 GET_POSITION/SET_POSITION/IS_MAXIMIZED 处理
src/preload/api/window.api.ts	暴露 getWindowPosition/setWindowPosition/isWindowMaximized
src/shared/constants/ipc-channels.ts	新增 IPC 通道常量

五、经验教训

5.1 关键认知

1. -webkit-app-region: drag 的拦截层级极低：在 Chromium 合成器层面，比 DOM 事件系统更早，任何 JS 层面的事件监听（包括 capture 阶段、主进程 input 事件）都无法绕过。

2. Electron 无边框窗口的特殊性：frame: false + transparent: true 的组合下，原生双击最大化行为可能不可靠，需要自行实现。

3. 手动拖拽与 dblclick 的冲突：双击时必然伴随微小的鼠标位移，如果 mousemove 处理器没有阈值限制，会立即移动窗口，破坏浏览器的 dblclick 识别机制。

5.2 调试方法反思

• 过度依赖 console.log 调试，浪费了大量时间在确认"事件是否触发"上
• 应该更早分析 -webkit-app-region: drag 的底层机制，而不是反复尝试不同层级的事件监听
• 最终定位到根因（mousemove 微小位移破坏 dblclick）后，修复非常简单（加阈值）

5.3 方案对比总结

方案	双击	拖拽	可行性
webkitAppRegion: drag + React onDoubleClick	❌	✅	事件被合成器拦截
webkitAppRegion: drag + 原生 addEventListener	❌	✅	同上
webkitAppRegion: drag + capture 阶段监听	❌	✅	同上
webkitAppRegion: drag + 主进程 before-input-event	❌	✅	事件不经过输入管道
透明覆盖层分离	❌	❌	层之间互相遮挡
移除 drag + React onDoubleClick	✅	❌	无拖拽能力
移除 drag + 手动拖拽（无阈值）	❌	✅	mousemove 破坏 dblclick
移除 drag + React onDoubleClick + 阈值拖拽	✅	✅	最终方案