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 等生態庫。