@easy-electron/core 1.0.1-alpha.1

package/dist/index.d.cts

@@ -0,0 +1,528 @@
+import { BrowserWindowConstructorOptions, BrowserWindow, IpcMainInvokeEvent, App } from 'electron';
+import { ILogger } from '@easy-electron/logger';
+
+/**
+ * 窗口事件类型数组
+ */
+declare const WindowEventTypes: readonly ["created", "closed", "focus", "blur", "ready"];
+
+/**
+ * 窗口事件类型
+ */
+type WindowEventType = typeof WindowEventTypes[number];
+/**
+ * 窗口事件监听器
+ */
+type WindowEventListener = (instance: WindowInstance) => void;
+/**
+ * 窗口配置接口
+ */
+interface EasyWindowConfig {
+    id?: string;
+    /**
+     * 窗口宽度，默认 800
+     */
+    width?: number;
+    /**
+     * 窗口高度，默认 600
+     */
+    height?: number;
+    /**
+     * 窗口最小宽度，默认 0
+     */
+    minWidth?: number;
+    /**
+     * 窗口最小高度，默认 0
+     */
+    minHeight?: number;
+    /**
+     * 窗口相对于屏幕左侧的偏移量，默认值为将窗口居中
+     */
+    x?: number;
+    /**
+     * 窗口相对于屏幕顶端的偏移量，默认值为将窗口居中
+     */
+    y?: number;
+    /**
+     * 窗口是否可被调整大小，默认 true
+     */
+    resizable?: boolean;
+    /**
+     * 窗口是否可被移动，默认 true
+     */
+    movable?: boolean;
+    /**
+     * 窗口是否可被最小化，默认 true
+     */
+    minimizable?: boolean;
+    /**
+     * 窗口是否可被最大化，默认 true
+     */
+    maximizable?: boolean;
+    /**
+     * 窗口是否可被关闭，默认 true
+     */
+    closable?: boolean;
+    /**
+     * 窗口是否始终显示在其他窗口之上，默认 false
+     */
+    alwaysOnTop?: boolean;
+    /**
+     * 窗口标题
+     */
+    title?: string;
+    /**
+     * 窗口图标
+     */
+    icon?: string;
+    /**
+     * 是否有边框，默认 true
+     */
+    frame?: boolean;
+    /**
+     * 使得窗口透明，默认 false
+     */
+    transparent?: boolean;
+    /**
+     * 在线地址
+     */
+    url?: string;
+    /**
+     * html 路径
+     */
+    htmlPath?: string;
+    webPreferences?: {
+        /**
+         * 预加载脚本
+         */
+        preload?: string;
+        /**
+         * 是否启用 Node integration（渲染进程是否能够直接访问 Node.js API），风险项！建议不要开启，默认 false
+         */
+        nodeIntegration?: boolean;
+        /**
+         * 是否启用上下文隔离（预加载脚本和 Electron 的内部逻辑是否在独立的上下文中运行），风险项！建议开启，默认 true
+         */
+        contextIsolation?: boolean;
+    };
+    raw?: BrowserWindowConstructorOptions;
+}
+/**
+ * 窗口实例接口
+ */
+interface WindowInstance {
+    /**
+     * 窗口ID
+     */
+    id: string;
+    /**
+     * 窗口
+     */
+    window: BrowserWindow;
+    /**
+     * 窗口配置
+     */
+    config: EasyWindowConfig;
+}
+
+/**
+ * 开发者工具模式
+ * - left 左侧
+ * - right 右侧
+ * - bottom 下方
+ * - undocked 拆离，单独一个窗口，但可以恢复为停靠状态
+ * - detach 拆离，单独一个窗口
+ */
+type DevToolsMode = 'left' | 'right' | 'bottom' | 'undocked' | 'detach';
+/**
+ * EasyElectron 配置接口
+ */
+interface EasyElectronConfig {
+    app?: {
+        name?: string;
+        /**
+         * 是否使用单例模式（只会有一个程序启动）
+         */
+        singleInstance?: boolean;
+    };
+    window?: EasyWindowConfig;
+    dev?: {
+        serverUrl?: string;
+        /**
+         * 打开开发者工具，默认 right，设置为 null 或 undefined 则不打开
+         */
+        openDevTools?: DevToolsMode;
+    };
+    prod?: {
+        /**
+         * html 页面路径
+         */
+        htmlPath?: string;
+    };
+    plugins?: EasyElectronPlugin[];
+}
+
+/**
+ * 窗口管理器类
+ * 负责创建、管理和销毁应用程序窗口
+ */
+declare class WindowManager {
+    private readonly windows;
+    private readonly defaultConfig;
+    private eventListeners;
+    private readonly logger;
+    /** 开发模式下的页面 URL（可选，替代默认的 VITE_DEV_SERVER_URL 检测） */
+    private readonly devUrl?;
+    /** 生产模式下的 HTML 路径（可选） */
+    private readonly prodHtmlPath?;
+    constructor(defaultConfig?: EasyWindowConfig, devUrl?: string, prodHtmlPath?: string);
+    /**
+     * 创建窗口
+     * @param config 窗口配置
+     * @returns 窗口实例
+     */
+    create(config?: EasyWindowConfig): Promise<WindowInstance>;
+    /**
+     * 加载窗口内容
+     */
+    private loadContent;
+    /**
+     * 设置窗口事件监听器
+     */
+    private setupWindowListeners;
+    /**
+     * 获取窗口实例
+     * @param id 窗口 ID
+     * @returns 窗口实例或 undefined
+     */
+    get(id: string): WindowInstance | undefined;
+    /**
+     * 获取所有窗口实例
+     * @returns 窗口实例数组
+     */
+    getAll(): WindowInstance[];
+    /**
+     * 检查窗口是否存在
+     * @param id 窗口 ID
+     * @returns 是否存在
+     */
+    has(id: string): boolean;
+    /**
+     * 获取窗口数量
+     * @returns 窗口数量
+     */
+    count(): number;
+    /**
+     * 关闭窗口
+     * @param id 窗口 ID
+     */
+    close(id: string): void;
+    /**
+     * 关闭所有窗口
+     */
+    closeAll(): void;
+    /**
+     * 注册窗口事件监听器
+     * @param event 事件类型
+     * @param listener 监听器函数
+     */
+    on(event: WindowEventType, listener: WindowEventListener): void;
+    /**
+     * 移除窗口事件监听器
+     * @param event 事件类型
+     * @param listener 监听器函数
+     */
+    off(event: WindowEventType, listener: WindowEventListener): void;
+    /**
+     * 触发窗口事件
+     * @param event 事件类型
+     * @param instance 窗口实例
+     */
+    protected emit(event: WindowEventType, instance: WindowInstance): void;
+    /**
+     * 获取默认配置
+     */
+    getDefaultConfig(): EasyWindowConfig;
+    /**
+     * 构建降级错误页面（当窗口内容加载失败时显示）
+     * @param windowId 窗口 ID
+     * @param errorMessage 错误信息
+     * @returns HTML 字符串
+     */
+    private buildErrorPage;
+    clear(): void;
+}
+
+/**
+ * IPC 处理器类型
+ */
+type IPCHandler<T = any, R = any> = (event: IpcMainInvokeEvent, ...args: T[]) => R | Promise<R>;
+/**
+ * IPC 处理器选项
+ */
+interface IPCHandlerOptions {
+    sync?: boolean;
+}
+
+/**
+ * IPC 管理器类
+ * 简化主进程和渲染进程之间的 IPC 通信
+ */
+declare class IpcManager {
+    private readonly handlers;
+    private readonly windowManager;
+    private readonly logger;
+    constructor(windowManager: WindowManager);
+    /**
+     * 注册 IPC 处理器
+     * @param channel IPC 通道名称
+     * @param handler 处理器函数
+     * @param options 处理器选项
+     */
+    handle<T = any, R = any>(channel: string, handler: IPCHandler<T, R>, options?: IPCHandlerOptions): void;
+    /**
+     * 批量注册 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: Record<string, unknown>, moduleName?: string): void;
+    /**
+     * 移除 IPC 处理器
+     * @param channel IPC 通道名称
+     */
+    removeHandler(channel: string): void;
+    /**
+     * 移除所有 IPC 处理器
+     */
+    removeAllHandlers(): void;
+    /**
+     * 获取已注册的处理器数量
+     */
+    count(): number;
+    /**
+     * 检查处理器是否已注册
+     */
+    has(channel: string): boolean;
+    /**
+     * 向主窗口发送消息
+     * @param channel IPC 通道名称
+     * @param args 消息参数
+     */
+    send(channel: string, ...args: any[]): void;
+    /**
+     * 向指定窗口发送消息
+     * @param windowId 窗口 ID
+     * @param channel IPC 通道名称
+     * @param args 消息参数
+     */
+    sendTo(windowId: string, channel: string, ...args: any[]): void;
+    /**
+     * 向所有窗口广播消息
+     * @param channel IPC 通道名称
+     * @param args 消息参数
+     */
+    broadcast(channel: string, ...args: any[]): void;
+}
+
+/**
+ * 插件上下文接口
+ */
+interface PluginContext {
+    /** 窗口管理器 */
+    windows: WindowManager;
+    /** IPC 管理器 */
+    ipc: IpcManager;
+    /** Electron app 实例 */
+    app: App;
+    /** 应用配置 */
+    config: EasyElectronConfig;
+}
+/**
+ * 插件接口
+ */
+interface EasyElectronPlugin {
+    name: string;
+    version?: string;
+    install?(context: PluginContext): void | Promise<void>;
+    onReady?(context: PluginContext): void | Promise<void>;
+    onBeforeQuit?(context: PluginContext): void | Promise<void>;
+}
+
+/**
+ * EasyElectron 核心类
+ * 应用程序的主入口点
+ */
+declare class EasyElectron {
+    private readonly windowManager;
+    private readonly ipcManager;
+    private lifecycleManager;
+    private readonly pluginManager;
+    private readonly config;
+    constructor(config?: EasyElectronConfig);
+    /**
+     * 获取窗口管理器
+     */
+    get windows(): WindowManager;
+    /**
+     * 获取 IPC 管理器
+     */
+    get ipc(): IpcManager;
+    /**
+     * 初始化应用程序
+     */
+    init(): Promise<void>;
+    /**
+     * 注册插件
+     */
+    use(plugin: EasyElectronPlugin): this;
+    /**
+     * 注册 ready 钩子
+     */
+    onReady(callback: () => void | Promise<void>): this;
+    /**
+     * 注册 activate 钩子
+     */
+    onActivate(callback: () => void | Promise<void>): this;
+    /**
+     * 注册 beforeQuit 钩子
+     */
+    onBeforeQuit(callback: () => void | Promise<void>): this;
+    /**
+     * 设置 IPC 处理器
+     * @param setup IPC 处理器设置函数
+     */
+    setupIpc(setup: (ipc: IpcManager) => void): this;
+    /**
+     * 批量注册 IPC 处理器
+     *
+     * 接收 defineIpc 返回的定义对象，自动识别模块名并注册所有处理器。
+     *
+     * @param handlers defineIpc 返回的处理器映射
+     *
+     * @example
+     * ```ts
+     * import ipcHandlers from './electron/ipc/handlers'
+     * app.registerIpc(ipcHandlers)
+     * ```
+     */
+    registerIpc(handlers: Record<string, unknown>): this;
+    /**
+     * 修改日志实现
+     * @param logger 日志实现
+     */
+    setLogger(logger: ILogger): this;
+}
+
+/**
+ * 生命周期钩子类型
+ */
+type LifecycleHook = () => void | Promise<void>;
+
+/**
+ * 生命周期管理器
+ *
+ * 管理 Electron 应用的生命周期事件，提供钩子注册机制。
+ *
+ * 事件处理策略：
+ * - ready / activate → 直接执行异步钩子
+ * - will-quit → 阻止退出 → 执行清理钩子 → 强制退出（避免 event.preventDefault + app.quit 循环）
+ */
+declare class LifecycleManager {
+    private app;
+    private readonly windowManager;
+    private readonly readyHooks;
+    private readonly activateHooks;
+    private readonly beforeQuitHooks;
+    constructor(app: App, windowManager: WindowManager);
+    /**
+     * 注册 ready 钩子
+     * @param hook 钩子函数
+     */
+    onReady(hook: LifecycleHook): void;
+    /**
+     * 注册 activate 钩子（macOS）
+     * @param hook 钩子函数
+     */
+    onActivate(hook: LifecycleHook): void;
+    /**
+     * 注册退出前的清理钩子
+     * @param hook 钩子函数
+     */
+    onBeforeQuit(hook: LifecycleHook): void;
+    /**
+     * 初始化生命周期监听
+     */
+    init(): void;
+    /**
+     * 执行钩子集合
+     * @param hooks 钩子函数集合
+     */
+    private executeHooks;
+}
+
+/**
+ * 插件管理器类
+ * 管理插件的注册和生命周期
+ */
+declare class PluginManager {
+    private plugins;
+    private readonly context;
+    constructor(context: PluginContext);
+    /**
+     * 注册插件
+     * @param plugin 插件对象
+     */
+    register(plugin: EasyElectronPlugin): void;
+    /**
+     * 获取插件
+     * @param name 插件名称
+     * @returns 插件对象或 undefined
+     */
+    get(name: string): EasyElectronPlugin | undefined;
+    /**
+     * 检查插件是否已注册
+     * @param name 插件名称
+     * @returns 是否已注册
+     */
+    has(name: string): boolean;
+    /**
+     * 调用插件钩子
+     * @param hookName 钩子名称
+     */
+    callHook(hookName: keyof EasyElectronPlugin): Promise<void>;
+    /**
+     * 获取已注册的插件数量
+     */
+    count(): number;
+    /**
+     * 获取所有插件
+     */
+    getAll(): EasyElectronPlugin[];
+}
+
+/**
+ * EasyElectron 自定义错误类
+ */
+declare class EasyElectronError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * 创建 EasyElectron 应用实例
+ * @param config 应用配置
+ * @returns EasyElectron 实例
+ */
+declare function createElectronApp(config?: EasyElectronConfig): EasyElectron;
+
+export { EasyElectron, EasyElectronError, IpcManager, LifecycleManager, PluginManager, WindowManager, createElectronApp };
+export type { DevToolsMode, EasyElectronConfig, EasyElectronPlugin, EasyWindowConfig, IPCHandler, IPCHandlerOptions, LifecycleHook, PluginContext, WindowEventListener, WindowEventType, WindowInstance };