Electron 常用 API 全面指南

Electron 常用 API 全面指南

Electron 提供了丰富的 API 来构建跨平台桌面应用程序。以下是 Electron 中最常用和最重要的 API 分类详解：

1. 应用生命周期管理

app 模块 (主进程)

const { app } = require('electron')

// 应用事件
app.on('ready', () => {
  console.log('应用已准备好')
})

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') app.quit()
})

app.on('activate', () => {
  if (BrowserWindow.getAllWindows().length === 0) createWindow()
})

// 应用控制
app.quit() // 退出应用
app.exit(0) // 立即退出并返回状态码

// 应用信息
console.log(app.getName()) // 应用名称
console.log(app.getVersion()) // 应用版本
console.log(app.getPath('userData')) // 获取各种系统路径

2. 窗口管理

BrowserWindow 模块 (主进程)

const { BrowserWindow } = require('electron')

// 创建窗口
const win = new BrowserWindow({
  width: 800,
  height: 600,
  webPreferences: {
    nodeIntegration: true,
    contextIsolation: false,
    preload: path.join(__dirname, 'preload.js')
  }
})

// 窗口操作
win.loadURL('https://electronjs.org') // 加载URL
win.loadFile('index.html') // 加载本地文件
win.show() // 显示窗口
win.hide() // 隐藏窗口
win.close() // 关闭窗口
win.maximize() // 最大化
win.minimize() // 最小化
win.restore() // 从最小化恢复

// 窗口事件
win.on('closed', () => { win = null })
win.on('focus', () => console.log('窗口获得焦点'))

3. 进程间通信 (IPC)

ipcMain (主进程) 和 ipcRenderer (渲染进程)

主进程:

const { ipcMain } = require('electron')

// 监听渲染进程消息
ipcMain.on('renderer-event', (event, arg) => {
  console.log('收到渲染进程消息:', arg)
  event.reply('main-reply', 'pong')
})

// 处理异步请求
ipcMain.handle('get-data', async () => {
  return await fetchDataFromDB()
})

渲染进程:

const { ipcRenderer } = require('electron')

// 发送消息
ipcRenderer.send('renderer-event', 'ping')

// 接收回复
ipcRenderer.on('main-reply', (event, arg) => {
  console.log('收到主进程回复:', arg)
})

// 调用主进程方法
const data = await ipcRenderer.invoke('get-data')

4. 原生对话框

dialog 模块 (主进程)

const { dialog } = require('electron')

// 文件对话框
dialog.showOpenDialog({
  properties: ['openFile', 'multiSelections'],
  filters: [
    { name: 'Images', extensions: ['jpg', 'png', 'gif'] },
    { name: 'All Files', extensions: ['*'] }
  ]
}).then(result => {
  if (!result.canceled) {
    console.log('选择的文件:', result.filePaths)
  }
})

// 保存对话框
dialog.showSaveDialog({
  title: '保存文件',
  defaultPath: '/path/to/default.extension'
})

// 消息对话框
dialog.showMessageBox({
  type: 'info',
  title: '提示',
  message: '操作已完成',
  buttons: ['确定', '取消']
})

5. 系统托盘

Tray 模块 (主进程)

const { Tray, Menu } = require('electron')
const path = require('path')

let tray = new Tray(path.join(__dirname, 'icon.png'))

const contextMenu = Menu.buildFromTemplate([
  { label: '显示', click: () => win.show() },
  { label: '退出', click: () => app.quit() }
])

tray.setToolTip('我的应用')
tray.setContextMenu(contextMenu)

// 点击托盘图标事件 (Windows/Linux)
tray.on('click', () => win.show())

6. 菜单系统

Menu 模块 (主进程)

const { Menu } = require('electron')

// 应用菜单模板
const template = [
  {
    label: '文件',
    submenu: [
      { 
        label: '打开',
        accelerator: 'CmdOrCtrl+O',
        click: () => openFile()
      },
      { type: 'separator' },
      { role: 'quit' }
    ]
  },
  {
    label: '编辑',
    submenu: [
      { role: 'undo' },
      { role: 'redo' },
      { type: 'separator' },
      { role: 'cut' },
      { role: 'copy' },
      { role: 'paste' }
    ]
  }
]

const menu = Menu.buildFromTemplate(template)
Menu.setApplicationMenu(menu)

7. 文件系统操作

fs 模块 (主进程)

const fs = require('fs')
const fsPromises = require('fs').promises

// 同步读取文件
try {
  const data = fs.readFileSync('/path/to/file', 'utf8')
  console.log(data)
} catch (err) {
  console.error(err)
}

// 异步读取文件
fsPromises.readFile('/path/to/file', 'utf8')
  .then(data => console.log(data))
  .catch(err => console.error(err))

// 写入文件
fs.writeFile('/path/to/file', '内容', err => {
  if (err) throw err
  console.log('文件已保存')
})

8. 系统通知

Notification 模块 (主进程或渲染进程)

const { Notification } = require('electron')

// 主进程或渲染进程中
new Notification({
  title: '通知标题',
  body: '通知内容',
  silent: false,
  icon: '/path/to/icon.png'
}).show()

9. 剪贴板操作

clipboard 模块 (主进程或渲染进程)

const { clipboard } = require('electron')

// 写入剪贴板
clipboard.writeText('要复制的文本')

// 读取剪贴板
const text = clipboard.readText()
console.log('剪贴板内容:', text)

// 图片操作
const image = clipboard.readImage()
const pngData = image.toPNG() // 获取PNG格式的Buffer

10. 网络监控

net 模块 (主进程)

const { net } = require('electron')

// 发起HTTP请求
const request = net.request('https://api.example.com/data')
request.on('response', (response) => {
  console.log(`状态码: ${response.statusCode}`)
  
  response.on('data', (chunk) => {
    console.log(`收到数据: ${chunk}`)
  })
  
  response.on('end', () => {
    console.log('请求完成')
  })
})
request.end()

11. 电源监控

powerMonitor 模块 (主进程)

const { powerMonitor } = require('electron')

powerMonitor.on('suspend', () => {
  console.log('系统即将进入睡眠状态')
})

powerMonitor.on('resume', () => {
  console.log('系统已从睡眠状态恢复')
})

powerMonitor.on('on-ac', () => {
  console.log('系统正在使用交流电源')
})

powerMonitor.on('on-battery', () => {
  console.log('系统正在使用电池电源')
})

12. 全局快捷键

globalShortcut 模块 (主进程)

const { globalShortcut } = require('electron')

app.on('ready', () => {
  // 注册全局快捷键
  globalShortcut.register('CommandOrControl+X', () => {
    console.log('快捷键被触发')
  })
})

app.on('will-quit', () => {
  // 注销所有快捷键
  globalShortcut.unregisterAll()
})

13. 屏幕信息

screen 模块 (主进程)

const { screen } = require('electron')

// 获取所有显示器信息
const displays = screen.getAllDisplays()
console.log('可用显示器:', displays)

// 主显示器
const primaryDisplay = screen.getPrimaryDisplay()
console.log('主显示器:', primaryDisplay)

// 光标位置
const point = screen.getCursorScreenPoint()
console.log('当前光标位置:', point)

14. 协议处理

protocol 模块 (主进程)

const { protocol } = require('electron')

// 注册自定义协议
protocol.registerFileProtocol('myapp', (request, callback) => {
  const url = request.url.substr(8) // 去掉 'myapp://'
  callback({ path: path.join(__dirname, url) })
})

// 拦截标准协议
protocol.interceptFileProtocol('file', (request, callback) => {
  // 自定义文件协议处理
})

15. 调试工具

debugger 模块 (主进程)

const { BrowserWindow } = require('electron')

const win = new BrowserWindow()

// 启用远程调试
win.webContents.openDevTools()

// 调试命令
win.webContents.debugger.attach()
win.webContents.debugger.sendCommand('Network.enable')
win.webContents.debugger.on('message', (event, method, params) => {
  if (method === 'Network.responseReceived') {
    console.log('收到网络响应:', params)
  }
})

16. 自动更新

autoUpdater 模块 (主进程)

const { autoUpdater } = require('electron-updater')

autoUpdater.on('update-available', () => {
  console.log('发现新版本')
})

autoUpdater.on('update-downloaded', () => {
  autoUpdater.quitAndInstall()
})

// 检查更新
autoUpdater.checkForUpdatesAndNotify()

17. 系统主题

nativeTheme 模块 (主进程或渲染进程)

const { nativeTheme } = require('electron')

// 检查暗黑模式
console.log('暗黑模式启用:', nativeTheme.shouldUseDarkColors)

// 监听主题变化
nativeTheme.on('updated', () => {
  console.log('主题变化:', nativeTheme.shouldUseDarkColors ? '暗黑' : '明亮')
})

18. 安全相关

session 模块 (主进程)

const { session } = require('electron')

// 默认session
const defaultSession = session.defaultSession

// 设置权限
defaultSession.setPermissionRequestHandler((webContents, permission, callback) => {
  if (permission === 'notifications') {
    callback(false) // 拒绝通知权限
  } else {
    callback(true)
  }
})

// 清除缓存
defaultSession.clearCache().then(() => {
  console.log('缓存已清除')
})

19. 子进程管理

使用 Node.js 的 child_process 模块

const { exec, spawn } = require('child_process')

// 执行简单命令
exec('ls -l', (error, stdout, stderr) => {
  if (error) throw error
  console.log(stdout)
})

// 生成长时间运行的进程
const pythonProcess = spawn('python', ['script.py'])

pythonProcess.stdout.on('data', (data) => {
  console.log(`Python输出: ${data}`)
})

pythonProcess.stderr.on('data', (data) => {
  console.error(`Python错误: ${data}`)
})

20. 性能监控

app 模块的指标方法

const { app } = require('electron')

// 获取内存使用情况
console.log('内存使用:', app.getAppMetrics())

// 获取GPU信息
app.getGPUFeatureStatus()
app.getGPUInfo('complete').then(info => {
  console.log('GPU信息:', info)
})