服务层 API

概述

服务层封装了应用的核心业务逻辑，提供了统一的服务接口供其他模块调用。

机器信息服务

MachineService

机器信息服务提供系统硬件和软件信息查询功能。

初始化

javascript

const MachineService = require('./services/machine-service');

// 初始化服务（自动收集机器信息）
await MachineService.initialize();

获取机器信息

javascript

// 获取完整机器信息
const machineInfo = MachineService.getMachineInfo();

// 返回数据结构
{
  machineId: "unique-machine-id",     // 机器唯一标识
  cpu: {
    model: "Intel Core i7-9700K",     // CPU 型号
    cores: 8,                          // 核心数
    speed: 3.6,                        // 主频 (GHz)
    usage: 45.2                        // 使用率 (%)
  },
  memory: {
    total: 16384,                      // 总内存 (MB)
    used: 8192,                        // 已用 (MB)
    free: 8192,                        // 可用 (MB)
    usagePercent: 50.0                 // 使用率 (%)
  },
  disk: [
    {
      mount: "C:",                     // 挂载点
      total: 500000,                   // 总容量 (MB)
      used: 250000,                    // 已用 (MB)
      free: 250000,                    // 可用 (MB)
      usagePercent: 50.0              // 使用率 (%)
    }
  ],
  network: {
    ipv4: "192.168.1.100",            // IPv4 地址
    ipv6: "fe80::1",                   // IPv6 地址
    mac: "00:11:22:33:44:55"          // MAC 地址
  },
  os: {
    platform: "win32",                 // 平台
    release: "10.0.19044",            // 版本号
    arch: "x64",                       // 架构
    hostname: "MY-PC"                  // 主机名
  }
}

IPC 通信

javascript

// 渲染进程中调用
const machineInfo = await window.electron.invoke('get-machine-info');

悬浮球服务

FloatingBallService

悬浮球服务管理桌面悬浮球窗口的创建、显示和隐藏。

初始化

javascript

const FloatingBallService = require('./services/floatingball-service');

// 初始化服务（传入主窗口引用）
FloatingBallService.initialize(mainWindow);

创建悬浮球

javascript

// 创建悬浮球窗口
FloatingBallService.create();

显示/隐藏主窗口

javascript

// 隐藏主窗口，显示悬浮球
FloatingBallService.hideMainWindow();

// 显示主窗口，隐藏悬浮球
FloatingBallService.showMainWindow();

销毁悬浮球

javascript

// 销毁悬浮球窗口
FloatingBallService.destroy();

特性

✅ 始终置顶显示
✅ 透明背景，圆形外观
✅ 可拖动，位置自动保存
✅ 点击恢复主窗口
✅ 不显示在任务栏

屏幕截图服务

ScreenService

屏幕截图服务提供截图功能，支持调用外部截图工具。

安全截图

javascript

const ScreenService = require('./services/screen-service');

// 执行截图（安全模式，带错误处理）
await ScreenService.safeCaptureScreen();

普通截图

javascript

// 执行截图（抛出异常）
await ScreenService.captureScreen();

配置截图工具

在 path-config.js 中配置截图工具路径：

javascript

const SCREEN_CAPTURE_EXE_PATH = path.join(BIN_DIR_PATH, 'ScreenCapture.exe');

特性

✅ 调用外部截图工具
✅ 自动检查工具是否存在
✅ 错误处理和日志记录
✅ 支持快捷键触发

打印服务

PrintService

打印服务提供网页内容打印功能，支持自定义打印参数。

创建打印服务

javascript

const PrintHandler = require('./services/print-service');

const printService = new PrintHandler();

打印网页内容

javascript

// 打印指定 URL
await printService.printPage({
  url: 'https://example.com',
  options: {
    silent: false, // 是否静默打印
    printBackground: true, // 是否打印背景
    color: true, // 彩色打印
    margins: {
      marginType: 'default', // 边距类型
    },
    landscape: false, // 横向/纵向
    scaleFactor: 100, // 缩放比例
    pagesPerSheet: 1, // 每页张数
    collate: false, // 逐份打印
    copies: 1, // 打印份数
  },
});

打印预览

javascript

// 打开打印预览窗口
const previewWindow = await printService.openPrintPreview({
  url: 'https://example.com',
  width: 800,
  height: 600,
});

IPC 通信

javascript

// 渲染进程中调用
await window.electron.invoke('print-page', {
  url: 'https://example.com',
  options: {
    /* ... */
  },
});

插件服务

PluginService

插件服务管理插件的生命周期，包括加载、启动、停止和卸载。

加载插件

javascript

const PluginService = require('./services/plugin-service');

// 上传插件（返回插件 ID）
const pluginId = await PluginService.uploadPlugin(filePath);

管理插件

javascript

// 获取插件列表
const plugins = PluginService.getPluginList();

// 启动插件
await PluginService.startPlugin(pluginId);

// 停止插件
await PluginService.stopPlugin(pluginId);

// 删除插件
await PluginService.deletePlugin(pluginId);

// 更新插件
await PluginService.updatePlugin(pluginId, newFilePath);

插件通信

javascript

// 发送消息到插件
PluginService.sendMessageToPlugin(pluginId, {
  action: 'do-something',
  data: {
    /* ... */
  },
});

// 监听插件消息
PluginService.onPluginMessage((pluginId, message) => {
  console.log(`收到插件 ${pluginId} 的消息:`, message);
});

IPC 通信

javascript

// 渲染进程中调用
const plugins = await window.customPluginAPI.getPluginList();
await window.customPluginAPI.startPlugin(pluginId);

插件结构

my-plugin.zip
├── manifest.json    # 插件配置
├── index.js         # 插件入口
├── package.json     # 依赖配置
└── assets/          # 资源文件

manifest.json 示例：

json

{
  "id": "my-plugin",
  "name": "我的插件",
  "version": "1.0.0",
  "main": "index.js",
  "description": "插件描述",
  "author": "作者名",
  "permissions": ["window", "ipc"]
}

服务注册

所有服务都通过 IPC 处理器注册到主进程，供渲染进程调用。

服务初始化流程

javascript

// app-initializer.js
async function initializeApp() {
  // 1. 创建主窗口
  const mainWindow = createWindow();

  // 2. 初始化悬浮球服务
  FloatingBallService.initialize(mainWindow);

  // 3. 并行初始化其他服务
  await Promise.all([
    MachineService.initialize(),
    // 其他服务初始化...
  ]);

  // 4. 注册服务到 IPC
  // (自动完成，见 ipc-handlers/)
}

IPC 处理器

每个服务都有对应的 IPC 处理器：

服务	IPC 处理器	位置
机器信息	machine-ipc-handler.js	ipc-handlers/
悬浮球	floating-ball-ipc-handler.js	ipc-handlers/
插件	plugin-ipc-handler.js	ipc-handlers/
打印	print-ipc-handler.js	ipc-handlers/
原生焦点	native-focus-ipc-handler.js	ipc-handlers/
保险业务	insur-ipc-handler.js	ipc-handlers/

最佳实践

1. 服务初始化

javascript

// ✅ 推荐：使用 Promise.all 并行初始化
await Promise.all([Service1.initialize(), Service2.initialize(), Service3.initialize()]);

// ❌ 避免：串行初始化（耗时长）
await Service1.initialize();
await Service2.initialize();
await Service3.initialize();

2. 错误处理

javascript

// ✅ 推荐：使用 try-catch 捕获异常
try {
  await SomeService.doSomething();
} catch (error) {
  logger.error('服务调用失败:', error);
  // 提供降级方案
}

// ❌ 避免：不处理异常
await SomeService.doSomething(); // 可能导致应用崩溃

3. 资源清理

javascript

// ✅ 推荐：在应用退出时清理资源
app.on('before-quit', () => {
  FloatingBallService.destroy();
  PluginService.stopAllPlugins();
  // 清理其他资源...
});

4. 服务单例

javascript

// ✅ 推荐：使用单例模式
class MyService {
  static instance = null;

  static getInstance() {
    if (!this.instance) {
      this.instance = new MyService();
    }
    return this.instance;
  }
}

// 使用
const service = MyService.getInstance();

扩展开发

创建新服务

创建服务文件

javascript

// services/my-service.js
const logger = require('../utils/logger');

class MyService {
  static async initialize() {
    logger.info('MyService 初始化完成');
  }

  static async doSomething(params) {
    // 实现业务逻辑
    return result;
  }
}

module.exports = MyService;

创建 IPC 处理器

javascript

// ipc-handlers/my-service-ipc-handler.js
const { ipcMain } = require('electron');
const MyService = require('../services/my-service');
const logger = require('../utils/logger');

function registerMyServiceHandlers() {
  ipcMain.handle('my-service-action', async (event, params) => {
    try {
      return await MyService.doSomething(params);
    } catch (error) {
      logger.error('MyService 调用失败:', error);
      throw error;
    }
  });

  logger.info('MyService IPC 处理器注册成功');
}

module.exports = { registerMyServiceHandlers };

注册到应用

javascript

// apps/app-ipc-handler.js
const { registerMyServiceHandlers } = require('../ipc-handlers/my-service-ipc-handler');

class IpcManager {
  static async registerHandlers() {
    registerMyServiceHandlers();
    // 注册其他处理器...
  }
}

渲染进程调用

javascript

// 在渲染进程中
const result = await window.electron.invoke('my-service-action', params);

服务层 API ​

概述 ​

机器信息服务 ​

MachineService ​

初始化 ​

获取机器信息 ​

IPC 通信 ​

悬浮球服务 ​

FloatingBallService ​

初始化 ​

创建悬浮球 ​

显示/隐藏主窗口 ​

销毁悬浮球 ​

特性 ​

屏幕截图服务 ​

ScreenService ​

安全截图 ​

普通截图 ​

配置截图工具 ​

特性 ​

打印服务 ​

PrintService ​

创建打印服务 ​

打印网页内容 ​

打印预览 ​

IPC 通信 ​

插件服务 ​

PluginService ​

加载插件 ​

管理插件 ​

插件通信 ​

IPC 通信 ​

插件结构 ​

服务注册 ​

服务初始化流程 ​

IPC 处理器 ​

最佳实践 ​

1. 服务初始化 ​

2. 错误处理 ​

3. 资源清理 ​

4. 服务单例 ​

扩展开发 ​

创建新服务 ​

相关文档 ​

服务层 API

概述

机器信息服务

MachineService

初始化

获取机器信息

IPC 通信

悬浮球服务

FloatingBallService

初始化

创建悬浮球

显示/隐藏主窗口

销毁悬浮球

特性

屏幕截图服务

ScreenService

安全截图

普通截图

配置截图工具

特性

打印服务

PrintService

创建打印服务

打印网页内容

打印预览

IPC 通信

插件服务

PluginService

加载插件

管理插件

插件通信

IPC 通信

插件结构

服务注册

服务初始化流程

IPC 处理器

最佳实践

1. 服务初始化

2. 错误处理

3. 资源清理

4. 服务单例

扩展开发

创建新服务

相关文档