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. 文件操作流程
// 主进程：选择文件 → 读取内容 → 返回结果
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. 窗口状态记忆
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