本文说明 Electron 对系统能力的集成方式。能力调用的通道与参数校验见 进程间通信与预加载,进程模型与生命周期见 Electron 架构与进程模型,外部输入与协议的安全要求见 Electron 安全加固,打印与导出文档的样式要求见 CSS 布局与响应式,文件与目录的权限模型见 linux: 权限模型,浏览器侧的下载与存储行为见 JavaScript 浏览器运行时。
一、起源
1.1 四类能力
| 类别 | 内容 | 典型用途 |
| 文件与数据 | 选择路径、读写文件、监听变化、下载与另存为 | 打开文档、导出结果、监控目录 |
| 界面外壳 | 应用菜单、右键菜单、窗口控制、托盘 | 符合平台习惯的操作入口 |
| 通知与状态 | 系统通知、任务栏角标与进度、窗口提示 | 后台任务完成提醒 |
| 外部唤起 | 文件关联、自定义协议、开机自启、打开外部程序 | 双击文件打开、浏览器唤起客户端 |
1.2 能力的持有者
所有系统能力都由主进程持有,界面通过通道请求。这一约束决定了本模块的统一模式:
界面触发 -> 通道请求 -> 主进程校验并调用系统能力 -> 返回结果 -> 界面更新
因此每一项能力的落地都包含三部分:主进程调用、通道暴露、界面调用与错误处理。通道与校验的具体规范见 进程间通信与预加载。
1.3 取舍
| 选择 | 获得 | 付出 |
| 完整集成系统能力 | 体验接近原生,符合平台习惯 | 平台差异需要逐一适配,测试矩阵扩大 |
| 只做最小集成 | 开发快 | 用户体验与系统习惯脱节,例如缺少菜单与快捷键 |
二、原理
2.1 文件与目录
| 关注点 | 要点 |
| 选择路径 | 通过系统对话框获得,不自行拼装路径 |
| 保存路径 | 同样通过对话框获得,并提供默认文件名与扩展名过滤 |
| 路径规范化 | 接收到路径后先解析为绝对路径并校验是否在白名单目录内 |
| 读写的异步化 | 一律使用异步接口,避免阻塞主进程 |
| 单次读取上限 | 大文件应分片读取或改用流式传输,避免一次性载入内存 |
| 写入策略 | 需要可靠写入时先写临时文件再重命名,避免写入中断产生损坏文件 |
| 文件监听 | 平台实现差异较大,递归监听支持情况不同,需要处理事件合并与重命名语义 |
| 默认目录 | 使用应用数据目录而不是应用安装目录,安装目录在多数平台不可写 |
写入策略中"临时文件加原子替换"是保证数据安全的关键:直接覆盖写入时若进程中断,原文件与目标文件都可能损坏。
2.2 应用菜单与右键菜单
| 关注点 | 说明 |
| 模板结构 | 菜单由标签、点击处理、快捷键与子菜单组成,分隔项用于分组 |
| 预置角色 | 复制、粘贴、撤销、重载、开发者工具、退出等可使用预置项,行为自动符合平台 |
| 平台差异 | 某类平台的首个菜单是应用菜单,包含关于与退出,需按平台构造 |
| 快捷键 | 使用跨平台修饰键写法,由菜单自动生效,无需额外注册全局快捷键 |
| 本地化 | 菜单文本需要与界面语言一致,语言切换后重建菜单 |
| 右键菜单 | 由界面触发请求,主进程构造并弹出,位置由触发点决定 |
2.3 托盘
| 关注点 | 要点 |
| 图标 | 需要提供合适尺寸与格式的图标,某类平台支持模板图标以自动适配明暗主题 |
| 菜单 | 托盘菜单与主菜单相互独立,需要单独构造 |
| 点击行为 | 各平台点击语义不同,某些平台单击即弹出菜单,某些平台需要右键 |
| 引用保持 | 托盘对象必须保持在长期存活的引用中,否则会被回收导致图标消失 |
| 平台依赖 | 部分平台需要系统组件支持,缺少时托盘不可见 |
"图标随机消失"的典型原因就是托盘对象被垃圾回收:创建后若只放在局部变量中,函数结束即可能被回收。
2.4 通知与任务栏状态
| 能力 | 说明 |
| 系统通知 | 主进程可发起通知,界面也可使用网页通知接口;后者依赖权限授予 |
| 平台标识 | 某类平台需要设置应用标识,否则通知不显示或分组异常 |
| 角标计数 | 部分平台支持在图标上显示数字 |
| 任务栏进度 | 可设置进度值或不确定状态,用于长任务反馈 |
| 窗口闪烁 | 用于请求用户注意,应避免滥用 |
| 通知点击 | 需要处理点击后聚焦窗口或跳转到对应页面 |
2.5 剪贴板与全局快捷键
| 项目 | 要点 |
| 剪贴板 | 支持文本与图像与标记内容;某类平台还需考虑选择区剪贴板 |
| 快捷键注册 | 注册前判断是否已被占用,注册失败需要提示用户 |
| 生命周期 | 必须在应用退出前统一注销,否则可能残留占用 |
| 冲突处理 | 用户可自定义的快捷键需要提供冲突检测与恢复默认 |
全局快捷键与菜单快捷键的分工:只在应用获得焦点时生效的用菜单快捷键,需要在任何界面下响应的才用全局快捷键,后者应尽量少用。
2.6 文件关联与自定义协议
| 关注点 | 说明 |
| 注册方式 | 由打包配置声明关联类型与协议,安装时由系统写入注册信息 |
| 参数传递 | 某类平台通过事件回调传入,另两类平台通过启动命令行参数传入 |
| 单实例配合 | 必须配合单实例控制,否则每次唤起都会启动新实例 |
| 开发环境 | 未安装时协议未注册,需要手动指定可执行文件与参数用于调试 |
| 参数校验 | 传入的地址与路径必须校验,不能直接当作可信输入使用 |
三个平台参数传递方式的差异是协议唤起最容易出错的环节:只在某类平台上测试会导致其他平台完全无法唤起。
2.7 下载与打印
| 能力 | 要点 |
| 下载会话 | 监听下载开始事件,可以决定保存路径、显示进度、支持暂停与取消 |
| 另存为 | 结合保存对话框与流式写入,避免大文件整体载入内存 |
| 打印 | 可静默打印或弹出系统打印对话框,需选择打印机与页面设置 |
| 导出文档 | 由页面生成文档数据再保存,页面样式需为分页做适配 |
| 打印样式 | 需要单独的分页控制样式,屏幕样式直接打印会出现截断 |
2.8 系统信息与电源事件
| 能力 | 用途 |
| 系统信息 | 平台与版本、内存、处理器等,用于界面展示与问题排查 |
| 显示器信息 | 多显示器与缩放比,用于窗口定位与尺寸换算 |
| 显示变化 | 显示器增减与分辨率变化,用于重排窗口 |
| 电源事件 | 休眠与恢复、锁屏与解锁、接入电源与使用电池,用于暂停任务与刷新状态 |
| 空闲检测 | 判断用户是否在一段时间内无操作 |
| 主题 | 系统明暗主题与强调色,用于界面适配 |
电源事件的实际用途常被忽略:休眠恢复后需要重建网络连接与刷新数据,锁屏时可以暂停敏感内容的展示。
2.9 开机自启与打开外部程序
| 能力 | 要点 |
| 开机自启 | 两类平台由系统接口设置,另一类平台需要写入自启动目录的配置文件 |
| 打开文件或地址 | 交给系统默认程序处理,必须校验协议白名单 |
| 在文件管理器中显示 | 用于"定位文件"功能 |
| 打开目录 | 同样需要校验路径存在与可访问 |
协议白名单是必须的:把不可信字符串直接交给"打开外部程序"接口,可能触发自定义协议处理程序执行非预期动作,这是桌面应用中一类常见的提权路径。
三、实现
3.1 对话框与文件读写
// main/file-service.js
const { dialog, BrowserWindow, app } = require('electron');
const fs = require('node:fs/promises');
const path = require('node:path');
const { randomUUID } = require('node:crypto');
// 允许访问的根目录白名单
const ALLOWED_ROOTS = [
app.getPath('documents'),
app.getPath('downloads'),
path.join(app.getPath('userData'), 'workspace'),
].map((p) => path.resolve(p));
function resolveSafely(target) {
const resolved = path.resolve(target);
const allowed = ALLOWED_ROOTS.some(
(root) => resolved === root || resolved.startsWith(root + path.sep)
);
if (!allowed) throw Object.assign(new Error('路径不在允许范围内'), { code: 'E_PATH_NOT_ALLOWED' });
return resolved;
}
async function pickFile(win, filters) {
const { canceled, filePaths } = await dialog.showOpenDialog(win, {
title: '选择文件',
properties: ['openFile'],
filters: filters || [{ name: '文本文件', extensions: ['txt', 'md', 'json'] }],
});
if (canceled || !filePaths.length) return null;
return resolveSafely(filePaths[0]);
}
async function readText(filePath, maxBytes = 5 * 1024 * 1024) {
const target = resolveSafely(filePath);
const stat = await fs.stat(target);
if (stat.size > maxBytes) {
throw Object.assign(new Error('文件过大'), { code: 'E_FILE_TOO_LARGE' });
}
return fs.readFile(target, 'utf8');
}
async function writeTextAtomic(filePath, content) {
const target = resolveSafely(filePath);
const dir = path.dirname(target);
// 先写临时文件再重命名,保证中断时不损坏原文件
const tmp = path.join(dir, `.${path.basename(target)}.${randomUUID()}.tmp`);
await fs.writeFile(tmp, content, 'utf8');
await fs.rename(tmp, target);
return target;
}
// 目录变化的监听:平台差异较大,事件需要做去抖与合并
async function watchDir(dir, onChange) {
const { watch } = require('node:fs');
const target = resolveSafely(dir);
const pending = new Set();
let timer = null;
const watcher = watch(target, { persistent: false }, (eventType, filename) => {
pending.add(`${eventType}:${filename}`);
// 合并短时间内的连续事件,避免界面频繁刷新
clearTimeout(timer);
timer = setTimeout(() => {
const events = [...pending];
pending.clear();
onChange(events);
}, 300);
});
return () => watcher.close();
}
module.exports = { pickFile, readText, writeTextAtomic, watchDir, resolveSafely };
3.2 菜单与托盘
// main/menus.js
const { Menu, Tray, app, shell, nativeImage } = require('electron');
const path = require('node:path');
let tray = null; // 必须保持引用,否则托盘图标会被回收
function buildAppMenu(win, handlers = {}) {
const isMac = process.platform === 'darwin';
const template = [
// 某类平台的首个菜单为应用菜单
...(isMac
? [{
label: app.name,
submenu: [
{ role: 'about', label: '关于' },
{ type: 'separator' },
{ role: 'hide', label: '隐藏' },
{ role: 'quit', label: '退出' },
],
}]
: []),
{
label: '文件',
submenu: [
{ label: '打开', accelerator: 'CmdOrCtrl+O', click: () => handlers.onOpen?.() },
{ label: '保存', accelerator: 'CmdOrCtrl+S', click: () => handlers.onSave?.() },
{ type: 'separator' },
isMac ? { role: 'close', label: '关闭窗口' } : { role: 'quit', label: '退出' },
],
},
{
label: '编辑',
submenu: [
{ role: 'undo', label: '撤销' },
{ role: 'redo', label: '重做' },
{ type: 'separator' },
{ role: 'cut', label: '剪切' },
{ role: 'copy', label: '复制' },
{ role: 'paste', label: '粘贴' },
{ role: 'selectAll', label: '全选' },
],
},
{
label: '视图',
submenu: [
{ role: 'reload', label: '重新加载' },
{ role: 'toggleDevTools', label: '开发者工具' },
{ type: 'separator' },
{ role: 'resetZoom', label: '实际大小' },
{ role: 'zoomIn', label: '放大' },
{ role: 'zoomOut', label: '缩小' },
],
},
{
label: '帮助',
submenu: [
{ label: '打开日志目录', click: () => shell.openPath(app.getPath('logs')) },
{ label: '项目主页', click: () => openExternalSafely('https://example.com') },
],
},
];
Menu.setApplicationMenu(Menu.buildFromTemplate(template));
}
function createTray(win, handlers = {}) {
const iconPath = path.join(__dirname, '../assets/tray.png');
const image = nativeImage.createFromPath(iconPath);
// 某类平台使用模板图标自动适配明暗主题
if (process.platform === 'darwin') image.setTemplateImage(true);
tray = new Tray(image);
tray.setToolTip('示例应用');
const menu = Menu.buildFromTemplate([
{ label: '显示主窗口', click: () => { win.show(); win.focus(); } },
{ label: '开始同步', click: () => handlers.onSync?.() },
{ type: 'separator' },
{ label: '退出', click: () => app.quit() },
]);
tray.setContextMenu(menu);
// 某类平台单击即显示菜单,此处统一处理点击显示窗口
tray.on('click', () => {
if (process.platform !== 'darwin') {
win.isVisible() ? win.hide() : win.show();
}
});
return tray;
}
// 打开外部地址:只允许安全协议,避免被自定义协议利用
const ALLOWED_PROTOCOLS = new Set(['https:', 'http:', 'mailto:']);
function openExternalSafely(url) {
try {
const parsed = new URL(url);
if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
console.warn('[main] 拒绝打开非白名单协议', parsed.protocol);
return false;
}
shell.openExternal(parsed.toString());
return true;
} catch {
return false;
}
}
module.exports = { buildAppMenu, createTray, openExternalSafely };
3.3 协议唤起与通知
// main/protocol.js:三个平台的参数传递方式不同,需要统一处理
const { app } = require('electron');
const path = require('node:path');
const PROTOCOL = 'myapp';
function registerProtocol() {
if (process.defaultApp && process.argv.length >= 2) {
// 开发环境未安装,需要显式指定可执行文件与入口
app.setAsDefaultProtocolClient(PROTOCOL, process.execPath, [path.resolve(process.argv[1])]);
} else {
app.setAsDefaultProtocolClient(PROTOCOL);
}
}
// 从命令行参数中解析出本应用的协议地址
function extractDeepLink(argv) {
return argv.find((arg) => arg.startsWith(`${PROTOCOL}://`)) || null;
}
function handleDeepLink(rawUrl, win) {
if (!rawUrl) return;
let parsed;
try {
parsed = new URL(rawUrl);
} catch {
return;
}
// 参数校验:只接受预期的主机与路径,其余忽略
if (parsed.host !== 'open') return;
const id = parsed.searchParams.get('id');
if (!/^[A-Za-z0-9_-]{1,64}$/.test(id || '')) return;
if (win && !win.isDestroyed()) {
if (win.isMinimized()) win.restore();
win.show();
win.focus();
win.webContents.send('deeplink:open', { id });
}
}
module.exports = { registerProtocol, extractDeepLink, handleDeepLink };
// main/notify.js:通知与任务栏状态
const { Notification, app } = require('electron');
function notify({ title, body, onClick }) {
if (!Notification.isSupported()) return false;
const notification = new Notification({ title, body });
if (onClick) {
notification.on('click', onClick);
}
notification.show();
return true;
}
function setTaskbarProgress(win, value) {
// 取值区间内的比例表示确定进度,负值表示不确定状态
win.setProgressBar(value);
}
function setBadge(count) {
// 部分平台支持角标计数,不支持时静默忽略
if (typeof app.setBadgeCount === 'function') {
app.setBadgeCount(count);
}
}
module.exports = { notify, setTaskbarProgress, setBadge };
3.4 全局快捷键
// main/shortcuts.js
const { globalShortcut, app } = require('electron');
const registered = new Set();
function registerShortcut(accelerator, handler) {
// 注册前判断是否被占用,失败时交由界面提示用户
if (globalShortcut.isRegistered(accelerator)) return false;
const success = globalShortcut.register(accelerator, handler);
if (success) registered.add(accelerator);
return success;
}
function unregisterAll() {
// 退出前统一注销,避免残留占用
for (const accelerator of registered) {
globalShortcut.unregister(accelerator);
}
registered.clear();
}
app.on('will-quit', unregisterAll);
module.exports = { registerShortcut, unregisterAll };
3.5 常见问题对照
| 现象 | 常见原因 | 处置 |
| 托盘图标随机消失 | 托盘对象被回收 | 保持在长期存活的引用中 |
| 某平台上没有托盘 | 系统缺少支持组件或图标格式不适用 | 确认平台依赖与图标尺寸 |
| 通知不显示 | 未设置平台应用标识或系统通知被禁用 | 设置应用标识并检查系统设置 |
| 双击文件未唤起已有窗口 | 未配合单实例或未处理命令行参数 | 申请实例锁并在二次唤醒中解析参数 |
| 某平台协议唤起无效 | 该平台通过事件回调传递而非命令行参数 | 按平台分别处理两种传入方式 |
| 协议被其他程序抢占 | 安装时未正确注册或存在同类软件 | 重新注册并核对系统默认程序设置 |
| 菜单在某平台上缺少退出项 | 未构造应用菜单 | 按平台在首个菜单中加入关于与退出 |
| 菜单文本语言与界面不一致 | 切换语言后未重建菜单 | 语言切换时重新构建应用菜单 |
| 全局快捷键注册失败 | 已被其他程序占用 | 返回结果交由界面提示并提供修改 |
| 应用退出后快捷键仍被占用 | 未在退出前注销 | 在退出前统一注销 |
| 大文件读取导致应用卡住或无响应 | 使用同步接口或整体读入内存 | 改用异步接口并限制单次读取大小 |
| 写入过程中断导致文件损坏 | 直接覆盖写入 | 先写临时文件再原子替换 |
| 导出文档打印时被截断 | 未提供分页控制样式 | 为打印单独定义分页与尺寸样式 |
| 打开外部地址后执行了非预期动作 | 未校验协议白名单 | 只允许安全协议,其余拒绝 |
| 目录监听重复触发 | 未合并连续事件 | 对事件做去抖与合并 |
| 休眠恢复后数据未刷新 | 未监听电源事件 | 在恢复事件中重建连接并刷新数据 |
四、总结
- 桌面应用需要与系统协同的四类能力是文件与数据、界面外壳、通知与状态、外部唤起,它们都只能由主进程持有。
- 每一项能力的落地都包含主进程调用、通道暴露与界面调用三部分,通道的参数与来源校验是安全前提。
- 文件访问必须做路径规范化与白名单校验并限制单次读取大小,可靠写入采用"临时文件加原子替换"。
- 菜单与托盘需要按平台构造,某类平台首个菜单为应用菜单;托盘对象必须保持长期引用,否则图标会消失。
- 通知需要设置平台应用标识并处理点击行为,任务栏进度与角标用于长任务的可见反馈。
- 全局快捷键注册前应判断占用、退出前必须统一注销,且应尽量少用,焦点内生效的用菜单快捷键即可。
- 文件关联与自定义协议必须配合单实例控制,且三个平台的参数传递方式不同,需要分别处理。
- 外部输入(协议地址与文件路径)必须做参数校验,打开外部程序时必须限制协议白名单。
- 文件监听与下载都需要处理事件合并与流式写入,避免频繁触发与内存膨胀。
- 电源与显示器事件的用途容易被忽略,休眠恢复与显示器变化都需要重建状态与重排窗口。