处理器 API

概述

处理器层负责处理特定的应用事件和业务逻辑，是服务层和应用层之间的桥梁。

更新处理器

UpdateHandler

管理应用的版本检查、下载和安装更新。

创建实例

javascript

const UpdateHandler = require('./handlers/update-handler');

const updateHandler = new UpdateHandler(mainWindow);

检查更新

javascript

// 手动检查更新
await updateHandler.checkForUpdates();

// 返回数据结构
{
  hasUpdate: true,
  currentVersion: "1.0.0",
  latestVersion: "1.1.0",
  downloadUrl: "https://example.com/download/v1.1.0.zip",
  releaseNotes: "更新说明..."
}

下载更新

javascript

// 下载更新包
await updateHandler.downloadUpdate({
  url: 'https://example.com/update.zip',
  version: '1.1.0',
});

// 监听下载进度
updateHandler.on('download-progress', (progress) => {
  console.log(`下载进度: ${progress.percent}%`);
  console.log(`已下载: ${progress.transferred}MB`);
  console.log(`总大小: ${progress.total}MB`);
});

安装更新

javascript

// 安装更新并重启应用
await updateHandler.installUpdate();

// 可选：延迟安装（下次启动时安装）
await updateHandler.installOnNextStartup();

更新流程

mermaid

graph TD
    A[启动应用] --> B[检查更新]
    B --> C{有新版本?}
    C -->|是| D[下载更新包]
    C -->|否| E[正常启动]
    D --> F[下载完成]
    F --> G[提示用户安装]
    G --> H{用户选择}
    H -->|立即安装| I[退出应用并安装]
    H -->|稍后安装| E
    I --> J[启动安装程序]
    J --> K[应用重启]

IPC 通信

javascript

// 渲染进程中触发更新检查
window.electron.send('check-for-updates');

// 监听更新事件
window.electron.on('update-available', (info) => {
  console.log('发现新版本:', info);
});

window.electron.on('update-downloaded', () => {
  console.log('更新下载完成');
});

托盘菜单集成

javascript

// 在托盘菜单中添加"检查更新"选项
{
  label: '检查更新',
  click: () => {
    updateHandler.checkForUpdates();
  }
}

加载错误处理器

LoadErrorHandler

处理页面加载失败的情况，显示友好的错误页面。

注册错误处理

javascript

const { registerLoadErrorHandler } = require('./handlers/load-error-handler');

// 为窗口注册错误处理
registerLoadErrorHandler(mainWindow);

错误处理逻辑

javascript

mainWindow.webContents.on('did-fail-load', (event, errorCode, errorDescription) => {
  logger.error('页面加载失败:', errorCode, errorDescription);

  // 加载错误页面
  mainWindow.loadFile('error.html');

  // 传递错误信息给错误页面
  mainWindow.webContents.once('did-finish-load', () => {
    mainWindow.webContents.send('load-error', {
      code: errorCode,
      description: errorDescription,
      url: originalUrl,
    });
  });
});

错误类型

错误码	说明	处理方式
-2	ERR_FAILED	通用错误，显示错误页
-3	ERR_ABORTED	加载中断，可重试
-6	ERR_FILE_NOT_FOUND	文件不存在
-106	ERR_INTERNET_DISCONNECTED	网络断开
-501	ERR_INSECURE_RESPONSE	不安全的响应

错误页面

html

<!-- error.html -->
<!doctype html>
<html>
  <head>
    <title>加载失败</title>
  </head>
  <body>
    <div class="error-container">
      <h1>页面加载失败</h1>
      <p id="error-message"></p>
      <button onclick="reload()">重新加载</button>
      <button onclick="goBack()">返回</button>
    </div>

    <script>
      // 接收错误信息
      window.electron.on('load-error', (error) => {
        document.getElementById('error-message').textContent = error.description;
      });

      function reload() {
        window.electron.send('reload-page');
      }

      function goBack() {
        window.electron.send('go-back');
      }
    </script>
  </body>
</html>

原生焦点处理器

NativeFocusHandler

处理原生窗口（如微信、QQ等）唤起 Electron 窗口的场景。

注册处理器

javascript

const { registerNativeFocusHandler } = require('./handlers/native-focus-handler');

registerNativeFocusHandler(mainWindow);

工作原理

当外部应用（如微信小程序）需要唤起 Electron 应用时：

外部应用通过自定义协议或命令行参数启动应用
NativeFocusHandler 捕获启动参数
将参数传递给主窗口
窗口自动聚焦并处理参数

使用场景

javascript

// 处理唤起参数
ipcMain.on('native-focus-params', (event, params) => {
  logger.info('收到原生焦点参数:', params);

  // 解析参数
  const { action, data } = parseParams(params);

  // 根据参数执行相应操作
  switch (action) {
    case 'open-page':
      mainWindow.webContents.send('navigate-to', data.page);
      break;
    case 'show-dialog':
      mainWindow.webContents.send('show-dialog', data);
      break;
  }
});

IPC 通信

javascript

// 渲染进程监听唤起事件
window.electron.on('native-focus', (params) => {
  console.log('应用被唤起:', params);
  // 处理唤起逻辑
});

右键菜单处理器

RightMenuHandler

管理应用的右键上下文菜单。

注册处理器

javascript

const { registerRightMenuHandler } = require('./handlers/right-menu-handler');

registerRightMenuHandler(mainWindow);

自定义右键菜单

javascript

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

// 监听右键菜单请求
mainWindow.webContents.on('context-menu', (event, params) => {
  const template = [
    {
      label: '复制',
      role: 'copy',
      enabled: params.selectionText.length > 0,
    },
    {
      label: '粘贴',
      role: 'paste',
    },
    { type: 'separator' },
    {
      label: '在浏览器中打开',
      visible: params.linkURL.length > 0,
      click: () => {
        shell.openExternal(params.linkURL);
      },
    },
    { type: 'separator' },
    {
      label: '检查元素',
      click: () => {
        mainWindow.webContents.inspectElement(params.x, params.y);
      },
    },
  ];

  const menu = Menu.buildFromTemplate(template);
  menu.popup();
});

菜单项配置

javascript

// 完整的菜单项示例
{
  label: '菜单文本',           // 显示文本
  role: 'copy',               // 预定义角色
  type: 'normal',             // 类型：normal, separator, submenu, checkbox, radio
  enabled: true,              // 是否启用
  visible: true,              // 是否可见
  checked: false,             // 是否选中（checkbox/radio）
  accelerator: 'CmdOrCtrl+C', // 快捷键
  icon: '/path/to/icon.png',  // 图标
  click: (menuItem, browserWindow, event) => {
    // 点击处理函数
  },
  submenu: [                  // 子菜单
    { /* ... */ }
  ]
}

预定义角色

角色	说明
`undo`	撤销
`redo`	重做
`cut`	剪切
`copy`	复制
`paste`	粘贴
`selectAll`	全选
`delete`	删除
`reload`	重新加载
`forceReload`	强制重新加载
`toggleDevTools`	切换开发者工具
`resetZoom`	重置缩放
`zoomIn`	放大
`zoomOut`	缩小
`quit`	退出应用

其他操作处理器

OtherActionHandler

处理其他杂项操作，如 JumpList、关于对话框等。

JumpList 管理

javascript

const { registerJumpList } = require('./handlers/other-action-handler');

// 注册 JumpList（Windows 任务栏快捷方式）
registerJumpList([
  {
    type: 'tasks',
    name: '任务',
    items: [
      {
        type: 'task',
        title: '打开配置',
        description: '打开配置页面',
        program: process.execPath,
        args: '--open-config',
        iconPath: process.execPath,
        iconIndex: 0,
      },
      {
        type: 'task',
        title: '清除缓存',
        description: '清除应用缓存',
        program: process.execPath,
        args: '--clear-cache',
      },
    ],
  },
  {
    type: 'recent',
    name: '最近打开',
    items: [
      // 动态添加最近打开的文件
    ],
  },
]);

关于对话框

javascript

const { showAboutDialog } = require('./handlers/other-action-handler');

// 显示关于对话框
showAboutDialog({
  applicationName: 'Vue3-Simple-Electron',
  applicationVersion: '1.0.0',
  copyright: 'Copyright © 2024-2025',
  authors: ['LMX'],
  website: 'https://github.com/username/repo',
  iconPath: '/path/to/icon.png',
});

文件关联

javascript

// 注册文件类型关联
app.setAsDefaultProtocolClient('myapp'); // 注册协议

// 处理打开文件
app.on('open-file', (event, filePath) => {
  event.preventDefault();
  logger.info('打开文件:', filePath);
  // 处理文件
});

app.on('open-url', (event, url) => {
  event.preventDefault();
  logger.info('打开 URL:', url);
  // 处理 URL
});

处理器注册流程

统一注册

javascript

// app-initializer.js
async function initializeApp() {
  const mainWindow = createWindow();

  // 注册各类处理器
  registerLoadErrorHandler(mainWindow);
  registerNativeFocusHandler(mainWindow);
  registerRightMenuHandler(mainWindow);
  registerJumpList();

  // 创建更新处理器
  const updateHandler = new UpdateHandler(mainWindow);

  // 注册到托盘菜单
  addTrayMenu(mainWindow, updateHandler, FloatingBallService);
}

处理器生命周期

mermaid

graph LR
    A[应用启动] --> B[创建窗口]
    B --> C[注册处理器]
    C --> D[监听事件]
    D --> E[处理请求]
    E --> F[清理资源]
    F --> G[应用退出]

最佳实践

1. 错误处理

javascript

// ✅ 推荐：捕获异常并记录
try {
  await handler.doSomething();
} catch (error) {
  logger.error('处理器执行失败:', error);
  // 提供用户友好的错误提示
  dialog.showErrorBox('操作失败', error.message);
}

2. 异步操作

javascript

// ✅ 推荐：使用 async/await
async function handleAction() {
  const result = await someAsyncOperation();
  return result;
}

// ❌ 避免：回调地狱
someAsyncOperation((error, result) => {
  if (error) {
    // 处理错误
  } else {
    anotherAsyncOperation(result, (error2, result2) => {
      // 更深的嵌套...
    });
  }
});

3. 事件监听器清理

javascript

// ✅ 推荐：清理事件监听器
const handler = () => {
  /* ... */
};
mainWindow.webContents.on('some-event', handler);

app.on('before-quit', () => {
  mainWindow.webContents.removeListener('some-event', handler);
});

4. 条件注册

javascript

// ✅ 推荐：根据配置条件注册
if (getConfigValue('enableAutoUpdate')) {
  const updateHandler = new UpdateHandler(mainWindow);
}

if (process.platform === 'win32') {
  registerJumpList(); // 仅 Windows
}

扩展开发

创建自定义处理器

javascript

// handlers/my-handler.js
const logger = require('../utils/logger');

class MyHandler {
  constructor(mainWindow) {
    this.mainWindow = mainWindow;
    this.initialize();
  }

  initialize() {
    // 注册事件监听
    this.mainWindow.webContents.on('some-event', this.handleEvent.bind(this));
    logger.info('MyHandler 初始化完成');
  }

  handleEvent(event, data) {
    try {
      // 处理事件
      logger.info('处理事件:', data);
    } catch (error) {
      logger.error('事件处理失败:', error);
    }
  }

  destroy() {
    // 清理资源
    this.mainWindow.webContents.removeAllListeners('some-event');
  }
}

module.exports = MyHandler;

处理器 API ​

概述 ​

更新处理器 ​

UpdateHandler ​

创建实例 ​

检查更新 ​

下载更新 ​

安装更新 ​

更新流程 ​

IPC 通信 ​

托盘菜单集成 ​

加载错误处理器 ​

LoadErrorHandler ​

注册错误处理 ​

错误处理逻辑 ​

错误类型 ​

错误页面 ​

原生焦点处理器 ​

NativeFocusHandler ​

注册处理器 ​

工作原理 ​

使用场景 ​

IPC 通信 ​

右键菜单处理器 ​

RightMenuHandler ​

注册处理器 ​

自定义右键菜单 ​

菜单项配置 ​

预定义角色 ​

其他操作处理器 ​

OtherActionHandler ​

JumpList 管理 ​

关于对话框 ​

文件关联 ​

处理器注册流程 ​

统一注册 ​

处理器生命周期 ​

最佳实践 ​

1. 错误处理 ​

2. 异步操作 ​

3. 事件监听器清理 ​

4. 条件注册 ​

扩展开发 ​

创建自定义处理器 ​

相关文档 ​

处理器 API

概述

更新处理器

UpdateHandler

创建实例

检查更新

下载更新

安装更新

更新流程

IPC 通信

托盘菜单集成

加载错误处理器

LoadErrorHandler

注册错误处理

错误处理逻辑

错误类型

错误页面

原生焦点处理器

NativeFocusHandler

注册处理器

工作原理

使用场景

IPC 通信

右键菜单处理器

RightMenuHandler

注册处理器

自定义右键菜单

菜单项配置

预定义角色

其他操作处理器

OtherActionHandler

JumpList 管理

关于对话框

文件关联

处理器注册流程

统一注册

处理器生命周期

最佳实践

1. 错误处理

2. 异步操作

3. 事件监听器清理

4. 条件注册

扩展开发

创建自定义处理器

相关文档