electron-multi-app-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dsir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,611 @@
+# electron-multi-app-kit
+
+> Electron 主进程生命周期 & 模块库 — setup 风格，Hook 驱动，按需配置。
+
+为 Electron 应用的主进程提供可复用的脚手架：窗口管理、IPC 事件、系统托盘、自动更新、下载管理、HTTP/WS 服务等模块，全部通过配置驱动，无需重复编写样板代码。
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install electron-multi-app-kit
+```
+
+### 最小示例
+
+用 `createElectronApp` 替换你的主进程入口：
+
+```ts
+// electron/main/index.ts
+import { createElectronApp } from 'electron-multi-app-kit'
+import path from 'node:path'
+
+const __dirname = path.dirname(new URL(import.meta.url).pathname)
+
+createElectronApp({
+  // 路径配置（必填）
+  paths: {
+    rendererDist: path.join(__dirname, '../../dist'),
+    mainDist: path.join(__dirname, '../../dist-electron'),
+    publicDir: path.join(__dirname, '../../public'),
+    preloadScript: path.join(__dirname, '../preload/index.js'),
+    iconPath: path.join(__dirname, '../../public/icons/icon.ico'),
+  },
+
+  // 窗口定义（必填）
+  windows: [
+    {
+      type: 'main',
+      options: {
+        width: 1200,
+        height: 800,
+        frame: false,
+        webPreferences: { webviewTag: true },
+      },
+      onCreate(win) {
+        // 加载页面 —— 适合用 Vite dev server 或本地文件
+        if (process.env.VITE_DEV_SERVER_URL) {
+          win.loadURL(process.env.VITE_DEV_SERVER_URL)
+        } else {
+          win.loadFile(path.join(__dirname, '../../dist/index.html'))
+        }
+      },
+    },
+  ],
+
+  mainWindowType: 'main',
+})
+```
+
+---
+
+## 配置结构
+
+```ts
+interface ElectronCliConfig {
+  paths: ElectronCliPaths          // 必填 - 路径配置
+  windows: WindowDefinition[]      // 必填 - 窗口定义
+  mainWindowType: string           // 必填 - 主窗口标识
+
+  isDev?: boolean                  // 开发模式
+  defaultWindowOptions?: BrowserWindowConstructorOptions  // 默认窗口选项
+
+  lifecycle?: LifecycleHooks       // 生命周期钩子
+  ipc?: IpcOptions                 // IPC 配置
+  session?: SessionConfig          // Session 拦截
+  tray?: TrayConfig                // 系统托盘
+  instance?: InstanceConfig        // 单实例锁
+  updater?: UpdaterConfig          // 自动更新
+}
+```
+
+---
+
+## 核心功能
+
+### 1. 路径配置 `paths`
+
+解耦构建工具（Vite/Webpack）的路径依赖，所有模块通过此配置获取路径。
+
+```ts
+paths: {
+  rendererDist: string      // 渲染进程构建产物目录
+  mainDist: string          // 主进程构建产物目录
+  publicDir: string         // 静态资源目录
+  preloadScript: string     // preload 脚本绝对路径
+  iconPath: string          // 应用图标路径
+  userAgent?: string        // 自定义 UA（未注入 node 时使用）
+}
+```
+
+### 2. 窗口定义 `windows`
+
+用声明式配置替代硬编码的 `WindowType` 枚举和 switch/case。
+
+```ts
+windows: [
+  {
+    type: 'main',                // 窗口类型标识
+    options: {                   // BrowserWindow 构造选项
+      width: 1200,
+      height: 800,
+      frame: false,
+      webPreferences: {
+        preload: '...',          // 可选，默认使用 paths.preloadScript
+        webviewTag: true,
+      },
+    },
+    onCreate(win) {
+      // 窗口创建后立即执行 —— 加载 URL、设置位置等
+      win.loadURL('https://example.com')
+    },
+  },
+]
+```
+
+`WindowManager` 会自动：
+- 合并 `defaultWindowOptions` + 各窗口的 `options`
+- 设置菜单隐藏、`ready-to-show`、外部链接处理
+- 转发 `fullscreen-change` / `maximize` / `minimize` 等状态到渲染进程
+
+### 3. IPC 事件 `ipc`
+
+内置 7 类 IPC 模块，同时支持三种方式自定义：
+
+```ts
+ipc: {
+  // 方式一：结构化定义
+  extraHandlers: [
+    { channel: 'dev-test', type: 'handle', handler: (e, ...args) => { /* ... */ } },
+    { channel: 'log', type: 'on', handler: (e, msg) => console.log(msg) },
+  ],
+
+  // 方式二：覆盖特定 channel
+  overrides: {
+    'window-control': { channel: 'window-control', type: 'handle', handler: myHandler },
+  },
+
+  // 方式三：完全自由的 ipcMain 配置
+  setup(ipcMain) {
+    ipcMain.handle('get-ipconfig', async () => await getLocalIP())
+    ipcMain.on('custom-event', (event, data) => { /* ... */ })
+  },
+
+  // 禁用不需要的内置模块
+  disabledBuiltins: ['downloader', 'notification'],
+}
+```
+
+**注册时序**：内置模块 → extraHandlers → overrides → `setup(ipcMain)`
+
+`setup` 最后调用，可以覆盖任何之前注册的 handler。
+
+#### 内置 IPC 模块
+
+| 模块 | Channel | 功能 |
+|------|---------|------|
+| `window-control` | `window-control` | BrowserWindow 控制（最小化/最大化/全屏/置顶/属性查询） |
+| `fs-api` | `fs-api` | fs 模块 IPC 桥接（readFile/writeFile/readFileAsBase64 等） |
+| `dialog` | `open-file-dialog` `show-message-box` | 原生对话框 |
+| `shell` | `open-file` `open-external` `show-file` | 文件/链接打开 |
+| `downloader` | `download-file` `download-controler` `get-download-tasks` | 下载管理 |
+| `notification` | `show-notification` | 原生通知 |
+| `window-move` | `window-move` `window-move-start` `window-move-end` | 无边框窗口拖拽 |
+
+**框架级 handler**（不可单独禁用）：
+
+| Channel | 功能 |
+|---------|------|
+| `get-preload` | 获取 preload 路径 |
+| `get-renderer-dist` | 获取渲染进程 dist 路径 |
+| `get-main-dist` | 获取主进程 dist 路径 |
+| `open-win` | 打开新窗口 |
+| `open-main-window` | 打开主窗口 |
+| `open-window-page` | 打开子窗口/模态窗口 |
+| `read-file` | 读取文件 |
+| `set-process` | 设置窗口进度条 |
+| `send-to-parent` | 向父窗口发送消息 |
+| `send-to-child` | 向子窗口发送消息 |
+| `set-ignore-mouse-events` | 设置鼠标穿透 |
+| `window-manager-api` | 窗口管理器 API 调用 |
+
+### 4. 生命周期钩子 `lifecycle`
+
+在 app 启动的各个阶段注入自定义逻辑：
+
+```ts
+lifecycle: {
+  async onReady() {
+    // app.whenReady() 内，窗口创建前
+    await initDatabase()
+  },
+  async afterReady() {
+    // app.whenReady() 内，窗口创建后
+    startBackgroundTasks()
+  },
+  onAllWindowsClosed() {
+    // 覆盖默认行为（非 macOS 默认 quit）
+    // 返回 void 表示使用自定义处理
+  },
+  onActivate() {
+    // macOS dock 点击，默认重新创建主窗口
+  },
+}
+```
+
+**内部启动流程**：
+
+```
+createElectronApp(config)
+  ├─ GPU 配置（Win7 兼容）
+  ├─ Windows app model ID
+  ├─ 单实例锁
+  ├─ IPC 事件注册（内置 + 自定义）
+  └─ useLifeCycle()
+       ├─ protocol.registerSchemesAsPrivileged('local:')
+       ├─ app.on('window-all-closed')
+       ├─ app.on('activate')
+       └─ app.whenReady()
+            ├─ lifecycle.onReady()
+            ├─ protocol.registerFileProtocol('local:', ...)
+            ├─ Session 配置
+            ├─ 创建主窗口
+            ├─ 系统托盘（可选）
+            ├─ HTTP/WS 服务（可选）
+            ├─ 自动更新（可选）
+            └─ lifecycle.afterReady()
+```
+
+### 5. 系统托盘 `tray`
+
+```ts
+tray: {
+  enabled: true,
+  tooltip: 'My App',
+  menuItems: [
+    { label: '显示主窗口', click: () => windowManager.openMainWindow() },
+    { label: '退出', click: () => app.quit() },
+  ],
+  onDoubleClick: () => { /* 自定义双击行为 */ },
+}
+```
+
+### 6. 单实例锁 `instance`
+
+```ts
+instance: {
+  enabled: true,
+  onSecondInstance() {
+    // 第二个实例启动时的行为（默认打开主窗口）
+  },
+}
+```
+
+### 7. 自动更新 `updater`
+
+基于 `electron-updater`，使用 generic provider：
+
+```ts
+updater: {
+  enabled: true,
+  feedUrl: 'https://update.example.com/releases',
+  channel: 'latest',
+  onUpdateAvailable(info) {
+    mainWindow.webContents.send('update-available', info)
+  },
+  onUpdateError(error) {
+    console.error('Update error:', error)
+  },
+  onUpdateDownloaded() {
+    // 默认弹窗询问是否重启；返回 false 阻止默认行为
+  },
+}
+```
+
+---
+
+## 高级用法
+
+### 独立使用模块
+
+除了 `createElectronApp` 一键启动，每个模块也可以独立导入使用：
+
+```ts
+import {
+  WindowManager,        // 窗口管理器类
+  DownloadManager,      // 下载管理器类
+  useIpcEvents,         // IPC 事件注册
+  useLifeCycle,         // 生命周期管理
+  useSession,           // Session 配置
+  useSingleInstance,    // 单实例锁
+  useTray,              // 系统托盘
+  useUpdater,           // 自动更新
+  useWinDrag,           // 透明窗口拖拽
+} from 'electron-multi-app-kit'
+
+// 单独使用 WindowManager
+const wm = new WindowManager({
+  windows: [...],
+  mainWindowType: 'main',
+  paths: { ... },
+})
+wm.openMainWindow()
+```
+
+### 独立使用 IPC 内置模块
+
+```ts
+import {
+  useWindowMove,
+  useWindowControl,
+  useFsApi,
+  useDialogApi,
+  useShellApi,
+  useDownloaderApi,
+  useNotificationApi,
+} from 'electron-multi-app-kit'
+
+// 在自定义 setup 中按需注册
+useWindowMove(windowManager)
+useFsApi()
+```
+
+### 工具函数
+
+```ts
+import { merge, debounce, cloneJSON } from 'electron-multi-app-kit'
+
+// 深度合并对象
+const opts = merge(defaults, userOptions, { deepMerge: true })
+
+// 防抖
+const save = debounce(() => persist(), 1000)
+
+// JSON 深克隆
+const copy = cloneJSON(original)
+```
+
+### WindowManager API
+
+```ts
+const wm = ctx.windowManager  // 从 createElectronApp 返回值获取
+
+wm.create('settings')           // 创建窗口
+wm.openWindow('settings')       // 打开（自动 show/restore/maximize）
+wm.openMainWindow()             // 打开主窗口
+wm.openWindowPage('/hash', { modal: true, parent: mainWin })
+wm.openUrl('/some-hash')
+
+wm.getMain()                    // 获取主窗口
+wm.getWindow('settings')        // 获取指定窗口
+wm.getWindowByWebContents(wc)   // 从 webContents 反查窗口
+wm.getAllWindows()              // 所有窗口
+wm.getWindowConfig(win)         // 窗口的合并配置
+
+wm.closeWindow('settings')      // 关闭窗口
+wm.closeAllWindows()            // 关闭所有
+
+wm.confirmExit(win)             // 弹出退出确认对话框
+```
+
+---
+
+## Preload 桥接模块
+
+`electron-multi-app-kit/preload` 提供一个开箱即用的 IPC 桥接层，通过 `contextBridge` 将 `ipcRenderer` 安全地暴露给渲染进程。
+
+### 使用方法
+
+在你的 preload 入口文件中导入（副作用导入即可）：
+
+```ts
+// electron/preload/index.ts
+import 'electron-multi-app-kit/preload'  // 自动注册 window.ipcRenderer
+
+// 基于 ipcBridge 构建业务 API
+import { ipcBridge } from 'electron-multi-app-kit/preload'
+import { contextBridge } from 'electron'
+
+contextBridge.exposeInMainWorld('MyAPI', {
+  async getVersion() {
+    return ipcBridge.invoke<string>('get-app-version')
+  },
+  onMessage(callback: (data: any) => void) {
+    ipcBridge.on('main-message', (_event, data) => callback(data))
+  },
+})
+```
+
+### 渲染进程中使用
+
+```ts
+// 直接调用
+const version = await window.ipcRenderer.invoke<string>('get-app-version')
+
+// 监听事件
+window.ipcRenderer.on('main-message', (_event, data) => {
+  console.log(data)
+})
+
+// 单向发送
+window.ipcRenderer.send('log', 'hello from renderer')
+
+// 向父窗口发送
+window.ipcRenderer.sendToParent('child-ready')
+
+// 向子窗口广播
+window.ipcRenderer.sendToChild('parent-data', payload)
+```
+
+### window.ipcRenderer API
+
+| 方法 | 类型 | 说明 |
+| ------ | ------ | ------ |
+| `invoke<T>(channel, ...args)` | `Promise<T>` | 请求-响应 |
+| `send(channel, ...args)` | `void` | 单向发送 |
+| `on(channel, listener)` | `void` | 监听事件 |
+| `once(channel, listener)` | `void` | 一次性监听 |
+| `off(channel, listener)` | `void` | 移除监听 |
+| `sendToParent(channel, ...args)` | `void` | 向父窗口发送 |
+| `sendToChild(channel, ...args)` | `void` | 向子窗口广播 |
+
+### 类型声明
+
+如需在渲染进程中为 `window.ipcRenderer` 添加类型：
+
+```ts
+// src/vite-env.d.ts 或全局声明文件
+import type { IpcBridge } from 'electron-multi-app-kit/preload'
+
+declare global {
+  interface Window {
+    ipcRenderer: IpcBridge
+  }
+}
+```
+
+---
+
+## Renderer 模块
+
+`electron-multi-app-kit/renderer` 提供 Vue 渲染进程可直接使用的组合式函数和组件。
+
+### useIpcRenderer
+
+内存安全的 IPC 封装，自动在组件卸载时清理监听器。
+
+```vue
+<script setup>
+import { useIpcRenderer } from 'electron-multi-app-kit/renderer'
+
+const ipc = useIpcRenderer()
+
+// 监听主进程消息（自动清理）
+ipc.on('main-message', (event, data) => {
+  console.log(data)
+})
+
+// 请求-响应
+const version = await ipc.invoke<string>('get-app-version')
+</script>
+```
+
+### NavBar — 无边框窗口导航栏
+
+开箱即用的自定义标题栏组件，专为无边框（`frame: false`）窗口设计。
+
+```vue
+<template>
+  <electron-nav-bar title="我的应用" icon="/icon.png">
+    <button @click="goBack">返回</button>
+  </electron-nav-bar>
+</template>
+
+<script setup>
+import { NavBar } from 'electron-multi-app-kit/renderer'
+</script>
+```
+
+**功能：**
+
+- 自动检测是否为无边框窗口，标准窗口自动隐藏
+- 窗口拖拽（`-webkit-app-region: drag`）
+- 窗口控制按钮：置顶、最小化、最大化/还原、关闭
+- 实时同步窗口状态（全屏、最大化、置顶等）
+- 通过 CSS 变量自定义样式
+
+**Props：**
+
+| Prop | 类型 | 说明 |
+| ------ | ------ | ------ |
+| `title` | `string` | 自定义标题（不传则使用 BrowserWindow 的 title） |
+| `icon` | `string` | 自定义图标 URL（不传则不显示图标） |
+
+**Slot：** 默认插槽，内容显示在标题和窗口控制按钮之间。
+
+**CSS 变量：**
+
+| 变量 | 默认值 | 说明 |
+| ------ | ------ | ------ |
+| `--app-nav-bar-size` | `40px` | 导航栏高度 |
+| `--app-color-f` | `#fff` | 背景色 |
+| `--app-color-0` | `#333` | 文字颜色 |
+| `--app-color-e` | `#e8e8e8` | 按钮 hover 背景 |
+| `--app-color-c` | `#d0d0d0` | 按钮 active 背景 |
+| `--app-color-red` | `#e81123` | 关闭按钮 hover 背景 |
+| `--app-color-red-light` | `#f1707a` | 关闭按钮 active 背景 |
+
+---
+
+## 完整示例
+
+以 Vite + Vue 项目为例，替换 `electron/main/index.ts`：
+
+```ts
+import { createElectronApp } from 'electron-multi-app-kit'
+import path from 'node:path'
+import { app, shell } from 'electron'
+
+const __dirname = path.dirname(new URL(import.meta.url).pathname)
+const isDev = process.env.NODE_ENV === 'development'
+
+const appCtx = createElectronApp({
+  // ---- 路径 ----
+  paths: {
+    rendererDist: path.join(__dirname, '../../dist'),
+    mainDist: path.join(__dirname, '../../dist-electron'),
+    publicDir: isDev
+      ? path.join(__dirname, '../../public')
+      : path.join(__dirname, '../../dist'),
+    preloadScript: path.join(__dirname, '../preload/index.js'),
+    iconPath: path.join(__dirname, '../../public/icons/icon.ico'),
+    userAgent: 'Mozilla/5.0 ...',
+  },
+
+  isDev,
+
+  // ---- 默认窗口选项 ----
+  defaultWindowOptions: {
+    icon: path.join(__dirname, '../../public/icons/icon.ico'),
+    webPreferences: {
+      nodeIntegration: false,
+      preload: path.join(__dirname, '../preload/index.js'),
+    },
+  },
+
+  // ---- 窗口定义 ----
+  windows: [
+    {
+      type: 'main',
+      options: {
+        width: 1200,
+        height: 800,
+        minWidth: 1200,
+        minHeight: 800,
+        frame: false,
+        webPreferences: { webviewTag: true, contextIsolation: true },
+      },
+      onCreate(win) {
+        if (process.env.VITE_DEV_SERVER_URL) {
+          win.loadURL(process.env.VITE_DEV_SERVER_URL)
+        } else {
+          win.loadFile(path.join(__dirname, '../../dist/index.html'))
+        }
+      },
+    },
+  ],
+
+  mainWindowType: 'main',
+
+  // ---- IPC 自定义 ----
+  ipc: {
+    setup(ipcMain) {
+      ipcMain.handle('dev-test', () => shell.beep())
+      ipcMain.handle('get-app-version', () => app.getVersion())
+    },
+  },
+
+  // ---- 启用模块 ----
+  tray: { enabled: true },
+  instance: { enabled: true },
+
+  // ---- 生命周期 ----
+  lifecycle: {
+    async onReady() {
+      console.log('App is ready, creating window...')
+    },
+  },
+})
+
+// 返回的 context 可后续使用
+export const { windowManager } = appCtx
+```
+
+---
+
+## License
+
+MIT

package/dist/core/context.d.ts

@@ -0,0 +1,15 @@
+import { ElectronCliConfig } from '../types';
+import { WindowBaseType, WindowManager } from '../modules/window/manager';
+export interface ElectronCliContext<W extends WindowBaseType = WindowBaseType> {
+    /** 用户原始配置 */
+    config: ElectronCliConfig<W>;
+    /** 窗口管理器实例 */
+    windowManager: WindowManager<W>;
+    /** 托盘是否已创建 */
+    trayCreated: boolean;
+    isDev: boolean;
+}
+/**
+ * 创建上下文实例
+ */
+export declare function createContext<W extends WindowBaseType>(config: ElectronCliConfig<W>): ElectronCliContext<W>;

package/dist/core/eventBus.d.ts

@@ -0,0 +1,2 @@
+import { default as EventEmitter } from 'events';
+export declare const AppEvent: EventEmitter<any>;

package/dist/core/lifecycle.d.ts

@@ -0,0 +1,9 @@
+import { ElectronCliContext } from './context';
+import { WindowBaseType } from '../modules/window/manager';
+/**
+ * 应用生命周期管理 — 从 electron/main/events/lifeCycle.ts 移植
+ *
+ * 负责 protocol 注册、app 事件监听、app.whenReady() 内部编排。
+ * 用户可通过 config.lifecycle 钩子注入自定义逻辑。
+ */
+export declare function useLifeCycle<W extends WindowBaseType = WindowBaseType>(ctx: ElectronCliContext<W>): void;

package/dist/create-app.d.ts

@@ -0,0 +1,30 @@
+import { ElectronCliConfig } from './types';
+import { ElectronCliContext } from './core/context';
+import { WindowBaseType } from './modules/window/manager';
+/**
+ * createElectronApp — electron-multi-app-kit 的主入口函数
+ *
+ * 对应 electron/main/app/index.ts 的 appSetup() 函数，
+ * 将所有硬编码逻辑改为通过 ElectronCliConfig 配置驱动。
+ *
+ * @example
+ * ```ts
+ * import { createElectronApp } from 'electron-multi-app-kit'
+ *
+ * createElectronApp({
+ *   paths: { ... },
+ *   windows: [ ... ],
+ *   mainWindowType: 'main',
+ *   isDev: process.env.NODE_ENV === 'development',
+ *   ipc: {
+ *     extraHandlers: [
+ *       { channel: 'dev-test', type: 'handle', handler: (e, ...args) => { ... } }
+ *     ]
+ *   },
+ *   tray: { enabled: true },
+ *   instance: { enabled: true },
+ * })
+ * ```
+ */
+export declare function createElectronApp<W extends WindowBaseType = WindowBaseType>(config: ElectronCliConfig<W>): ElectronCliContext<W>;
+export type { ElectronCliConfig } from './types';