nexfep 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhuxiaojt
+
+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,238 @@
+# Nexfep
+
+基于 WebView 的桌面应用框架
+
+## 项目状态
+
+**🚧 早期阶段**
+
+本项目目前处于早期开发阶段，仍缺失大量桌面应用开发所需的核心能力。框架正在持续迭代中。
+
+## 简介
+
+Nexfep 是一个基于 [@webviewjs/webview](https://github.com/webview/webview) 构建的桌面应用框架，使用 TypeScript 编写。它旨在为开发者提供一套简洁、高效的工具链，用于构建跨平台桌面应用。
+
+框架采用窗口池管理机制，支持多窗口应用场景，如代码编辑器、聊天工具、仪表盘等。
+
+## 特性
+
+- **窗口池管理** — 内置窗口池机制，自动复用和回收窗口资源，避免频繁创建销毁的开销
+- **IPC 通信** — 支持主进程与 WebView 之间的双向消息通信，通过注入的函数进行调用
+- **窗口控制** — 提供最大化、最小化、关闭、标题设置、开发者工具等完整窗口操作 API
+- **拖拽区域** — 内置 HTML 属性支持，方便定义窗口拖拽区域（`nexfep-area-drag` 等）
+- **TypeScript 支持** — 完整的类型定义，开发体验优秀
+
+## 安装
+
+```bash
+pnpm add nexfep
+```
+
+## 快速开始
+
+```typescript
+import { WindowPool } from 'nexfep';
+
+const pool = new WindowPool();
+
+const window = await pool.createWindow(true, false);
+
+await window.loadHTML('<h1 nexfep-area-drag>Hello Nexfep!</h1>');
+
+pool.mainloop();
+```
+
+## 使用指南
+
+### 窗口池
+
+`WindowPool` 是框架的核心管理类，负责窗口的创建和回收。
+
+```typescript
+const pool = new WindowPool();
+```
+
+**构造函数参数**
+
+- `WindowsWebview2UserDataFolder`（可选）— WebView2 用户数据目录，默认为 `%LOCALAPPDATA%\NexfepDevelopment.webview2-data`
+
+### 窗口创建
+
+```typescript
+const win = await pool.createWindow(true, false);
+```
+
+**参数说明**
+
+- `isShow`（布尔值，默认 `true`）— 是否立即显示窗口
+- `isDecorated`（布尔值，默认 `true`）— 是否使用系统窗口装饰。设为 `false` 时，窗口无边框，需要自定义标题栏
+
+### 窗口操作
+
+```typescript
+window.show();
+window.hide();
+window.maximize();
+window.minimize();
+window.close();
+window.setTitle('新标题');
+window.openDevTools();
+```
+
+### IPC 通信
+
+框架在 WebView 页面加载完成后会自动注入一系列控制函数，建议使用这些注入的函数进行 IPC 通信，而非直接使用 `@webviewjs/webview` 原生包装的 IPC。
+
+#### 发送自定义消息
+
+在页面中通过 `window.postMessage` 发送消息：
+
+```javascript
+window.postMessage({ hello: 'world' });
+```
+
+**参数说明**
+
+- `data` — 任意类型的可序列化数据，会被序列化为 JSON 字符串后发送
+
+#### 监听消息
+
+在主进程中通过 `onCustomMessage` 回调接收消息：
+
+```typescript
+pool.onCustomMessage = (window, data) => {
+  console.log(`来自窗口 ${window.id} 的消息:`, data);
+};
+```
+
+**回调参数**
+
+- `window` — 发送消息的窗口对象
+- `data` — 消息内容，为对象类型（JSON 序列化后会自动通过 `JSON.parse` 转换为对象）
+
+#### 窗口控制函数
+
+页面中可直接调用以下注入函数进行窗口控制：
+
+```javascript
+window.close();              // 关闭窗口
+window.minimize();           // 最小化窗口
+window.unminimize();         // 还原最小化的窗口
+window.maximize();           // 最大化窗口
+window.unmaximize();         // 还原最大化的窗口
+window.setTitle('标题');     // 设置窗口标题
+window.openDevTools();       // 打开开发者工具
+window.closeDevTools();      // 关闭开发者工具
+```
+
+### 拖拽区域
+
+通过 HTML 属性即可定义窗口拖拽区域，无需编写额外 JavaScript 代码。这些属性会自动应用 `-webkit-app-region` 和 `app-region` CSS 属性。
+
+#### `nexfep-area-drag`
+
+使整个区域及其所有子元素均可拖拽。适用于自定义标题栏等需要整块区域可拖拽的场景。
+
+```html
+<div nexfep-area-drag>
+  <h1>标题栏</h1>
+  <span>副标题</span>
+</div>
+```
+
+#### `nexfep-element-drag`
+
+仅使指定元素本身可拖拽，子元素不受影响。适用于需要精确控制拖拽区域的场景。
+
+```html
+<div>
+  <div nexfep-element-drag>拖拽手柄</div>
+  <p>这部分不可拖拽</p>
+</div>
+```
+
+#### `nexfep-no-drag`
+
+使指定区域及其所有子元素不可拖拽，优先级最高，可覆盖父元素的拖拽属性。适用于按钮、输入框等交互元素。
+
+```html
+<div nexfep-area-drag>
+  <h1>标题栏</h1>
+  <button nexfep-no-drag>点击按钮</button>
+</div>
+```
+
+#### `nexfep-auto-drag`
+
+自动判断拖拽区域：整个区域可拖拽，但常见交互元素（`button`、`input`、`select`、`textarea`、`a`）自动设为不可拖拽。适用于包含多种交互元素的复杂区域。
+
+```html
+<div nexfep-auto-drag>
+  <h1>标题栏</h1>
+  <button>自动不可拖拽</button>
+  <input placeholder="自动不可拖拽" />
+  <a href="#">自动不可拖拽</a>
+</div>
+```
+
+### 加载完成事件
+
+WebView 窗口加载完成后会触发 `nexfep-load-done` 事件：
+
+```javascript
+window.addEventListener('nexfep-load-done', () => {
+  console.log('Nexfep 窗口加载完成');
+});
+```
+
+也可通过 `window.isNexfepLoadDone` 属性判断：
+
+```javascript
+if (window.isNexfepLoadDone) {
+  // 窗口已就绪
+}
+```
+
+## API
+
+### WindowPool
+
+| 方法/属性                                 | 参数                                                          | 返回值              | 说明                         |
+| ------------------------------------- | ----------------------------------------------------------- | ---------------- | -------------------------- |
+| `constructor(userDataFolder?)`        | `userDataFolder`: string（可选）                                | WindowPool       | 创建窗口池，可选指定 WebView2 用户数据目录 |
+| `createWindow(isShow?, isDecorated?)` | `isShow`: boolean（默认 true）, `isDecorated`: boolean（默认 true） | Promise\<Window> | 创建并获取一个窗口                  |
+| `closeWindow(window)`                 | `window`: Window                                            | Promise\<void>   | 关闭指定窗口并回收至池中               |
+| `closePool()`                         | 无                                                           | Promise\<void>   | 关闭窗口池，退出应用                 |
+| `mainloop()`                          | 无                                                           | void             | 启动应用主循环，阻塞直到应用退出           |
+| `onCustomMessage`                     | `(window: Window, data: string) => void`                    | 无                | 自定义消息回调函数，当收到页面发来的自定义消息时触发 |
+
+### Window
+
+| 方法/属性                       | 参数                                | 返回值            | 说明            |
+| --------------------------- | --------------------------------- | -------------- | ------------- |
+| `loadURL(url)`              | `url`: string — 要加载的网页地址          | Promise\<void> | 加载指定 URL      |
+| `loadHTML(html)`            | `html`: string — HTML 字符串         | Promise\<void> | 加载指定 HTML 内容  |
+| `show()`                    | 无                                 | void           | 显示窗口          |
+| `hide()`                    | 无                                 | void           | 隐藏窗口          |
+| `maximize()`                | 无                                 | void           | 最大化窗口         |
+| `unMaximize()`              | 无                                 | void           | 还原窗口（取消最大化）   |
+| `minimize()`                | 无                                 | void           | 最小化窗口         |
+| `unMinimize()`              | 无                                 | void           | 还原窗口（取消最小化）   |
+| `close()`                   | 无                                 | void           | 关闭窗口并回收至池中    |
+| `setTitle(title)`           | `title`: string — 窗口标题            | void           | 设置窗口标题        |
+| `setDecorated(isDecorated)` | `isDecorated`: boolean — 是否使用系统装饰 | void           | 设置窗口是否带边框和标题栏 |
+| `resizable(resizable)`      | `resizable`: boolean — 是否可调整大小    | void           | 设置窗口是否可调整大小   |
+| `openDevTools()`            | 无                                 | void           | 打开开发者工具       |
+| `closeDevTools()`           | 无                                 | void           | 关闭开发者工具       |
+| `id`                        | 无                                 | number         | 窗口唯一标识，自增编号   |
+
+## 开发
+
+```bash
+pnpm install
+pnpm run compile
+```
+
+## 许可证
+
+MIT License

package/index.d.ts

@@ -0,0 +1,41 @@
+import { BrowserWindow, Webview } from "@webviewjs/webview";
+declare class Window {
+    window: BrowserWindow;
+    webview: Webview;
+    isOpen: boolean;
+    isShow: boolean;
+    isDecorated: boolean;
+    id: number;
+    private myPool;
+    constructor(window: BrowserWindow, webview: Webview, id: number, myPool: WindowPool);
+    setDecorated(isDecorated: boolean): void;
+    setTitle(title: string): void;
+    resizable(resizable: boolean): void;
+    maximize(): void;
+    minimize(): void;
+    unMaximize(): void;
+    unMinimize(): void;
+    openDevTools(): void;
+    closeDevTools(): void;
+    hide(): void;
+    show(): void;
+    close(): void;
+    loadURL(url: string): Promise<void>;
+    loadHTML(html: string): Promise<void>;
+}
+declare class WindowPool {
+    onCustomMessage: (window: Window, data: string) => void;
+    private app;
+    private windows;
+    private windowCount;
+    private freeWindowCount;
+    constructor(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>;
+    mainloop(): void;
+}
+export { WindowPool, Window };

package/index.js

@@ -0,0 +1,290 @@
+import { Application } from "@webviewjs/webview";
+import os from 'os';
+import path from 'path';
+import fs from 'fs';
+class Window {
+    window;
+    webview;
+    isOpen;
+    isShow;
+    isDecorated;
+    id;
+    myPool;
+    constructor(window, webview, id, myPool) {
+        this.myPool = myPool;
+        this.window = window;
+        this.webview = webview;
+        this.isOpen = false;
+        this.isShow = false;
+        this.isDecorated = false;
+        this.id = id;
+    }
+    setDecorated(isDecorated) {
+        this.window.setDecorations(isDecorated);
+        this.isDecorated = isDecorated;
+    }
+    setTitle(title) {
+        this.window.setTitle(title);
+    }
+    resizable(resizable) {
+        this.window.setResizable(resizable);
+    }
+    maximize() {
+        this.window.setMaximized(true);
+    }
+    minimize() {
+        this.window.setMinimized(true);
+    }
+    unMaximize() {
+        this.window.setMaximized(false);
+    }
+    unMinimize() {
+        this.window.setMinimized(false);
+    }
+    openDevTools() {
+        this.webview.openDevtools();
+    }
+    closeDevTools() {
+        this.webview.closeDevtools();
+    }
+    hide() {
+        this.window.hide();
+        this.isShow = false;
+    }
+    show() {
+        this.window.show();
+        this.isShow = true;
+    }
+    close() {
+        this.myPool.closeWindow(this);
+    }
+    async loadURL(url) {
+        await this.webview.loadUrl(url);
+        await this.myPool.__injectControlFunctions(this);
+    }
+    async loadHTML(html) {
+        console.log("Before loadHTML");
+        await this.webview.loadHtml(html);
+        await this.myPool.__injectControlFunctions(this);
+        console.log("After loadHTML");
+    }
+}
+class WindowPool {
+    onCustomMessage;
+    app;
+    windows;
+    windowCount;
+    freeWindowCount;
+    constructor(WindowsWebview2UserDataFolder = path.join(process.env.LOCALAPPDATA || os.homedir(), 'NexfepDevelopment.webview2-data')) {
+        if (os.platform() === 'win32') {
+            // 设置 WebView2 用户数据目录（仅 Windows 需要此配置）
+            const userDataDir = WindowsWebview2UserDataFolder;
+            if (!fs.existsSync(userDataDir)) {
+                fs.mkdirSync(userDataDir, { recursive: true });
+            }
+            process.env.WEBVIEW2_USER_DATA_FOLDER = userDataDir;
+            console.log('WebView2 user data folder:', userDataDir);
+        }
+        this.onCustomMessage = (window, data) => {
+            console.log('Get Custom Message:', data, "from window", window.id);
+        };
+        this.app = new Application();
+        this.windows = [];
+        this.windowCount = 0;
+        this.freeWindowCount = 0;
+    }
+    async __injectCode(window, code) {
+        await window.webview.evaluateScript(code);
+    }
+    async __injectControlFunctions(windowObj) {
+        console.log("Create INJECT_CODE");
+        const INJECT_CSS = `
+        [nexfep-area-drag],
+        [nexfep-area-drag] * {
+            -webkit-app-region: drag;
+            app-region: drag;
+        }
+        
+        [nexfep-element-drag] {
+            -webkit-app-region: drag;
+            app-region: drag;
+        }
+        
+        [nexfep-no-drag],
+        [nexfep-no-drag] * {
+            -webkit-app-region: no-drag !important;
+            app-region: no-drag !important;
+        }
+        
+        [nexfep-auto-drag],
+        [nexfep-auto-drag] * {
+            -webkit-app-region: drag;
+            app-region: drag;
+        }
+        
+        [nexfep-auto-drag] button,
+        [nexfep-auto-drag] input,
+        [nexfep-auto-drag] select,
+        [nexfep-auto-drag] textarea,
+        [nexfep-auto-drag] a {
+            -webkit-app-region: no-drag;
+            app-region: no-drag;
+        }
+        `;
+        const INJECT_CODE = `
+        // 事件监听
+        window.addEventListener("beforeunload", () => {
+            const MessageBody = { type: 'NexfepBeforeUnload' }
+            window.ipc.postMessage(JSON.stringify(MessageBody));
+        });
+        
+        // 窗口控制函数
+        window.close = () => {
+            const MessageBody = { type: 'NexfepCloseWindow' }
+            window.ipc.postMessage(JSON.stringify(MessageBody));
+        };
+        
+        window.minimize = () => {
+            const MessageBody = { type: 'NexfepMinimizeWindow' }
+            window.ipc.postMessage(JSON.stringify(MessageBody));
+        };
+        
+        window.unminimize = () => {
+            const MessageBody = { type: 'NexfepUnMinimizeWindow' }
+            window.ipc.postMessage(JSON.stringify(MessageBody));
+        };
+        
+        window.maximize = () => {
+            const MessageBody = { type: 'NexfepMaximizeWindow' }
+            window.ipc.postMessage(JSON.stringify(MessageBody));
+        };
+        
+        window.unmaximize = () => {
+            const MessageBody = { type: 'NexfepUnMaximizeWindow' }
+            window.ipc.postMessage(JSON.stringify(MessageBody));
+        };
+        window.setTitle = (title) => {
+            const MessageBody = { type: 'NexfepSetTitle', title: title }
+            window.ipc.postMessage(JSON.stringify(MessageBody));
+        };
+        
+        window.openDevTools = () => {
+            const MessageBody = { type: 'NexfepOpenDevTools' }
+            window.ipc.postMessage(JSON.stringify(MessageBody));
+        };
+        
+        window.closeDevTools = () => {
+            const MessageBody = { type: 'NexfepCloseDevTools' }
+            window.ipc.postMessage(JSON.stringify(MessageBody));
+        };
+
+        window.postMessage = (data) => {
+            const MessageBody = { type: 'CustomMessage', data: data }
+            window.ipc.postMessage(JSON.stringify(MessageBody));
+        };
+        
+        // 注入 CSS 样式
+        const style = document.createElement('style');
+        style.textContent = \`${INJECT_CSS}\`;
+        document.head.appendChild(style);
+        
+        // 标记加载完成
+        window.isNexfepLoadDone = true;
+
+        // 触发加载完成事件
+        window.dispatchEvent(new Event('nexfep-load-done'));
+        `;
+        console.log("Before inject code INJECT_CODE");
+        await this.__injectCode(windowObj, INJECT_CODE);
+        console.log("After inject control functions");
+    }
+    async __createNewWindowObj() {
+        const window = this.app.createBrowserWindow({ title: "Nexfep" });
+        window.hide();
+        this.freeWindowCount++;
+        const webview = window.createWebview();
+        const windowObj = new Window(window, webview, ++this.windowCount, this);
+        this.windows.push(windowObj);
+        webview.onIpcMessage((data) => {
+            const dataText = data.body.toString();
+            const dataObj = JSON.parse(dataText);
+            if (dataObj.type == 'NexfepBeforeUnload') {
+                webview.evaluateScript(`if(window?.isNexfepLoadDone){
+                    const MessageBody = { type: 'NexfepBeforeUnload' }
+                    window.ipc.postMessage(JSON.stringify(MessageBody));
+                }else{
+                    const MessageBody = { type: 'NexfepLoadFalse' }
+                    window.ipc.postMessage(JSON.stringify(MessageBody));
+                }`);
+            }
+            else if (dataObj.type == 'NexfepLoadFalse') {
+                this.__injectControlFunctions(windowObj);
+            }
+            else if (dataObj.type == 'NexfepCloseWindow') {
+                this.closeWindow(windowObj);
+            }
+            else if (dataObj.type == 'NexfepMinimizeWindow') {
+                window.setMinimized(true);
+            }
+            else if (dataObj.type == 'NexfepUnMinimizeWindow') {
+                window.setMinimized(false);
+            }
+            else if (dataObj.type == 'NexfepMaximizeWindow') {
+                window.setMaximized(true);
+            }
+            else if (dataObj.type == 'NexfepUnMaximizeWindow') {
+                window.setMaximized(false);
+            }
+            else if (dataObj.type == 'NexfepSetTitle') {
+                window.setTitle(dataObj.title);
+            }
+            else if (dataObj.type == 'NexfepOpenDevTools') {
+                webview.openDevtools();
+            }
+            else if (dataObj.type == 'NexfepCloseDevTools') {
+                webview.closeDevtools();
+            }
+            else if (dataObj.type == 'CustomMessage') {
+                this.onCustomMessage(windowObj, dataObj.data);
+            }
+        });
+        return windowObj;
+    }
+    async createWindow(isShow = true, isDecorated = true) {
+        const window = this.windows.find(w => w.isOpen === false) || await this.__createNewWindowObj();
+        this.freeWindowCount--;
+        if (window) {
+            window.isOpen = true;
+            window.isShow = isShow;
+            window.setDecorated(isDecorated);
+            if (isShow) {
+                window.show();
+            }
+        }
+        if (this.freeWindowCount == 0) {
+            await this.__createNewWindowObj();
+        }
+        return window;
+    }
+    async closeWindow(window) {
+        if (window.isOpen) {
+            window.isOpen = false;
+            window.isShow = false;
+            window.setDecorated(true);
+            window.hide();
+            await window.loadHTML("<!DOCTYPE html><html><head></head><body></body></html>");
+            this.freeWindowCount++;
+        }
+        else {
+            throw new Error("Window is not open");
+        }
+    }
+    async closePool() {
+        this.app.exit();
+    }
+    mainloop() {
+        this.app.run();
+    }
+}
+export { WindowPool, Window };
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "nexfep",
+  "version": "0.0.1",
+  "type": "module",
+  "packageManager": "pnpm@9.15.9",
+  "main": "./index.js",
+  "scripts": {
+    "compile": "tsc"
+  },
+  "author": "nexfteam",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "dependencies": {
+    "@webviewjs/webview": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}