@easy-electron/core 1.0.1-alpha.1

package/dist/index.mjs

@@ -0,0 +1,787 @@
+import { BrowserWindow, ipcMain, app } from 'electron';
+import { Logger } from '@easy-electron/logger';
+import path from 'node:path';
+import { EEUtil, ConfigUtil, ipcRegistry } from '@easy-electron/utils';
+import { randomUUID } from 'node:crypto';
+
+class EasyElectronError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EasyElectronError";
+  }
+}
+
+class IpcError extends EasyElectronError {
+  /** 错误码 */
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "IpcError";
+    this.code = code;
+  }
+  /**
+   * 将任意错误包装为 IpcError
+   * @param error 原始错误
+   * @returns IpcError 实例
+   */
+  static from(error) {
+    if (error instanceof IpcError) return error;
+    const message = error instanceof Error ? error.message : String(error);
+    return new IpcError("IPC_UNKNOWN" /* UNKNOWN */, message);
+  }
+}
+
+const WindowEventTypes = ["created", "closed", "focus", "blur", "ready"];
+const DEFAULT_MAIN_WINDOW_ID = "main";
+const DEFAULT_APP_CONFIG = {
+  app: {
+    name: "Electron App",
+    singleInstance: true
+  },
+  window: {
+    width: 800,
+    height: 600,
+    webPreferences: {
+      preload: EEUtil.getDefaultPreloadPath()
+    }
+  },
+  dev: {
+    openDevTools: "right"
+  },
+  prod: {
+    htmlPath: "dist/index.html"
+  },
+  plugins: []
+};
+
+class WindowManager {
+  windows;
+  defaultConfig;
+  eventListeners;
+  logger = Logger.scope("WindowManager");
+  /** 开发模式下的页面 URL（可选，替代默认的 VITE_DEV_SERVER_URL 检测） */
+  devUrl;
+  /** 生产模式下的 HTML 路径（可选） */
+  prodHtmlPath;
+  constructor(defaultConfig, devUrl, prodHtmlPath) {
+    this.windows = /* @__PURE__ */ new Map();
+    this.defaultConfig = defaultConfig || {};
+    this.eventListeners = /* @__PURE__ */ new Map();
+    this.devUrl = devUrl;
+    this.prodHtmlPath = prodHtmlPath;
+    WindowEventTypes.forEach((type) => {
+      this.eventListeners.set(type, /* @__PURE__ */ new Set());
+    });
+  }
+  /**
+   * 创建窗口
+   * @param config 窗口配置
+   * @returns 窗口实例
+   */
+  async create(config) {
+    const mergedConfig = ConfigUtil.deepMergeConfig(this.defaultConfig, config || {});
+    const windowId = this.windows.size === 0 ? DEFAULT_MAIN_WINDOW_ID : mergedConfig.id || randomUUID();
+    if (this.windows.has(windowId)) {
+      const error = new EasyElectronError(`Window with id '${windowId}' already exists`);
+      this.logger.error(error.message);
+      throw error;
+    }
+    this.logger.info(`Creating window with id '${windowId}'`);
+    const { id: _id, url: _url, htmlPath: _htmlPath, raw, ...nativeOptions } = mergedConfig;
+    const windowOptions = ConfigUtil.deepMergeConfig(
+      nativeOptions,
+      raw || {}
+    );
+    const browserWindow = new BrowserWindow(windowOptions);
+    const instance = {
+      id: windowId,
+      window: browserWindow,
+      config: mergedConfig
+    };
+    this.windows.set(windowId, instance);
+    this.setupWindowListeners(instance);
+    try {
+      await this.loadContent(browserWindow, mergedConfig);
+    } catch (error) {
+      this.logger.error(`\u7A97\u53E3\u52A0\u8F7D\u5931\u8D25 [${windowId}]:`, error instanceof Error ? error.message : "");
+      const errMsg = error instanceof Error ? error.message : String(error);
+      browserWindow.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(this.buildErrorPage(windowId, errMsg))}`);
+    }
+    this.emit("created", instance);
+    return instance;
+  }
+  /**
+   * 加载窗口内容
+   */
+  async loadContent(window, config) {
+    if (config.url) {
+      await window.loadURL(config.url);
+    } else if (config.htmlPath) {
+      await window.loadFile(config.htmlPath);
+    } else if (this.devUrl) {
+      await window.loadURL(this.devUrl);
+    } else {
+      const htmlPath = this.prodHtmlPath || path.join(EEUtil.getAppRoot(), "dist", "index.html");
+      await window.loadFile(htmlPath);
+    }
+  }
+  /**
+   * 设置窗口事件监听器
+   */
+  setupWindowListeners(instance) {
+    const { window } = instance;
+    window.once("ready-to-show", () => {
+      this.emit("ready", instance);
+    });
+    window.on("focus", () => {
+      this.emit("focus", instance);
+    });
+    window.on("blur", () => {
+      this.emit("blur", instance);
+    });
+    window.on("close", () => {
+      this.emit("closed", instance);
+      this.windows.delete(instance.id);
+    });
+  }
+  /**
+   * 获取窗口实例
+   * @param id 窗口 ID
+   * @returns 窗口实例或 undefined
+   */
+  get(id) {
+    return this.windows.get(id);
+  }
+  /**
+   * 获取所有窗口实例
+   * @returns 窗口实例数组
+   */
+  getAll() {
+    return Array.from(this.windows.values());
+  }
+  /**
+   * 检查窗口是否存在
+   * @param id 窗口 ID
+   * @returns 是否存在
+   */
+  has(id) {
+    return this.windows.has(id);
+  }
+  /**
+   * 获取窗口数量
+   * @returns 窗口数量
+   */
+  count() {
+    return this.windows.size;
+  }
+  /**
+   * 关闭窗口
+   * @param id 窗口 ID
+   */
+  close(id) {
+    const instance = this.windows.get(id);
+    if (!instance) {
+      const error = new EasyElectronError(`Window with id '${id}' not found`);
+      this.logger.error(error.message);
+      throw error;
+    }
+    this.logger.info(`Closing window with id '${id}'`);
+    if (!instance.window.isDestroyed()) {
+      instance.window.close();
+    }
+  }
+  /**
+   * 关闭所有窗口
+   */
+  closeAll() {
+    const windowIds = Array.from(this.windows.keys());
+    windowIds.forEach((id) => {
+      try {
+        this.close(id);
+      } catch (error) {
+        console.error(`Error closing window '${id}':`, error);
+      }
+    });
+  }
+  /**
+   * 注册窗口事件监听器
+   * @param event 事件类型
+   * @param listener 监听器函数
+   */
+  on(event, listener) {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.add(listener);
+    }
+  }
+  /**
+   * 移除窗口事件监听器
+   * @param event 事件类型
+   * @param listener 监听器函数
+   */
+  off(event, listener) {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.delete(listener);
+    }
+  }
+  /**
+   * 触发窗口事件
+   * @param event 事件类型
+   * @param instance 窗口实例
+   */
+  emit(event, instance) {
+    const listeners = this.eventListeners.get(event);
+    if (listeners) {
+      listeners.forEach((listener) => {
+        try {
+          listener(instance);
+        } catch (error) {
+          console.error(`Error in window event listener for '${event}':`, error);
+        }
+      });
+    }
+  }
+  /**
+   * 获取默认配置
+   */
+  getDefaultConfig() {
+    return ConfigUtil.deepMergeConfig({}, this.defaultConfig);
+  }
+  /**
+   * 构建降级错误页面（当窗口内容加载失败时显示）
+   * @param windowId 窗口 ID
+   * @param errorMessage 错误信息
+   * @returns HTML 字符串
+   */
+  buildErrorPage(windowId, errorMessage) {
+    return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      display: flex; justify-content: center; align-items: center;
+      min-height: 100vh; background: #1a1a2e; color: #e0e0e0;
+    }
+    .card {
+      background: #16213e; border-radius: 12px; padding: 40px;
+      max-width: 520px; text-align: center;
+      box-shadow: 0 8px 32px rgba(0,0,0,0.3);
+    }
+    h1 { font-size: 20px; color: #e94560; margin-bottom: 16px; }
+    .detail {
+      background: #0f3460; border-radius: 8px; padding: 16px;
+      font-size: 13px; color: #a0a0b0; text-align: left;
+      word-break: break-all; margin: 16px 0;
+    }
+    .hint { font-size: 12px; color: #666; }
+    .hint code { background: #0f3460; padding: 2px 6px; border-radius: 4px; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>\u26A0 \u7A97\u53E3\u52A0\u8F7D\u5931\u8D25</h1>
+    <p>\u7A97\u53E3 <strong>${windowId}</strong> \u7684\u5185\u5BB9\u672A\u80FD\u6210\u529F\u52A0\u8F7D\u3002</p>
+    <div class="detail">${errorMessage}</div>
+    <p class="hint">
+      \u8BF7\u68C0\u67E5 <code>htmlPath</code> \u6216 <code>url</code> \u914D\u7F6E\uFF0C\u6216\u786E\u4FDD\u5F00\u53D1\u670D\u52A1\u5668\u5DF2\u542F\u52A8\u3002
+    </p>
+  </div>
+</body>
+</html>`;
+  }
+  clear() {
+    this.windows.clear();
+    this.eventListeners.clear();
+  }
+}
+
+const IPC_MODULE_KEY = Symbol.for("easy-electron:ipc-module");
+class IpcManager {
+  handlers;
+  windowManager;
+  logger = Logger.scope("IpcManager");
+  constructor(windowManager) {
+    this.handlers = /* @__PURE__ */ new Map();
+    this.windowManager = windowManager;
+  }
+  /**
+   * 注册 IPC 处理器
+   * @param channel IPC 通道名称
+   * @param handler 处理器函数
+   * @param options 处理器选项
+   */
+  handle(channel, handler, options) {
+    if (this.handlers.has(channel)) {
+      const error = new EasyElectronError(`IPC handler for channel '${channel}' already exists`);
+      this.logger.error(error.message);
+      throw error;
+    }
+    this.logger.info(`Registering IPC handler for channel '${channel}'`);
+    this.handlers.set(channel, handler);
+    if (options?.sync) {
+      ipcMain.on(channel, (event, ...args) => {
+        try {
+          const result = handler(event, ...args);
+          event.returnValue = result;
+        } catch (error) {
+          console.error(`Error in sync IPC handler for '${channel}':`, error);
+          event.returnValue = { error: error instanceof Error ? error.message : "Unknown error" };
+        }
+      });
+    } else {
+      ipcMain.handle(channel, async (event, ...args) => {
+        try {
+          return await handler(event, ...args);
+        } catch (error) {
+          console.error(`Error in async IPC handler for '${channel}':`, error);
+          throw error;
+        }
+      });
+    }
+  }
+  /**
+   * 批量注册 defineIpc 返回的处理器映射
+   *
+   * 自动识别函数形式（handle）和对象形式（{type, handler}），
+   * 根据 moduleName 前缀拼接 IPC 通道名。
+   *
+   * @param handlers defineIpc 返回的处理器映射对象
+   * @param moduleName 可选的模块名称（用于拼接通道前缀，如 `module:method`）
+   *
+   * @example
+   * ```ts
+   * import ipcHandlers from './electron/ipc/handlers'
+   * app.ipc.registerHandlers(ipcHandlers)
+   * ```
+   */
+  registerHandlers(handlers, moduleName) {
+    if (!moduleName) {
+      moduleName = handlers[IPC_MODULE_KEY];
+    }
+    for (const [name, handler] of Object.entries(handlers)) {
+      if (typeof name === "string" && name.startsWith("__")) continue;
+      const channel = moduleName ? `${moduleName}:${name}` : name;
+      if (typeof handler === "object" && handler !== null && "handler" in handler) {
+        const config = handler;
+        const type = config.type ?? "handle";
+        const handlerFn = config.handler;
+        if (type === "on" || type === "once") {
+          this.logger.info(`\u6CE8\u518C IPC \u5904\u7406\u5668(${type}): ${channel}`);
+          const method = type === "once" ? "once" : "on";
+          ipcMain[method](channel, (event, ...args) => {
+            try {
+              handlerFn(event, ...args);
+            } catch (error) {
+              console.error(`Error in IPC ${type} handler for '${channel}':`, error);
+            }
+          });
+        } else {
+          this.logger.info(`\u6CE8\u518C IPC \u5904\u7406\u5668(${type}): ${channel}`);
+          const method = type === "handleOnce" ? "handleOnce" : "handle";
+          ipcMain[method](channel, async (event, ...args) => {
+            try {
+              return await handlerFn(event, ...args);
+            } catch (error) {
+              console.error(`Error in IPC ${type} handler for '${channel}':`, error);
+              throw IpcError.from(error);
+            }
+          });
+        }
+        if (!this.handlers.has(channel)) {
+          this.handlers.set(channel, handlerFn);
+        }
+      } else if (typeof handler === "function") {
+        this.logger.info(`\u6CE8\u518C IPC \u5904\u7406\u5668(handle): ${channel}`);
+        ipcMain.handle(channel, async (event, ...args) => {
+          try {
+            return await handler(event, ...args);
+          } catch (error) {
+            console.error(`Error in IPC handler for '${channel}':`, error);
+            throw IpcError.from(error);
+          }
+        });
+        if (!this.handlers.has(channel)) {
+          this.handlers.set(channel, handler);
+        }
+      } else {
+        this.logger.warn(`\u8DF3\u8FC7\u65E0\u6CD5\u8BC6\u522B\u7684\u5904\u7406\u5668: ${channel}`);
+      }
+    }
+  }
+  /**
+   * 移除 IPC 处理器
+   * @param channel IPC 通道名称
+   */
+  removeHandler(channel) {
+    if (!this.handlers.has(channel)) {
+      return;
+    }
+    this.handlers.delete(channel);
+    ipcMain.removeHandler(channel);
+    ipcMain.removeAllListeners(channel);
+  }
+  /**
+   * 移除所有 IPC 处理器
+   */
+  removeAllHandlers() {
+    const channels = Array.from(this.handlers.keys());
+    channels.forEach((channel) => {
+      this.removeHandler(channel);
+    });
+  }
+  /**
+   * 获取已注册的处理器数量
+   */
+  count() {
+    return this.handlers.size;
+  }
+  /**
+   * 检查处理器是否已注册
+   */
+  has(channel) {
+    return this.handlers.has(channel);
+  }
+  /**
+   * 向主窗口发送消息
+   * @param channel IPC 通道名称
+   * @param args 消息参数
+   */
+  send(channel, ...args) {
+    const instance = this.windowManager.get(DEFAULT_MAIN_WINDOW_ID);
+    if (!instance) {
+      throw new EasyElectronError("Main window not found");
+    }
+    if (!instance.window.isDestroyed()) {
+      instance.window.webContents.send(channel, ...args);
+    }
+  }
+  /**
+   * 向指定窗口发送消息
+   * @param windowId 窗口 ID
+   * @param channel IPC 通道名称
+   * @param args 消息参数
+   */
+  sendTo(windowId, channel, ...args) {
+    const instance = this.windowManager.get(windowId);
+    if (!instance) {
+      throw new EasyElectronError(`Window with id '${windowId}' not found`);
+    }
+    if (!instance.window.isDestroyed()) {
+      instance.window.webContents.send(channel, ...args);
+    }
+  }
+  /**
+   * 向所有窗口广播消息
+   * @param channel IPC 通道名称
+   * @param args 消息参数
+   */
+  broadcast(channel, ...args) {
+    const instances = this.windowManager.getAll();
+    instances.forEach((instance) => {
+      if (!instance.window.isDestroyed()) {
+        try {
+          instance.window.webContents.send(channel, ...args);
+        } catch (error) {
+          console.error(`Error broadcasting to window '${instance.id}':`, error);
+        }
+      }
+    });
+  }
+}
+
+class LifecycleManager {
+  app;
+  windowManager;
+  readyHooks;
+  activateHooks;
+  beforeQuitHooks;
+  constructor(app, windowManager) {
+    this.app = app;
+    this.windowManager = windowManager;
+    this.readyHooks = /* @__PURE__ */ new Set();
+    this.activateHooks = /* @__PURE__ */ new Set();
+    this.beforeQuitHooks = /* @__PURE__ */ new Set();
+  }
+  /**
+   * 注册 ready 钩子
+   * @param hook 钩子函数
+   */
+  onReady(hook) {
+    this.readyHooks.add(hook);
+  }
+  /**
+   * 注册 activate 钩子（macOS）
+   * @param hook 钩子函数
+   */
+  onActivate(hook) {
+    this.activateHooks.add(hook);
+  }
+  /**
+   * 注册退出前的清理钩子
+   * @param hook 钩子函数
+   */
+  onBeforeQuit(hook) {
+    this.beforeQuitHooks.add(hook);
+  }
+  /**
+   * 初始化生命周期监听
+   */
+  init() {
+    this.app.whenReady().then(async () => {
+      await this.executeHooks(this.readyHooks);
+    });
+    this.app.on("activate", async () => {
+      await this.executeHooks(this.activateHooks);
+    });
+    this.app.on("will-quit", async (event) => {
+      if (this.beforeQuitHooks.size > 0) {
+        event.preventDefault();
+        try {
+          await this.executeHooks(this.beforeQuitHooks);
+        } catch (error) {
+          console.error("\u9000\u51FA\u524D\u6E05\u7406\u5931\u8D25:", error);
+        }
+        this.app.exit(0);
+      }
+    });
+    this.app.on("window-all-closed", () => {
+      if (process.platform !== "darwin") {
+        this.app.quit();
+        this.windowManager.clear();
+      }
+    });
+  }
+  /**
+   * 执行钩子集合
+   * @param hooks 钩子函数集合
+   */
+  async executeHooks(hooks) {
+    for (const hook of hooks) {
+      try {
+        await hook();
+      } catch (error) {
+        console.error("\u751F\u547D\u5468\u671F\u94A9\u5B50\u6267\u884C\u5931\u8D25:", error);
+      }
+    }
+  }
+}
+
+class PluginManager {
+  plugins;
+  context;
+  constructor(context) {
+    this.plugins = /* @__PURE__ */ new Map();
+    this.context = context;
+  }
+  /**
+   * 注册插件
+   * @param plugin 插件对象
+   */
+  register(plugin) {
+    if (!plugin.name) {
+      throw new EasyElectronError("Plugin must have a name");
+    }
+    if (this.plugins.has(plugin.name)) {
+      throw new EasyElectronError(`Plugin '${plugin.name}' is already registered`);
+    }
+    this.plugins.set(plugin.name, plugin);
+  }
+  /**
+   * 获取插件
+   * @param name 插件名称
+   * @returns 插件对象或 undefined
+   */
+  get(name) {
+    return this.plugins.get(name);
+  }
+  /**
+   * 检查插件是否已注册
+   * @param name 插件名称
+   * @returns 是否已注册
+   */
+  has(name) {
+    return this.plugins.has(name);
+  }
+  /**
+   * 调用插件钩子
+   * @param hookName 钩子名称
+   */
+  async callHook(hookName) {
+    for (const plugin of this.plugins.values()) {
+      const hook = plugin[hookName];
+      if (typeof hook === "function") {
+        try {
+          await hook.call(plugin, this.context);
+        } catch (error) {
+          console.error(`Error in plugin '${plugin.name}' hook '${String(hookName)}':`, error);
+        }
+      }
+    }
+  }
+  /**
+   * 获取已注册的插件数量
+   */
+  count() {
+    return this.plugins.size;
+  }
+  /**
+   * 获取所有插件
+   */
+  getAll() {
+    return Array.from(this.plugins.values());
+  }
+}
+
+class EasyElectron {
+  windowManager;
+  ipcManager;
+  lifecycleManager;
+  pluginManager;
+  config;
+  constructor(config) {
+    this.config = ConfigUtil.deepMergeConfig(DEFAULT_APP_CONFIG, config || {});
+    this.windowManager = new WindowManager(
+      this.config.window,
+      this.config.dev?.serverUrl,
+      this.config.prod?.htmlPath
+    );
+    this.ipcManager = new IpcManager(this.windowManager);
+    this.lifecycleManager = new LifecycleManager(app, this.windowManager);
+    const pluginContext = {
+      windows: this.windowManager,
+      ipc: this.ipcManager,
+      app,
+      config: this.config
+    };
+    this.pluginManager = new PluginManager(pluginContext);
+    if (this.config.plugins) {
+      this.config.plugins.forEach((plugin) => {
+        this.pluginManager.register(plugin);
+      });
+    }
+  }
+  /**
+   * 获取窗口管理器
+   */
+  get windows() {
+    return this.windowManager;
+  }
+  /**
+   * 获取 IPC 管理器
+   */
+  get ipc() {
+    return this.ipcManager;
+  }
+  /**
+   * 初始化应用程序
+   */
+  async init() {
+    if (this.config.app?.singleInstance) {
+      const gotLock = app.requestSingleInstanceLock();
+      if (!gotLock) {
+        app.quit();
+        return;
+      }
+      app.on("second-instance", () => {
+        const mainWindow = this.windowManager.get("main");
+        if (mainWindow && !mainWindow.window.isDestroyed()) {
+          if (mainWindow.window.isMinimized()) mainWindow.window.restore();
+          mainWindow.window.focus();
+        }
+      });
+    }
+    await this.pluginManager.callHook("install");
+    const entries = ipcRegistry.drain();
+    for (const entry of entries) {
+      this.ipcManager.registerHandlers(entry.handlers, entry.moduleName);
+    }
+    this.lifecycleManager.onActivate(async () => {
+      if (this.windowManager.count() === 0) {
+        await this.windowManager.create();
+      }
+    });
+    this.lifecycleManager.onReady(async () => {
+      await this.pluginManager.callHook("onReady");
+      const instance = await this.windowManager.create();
+      if (EEUtil.isDev && this.config.dev?.openDevTools) {
+        instance.window.webContents.openDevTools({ mode: this.config.dev?.openDevTools || "right" });
+      }
+    });
+    this.lifecycleManager.onBeforeQuit(async () => {
+      await this.pluginManager.callHook("onBeforeQuit");
+      this.ipcManager.removeAllHandlers();
+    });
+    this.lifecycleManager.init();
+  }
+  /**
+   * 注册插件
+   */
+  use(plugin) {
+    this.pluginManager.register(plugin);
+    return this;
+  }
+  /**
+   * 注册 ready 钩子
+   */
+  onReady(callback) {
+    this.lifecycleManager.onReady(callback);
+    return this;
+  }
+  /**
+   * 注册 activate 钩子
+   */
+  onActivate(callback) {
+    this.lifecycleManager.onActivate(callback);
+    return this;
+  }
+  /**
+   * 注册 beforeQuit 钩子
+   */
+  onBeforeQuit(callback) {
+    this.lifecycleManager.onBeforeQuit(callback);
+    return this;
+  }
+  /**
+   * 设置 IPC 处理器
+   * @param setup IPC 处理器设置函数
+   */
+  setupIpc(setup) {
+    setup(this.ipcManager);
+    return this;
+  }
+  /**
+   * 批量注册 IPC 处理器
+   *
+   * 接收 defineIpc 返回的定义对象，自动识别模块名并注册所有处理器。
+   *
+   * @param handlers defineIpc 返回的处理器映射
+   *
+   * @example
+   * ```ts
+   * import ipcHandlers from './electron/ipc/handlers'
+   * app.registerIpc(ipcHandlers)
+   * ```
+   */
+  registerIpc(handlers) {
+    this.ipcManager.registerHandlers(handlers);
+    return this;
+  }
+  /**
+   * 修改日志实现
+   * @param logger 日志实现
+   */
+  setLogger(logger) {
+    Logger.setImpl(logger);
+    return this;
+  }
+}
+
+function createElectronApp(config) {
+  return new EasyElectron(config);
+}
+
+export { EasyElectron, EasyElectronError, IpcManager, LifecycleManager, PluginManager, WindowManager, createElectronApp };