API 参考总览

概述

本节提供了项目中所有核心 API 的详细参考文档，包括服务层、处理器层和工具函数等。

快速导航

📦 服务层 API

封装了应用的核心业务逻辑，提供统一的服务接口。

• MachineService - 机器信息服务（CPU、内存、硬盘、网络）
• FloatingBallService - 悬浮球服务（创建、显示、隐藏）
• ScreenService - 屏幕截图服务
• PrintService - 打印服务
• PluginService - 插件管理服务

🎯 处理器 API

处理特定的应用事件和业务逻辑。

• UpdateHandler - 更新处理器（检查、下载、安装更新）
• LoadErrorHandler - 加载错误处理器
• NativeFocusHandler - 原生焦点处理器
• RightMenuHandler - 右键菜单处理器
• OtherActionHandler - 其他操作处理器

API 使用示例

基本使用流程

// 1. 导入所需模块
const MachineService = require('./services/machine-service');
const UpdateHandler = require('./handlers/update-handler');

// 2. 初始化服务
async function initialize() {
  await MachineService.initialize();
  const updateHandler = new UpdateHandler(mainWindow);
}

// 3. 调用 API
const machineInfo = MachineService.getMachineInfo();
await updateHandler.checkForUpdates();

从渲染进程调用

// 通过 IPC 调用主进程服务
const machineInfo = await window.electron.invoke('get-machine-info');

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

// 发送事件到主进程
window.electron.send('check-for-updates');

API 分类

系统服务

API	说明	文档链接
MachineService	获取系统硬件和软件信息	查看详情
ScreenService	屏幕截图功能	查看详情
PrintService	打印和打印预览	查看详情

UI 服务

API	说明	文档链接
FloatingBallService	悬浮球窗口管理	查看详情
WindowManager	窗口创建和管理	查看详情
TrayManager	系统托盘菜单	查看详情

插件服务

API	说明	文档链接
PluginService	插件生命周期管理	查看详情
PluginLoader	插件加载器	查看详情
PluginValidator	插件验证器	查看详情

事件处理

API	说明	文档链接
UpdateHandler	更新检查和安装	查看详情
LoadErrorHandler	页面加载错误处理	查看详情
RightMenuHandler	右键菜单管理	查看详情

IPC 通信接口

服务调用

// 机器信息
window.electron.invoke('get-machine-info');

// 悬浮球
window.electron.invoke('show-floating-ball');
window.electron.invoke('hide-floating-ball');

// 插件管理
window.electron.invoke('plugin-upload', { filePath });
window.electron.invoke('plugin-start', { pluginId });
window.electron.invoke('plugin-stop', { pluginId });

// 打印
window.electron.invoke('print-page', { url, options });

事件监听

// 更新事件
window.electron.on('update-available', (info) => {});
window.electron.on('update-downloaded', () => {});
window.electron.on('update-error', (error) => {});

// 插件事件
window.electron.on('plugin-loaded', (pluginId) => {});
window.electron.on('plugin-error', (error) => {});

// 系统事件
window.electron.on('app-ready', () => {});
window.electron.on('app-quit', () => {});

配置 API

读取配置

const { getConfigValue } = require('./config/reader-config');

// 读取单个配置
const title = getConfigValue('electronTitle');
const port = getConfigValue('localServerPort');

// 读取布尔值
const enablePlugin = getConfigValue('enablePluginSystem'); // 返回 boolean

配置文件位置

resources/config/
├── config.ini          # 主配置文件
├── proxy-rules.yaml    # 代理规则
└── apps-install.yaml   # 程序安装配置

工具函数

日志记录

const logger = require('./utils/logger');

logger.info('信息日志', data);
logger.warn('警告日志', warning);
logger.error('错误日志', error);
logger.debug('调试日志', debug);

路径工具

const {
  APP_DIR_PATH, // 应用目录
  USER_DATA_DIR_PATH, // 用户数据目录
  LOGS_DIR_PATH, // 日志目录
  CONFIG_DIR_PATH, // 配置目录
  PLUGINS_DIR_PATH, // 插件目录
} = require('./config/path-config');

更新工具

const { checkPendingUpdate } = require('./utils/update-utils');

// 检查待处理的更新
const hasUpdate = await checkPendingUpdate();
if (hasUpdate) {
  // 有更新待安装
  app.exit();
}

常量定义

错误码

const {
  ERROR_PLUGIN_NOT_FOUND,
  ERROR_PLUGIN_INVALID,
  ERROR_SERVICE_UNAVAILABLE,
} = require('./constants/error-codes');

应用常量

const {
  APP_TITLE, // 应用标题
  APP_VERSION, // 应用版本
  IS_DEV, // 是否开发环境
  IS_WIN, // 是否 Windows
  IS_MAC, // 是否 macOS
  IS_LINUX, // 是否 Linux
} = require('./config/app-icon-config');

类型定义

MachineInfo

interface MachineInfo {
  machineId: string;
  cpu: {
    model: string;
    cores: number;
    speed: number;
    usage: number;
  };
  memory: {
    total: number;
    used: number;
    free: number;
    usagePercent: number;
  };
  disk: Array<{
    mount: string;
    total: number;
    used: number;
    free: number;
    usagePercent: number;
  }>;
  network: {
    ipv4: string;
    ipv6: string;
    mac: string;
  };
  os: {
    platform: string;
    release: string;
    arch: string;
    hostname: string;
  };
}

UpdateInfo

interface UpdateInfo {
  hasUpdate: boolean;
  currentVersion: string;
  latestVersion: string;
  downloadUrl: string;
  releaseNotes: string;
}

PluginManifest

interface PluginManifest {
  id: string;
  name: string;
  version: string;
  main: string;
  description?: string;
  author?: string;
  permissions?: string[];
}

最佳实践

错误处理

try {
  const result = await someService.doSomething();
  return result;
} catch (error) {
  logger.error('操作失败:', error);
  // 提供降级方案或友好提示
  return defaultValue;
}

异步初始化

// 并行初始化多个服务
await Promise.all([Service1.initialize(), Service2.initialize(), Service3.initialize()]);

资源清理

app.on('before-quit', () => {
  // 清理资源
  FloatingBallService.destroy();
  PluginService.stopAllPlugins();
  logger.info('应用退出，资源已清理');
});

相关链接

• 服务层详细文档
• 处理器详细文档
• IPC 通信文档
• 插件开发文档
• 配置系统文档

获取帮助

如果在使用 API 时遇到问题：

1. 📖 查看相关功能的详细文档
2. 🔍 搜索 常见问题 FAQ
3. 💡 参考 最佳实践
4. 🐛 提交 GitHub Issue

---

持续更新中...

如发现文档问题或有改进建议，欢迎提交 PR！