nexfep 0.1.7 → 0.2.0

package/README-CN.md

@@ -33,29 +33,117 @@ pnpm add nexfep
 ## 快速开始
 
 ```typescript
-import { WindowPool } from 'nexfep';
+import { Application } from 'nexfep';
 
-const pool = new WindowPool();
+const app = new Application();
 
-const window = await pool.createWindow(true, false);
+const window = await app.windows.createWindow(true, false);
 
 await window.loadHTML('<h1 nexfep-area-drag>Hello Nexfep!</h1>');
-
-pool.mainloop();
 ```
 
 ## 使用指南
 
+### Application
+
+`Application` 是框架的主入口，负责管理应用生命周期，提供窗口和系统托盘的访问。
+
+```typescript
+import { Application } from 'nexfep';
+
+const app = new Application();
+// 或指定自定义 WebView2 用户数据目录（仅 Windows）
+const app = new Application('C:\\custom\\webview2-data');
+```
+
+**属性**
+
+- `windows` — `WindowPool` 实例，用于管理浏览器窗口
+- `utils` — 工具方法（如桌面通知）
+
+**方法**
+
+- `createTray(options)` — 创建系统托盘图标和右键菜单
+- `exit()` — 退出应用
+
+### 托盘图标
+
+通过 `app.createTray()` 创建和管理系统托盘图标及右键菜单。
+
+```typescript
+import { readFileSync } from 'fs';
+
+const tray = app.createTray({
+  id: 'my-tray',
+  tooltip: '我的应用',
+  icon: {
+    data: readFileSync('./icon.png'),
+    width: 32,
+    height: 32,
+  },
+  menuItems: [
+    { id: 'show', label: '显示窗口' },
+    { id: 'quit', label: '退出' },
+  ],
+});
+```
+
+`icon` 字段接受 `TrayIconImage` 对象：
+
+```typescript
+interface TrayIconImage {
+  data: Buffer;      // 图片二进制数据
+  width?: number;    // 可选宽度
+  height?: number;   // 可选高度
+}
+```
+
+**方法**
+
+| 方法                                         | 描述               |
+|---------------------------------------------|--------------------|
+| `addMenuItem(item)`                         | 添加菜单项          |
+| `removeMenuItem(id)`                        | 按 ID 删除菜单项    |
+| `setMenuItems(items)`                       | 替换所有菜单项      |
+| `setIcon(icon, width?, height?)`            | 更改托盘图标（原始像素数据 `Uint8Array` / `number[]`） |
+| `setTooltip(tooltip)`                       | 更改悬停提示文本    |
+| `on(event, callback)`                       | 监听托盘事件（如 `'click'`） |
+| `show()`                                    | 显示托盘图标        |
+| `hide()`                                    | 隐藏托盘图标        |
+| `destroy()`                                 | 销毁托盘图标        |
+
+```typescript
+tray.on('click', () => {
+  console.log('托盘被点击');
+});
+tray.addMenuItem({ id: 'about', label: '关于' });
+tray.setTooltip('Nexfep 应用');
+```
+
+### 桌面通知
+
+通过 `app.utils.notify()` 发送桌面通知。
+
+```typescript
+const notification = app.utils.notify('标题', '通知内容');
+```
+
+**参数**
+
+- `title` — 通知标题
+- `body`（可选）— 通知正文
+
 ### 窗口池
 
 `WindowPool` 是框架的核心管理类，负责窗口的创建和回收。
 
 ```typescript
-const pool = new WindowPool();
+const pool = app.windows;
 ```
 
 **构造函数参数**
 
+- `app` — `Application` 实例
 - `WindowsWebview2UserDataFolder`（可选）— WebView2 用户数据目录，默认为 `%LOCALAPPDATA%\NexfepDevelopment.webview2-data`
 
 ### 窗口创建
@@ -348,8 +436,6 @@ if (window.isNexfepLoadDone) {
 | `unhandle(event, callback)`                     | `event`: string, `callback`: (data: string) => void | 无                | 取消监听指定事件回调中的指定函数 |
 | `global`                              | /                                                                          | Map\<string, any> | 全局变量Map，类型为 `Map<string, any>`                         |
 | `closeWindow(window)`                 | `window`: Window                                            | Promise\<void>   | 关闭指定窗口并回收至池中               |
-| `closePool()`                         | 无                                                           | Promise\<void>   | 关闭窗口池，退出应用                 |
-| `mainloop()`                          | 无                                                           | void             | 启动应用主循环，阻塞直到应用退出           |
 | `onCustomMessage`                     | `(window: Window, data: string) => void`                    | 无                | 自定义消息回调函数，当收到页面发来的自定义消息时触发 |
 
 ### Window
@@ -368,6 +454,7 @@ if (window.isNexfepLoadDone) {
 | `setTitle(title)`           | `title`: string — 窗口标题            | void           | 设置窗口标题        |
 | `setDecorated(isDecorated)` | `isDecorated`: boolean — 是否使用系统装饰 | void           | 设置窗口是否带边框和标题栏 |
 | `resizable(resizable)`      | `resizable`: boolean — 是否可调整大小    | void           | 设置窗口是否可调整大小   |
+| `setSize(width, height)`    | `width`: number, `height`: number  | void           | 设置窗口尺寸（像素）   |
 | `openDevTools()`            | 无                                 | void           | 打开开发者工具       |
 | `closeDevTools()`           | 无                                 | void           | 关闭开发者工具       |
 | `id`                        | 无                                 | number         | 窗口唯一标识，自增编号   |

package/README.md

@@ -33,29 +33,117 @@ pnpm add nexfep
 ## Quick Start
 
 ```typescript
-import { WindowPool } from 'nexfep';
+import { Application } from 'nexfep';
 
-const pool = new WindowPool();
+const app = new Application();
 
-const window = await pool.createWindow(true, false);
+const window = await app.windows.createWindow(true, false);
 
 await window.loadHTML('<h1 nexfep-area-drag>Hello Nexfep!</h1>');
-
-pool.mainloop();
 ```
 
 ## Usage Guide
 
+### Application
+
+`Application` is the main entry point of the framework, responsible for managing the application lifecycle and providing access to windows and system tray.
+
+```typescript
+import { Application } from 'nexfep';
+
+const app = new Application();
+// or with custom WebView2 user data directory (Windows only)
+const app = new Application('C:\\custom\\webview2-data');
+```
+
+**Properties**
+
+- `windows` — The `WindowPool` instance for managing browser windows
+- `utils` — Utility methods (e.g., desktop notifications)
+
+**Methods**
+
+- `createTray(options)` — Create a system tray icon with context menu
+- `exit()` — Exit the application
+
+### Tray
+
+Create and manage system tray icons with context menus via `app.createTray()`.
+
+```typescript
+import { readFileSync } from 'fs';
+
+const tray = app.createTray({
+  id: 'my-tray',
+  tooltip: 'My App',
+  icon: {
+    data: readFileSync('./icon.png'),
+    width: 32,
+    height: 32,
+  },
+  menuItems: [
+    { id: 'show', label: 'Show Window' },
+    { id: 'quit', label: 'Quit' },
+  ],
+});
+```
+
+The `icon` field accepts a `TrayIconImage` object:
+
+```typescript
+interface TrayIconImage {
+  data: Buffer;      // Image binary data
+  width?: number;    // Optional width
+  height?: number;   // Optional height
+}
+```
+
+**Methods**
+
+| Method                                      | Description                         |
+|---------------------------------------------|-------------------------------------|
+| `addMenuItem(item)`                         | Add a menu item                     |
+| `removeMenuItem(id)`                        | Remove a menu item by ID            |
+| `setMenuItems(items)`                       | Replace all menu items              |
+| `setIcon(icon, width?, height?)`            | Change the tray icon (raw pixel data as `Uint8Array` / `number[]`) |
+| `setTooltip(tooltip)`                       | Change the tooltip text             |
+| `on(event, callback)`                       | Listen for tray events (e.g. `'click'`) |
+| `show()`                                    | Show the tray icon                  |
+| `hide()`                                    | Hide the tray icon                  |
+| `destroy()`                                 | Destroy the tray icon               |
+
+```typescript
+tray.on('click', () => {
+  console.log('Tray clicked');
+});
+tray.addMenuItem({ id: 'about', label: 'About' });
+tray.setTooltip('Nexfep App');
+```
+
+### Notifications
+
+Send desktop notifications via `app.utils.notify()`.
+
+```typescript
+const notification = app.utils.notify('Title', 'Notification body');
+```
+
+**Parameters**
+
+- `title` — Notification title
+- `body` (optional) — Notification body text
+
 ### Window Pool
 
 `WindowPool` is the core management class of the framework, responsible for window creation and recycling.
 
 ```typescript
-const pool = new WindowPool();
+const pool = app.windows;
 ```
 
 **Constructor Parameters**
 
+- `app` — The `Application` instance
 - `WindowsWebview2UserDataFolder` (optional) — WebView2 user data directory, defaults to `%LOCALAPPDATA%\NexfepDevelopment.webview2-data`
 
 ### Window Creation
@@ -348,8 +436,6 @@ if (window.isNexfepLoadDone) {
 | `unhandle(event, callback)`           | `event`: string, `callback`: (data: string) => void                        | None             | Removes the specified callback from the event listener                     |
 | `global`                              | /                                                                          | Map\<string, any> | A global variable map of type: `Map<string, any>`                         |
 | `closeWindow(window)`                 | `window`: Window                                                           | Promise\<void>   | Closes the specified window and returns it to the pool                   |
-| `closePool()`                         | None                                                                       | Promise\<void>   | Closes the window pool and exits the application                         |
-| `mainloop()`                          | None                                                                       | void             | Starts the application main loop, blocking until the application exits   |
 | `onCustomMessage`                     | `(window: Window, data: string) => void`                                   | None             | Custom message callback, triggered when receiving custom messages from pages |
 
 ### Window
@@ -368,6 +454,7 @@ if (window.isNexfepLoadDone) {
 | `setTitle(title)`                     | `title`: string — Window title              | void             | Sets the window title                   |
 | `setDecorated(isDecorated)`           | `isDecorated`: boolean — Use system decorations | void          | Sets whether the window has borders and title bar |
 | `resizable(resizable)`                | `resizable`: boolean — Resizable            | void             | Sets whether the window is resizable     |
+| `setSize(width, height)`              | `width`: number, `height`: number           | void             | Sets the window size in pixels           |
 | `openDevTools()`                      | None                                        | void             | Opens developer tools                   |
 | `closeDevTools()`                     | None                                        | void             | Closes developer tools                  |
 | `id`                                  | None                                        | number           | Unique window identifier, auto-incrementing |

package/index.d.ts

@@ -1 +1 @@
-export * from './src/WindowManager.js';
+export * from './src/Application.js';

package/index.js

@@ -1 +1 @@
-export * from './src/WindowManager.js';
+export * from './src/Application.js';

package/package.json

@@ -14,7 +14,7 @@
     "webview",
     "typescript"
   ],
-  "version": "0.1.7",
+  "version": "0.2.0",
   "type": "module",
   "main": "./index.js",
   "scripts": {
@@ -33,10 +33,14 @@
     "LICENSE",
     "package.json",
     "src/WindowManager.js",
-    "src/WindowManager.d.ts"
+    "src/WindowManager.d.ts",
+    "src/Application.js",
+    "src/Application.d.ts",
+    "src/Tray.js",
+    "src/Tray.d.ts"
   ],
   "dependencies": {
-    "@webviewjs/webview": "0.1.4"
+    "@webviewjs/webview": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/Application.d.ts

@@ -0,0 +1,25 @@
+import { Application as WebviewApplication, TrayIconImage, Notification } from '@webviewjs/webview';
+import { WindowPool } from './WindowManager.js';
+import { Tray } from './Tray.js';
+declare class __Utils {
+    app: WebviewApplication;
+    constructor(app: WebviewApplication);
+    notify(title: string, body?: string): Notification;
+}
+declare class Application {
+    app: WebviewApplication;
+    windows: WindowPool;
+    utils: __Utils;
+    constructor(WindowsWebview2UserDataFolder?: string);
+    createTray(options: {
+        id: string;
+        tooltip: string;
+        icon: TrayIconImage | undefined;
+        menuItems: Array<{
+            id: string;
+            label: string;
+        }>;
+    }): Tray;
+    exit(): void;
+}
+export { Application };

package/src/Application.js

@@ -0,0 +1,33 @@
+import { Application as WebviewApplication, Notification } from '@webviewjs/webview';
+import { WindowPool } from './WindowManager.js';
+import { Tray } from './Tray.js';
+import path from 'path';
+import os from 'os';
+class __Utils {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    notify(title, body) {
+        const notification = new Notification(title, { body });
+        return notification;
+    }
+}
+class Application {
+    app;
+    windows;
+    utils;
+    constructor(WindowsWebview2UserDataFolder = path.join(process.env.LOCALAPPDATA || os.homedir(), 'NexfepDevelopment.webview2-data')) {
+        this.app = new WebviewApplication();
+        this.utils = new __Utils(this.app);
+        this.windows = new WindowPool(this.app, WindowsWebview2UserDataFolder);
+        this.app.whenReady();
+    }
+    createTray(options) {
+        return new Tray(this.app, options);
+    }
+    exit() {
+        this.app.exit();
+    }
+}
+export { Application };

package/src/Tray.d.ts

@@ -0,0 +1,36 @@
+import { Application, TrayIcon, TrayIconImage } from '@webviewjs/webview';
+declare class Tray {
+    app: Application;
+    tray: TrayIcon;
+    menuItems: Array<{
+        id: string;
+        label: string;
+    }>;
+    destroyed: boolean;
+    constructor(app: Application, options: {
+        id: string;
+        tooltip: string;
+        icon: TrayIconImage | undefined;
+        menuItems: Array<{
+            id: string;
+            label: string;
+        }>;
+    });
+    __ErrorWhenDestroyed(): void;
+    addMenuItem(item: {
+        id: string;
+        label: string;
+    }): void;
+    removeMenuItem(id: string): void;
+    setMenuItems(items: Array<{
+        id: string;
+        label: string;
+    }>): void;
+    setIcon(icon: Uint8Array<ArrayBuffer | SharedArrayBuffer> | number[], width?: number | null | undefined, height?: number | null | undefined): void;
+    on(event: string, callback: (event: any) => void): void;
+    setTooltip(tooltip: string): void;
+    hide(): void;
+    show(): void;
+    destroy(): void;
+}
+export { Tray };

package/src/Tray.js

@@ -0,0 +1,65 @@
+class Tray {
+    app;
+    tray;
+    menuItems;
+    destroyed;
+    constructor(app, options) {
+        this.menuItems = options.menuItems;
+        this.destroyed = false;
+        this.app = app;
+        this.tray = app.createTrayIcon({
+            id: options.id,
+            tooltip: options.tooltip,
+            icon: options.icon,
+            menu: {
+                items: this.menuItems
+            }
+        });
+    }
+    __ErrorWhenDestroyed() {
+        if (this.destroyed) {
+            throw new Error('Tray has been destroyed');
+        }
+    }
+    addMenuItem(item) {
+        this.__ErrorWhenDestroyed();
+        this.menuItems.push(item);
+        this.tray.setMenu({ items: this.menuItems });
+    }
+    removeMenuItem(id) {
+        this.__ErrorWhenDestroyed();
+        this.menuItems = this.menuItems.filter(item => item.id !== id);
+        this.tray.setMenu({ items: this.menuItems });
+    }
+    setMenuItems(items) {
+        this.__ErrorWhenDestroyed();
+        this.menuItems = items;
+        this.tray.setMenu({ items: this.menuItems });
+    }
+    setIcon(icon, width, height) {
+        this.__ErrorWhenDestroyed();
+        this.tray.setIcon(icon, width, height);
+    }
+    on(event, callback) {
+        this.__ErrorWhenDestroyed();
+        this.tray.on(event, callback);
+    }
+    setTooltip(tooltip) {
+        this.__ErrorWhenDestroyed();
+        this.tray.setTooltip(tooltip);
+    }
+    hide() {
+        this.__ErrorWhenDestroyed();
+        this.tray.setVisible(false);
+    }
+    show() {
+        this.__ErrorWhenDestroyed();
+        this.tray.setVisible(true);
+    }
+    destroy() {
+        this.__ErrorWhenDestroyed();
+        this.tray.dispose();
+        this.destroyed = true;
+    }
+}
+export { Tray };

package/src/WindowManager.d.ts

@@ -1,4 +1,4 @@
-import { BrowserWindow, Webview } from "@webviewjs/webview";
+import { Application, BrowserWindow, Webview } from "@webviewjs/webview";
 declare class Window {
     window: BrowserWindow;
     webview: Webview;
@@ -17,6 +17,7 @@ declare class Window {
     unMinimize(): void;
     openDevTools(): void;
     closeDevTools(): void;
+    setSize(width: number, height: number): void;
     hide(): void;
     show(): void;
     close(): void;
@@ -25,22 +26,20 @@ declare class Window {
 }
 declare class WindowPool {
     onCustomMessage: (window: Window, data: string) => void;
-    private app;
+    app: Application;
     private windows;
     private handlers;
     private injectCount;
     private windowCount;
     private freeWindowCount;
     global: Map<string, any>;
-    constructor(WindowsWebview2UserDataFolder?: string);
+    constructor(app: Application, WindowsWebview2UserDataFolder?: string);
     __injectCode(window: Window, code: string): Promise<void>;
     __injectControlFunctions(windowObj: Window): Promise<void>;
     __createNewWindowObj(): Promise<Window>;
     createWindow(isShow?: boolean, isDecorated?: boolean): Promise<Window>;
     closeWindow(window: Window): Promise<void>;
-    closePool(): Promise<void>;
     handle(event: string, callback: (data: any) => any): Promise<void>;
     unhandle(event: string, callback: (data: any) => any): Promise<void>;
-    mainloop(): void;
 }
 export { WindowPool, Window };

package/src/WindowManager.js

@@ -1,4 +1,3 @@
-import { Application } from "@webviewjs/webview";
 import os from 'os';
 import path from 'path';
 import fs from 'fs';
@@ -47,6 +46,9 @@ class Window {
     closeDevTools() {
         this.webview.closeDevtools();
     }
+    setSize(width, height) {
+        this.window.setSize(width, height);
+    }
     hide() {
         this.window.hide();
         this.isShow = false;
@@ -76,7 +78,7 @@ class WindowPool {
     windowCount;
     freeWindowCount;
     global;
-    constructor(WindowsWebview2UserDataFolder = path.join(process.env.LOCALAPPDATA || os.homedir(), 'NexfepDevelopment.webview2-data')) {
+    constructor(app, WindowsWebview2UserDataFolder = path.join(process.env.LOCALAPPDATA || os.homedir(), 'NexfepDevelopment.webview2-data')) {
         if (os.platform() === 'win32') {
             // 设置 WebView2 用户数据目录（仅 Windows 需要此配置）
             const userDataDir = WindowsWebview2UserDataFolder;
@@ -89,7 +91,7 @@ class WindowPool {
             console.log('Get Custom Message:', data, "from window", window.id);
         };
         this.handlers = new Map();
-        this.app = new Application();
+        this.app = app;
         this.injectCount = 0;
         this.windows = [];
         this.windowCount = 0;
@@ -371,17 +373,11 @@ class WindowPool {
             throw new Error("Window is not open");
         }
     }
-    async closePool() {
-        this.app.exit();
-    }
     async handle(event, callback) {
         this.handlers.set(event, [...this.handlers.get(event) || [], callback]);
     }
     async unhandle(event, callback) {
         this.handlers.set(event, (this.handlers.get(event) || []).filter(c => c !== callback));
     }
-    mainloop() {
-        this.app.run();
-    }
 }
 export { WindowPool, Window };