本文说明 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 常见问题对照

现象 常见原因 处置
托盘图标随机消失 托盘对象被回收 保持在长期存活的引用中
某平台上没有托盘 系统缺少支持组件或图标格式不适用 确认平台依赖与图标尺寸
通知不显示 未设置平台应用标识或系统通知被禁用 设置应用标识并检查系统设置
双击文件未唤起已有窗口 未配合单实例或未处理命令行参数 申请实例锁并在二次唤醒中解析参数
某平台协议唤起无效 该平台通过事件回调传递而非命令行参数 按平台分别处理两种传入方式
协议被其他程序抢占 安装时未正确注册或存在同类软件 重新注册并核对系统默认程序设置
菜单在某平台上缺少退出项 未构造应用菜单 按平台在首个菜单中加入关于与退出
菜单文本语言与界面不一致 切换语言后未重建菜单 语言切换时重新构建应用菜单
全局快捷键注册失败 已被其他程序占用 返回结果交由界面提示并提供修改
应用退出后快捷键仍被占用 未在退出前注销 在退出前统一注销
大文件读取导致应用卡住或无响应 使用同步接口或整体读入内存 改用异步接口并限制单次读取大小
写入过程中断导致文件损坏 直接覆盖写入 先写临时文件再原子替换
导出文档打印时被截断 未提供分页控制样式 为打印单独定义分页与尺寸样式
打开外部地址后执行了非预期动作 未校验协议白名单 只允许安全协议,其余拒绝
目录监听重复触发 未合并连续事件 对事件做去抖与合并
休眠恢复后数据未刷新 未监听电源事件 在恢复事件中重建连接并刷新数据

四、总结

  1. 桌面应用需要与系统协同的四类能力是文件与数据、界面外壳、通知与状态、外部唤起,它们都只能由主进程持有。
  2. 每一项能力的落地都包含主进程调用、通道暴露与界面调用三部分,通道的参数与来源校验是安全前提。
  3. 文件访问必须做路径规范化与白名单校验并限制单次读取大小,可靠写入采用"临时文件加原子替换"。
  4. 菜单与托盘需要按平台构造,某类平台首个菜单为应用菜单;托盘对象必须保持长期引用,否则图标会消失。
  5. 通知需要设置平台应用标识并处理点击行为,任务栏进度与角标用于长任务的可见反馈。
  6. 全局快捷键注册前应判断占用、退出前必须统一注销,且应尽量少用,焦点内生效的用菜单快捷键即可。
  7. 文件关联与自定义协议必须配合单实例控制,且三个平台的参数传递方式不同,需要分别处理。
  8. 外部输入(协议地址与文件路径)必须做参数校验,打开外部程序时必须限制协议白名单。
  9. 文件监听与下载都需要处理事件合并与流式写入,避免频繁触发与内存膨胀。
  10. 电源与显示器事件的用途容易被忽略,休眠恢复与显示器变化都需要重建状态与重排窗口。