Electron 核心模块速查表

为了更全面地覆盖常用 API，以下表格补充了更多实用方法和场景化示例，同时保持格式清晰易读。

一、主进程模块

模块名	核心用途	关键用法 + 示例	注意事项
app	应用生命周期管理	• 退出应用：`app.quit()` • 重启应用：`app.relaunch()` 后需 `app.quit()` • 获取版本信息：`app.getVersion()` • 检查是否打包：`app.isPackaged` • 跨平台退出逻辑： `app.on('window-all-closed', () => { if (process.platform !== 'darwin') app.quit()})`	• 重启应用需先调用 `relaunch()` 再 `quit()` • `isPackaged` 可区分开发/生产环境 • macOS 下窗口全关后应保留应用实例
BrowserWindow	窗口管理	• 置顶窗口：`win.setAlwaysOnTop(true)` • 全屏切换：`win.setFullScreen(!win.isFullScreen())` • 隐藏/显示：`win.hide()` / `win.show()` • 设置标题：`win.setTitle('新标题')` • 获取所有窗口：`BrowserWindow.getAllWindows()`	• 全屏时建议提供退出按钮 • 频繁显隐比创建销毁更高效 • 多窗口应用注意内存泄漏
ipcMain	主进程通信	• 一次性监听：`ipcMain.once('channel', callback)` • 发送消息给所有窗口： `BrowserWindow.getAllWindows().forEach(w => w.webContents.send('msg', data))` • 异步处理：`ipcMain.handle('task', asyncHandler)`	• `once` 适合初始化类消息 • 广播消息注意过滤已关闭窗口 • `handle` 支持返回 Promise
Menu	应用菜单管理	• 创建菜单： `const menu = Menu.buildFromTemplate([ { label: '文件', submenu: [ { label: '退出', click: () => app.quit() } ]}])Menu.setApplicationMenu(menu)` • 上下文菜单： `win.webContents.on('context-menu', () => menu.popup())`	• macOS 应用菜单第一项是应用名称 • 上下文菜单需监听右键事件 • 动态更新菜单使用 `menu.items[index].visible = false`
Tray	系统托盘图标	• 创建托盘： `const tray = new Tray('icon.png')<br>tray.setToolTip('我的应用')<br>tray.setContextMenu(menu)` • 点击显示窗口：`tray.on('click', () => win.show())`	• 图标路径需绝对路径 • macOS 托盘点击行为与 Windows 不同 • Linux 需安装额外依赖
dialog	系统对话框	• 错误提示：`dialog.showErrorBox('错误', '文件读取失败')` • 多选文件： `dialog.showOpenDialog({ properties: ['openFile', 'multiSelections']})` • 保存文件：`dialog.showSaveDialog()`	• `showErrorBox` 无需异步处理 • 大文件选择可设置过滤器 • 保存对话框可预设文件名
session	会话管理	• 清除缓存： `session.defaultSession.clearStorageData({ type: 'cache'})` • 拦截请求： `session.defaultSession.webRequest.onBeforeRequest( filter, callback)`	• 清除数据是异步操作 • 请求拦截需在页面加载前设置 • 可用于实现离线模式或广告拦截

二、渲染进程模块

模块名	核心用途	关键用法 + 示例	注意事项
ipcRenderer	渲染进程通信	• 发送同步消息（不推荐）： `const result = ipcRenderer.sendSync('sync-channel', data)` • 移除所有监听：`ipcRenderer.removeAllListeners('channel')` • 异步调用：`ipcRenderer.invoke('async-task')`	• 同步消息会阻塞UI，谨慎使用 • 组件卸载时务必移除监听 • `invoke` 配合 `ipcMain.handle` 使用
webFrame	页面渲染控制	• 缩放页面：`webFrame.setZoomFactor(1.2)` • 插入CSS： `webFrame.insertCSS('body { background: #f0f0f0; }')` • 设置文本缩放：`webFrame.setTextZoomFactor(150)`	• 仅在渲染进程可用 • 缩放会影响所有内容 • 可用于实现阅读模式
Notification	系统通知	• 带图标和点击事件： `new Notification({ title: '提醒', body: '有新消息', icon: 'notification.png'}).onclick = () => window.focus()`	• 部分系统会限制频繁通知 • 图标尺寸建议 128x128 • 需用户授权才能显示
clipboard	剪贴板操作	• 复制HTML：`clipboard.writeHTML('<b>加粗文本</b>')` • 读取RTF：`clipboard.readRTF()` • 复制富文本：`clipboard.write({ text, html })`	• 复杂格式复制在不同系统表现可能不同 • 大内容复制可能影响性能 • 安全考虑，部分敏感操作需确认

三、通用模块

模块名	核心用途	关键用法 + 示例	注意事项
shell	系统交互	• 移动文件到回收站： `shell.trashItem('/path/to/file')` • 打开外部链接：`shell.openExternal('https://github.com')` • 显示在文件管理器中：`shell.showItemInFolder('/path/to/file')`	• 回收站操作不可恢复 • 目录路径必须存在 • `openExternal` 有安全风险，需验证URL
nativeImage	图像处理	• 从Base64创建： `nativeImage.createFromDataURL(base64Str)` • 保存为文件： `fs.writeFileSync('out.png', image.toPNG())` • 调整大小：`image.resize({ width: 64 })`	• 大图片处理可能占用较多内存 • 支持格式：PNG, JPEG, ICO, ICNS • 可用于生成托盘图标或缩略图
screen	屏幕信息	• 获取主屏幕尺寸： `screen.getPrimaryDisplay().workAreaSize` • 所有屏幕信息：`screen.getAllDisplays()` • 监听显示变化：`screen.on('display-added', callback)`	• 多显示器环境需判断窗口所在屏幕 • 屏幕尺寸可能随分辨率变化 • 可用于实现多屏展示应用
process	进程信息	• 环境变量：`process.env.NODE_ENV` • 内存使用： `process.getProcessMemoryInfo()` • 架构信息：`process.arch`	• 渲染进程中环境变量可能受限 • 内存信息获取是异步操作 • 可用于条件加载不同资源
crashReporter	崩溃报告	• 配置崩溃报告： `crashReporter.start({ productName: 'MyApp', companyName: 'MyCompany', submitURL: 'https://my-server.com/crashes'})`	• 需在应用启动早期配置 • 开发环境可能不触发 • 可结合 Sentry 等服务使用

四、应用生命周期深度解析

1. 生命周期阶段与核心事件

Electron 应用生命周期可分为四个阶段：

阶段 1：启动初始化

事件/方法	作用	示例
`app.whenReady()`	返回 Promise，等待应用就绪	`app.whenReady().then(createWindow)`
`will-finish-launching`	macOS 特有，启动初期事件	`app.on('will-finish-launching', () => { app.setAsDefaultProtocolClient('myapp')})`
`app.isReady()`	检查是否已就绪	`if (!app.isReady()) waitFirst`

阶段 2：运行中交互

事件/方法	作用	示例
`activate`	应用被激活（如点击 Dock）	`app.on('activate', () => { if (noWindows) createWindow()})`
`second-instance`	重复启动实例	`app.on('second-instance', () => { mainWindow.focus()})`
`open-file`	文件拖拽到应用（macOS）	`app.on('open-file', (e,f) => { sendToRenderer(f)})`

阶段 3：退出前准备

事件/方法	作用	示例
`before-quit`	即将退出（可取消）	`app.on('before-quit', (e) => { if (unsaved) e.preventDefault()})`
`will-quit`	即将退出（不可取消）	`app.on('will-quit', cleanupResources)`
`app.exit()`	强制退出（不触发事件）	`process.on('uncaughtException', () => app.exit(1))`

阶段 4：退出完成

事件/方法	作用	示例
`quit`	应用已退出	app.on('quit', (e, code) => { log(`退出码: ${code}`)})

五、场景化API组合示例

1. 文件操作流程

javascript 复制代码

// 主进程：选择文件 → 读取内容 → 返回结果
ipcMain.handle('read-file', async (e) => {
  const { filePaths } = await dialog.showOpenDialog({
    properties: ['openFile'],
    filters: [{ name: 'Text', extensions: ['txt'] }]
  });
  if (filePaths.length > 0) {
    return fs.promises.readFile(filePaths[0], 'utf8');
  }
});

// 渲染进程：调用 → 显示结果
document.querySelector('#read-btn').addEventListener('click', async () => {
  try {
    const content = await ipcRenderer.invoke('read-file');
    document.querySelector('#content').textContent = content;
  } catch (err) {
    console.error('读取失败:', err);
  }
});

2. 窗口状态记忆

javascript 复制代码

const STATE_FILE = path.join(app.getPath('userData'), 'window-state.json');

// 保存窗口状态
function saveWindowState(win) {
  const state = { ...win.getBounds(), isMaximized: win.isMaximized() };
  fs.writeFileSync(STATE_FILE, JSON.stringify(state));
}

// 恢复窗口状态
function loadWindowState() {
  try {
    return JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
  } catch (e) {
    return { width: 800, height: 600 };
  }
}

// 创建窗口时应用状态
app.whenReady().then(() => {
  const state = loadWindowState();
  let win = new BrowserWindow({
    x: state.x,
    y: state.y,
    width: state.width,
    height: state.height,
    webPreferences: { contextIsolation: true }
  });

  if (state.isMaximized) win.maximize();

  win.on('close', () => saveWindowState(win));
});

这份速查表涵盖了 Electron 开发中 80% 的常用 API 和典型场景。建议根据具体需求结合官方文档深入学习，并关注安全性最佳实践（如启用 contextIsolation、使用 contextBridge 暴露 API）。对于复杂功能，可进一步查阅 electron-store、electron-builder 等生态库。

六、Electron 官网 API

https://www.electronjs.org/zh/docs/latest/api/app