nexfep 0.0.4 → 0.1.1

package/README-CN.md

@@ -1,240 +1,285 @@
-# Nexfep
-
-语言: [English](https://github.com/zhuxiaojt/Nexfep/blob/main/README.md) | 简体中文(当前)
-
-基于 @webviewjs/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
+# Nexfep
+
+语言: [English](https://github.com/nexfteam/Nexfep/blob/main/README.md) | 简体中文(当前)
+
+基于 @webviewjs/webview 的桌面应用框架
+
+## 项目状态
+
+**🚧 早期阶段**
+
+本项目目前处于早期开发阶段，仍缺失大量桌面应用开发所需的核心能力。框架正在持续迭代中。
+
+## 简介
+
+Nexfep 是一个基于 [@webviewjs/webview](https://github.com/webviewjs/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` 转换为对象）
+
+#### 触发自定义事件
+
+在页面中通过 `window.invoke` 触发事件：
+
+```javascript
+window.invoke('hello', 'world');
+```
+
+**参数说明**
+
+- `event` — 事件名称
+- `data` — 任意类型的可序列化数据，会被序列化为 JSON 字符串后发送
+
+#### 监听事件
+
+在主进程中通过 `pool.handle` 监听事件：
+
+```typescript
+pool.handle('hello', (data) => {
+  console.log('收到事件 hello:', data);
+});
+```
+
+**参数说明**
+
+- `event` — 事件名称，需要和触发事件时的事件名称一致
+- `callback` — 事件处理函数，需要接收事件数据作为 `data` 参数。返回任意类型的可序列化数据，会被序列化为 JSON 字符串后发送至前端作为 `window.invoke` 的返回值（也可以不返回任何值）
+
+#### 取消监听事件
+
+在主进程中通过 `pool.unhandle` 取消监听事件：
+
+```typescript
+pool.unhandle('hello', (data) => {
+  console.log('收到事件 hello:', data);
+});
+```
+
+**参数说明**
+
+- `event` — 事件名称，需要和触发事件时的事件名称一致
+- `callback` — 事件处理函数，需要和监听事件时的回调函数一致
+
+#### 窗口控制函数
+
+页面中可直接调用以下注入函数进行窗口控制：
+
+```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> | 创建并获取一个窗口                  |
+| `handle(event, callback)`             | `event`: string, `callback`: (data: string) => void | 无                | 监听指定事件，当收到事件时触发回调函数 |
+| `unhandle(event, callback)`                     | `event`: string, `callback`: (data: string) => void | 无                | 取消监听指定事件回调中的指定函数 |
+| `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/README.md

@@ -1,240 +1,285 @@
-# Nexfep
-
-Language: English(now) | [简体中文](https://github.com/zhuxiaojt/Nexfep/blob/main/README-CN.md)
-
-A desktop application framework based on @webviewjs/webview
-
-## Project Status
-
-**🚧 Early Stage**
-
-This project is currently in early development, with many core capabilities for desktop application development still missing. The framework is being continuously iterated.
-
-## Introduction
-
-Nexfep is a desktop application framework built on [@webviewjs/webview](https://github.com/webview/webview), written in TypeScript. It aims to provide developers with a concise and efficient toolchain for building cross-platform desktop applications.
-
-The framework uses a window pool management mechanism, supporting multi-window application scenarios such as code editors, chat tools, dashboards, etc.
-
-## Features
-
-- **Window Pool Management** — Built-in window pool mechanism for automatic reuse and recycling of window resources, avoiding the overhead of frequent creation and destruction
-- **IPC Communication** — Supports bidirectional message communication between the main process and WebView, via injected functions
-- **Window Control** — Provides complete window operation APIs including maximize, minimize, close, title setting, and developer tools
-- **Drag Regions** — Built-in HTML attribute support for defining window drag regions (`nexfep-area-drag`, etc.)
-- **TypeScript Support** — Complete type definitions for excellent development experience
-
-## Installation
-
-```bash
-pnpm add nexfep
-```
-
-## Quick Start
-
-```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();
-```
-
-## Usage Guide
-
-### Window Pool
-
-`WindowPool` is the core management class of the framework, responsible for window creation and recycling.
-
-```typescript
-const pool = new WindowPool();
-```
-
-**Constructor Parameters**
-
-- `WindowsWebview2UserDataFolder` (optional) — WebView2 user data directory, defaults to `%LOCALAPPDATA%\NexfepDevelopment.webview2-data`
-
-### Window Creation
-
-```typescript
-const win = await pool.createWindow(true, false);
-```
-
-**Parameters**
-
-- `isShow` (boolean, default `true`) — Whether to immediately show the window
-- `isDecorated` (boolean, default `true`) — Whether to use system window decorations. When set to `false`, the window has no border and requires a custom title bar
-
-### Window Operations
-
-```typescript
-window.show();
-window.hide();
-window.maximize();
-window.minimize();
-window.close();
-window.setTitle('New Title');
-window.openDevTools();
-```
-
-### IPC Communication
-
-The framework automatically injects a series of control functions after WebView page loading is complete. It is recommended to use these injected functions for IPC communication, rather than the native IPC wrapped by `@webviewjs/webview`.
-
-#### Send Custom Messages
-
-Send messages via `window.postMessage` in the page:
-
-```javascript
-window.postMessage({ hello: 'world' });
-```
-
-**Parameters**
-
-- `data` — Any serializable data, will be serialized to JSON string before sending
-
-#### Listen for Messages
-
-Receive messages via `onCustomMessage` callback in the main process:
-
-```typescript
-pool.onCustomMessage = (window, data) => {
-  console.log(`Message from window ${window.id}:`, data);
-};
-```
-
-**Callback Parameters**
-
-- `window` — The window object that sent the message
-- `data` — Message content, an object type (automatically converted from JSON string via `JSON.parse`)
-
-#### Window Control Functions
-
-The following injected functions can be directly called in the page for window control:
-
-```javascript
-window.close();              // Close window
-window.minimize();           // Minimize window
-window.unminimize();         // Restore minimized window
-window.maximize();           // Maximize window
-window.unmaximize();         // Restore maximized window
-window.setTitle('Title');    // Set window title
-window.openDevTools();       // Open developer tools
-window.closeDevTools();      // Close developer tools
-```
-
-### Drag Regions
-
-Define window drag regions via HTML attributes without writing additional JavaScript code. These attributes automatically apply `-webkit-app-region` and `app-region` CSS properties.
-
-#### `nexfep-area-drag`
-
-Makes the entire region and all its child elements draggable. Suitable for scenarios like custom title bars where the entire region needs to be draggable.
-
-```html
-<div nexfep-area-drag>
-  <h1>Title Bar</h1>
-  <span>Subtitle</span>
-</div>
-```
-
-#### `nexfep-element-drag`
-
-Makes only the specified element itself draggable; child elements are not affected. Suitable for scenarios requiring precise control over the drag region.
-
-```html
-<div>
-  <div nexfep-element-drag>Drag Handle</div>
-  <p>This part is not draggable</p>
-</div>
-```
-
-#### `nexfep-no-drag`
-
-Makes the specified region and all its child elements non-draggable. Highest priority, can override parent element's drag attributes. Suitable for interactive elements like buttons and input fields.
-
-```html
-<div nexfep-area-drag>
-  <h1>Title Bar</h1>
-  <button nexfep-no-drag>Click Button</button>
-</div>
-```
-
-#### `nexfep-auto-drag`
-
-Automatically determines drag regions: the entire region is draggable, but common interactive elements (`button`, `input`, `select`, `textarea`, `a`) are automatically set to non-draggable. Suitable for complex regions containing multiple interactive elements.
-
-```html
-<div nexfep-auto-drag>
-  <h1>Title Bar</h1>
-  <button>Automatically non-draggable</button>
-  <input placeholder="Automatically non-draggable" />
-  <a href="#">Automatically non-draggable</a>
-</div>
-```
-
-### Load Complete Event
-
-The `nexfep-load-done` event is triggered after the WebView window finishes loading:
-
-```javascript
-window.addEventListener('nexfep-load-done', () => {
-  console.log('Nexfep window loaded');
-});
-```
-
-It can also be checked via the `window.isNexfepLoadDone` property:
-
-```javascript
-if (window.isNexfepLoadDone) {
-  // Window is ready
-}
-```
-
-## API
-
-### WindowPool
-
-| Method/Property                       | Parameters                                                                 | Return Value     | Description                                                              |
-| ------------------------------------- | -------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------ |
-| `constructor(userDataFolder?)`        | `userDataFolder`: string (optional)                                        | WindowPool       | Creates a window pool, optionally specifying the WebView2 user data directory |
-| `createWindow(isShow?, isDecorated?)` | `isShow`: boolean (default true), `isDecorated`: boolean (default true)    | Promise\<Window> | Creates and returns a window                                             |
-| `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
-
-| Method/Property                       | Parameters                                  | Return Value     | Description                              |
-| ------------------------------------- | ------------------------------------------- | ---------------- | ---------------------------------------- |
-| `loadURL(url)`                        | `url`: string — URL to load                 | Promise\<void>   | Loads the specified URL                 |
-| `loadHTML(html)`                      | `html`: string — HTML string                | Promise\<void>   | Loads the specified HTML content        |
-| `show()`                              | None                                        | void             | Shows the window                         |
-| `hide()`                              | None                                        | void             | Hides the window                         |
-| `maximize()`                          | None                                        | void             | Maximizes the window                     |
-| `unMaximize()`                        | None                                        | void             | Restores the window (cancels maximize)   |
-| `minimize()`                          | None                                        | void             | Minimizes the window                     |
-| `unMinimize()`                        | None                                        | void             | Restores the window (cancels minimize)   |
-| `close()`                             | None                                        | void             | Closes the window and returns to pool    |
-| `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     |
-| `openDevTools()`                      | None                                        | void             | Opens developer tools                   |
-| `closeDevTools()`                     | None                                        | void             | Closes developer tools                  |
-| `id`                                  | None                                        | number           | Unique window identifier, auto-incrementing |
-
-## Development
-
-```bash
-pnpm install
-pnpm run compile
-```
-
-## License
-
-MIT License
+# Nexfep
+
+Language: English(now) | [简体中文](https://github.com/nexfteam/Nexfep/blob/main/README-CN.md)
+
+A desktop application framework based on @webviewjs/webview
+
+## Project Status
+
+**🚧 Early Stage**
+
+This project is currently in early development, with many core capabilities for desktop application development still missing. The framework is being continuously iterated.
+
+## Introduction
+
+Nexfep is a desktop application framework built on [@webviewjs/webview](https://github.com/webviewjs/webview), written in TypeScript. It aims to provide developers with a concise and efficient toolchain for building cross-platform desktop applications.
+
+The framework uses a window pool management mechanism, supporting multi-window application scenarios such as code editors, chat tools, dashboards, etc.
+
+## Features
+
+- **Window Pool Management** — Built-in window pool mechanism for automatic reuse and recycling of window resources, avoiding the overhead of frequent creation and destruction
+- **IPC Communication** — Supports bidirectional message communication between the main process and WebView, via injected functions
+- **Window Control** — Provides complete window operation APIs including maximize, minimize, close, title setting, and developer tools
+- **Drag Regions** — Built-in HTML attribute support for defining window drag regions (`nexfep-area-drag`, etc.)
+- **TypeScript Support** — Complete type definitions for excellent development experience
+
+## Installation
+
+```bash
+pnpm add nexfep
+```
+
+## Quick Start
+
+```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();
+```
+
+## Usage Guide
+
+### Window Pool
+
+`WindowPool` is the core management class of the framework, responsible for window creation and recycling.
+
+```typescript
+const pool = new WindowPool();
+```
+
+**Constructor Parameters**
+
+- `WindowsWebview2UserDataFolder` (optional) — WebView2 user data directory, defaults to `%LOCALAPPDATA%\NexfepDevelopment.webview2-data`
+
+### Window Creation
+
+```typescript
+const win = await pool.createWindow(true, false);
+```
+
+**Parameters**
+
+- `isShow` (boolean, default `true`) — Whether to immediately show the window
+- `isDecorated` (boolean, default `true`) — Whether to use system window decorations. When set to `false`, the window has no border and requires a custom title bar
+
+### Window Operations
+
+```typescript
+window.show();
+window.hide();
+window.maximize();
+window.minimize();
+window.close();
+window.setTitle('New Title');
+window.openDevTools();
+```
+
+### IPC Communication
+
+The framework automatically injects a series of control functions after WebView page loading is complete. It is recommended to use these injected functions for IPC communication, rather than the native IPC wrapped by `@webviewjs/webview`.
+
+#### Send Custom Messages
+
+Send messages via `window.postMessage` in the page:
+
+```javascript
+window.postMessage({ hello: 'world' });
+```
+
+**Parameters**
+
+- `data` — Any serializable data, will be serialized to JSON string before sending
+
+#### Listen for Messages
+
+Receive messages via `onCustomMessage` callback in the main process:
+
+```typescript
+pool.onCustomMessage = (window, data) => {
+  console.log(`Message from window ${window.id}:`, data);
+};
+```
+
+**Callback Parameters**
+
+- `window` — The window object that sent the message
+- `data` — Message content, an object type (automatically converted from JSON string via `JSON.parse`)
+
+#### Invoke Custom Events
+
+Invoke events via `window.invoke` in the page:
+
+```javascript
+window.invoke('hello', 'world');
+```
+
+**Parameters**
+
+- `event` — Event name
+- `data` — Any serializable data, will be serialized to JSON string before sending
+
+#### Listen for Events
+
+Listen for events via `pool.handle` in the main process:
+
+```typescript
+pool.handle('hello', (data) => {
+  console.log('Received event hello:', data);
+});
+```
+
+**Parameters**
+
+- `event` — Event name, must match the event name when invoking
+- `callback` — Event handler function, receives event data as `data` parameter. Can return any serializable data, which will be serialized to JSON string and sent back to the frontend as the return value of `window.invoke` (can also return nothing)
+
+#### Remove Event Listener
+
+Remove event listener via `pool.unhandle` in the main process:
+
+```typescript
+pool.unhandle('hello', (data) => {
+  console.log('Received event hello:', data);
+});
+```
+
+**Parameters**
+
+- `event` — Event name, must match the event name when listening
+- `callback` — Event handler function, must match the callback function when listening
+
+#### Window Control Functions
+
+The following injected functions can be directly called in the page for window control:
+
+```javascript
+window.close();              // Close window
+window.minimize();           // Minimize window
+window.unminimize();         // Restore minimized window
+window.maximize();           // Maximize window
+window.unmaximize();         // Restore maximized window
+window.setTitle('Title');    // Set window title
+window.openDevTools();       // Open developer tools
+window.closeDevTools();      // Close developer tools
+```
+
+### Drag Regions
+
+Define window drag regions via HTML attributes without writing additional JavaScript code. These attributes automatically apply `-webkit-app-region` and `app-region` CSS properties.
+
+#### `nexfep-area-drag`
+
+Makes the entire region and all its child elements draggable. Suitable for scenarios like custom title bars where the entire region needs to be draggable.
+
+```html
+<div nexfep-area-drag>
+  <h1>Title Bar</h1>
+  <span>Subtitle</span>
+</div>
+```
+
+#### `nexfep-element-drag`
+
+Makes only the specified element itself draggable; child elements are not affected. Suitable for scenarios requiring precise control over the drag region.
+
+```html
+<div>
+  <div nexfep-element-drag>Drag Handle</div>
+  <p>This part is not draggable</p>
+</div>
+```
+
+#### `nexfep-no-drag`
+
+Makes the specified region and all its child elements non-draggable. Highest priority, can override parent element's drag attributes. Suitable for interactive elements like buttons and input fields.
+
+```html
+<div nexfep-area-drag>
+  <h1>Title Bar</h1>
+  <button nexfep-no-drag>Click Button</button>
+</div>
+```
+
+#### `nexfep-auto-drag`
+
+Automatically determines drag regions: the entire region is draggable, but common interactive elements (`button`, `input`, `select`, `textarea`, `a`) are automatically set to non-draggable. Suitable for complex regions containing multiple interactive elements.
+
+```html
+<div nexfep-auto-drag>
+  <h1>Title Bar</h1>
+  <button>Automatically non-draggable</button>
+  <input placeholder="Automatically non-draggable" />
+  <a href="#">Automatically non-draggable</a>
+</div>
+```
+
+### Load Complete Event
+
+The `nexfep-load-done` event is triggered after the WebView window finishes loading:
+
+```javascript
+window.addEventListener('nexfep-load-done', () => {
+  console.log('Nexfep window loaded');
+});
+```
+
+It can also be checked via the `window.isNexfepLoadDone` property:
+
+```javascript
+if (window.isNexfepLoadDone) {
+  // Window is ready
+}
+```
+
+## API
+
+### WindowPool
+
+| Method/Property                       | Parameters                                                                 | Return Value     | Description                                                              |
+| ------------------------------------- | -------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------ |
+| `constructor(userDataFolder?)`        | `userDataFolder`: string (optional)                                        | WindowPool       | Creates a window pool, optionally specifying the WebView2 user data directory |
+| `createWindow(isShow?, isDecorated?)` | `isShow`: boolean (default true), `isDecorated`: boolean (default true)    | Promise\<Window> | Creates and returns a window                                             |
+| `handle(event, callback)`            | `event`: string, `callback`: (data: string) => void                       | None             | Listens for the specified event, triggers callback when event is received   |
+| `unhandle(event, callback)`           | `event`: string, `callback`: (data: string) => void                       | None             | Removes the specified callback from the event listener                     |
+| `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
+
+| Method/Property                       | Parameters                                  | Return Value     | Description                              |
+| ------------------------------------- | ------------------------------------------- | ---------------- | ---------------------------------------- |
+| `loadURL(url)`                        | `url`: string — URL to load                 | Promise\<void>   | Loads the specified URL                 |
+| `loadHTML(html)`                      | `html`: string — HTML string                | Promise\<void>   | Loads the specified HTML content        |
+| `show()`                              | None                                        | void             | Shows the window                         |
+| `hide()`                              | None                                        | void             | Hides the window                         |
+| `maximize()`                          | None                                        | void             | Maximizes the window                     |
+| `unMaximize()`                        | None                                        | void             | Restores the window (cancels maximize)   |
+| `minimize()`                          | None                                        | void             | Minimizes the window                     |
+| `unMinimize()`                        | None                                        | void             | Restores the window (cancels minimize)   |
+| `close()`                             | None                                        | void             | Closes the window and returns to pool    |
+| `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     |
+| `openDevTools()`                      | None                                        | void             | Opens developer tools                   |
+| `closeDevTools()`                     | None                                        | void             | Closes developer tools                  |
+| `id`                                  | None                                        | number           | Unique window identifier, auto-incrementing |
+
+## Development
+
+```bash
+pnpm install
+pnpm run compile
+```
+
+## License
+
+MIT License

package/index.d.ts

@@ -1,41 +1,45 @@
-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 };
+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 handlers;
+    private injectCount;
+    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>;
+    handle(event: string, callback: (data: any) => any): Promise<void>;
+    unhandle(event: string, callback: (data: any) => any): Promise<void>;
+    mainloop(): void;
+}
+export { WindowPool, Window };

package/index.js

@@ -73,6 +73,8 @@ class WindowPool {
     onCustomMessage;
     app;
     windows;
+    handlers;
+    injectCount;
     windowCount;
     freeWindowCount;
     constructor(WindowsWebview2UserDataFolder = path.join(process.env.LOCALAPPDATA || os.homedir(), 'NexfepDevelopment.webview2-data')) {
@@ -88,7 +90,9 @@ class WindowPool {
         this.onCustomMessage = (window, data) => {
             console.log('Get Custom Message:', data, "from window", window.id);
         };
+        this.handlers = new Map();
         this.app = new Application();
+        this.injectCount = 0;
         this.windows = [];
         this.windowCount = 0;
         this.freeWindowCount = 0;
@@ -182,6 +186,23 @@ class WindowPool {
             const MessageBody = { type: 'CustomMessage', data: data }
             window.ipc.postMessage(JSON.stringify(MessageBody));
         };
+
+        window.eventCount = 0;
+
+        window.invoke = async (event, data) => {
+            const MessageBody = { type: 'NexfepInvoke', eventId: [${this.injectCount}, ++window.eventCount], event: event, data: data }
+            window.ipc.postMessage(JSON.stringify(MessageBody));
+            return new Promise((resolve, reject) => {
+                window.addEventListener("nexfep-invoke-result-"+${this.injectCount}+"-"+window.eventCount, (event) => {
+                    window.removeEventListener("nexfep-invoke-result-"+${this.injectCount}+"-"+window.eventCount, event);
+                    if(event.detail){
+                        resolve(event.detail);
+                    }else{
+                        resolve();
+                    }
+                });
+            });
+        }
         
         // 注入 CSS 样式
         const style = document.createElement('style');
@@ -247,6 +268,22 @@ class WindowPool {
             else if (dataObj.type == 'CustomMessage') {
                 this.onCustomMessage(windowObj, dataObj.data);
             }
+            else if (dataObj.type == 'NexfepInvoke') {
+                const handlers = this.handlers.get(dataObj.event) || [];
+                handlers.forEach(async (handler) => {
+                    const result = await handler(dataObj.data);
+                    if (result) {
+                        webview.evaluateScript(`
+                            window.dispatchEvent(new Event('nexfep-invoke-result-${dataObj.eventId[0]}-${dataObj.eventId[1]}', { detail: ${JSON.stringify(result)} }));
+                        `);
+                    }
+                    else {
+                        webview.evaluateScript(`
+                            window.dispatchEvent(new Event('nexfep-invoke-result-${dataObj.eventId[0]}-${dataObj.eventId[1]}', { detail: undefined }));
+                        `);
+                    }
+                });
+            }
         });
         return windowObj;
     }
@@ -282,9 +319,14 @@ class WindowPool {
     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 };
-//# sourceMappingURL=index.js.map

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "nexfep",
-  "description": "A desktop application framework based on @webviewjs/webview",
-  "repository": "https://github.com/zhuxiaojt/Nexfep",
-  "homepage": "https://github.com/zhuxiaojt/Nexfep#readme",
-  "bugs": {
-    "url": "https://github.com/zhuxiaojt/Nexfep/issues"
-  },
-  "keywords": [
-    "desktop",
-    "application",
-    "framework",
-    "@webviewjs/webview",
-    "webview",
-    "typescript"
-  ],
-  "version": "0.0.4",
-  "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"
-  }
+{
+  "name": "nexfep",
+  "description": "A desktop application framework based on @webviewjs/webview",
+  "repository": "https://github.com/nexfteam/Nexfep",
+  "homepage": "https://github.com/nexfteam/Nexfep#readme",
+  "bugs": {
+    "url": "https://github.com/nexfteam/Nexfep/issues"
+  },
+  "keywords": [
+    "desktop",
+    "application",
+    "framework",
+    "@webviewjs/webview",
+    "webview",
+    "typescript"
+  ],
+  "version": "0.1.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"
+  }
 }