简介

Electron 主进程功能模块。提供应用生命周期管理（electronApp、createElectron）和窗口管理（getMainWindow、createMainWindow、restoreMainWindow 等）。所有 Electron 相关 API 由框架重新导出或封装。

重要

所有 Electron 相关 API 不能在子进程（jobs）或渲染进程中使用。仅在主进程中可用。

导入

// CJS
const {
  electronApp,
  createElectron,
  getMainWindow,
  createMainWindow,
  restoreMainWindow,
  setCloseAndQuit,
  getCloseAndQuit,
  loadServer,
} = require('ee-core/electron');

// ESM
import {
  electronApp,
  createElectron,
  getMainWindow,
  createMainWindow,
  restoreMainWindow,
  setCloseAndQuit,
  getCloseAndQuit,
  loadServer,
} from 'ee-core/electron';

Electron App

electronApp

说明：Electron app 模块，为方便使用而重新导出。提供所有标准 Electron app API。使用 electronApp 访问路径、名称、版本、生命周期方法及其他标准 app 模块功能。

返回值：Electron.App — Electron app 模块对象

示例：

import { electronApp } from 'ee-core/electron';

electronApp.getPath('exe')       // 可执行文件路径
electronApp.getPath('home')      // 用户主目录
electronApp.getPath('userData')  // 用户数据目录
electronApp.getName()            // 应用名称
electronApp.getVersion()         // 应用版本
electronApp.isPackaged           // 是否已打包
electronApp.whenReady()          // app 就绪 Promise

官方文档：https://www.electronjs.org/docs/latest/api/app

---

createElectron()

说明：创建并启动 Electron 应用。执行流程：

1. 检查单实例锁（config.singleLock=true 防止同时运行多个实例；若已有实例运行则退出当前实例）
2. 等待 app.whenReady() 完成
3. 创建主窗口，触发 Preload 事件，加载服务页面，触发 ElectronAppReady 事件
4. 注册系统事件监听器：window-all-closed（非 macOS 退出应用）、before-quit（清理跨进程服务和子任务）

返回值：void

注意

此函数在 Application.run() 启动流程末尾由 loadElectron() 内部调用。通常无需直接调用。

---

loadElectron()

说明：加载 Electron 主进程功能。调用 createElectron() 创建应用并注册系统事件。在框架启动流程中由 Application.run() 最后调用。

返回值：void

注意

此函数由框架内部调用。通常不在应用代码中直接使用。

Electron 窗口

getMainWindow()

说明：获取主窗口实例。返回在 WindowReady 生命周期事件之后保证非空的 BrowserWindow。

返回值：BrowserWindow — 主窗口实例

抛出：如果在 mainWindow 创建之前调用（即在 WindowReady 事件之前）抛出 Error。这表示生命周期顺序错误。

示例：

import { getMainWindow } from 'ee-core/electron';

const win = getMainWindow();
win.setSize(800, 600);
win.center();
win.setMenuBarVisibility(false);

注意

v5 变更：getMainWindow() 现返回 BrowserWindow（而非 BrowserWindow | null）。在 WindowReady 生命周期事件后无需空值检查。如果在窗口创建前调用，会抛出 Error 提示生命周期顺序错误。

---

createMainWindow()

说明：使用 config.windowsOption 配置创建主应用窗口。当配置中 openDevTools=true 时，页面加载完成后自动打开开发者工具。窗口创建后触发 WindowReady 生命周期事件。

返回值：BrowserWindow — 创建的窗口实例

注意

此函数由 createElectron() 内部调用。通常无需直接调用，除非实现自定义窗口创建逻辑。

---

restoreMainWindow()

说明：如果主窗口最小化，则恢复、显示并聚焦它。用于第二个实例启动时（单实例锁场景）激活已有实例的窗口。

返回值：void

示例：

import { electronApp, restoreMainWindow } from 'ee-core/electron';

electronApp.on('second-instance', () => {
  restoreMainWindow();
});

---

setCloseAndQuit(flag)

说明：设置控制窗口退出行为的标志。当 flag=true 时，窗口关闭后应用将退出。适用于托盘图标场景——关闭窗口不应退出应用。

参数：

参数	类型	必填	说明
flag	boolean	是	true 表示窗口关闭后应用退出

返回值：void

示例：

import { getMainWindow, setCloseAndQuit } from 'ee-core/electron';

const win = getMainWindow();
win.on('close', (e) => {
  const closeAndQuit = getCloseAndQuit();
  if (!closeAndQuit) {
    e.preventDefault();
    win.hide(); // 隐藏到托盘而非退出
  }
});

// 当用户明确想要退出时
setCloseAndQuit(true);

---

getCloseAndQuit()

说明：获取当前的 close-and-quit 标志值。默认为 true。

返回值：boolean — closeAndQuit 标志

参见：setCloseAndQuit()

---

loadServer()

说明：根据配置和环境加载服务页面内容。选择页面加载策略：

1. 远程模式（config.remote.enable=true） -> 通过 loadURL 直接加载远程 URL
2. 开发环境 -> 加载前端开发服务器（轮询等待就绪），先显示加载页，超时显示失败页
3. 生产 + 跨进程接管（config.mainServer.takeover） -> 等待跨进程服务（Go/Python 后端）就绪后加载其 URL
4. 生产环境（默认） -> 通过 loadFile 加载本地打包的 HTML 文件

开发模式下使用 HTTP URL 时：显示加载页（如配置了 config.dev.electron.loadingPage），轮询前端开发服务器最多 60 次（force=true 时 3 次），服务器不可达时显示失败页。

跨进程接管模式下：显示加载页，轮询跨进程服务 URL，超时时显示跨进程失败页。

返回值：Promise<void>

注意

此函数由 createElectron() 内部调用。通常无需直接调用，除非实现自定义页面加载逻辑。