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

Electron API 详细文档

目录

1. app 模块
2. BrowserWindow 模块
3. ipcMain 和 ipcRenderer 模块
4. 系统资源 模块
5. dialog 模块
6. menu 和 MenuItem 模块
7. shell 模块
8. clipboard 模块
9. powerMonitor 模块
10. systemPreferences 模块
11. globalShortcut 模块
12. 其他常用模块
13. 最佳实践和注意事项

app 模块

app 模块用于控制应用的生命周期，是整个应用的入口模块。一般在 Electron 项目的 main.js 文件中引用并初始化 app。

• 基本配置和生命周期事件：

  • app.on('ready')：表示 Electron 已经初始化完毕，可以创建浏览器窗口。
  • app.on('window-all-closed')：监听所有窗口关闭，通常用于在非 macOS 系统中退出应用。
  • app.on('before-quit')：在应用退出前执行一些清理操作，比如保存状态、释放资源。
  • app.on('activate')：macOS 专用，用户点击 dock 图标时重新打开窗口。

• 常用方法：

  • app.quit()：退出应用。
  • app.relaunch()：重新启动应用，用于应用更新等场景。
  • app.getAppPath()：返回应用的根目录路径。
  • app.getPath(name)：获取应用特定目录的路径（如缓存、临时文件、用户数据等）。
  • app.setAppUserModelId()：设置应用的用户模型 ID，提升在 Windows 上的通知能力。

• 示例：

  const { app } = require('electron');
  
  app.on('ready', () => {
    createMainWindow(); // 创建主窗口
  });
  
  app.on('window-all-closed', () => {
    if (process.platform !== 'darwin') {
      app.quit();
    }
  });
  
  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
      createMainWindow();
    }
  });
  

BrowserWindow 模块

BrowserWindow 模块用于创建和管理应用中的窗口，是 Electron 的核心组件。

• 创建窗口的配置项：

  • width 和 height：窗口宽度和高度。
  • fullscreen：是否全屏显示。
  • resizable：窗口是否可以调整大小。
  • transparent：设置透明窗口。
  • frame：设置无边框窗口（通常用于自定义窗口界面）。

• webPreferences 选项：

  • nodeIntegration：是否在渲染进程中启用 Node.js（通常为 false，以提高安全性）。
  • contextIsolation：启用上下文隔离，提升安全性。
  • preload：指定预加载脚本的路径，常用于安全地与渲染进程通信。

• 示例：

  const { BrowserWindow } = require('electron');
  let win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      nodeIntegration: false,
      contextIsolation: true,
      preload: path.join(__dirname, 'preload.js')
    }
  });
  
  win.loadURL('https://example.com');
  

• 窗口事件：

  • closed：窗口关闭时触发。
  • focus 和 blur：窗口获得或失去焦点时触发。

ipcMain 和 ipcRenderer 模块

ipcMain 和 ipcRenderer 模块是主进程和渲染进程之间的通信桥梁。

• ipcMain 用法：

  const { ipcMain } = require('electron');
  
  ipcMain.on('message-from-renderer', (event, arg) => {
    console.log('Received:', arg);
    event.reply('message-from-main', 'Hello from main process');
  });
  

• ipcRenderer 用法：

  const { ipcRenderer } = require('electron');
  ipcRenderer.send('message-from-renderer', 'Hello from renderer process');
  
  ipcRenderer.on('message-from-main', (event, response) => {
    console.log('Main said:', response);
  });
  

• 异步通信示例：

  // main.js
  ipcMain.handle('async-message', async (event, data) => {
    return await someAsyncFunction(data);
  });
  
  // renderer.js
  const response = await ipcRenderer.invoke('async-message', 'Hello');
  

Electron 系统资源相关模块

os 模块

os 模块来自 Node.js，可以直接在 Electron 中使用，用于获取操作系统的信息，如 CPU、内存、网络接口等。

常用方法

• os.platform()：返回操作系统平台（如 win32、linux、darwin）。
• os.type()：返回操作系统类型（如 Windows_NT、Linux、Darwin）。
• os.arch()：返回 CPU 架构（如 x64、arm）。
• os.cpus()：返回一个对象数组，包含每个逻辑 CPU 内核的信息。
• os.totalmem()：返回系统的总内存，以字节为单位。
• os.freemem()：返回空闲的系统内存，以字节为单位。
• os.networkInterfaces()：返回网络接口的详细信息。
• os.uptime()：返回系统已启动时间，以秒为单位。
  示例

const os = require('os');

console.log('操作系统平台:', os.platform());
console.log('操作系统类型:', os.type());
console.log('CPU 架构:', os.arch());
console.log('CPU 信息:', os.cpus());
console.log('总内存:', os.totalmem() / (1024 ** 3), 'GB');
console.log('空闲内存:', os.freemem() / (1024 ** 3), 'GB');
console.log('网络接口:', os.networkInterfaces());
console.log('系统已启动时间:', os.uptime(), '秒');

process 模块

process 模块用于访问应用和系统的进程信息，包括内存使用、Node.js 版本等。

常用属性和方法

• process.platform：当前平台，和 os.platform() 类似。
• process.arch：当前 CPU 架构。
• process.memoryUsage()：返回一个对象，包含当前应用的内存使用情况。
• process.uptime()：返回当前应用的运行时间。
• process.getCPUUsage()：返回 CPU 使用信息（Electron 特有）。
• process.versions：返回一个对象，包含 Node.js、V8 引擎等版本信息。
• process.env：系统环境变量。
  示例

console.log('平台:', process.platform);
console.log('架构:', process.arch);
console.log('内存使用情况:', process.memoryUsage());
console.log('应用运行时间:', process.uptime(), '秒');
console.log('CPU 使用情况:', process.getCPUUsage());
console.log('Node.js 版本:', process.versions.node);
console.log('V8 引擎版本:', process.versions.v8);

powerMonitor 模块

powerMonitor 是 Electron 专有模块，用于监控系统的电源状态。它可以监听系统的睡眠、唤醒等状态，非常适合用于节能、恢复操作等场景。

常用事件
suspend：系统进入睡眠模式时触发。
resume：系统从睡眠模式恢复时触发。
on-ac：设备切换到交流电源时触发。
on-battery：设备切换到电池供电时触发。
示例

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('系统已切换到电池供电');
});

systemPreferences 模块（macOS 和 Windows）

systemPreferences 模块主要用于访问系统的一些偏好设置和配置信息，特别是用户界面的外观设置，比如暗黑模式、通知权限等。

常用方法

• systemPreferences.isDarkMode()：判断当前系统是否为暗黑模式。
• systemPreferences.isInvertedColorScheme()：判断系统是否使用反转颜色方案。
• systemPreferences.getUserDefault(key, type)：获取系统配置项（仅 macOS 支持）。
  systemPreferences.askForMediaAccess()：请求应用的媒体设备访问权限（macOS）。
  示例

const { systemPreferences } = require('electron');

if (systemPreferences.isDarkMode()) {
  console.log('当前系统为暗黑模式');
}

systemPreferences.getUserDefault('AppleInterfaceStyle', 'string');

os-utils 第三方库

os-utils 是一个 Node.js 库，专门用于实时获取系统资源使用情况，比如 CPU 使用率、空闲率等。虽然不是 Electron 自带模块，但可安装并在 Electron 中使用。

安装

npm install os-utils

使用示例

const os = require('os-utils');

os.cpuUsage(function(v){
  console.log('CPU 使用率 (%): ' + v * 100);
});

os.freememPercentage(function(v){
  console.log('空闲内存比例 (%): ' + v * 100);
});

dialog 模块

dialog 模块提供了系统的对话框，可以显示消息、警告、错误提示等。

• 文件对话框示例：

  const { dialog } = require('electron');
  dialog.showOpenDialog({
    properties: ['openFile', 'multiSelections']
  }).then(result => {
    console.log('Selected files:', result.filePaths);
  });
  

• 消息框示例：

  dialog.showMessageBox({
    type: 'info',
    title: 'Information',
    message: 'Operation Successful',
    buttons: ['OK', 'Cancel']
  }).then(result => {
    console.log('User selected button:', result.response);
  });
  

menu 和 MenuItem 模块

通过 menu 和 MenuItem 可以创建自定义的菜单项，如文件菜单、上下文菜单。

• 创建菜单并应用：

  const { Menu, MenuItem } = require('electron');
  
  const menu = new Menu();
  menu.append(new MenuItem({ label: 'Copy', role: 'copy' }));
  menu.append(new MenuItem({ label: 'Paste', role: 'paste' }));
  
  Menu.setApplicationMenu(menu); // 设置为应用全局菜单
  

shell 模块

shell 模块允许在系统中打开外部链接、文件管理器、启动外部程序等。

• 打开文件管理器：

  const { shell } = require('electron');
  shell.showItemInFolder('/path/to/file');
  

• 在默认浏览器中打开链接：

  shell.openExternal('https://example.com');
  

clipboard 模块

clipboard 模块用于读写系统剪贴板的内容，支持文本、HTML 等多种数据格式。

• 读写剪贴板：

  const { clipboard } = require('electron');
  clipboard.writeText('Hello, Electron!');
  console.log(clipboard.readText()); // 输出 "Hello, Electron!"
  

powerMonitor 模块

powerMonitor 模块监控系统电源状态，如系统唤醒、待机。

• 监听电源事件：

  const { powerMonitor } = require('electron');
  powerMonitor.on('suspend', () => {
    console.log('系统进入待机状态');
  });
  
  powerMonitor.on('resume', () => {
    console.log('系统恢复');
  });
  

systemPreferences 模块

systemPreferences 模块用于访问系统的一些偏好设置，支持获取颜色模式、通知权限等。

• 常用操作：

  const { systemPreferences } = require('electron');
  if (systemPreferences.isDarkMode()) {
    console.log('当前为暗色模式');
  }
  

globalShortcut 模块

globalShortcut 模块用于注册全局快捷键，可以在应用不活跃时捕获键盘输入。

• 注册和注销快捷键：

  const { app, globalShortcut } = require('electron');
  
  app.whenReady().then(() => {
    globalShortcut.register('CommandOrControl+X', () => {
      console.log('全局快捷键按下');
    });
  });
  
  app.on('will-quit', () => {
    globalShortcut.unregisterAll();
  });
  

其他常用模块

• screen 模块：可以获取系统显示器信息，用于多显示器支持。

nativeTheme 模块：可以获取或设置应用的主题模式。

最佳实践和注意事项

• 安全性：

  • 禁用 nodeIntegration 和启用 contextIsolation 以减少安全风险。
  • 使用 preload 脚本进行主、渲染进程通信，避免直接暴露 Node.js API。

• 性能优化：

  • 延迟加载窗口或使用懒加载方式。
  • 避免过多的渲染进程间通信。

• 打包和发布：

  • 使用 electron-builder 或 electron-packager 打包应用，支持跨平台打包配置。
  • 为应用设置自动更新，Electron 支持集成自动更新功能，如 Squirrel、electron-updater 等。

以上是 Electron 的核心 API 详细说明。通过这些模块的组合，你可以构建具有丰富交互功能的桌面应用。