Electron中调用`win.maximize()`后为何无法真正全屏？

Question

在 Electron 中调用 `win.maximize()` 后窗口看似铺满屏幕，但实际并非“真正全屏”——它仅最大化至桌面可用区域（扣除任务栏/ Dock 高度），且仍显示窗口边框、标题栏及系统菜单栏。这与 `win.setFullScreen(true)` 实现的无边框、无任务栏遮挡、独占显示的**真全屏模式**有本质区别。常见误判源于混淆“最大化”（maximize）与“全屏”（fullscreen）语义：前者是窗口管理行为，受 OS 窗口装饰和多显示器布局影响；后者触发 OS 全屏 API（如 Windows 的 `WS_EX_TOPMOST` + `SW_MAXIMIZE` 组合、macOS 的 `NSFullScreenWindowMask`），并自动隐藏 Dock/菜单栏。此外，若主进程未正确配置 `frame: false` 或渲染进程未处理 `resize`/`enter-full-screen` 事件，也可能导致视觉异常。调试时建议检查 `win.isMaximized()` 与 `win.isFullScreen()` 返回值，并确认 `mainWindow` 创建时是否禁用 `titleBarStyle` 或启用了 `transparent` 等干扰样式。

Answer 1

```html

一、概念辨析：最大化（Maximize）≠ 全屏（Fullscreen）

这是绝大多数 Electron 开发者踩入的第一个认知陷阱。调用 win.maximize() 仅触发 OS 窗口管理器的“最大化布局策略”，即计算当前显示器的 可用工作区（work area） —— 自动扣除任务栏（Windows）、Dock（macOS）或面板（Linux）所占空间；而 win.setFullScreen(true) 则调用原生全屏 API，强制进入独占渲染模式，隐藏系统 UI 元素并绕过窗口管理器布局约束。二者在 Windows 上分别对应 SW_MAXIMIZE 与 WS_EX_TOPMOST | WS_EX_LAYERED + 全屏状态切换，在 macOS 中则对应 NSWindowStyleMaskTitled vs NSFullScreenWindowMask。关键区别见下表：

维度	maximize()	setFullScreen(true)
窗口边框/标题栏	保留（除非 frame: false）	强制隐藏（OS 级压制）
任务栏/Dock 遮挡	存在（占用工作区顶部/底部）	自动隐藏，无遮挡
多显示器行为	仅在主显示器或当前显示器最大化	可跨显示器全屏（需显式指定 screen）

二、运行时诊断：如何精准判断当前状态？

依赖视觉判断极易出错。应始终通过 Electron 提供的布尔状态 API 进行断言：

// 主进程示例
console.log('isMaximized:', win.isMaximized());     // true / false  
console.log('isFullScreen:', win.isFullScreen());   // true / false
console.log('isVisible:', win.isVisible());         // 排查渲染阻塞
console.log('getBounds():', win.getBounds());       // 查看实际坐标与尺寸

特别注意：isMaximized() 与 isFullScreen() 互斥但非互补 —— 窗口可同时为 false/false（普通窗口），也可为 true/false（最大化非全屏），但绝不会为 true/true（Electron 内部会自动解除 maximize 状态以进入 fullscreen）。调试时建议在 'maximize'、'enter-full-screen'、'resize' 事件中埋点日志。

三、配置陷阱：frame、titleBarStyle 与 transparent 的隐式干扰

即使调用了 setFullScreen(true)，若窗口创建时未合理配置基础选项，仍会导致“伪全屏”现象：

• frame: true（默认）→ 标题栏和边框强制显示，全屏时 OS 无法完全接管装饰控制；
• titleBarStyle: 'hidden' 或 'customButtonsOnHover' → 在 macOS 下可能与全屏动画冲突，导致 Dock 未隐藏；
• transparent: true → 启用透明后，部分平台（尤其是 Windows 10/11）会禁用硬件加速全屏路径，回退至软件合成，造成闪烁或菜单栏残留。

✅ 正确最小化配置模板：

const mainWindow = new BrowserWindow({
  width: 1280,
  height: 720,
  frame: false,                    // 必须关闭原生边框
  webPreferences: {
    nodeIntegration: false,
    contextIsolation: true,
    enableRemoteModule: false
  }
});

四、跨平台行为差异与适配策略

不同操作系统对“全屏”的语义实现存在底层差异，需针对性处理：

1. Windows：全屏时默认不隐藏任务栏，需配合 win.setIgnoreMouseEvents(true, { forward: false }) 防止鼠标逃逸，并监听 'leave-full-screen' 恢复任务栏可见性；
2. macOS：启用 fullScreenable: true（默认），但若应用未签名或未启用 NSHighResolutionCapable Info.plist 键，可能降级为“伪全屏”；
3. Linux（X11）：依赖窗口管理器（如 GNOME/Mutter），需测试 skipTaskbar: true + alwaysOnTop: true 组合是否生效。

五、事件驱动闭环：从触发到渲染的端到端响应链

真正的全屏体验需主进程与渲染进程协同。以下是典型事件流与推荐处理范式：

graph LR
  A[用户点击全屏按钮] --> B[渲染进程发送 IPC：'toggle-fullscreen']
  B --> C[主进程 win.setFullScreen(!win.isFullScreen())]
  C --> D{OS 触发 enter-full-screen}
  D --> E[主进程 emit 'enter-full-screen']
  E --> F[渲染进程监听并更新 CSS 类 .is-fullscreen]
  F --> G[CSS 应用 :fullscreen 伪类 & 移除 padding/margin]
  G --> H[完成视觉闭环]

⚠️ 若缺失 enter-full-screen 监听，渲染层将无法响应尺寸突变，导致内容错位或滚动条异常。务必在 webPreferences.contextIsolation === true 下使用 contextBridge 安全暴露控制接口。

六、进阶实践：构建可切换的沉浸式模式（Kiosk Mode Ready）

面向数字标牌、医疗终端等场景，需融合全屏、无鼠标、防退出、热键锁定能力：

// 主进程增强逻辑
win.setFullScreen(true);
win.setIgnoreMouseEvents(true);
win.setKiosk(true); // 强制 kiosk 模式（macOS/Windows）
app.on('browser-window-blur', () => win.focus()); // 防失焦退出

// 渲染进程绑定 ESC 禁用
window.addEventListener('keydown', (e) => {
  if (e.key === 'Escape') e.preventDefault();
});

该模式下 setKiosk(true) 将覆盖所有窗口管理行为，包括禁用 Alt+Tab、Win 键、Cmd+Tab，并阻止右键菜单——比单纯 setFullScreen 更彻底，适用于强管控终端环境。

```