Electron mainWindow.restore() 失效问题

问题描述

在开发 Electron 应用过程中，当创建窗口时设置 transparent: true 属性，会导致 win.restore() 方法失效。

具体表现为：

• 当窗口处于最大化状态时，调用 win.restore() 无法将窗口恢复到原始大小
• 窗口仍然保持最大化状态，没有任何视觉变化
• 这个问题只在窗口设置了 transparent: true 时出现

注意： Electron 版本为 21.4.4。

问题重现

以下是一个可以复现该问题的简化代码示例：

const { app, BrowserWindow } = require("electron");

let mainWindow;

function createWindow() {
  // 创建带有透明背景的窗口
  mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    transparent: true, // 关键配置，设置为true会导致问题
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false,
    },
  });

  // 加载应用
  mainWindow.loadFile("index.html");

  // 示例：绑定窗口控制按钮事件
  setTimeout(() => {
    // 1. 先最大化窗口
    mainWindow.maximize();
    console.log("窗口已最大化");

    // 2. 尝试恢复窗口（这里会失效）
    setTimeout(() => {
      mainWindow.restore();
      console.log("尝试恢复窗口，但操作会失效");
    }, 2000);
  }, 2000);
}

app.whenReady().then(() => {
  createWindow();

  app.on("activate", function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow();
  });
});

app.on("window-all-closed", function () {
  if (process.platform !== "darwin") app.quit();
});

原因分析

这是 Electron 旧版本中的一个已知 Bug：

1. 根本原因：在窗口设置了透明属性 (transparent: true) 的情况下，Electron 的窗口管理器在处理 restore() 操作时存在逻辑错误
2. 技术细节：当窗口透明化时，窗口的边界和状态跟踪机制发生变化，导致 restore() 方法无法正确识别和恢复窗口的原始尺寸
3. 影响范围：该问题主要影响 Electron 21.x 及以下版本，在较新的版本中已经修复

解决方案

针对这个问题，有两种可行的解决方案：

方案一：禁用窗口透明属性

最简单直接的解决方案是在创建窗口时不使用透明背景：

mainWindow = new BrowserWindow({
  width: 800,
  height: 600,
  transparent: false, // 设置为false解决问题
  webPreferences: {
    nodeIntegration: true,
    contextIsolation: false,
  },
});

优点：实现简单，无需额外代码 缺点：无法使用窗口透明效果

方案二：使用 maximize/unmaximize 替代 restore

如果需要保持窗口透明效果，可以使用 win.maximize() 和 win.unmaximize() 方法来控制窗口状态，而不是使用 win.restore()：

// 检查窗口是否最大化
function toggleWindowState() {
  if (mainWindow.isMaximized()) {
    // 使用unmaximize代替restore
    mainWindow.unmaximize();
  } else {
    mainWindow.maximize();
  }
}

// 使用示例
setTimeout(() => {
  // 1. 先最大化窗口
  mainWindow.maximize();
  console.log("窗口已最大化");

  // 2. 使用unmaximize恢复窗口
  setTimeout(() => {
    mainWindow.unmaximize();
    console.log("窗口已恢复到原始大小");
  }, 2000);
}, 2000);

优点：可以保持窗口透明效果 缺点：需要额外的状态检查逻辑

方案三：升级 Electron 版本

如果项目允许，可以考虑升级到较新版本的 Electron，该问题在后续版本中可能已经修复：

# 更新package.json中的Electron版本
npm install electron@latest --save-dev

完整解决方案示例

以下是一个完整的实现示例，展示如何在保持窗口透明的情况下正确管理窗口状态：

const { app, BrowserWindow } = require("electron");

let mainWindow;
let windowSize = { width: 800, height: 600 }; // 保存原始窗口尺寸
let isMaximized = false; // 跟踪窗口状态

function createWindow() {
  // 创建带有透明背景的窗口
  mainWindow = new BrowserWindow({
    width: windowSize.width,
    height: windowSize.height,
    transparent: true,
    webPreferences: {
      nodeIntegration: true,
      contextIsolation: false,
    },
  });

  // 加载应用
  mainWindow.loadFile("index.html");

  // 监听窗口事件，更新状态
  mainWindow.on("maximize", () => {
    isMaximized = true;
  });

  mainWindow.on("unmaximize", () => {
    isMaximized = false;
  });

  // 示例：自定义窗口控制函数
  global.toggleWindow = function () {
    if (isMaximized) {
      mainWindow.unmaximize();
    } else {
      mainWindow.maximize();
    }
  };

  global.restoreWindow = function () {
    if (isMaximized) {
      mainWindow.unmaximize();
    }
  };
}

app.whenReady().then(() => {
  createWindow();

  app.on("activate", function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow();
  });
});

app.on("window-all-closed", function () {
  if (process.platform !== "darwin") app.quit();
});

注意事项

1. 版本兼容性：不同版本的 Electron 可能存在差异，建议在特定版本上进行充分测试
2. 平台差异：Windows、macOS 和 Linux 平台的窗口行为可能略有不同，需要考虑跨平台兼容性
3. 性能影响：使用透明窗口可能会对应用性能产生一定影响，特别是在低配置设备上
4. 用户体验：在某些情况下，使用替代方案可能会导致窗口状态转换不够流畅，需要进行适当的用户体验优化
5. 安全考虑：如果使用 nodeIntegration: true 和 contextIsolation: false，请注意潜在的安全风险