本帖最后由 花老板 于 2026-5-16 08:25 编辑
JadeView v2.0
基于 Rust 的下一代高性能 WebView 窗口库
全新 API 架构 | Python SDK2 | 系统托盘 | 全局热键 | 多显示器支持
极致轻量 | 零依赖 | 原生渲染 | 16ms 启动
DLL < 1 MB · 无额外运行时 · 系统内置 WebView2 · IPC < 1 ms
调用系统原生 WebView2(Edge 内核),无需打包浏览器引擎
支持 HTML/CSS/JS 构建桌面界面,DLL 体积不足 1 MB
资源与链接
- 官方文档站:https://jade.run
- v2.0 API 预览:https://jade.run/api-2-preview
- Python SDK2 文档:https://jade.run/python-sdk2
- 仓库:https://gitee.com/ilinxuan/JadeView_library/releases/tag/v2.0.0
- https://github.com/JadeViewDocs/library/releases/tag/v2.0.0
- SDK 下载:GitHub Releases
- 交流反馈:QQ群: 1103426302
- 火山PC:bbs.voldp.com/thread-29385-1-1.html
- 易语言例子:【易语言】jadeview前端UI,全功能演示例子_精易论坛
- 易语言例子:【新提醒】【jadeview】自定义标题栏覆盖层,UI演示_精易论坛
- jadeview模块,SDK+例子下载
▌ 快速概览
启动性能对比(不计算 HTML 加载时间)
测试环境:易语言下核心启动至窗口显示。来自 jade.run/spec/behavior 官方数据。
| 框架 | 启动耗时 | 核心架构 | | JadeView | 16 ms | Rust + wry | | Electron 23 | 1400 ms | Chromium + Node.js | | NW.js 0.70 | 850 ms | Chromium + Node.js | | CEF / CefSharp | 数百毫秒 | Chromium |
JadeView 完整启动流程(含加载 HTML 内容):约 300 ms
IPC 通信性能对比
| 框架 | 往返延迟 | 并发处理能力 | 架构特点 | | JadeView | < 1 ms | > 800 请求/秒 | 自定义协议 + Rust 实现 | | Electron 23 | 10-50 ms | ~100 请求/秒 | Chromium + Node.js IPC | | NW.js 0.70 | 8-40 ms | ~150 请求/秒 | Chromium + Node.js IPC | | CEF / CefSharp | 5-30 ms | ~200 请求/秒 | Chromium IPC |
IPC 性能优势:CPU 消耗降低 30%-50%,内存占用降低 20%-40%(相比传统 IPC 方案)
架构特点
- 技术栈:Rust + wry(WebView)+ tao(窗口管理)+ tokio(异步运行时)+ serde(序列化)
- 异步架构:初始化非阻塞;create_webview_window 立即返回 window_id,实际创建在事件循环线程中异步完成
- 线程安全:所有 API 函数均为线程安全(互斥锁保护全局状态、无共享可变状态)
- IPC 协议:基于 Fetch API 的自定义协议,发布-订阅模式事件系统
- 分层架构:核心层 → API 层 → SDK 层 → 应用层
- 内存安全:Rust 所有权模型 + 自动内存释放,无直接 malloc/free 调用
▌ v2.0 升级指南
新增接口(14 个符号)
| 接口 | 说明 | | create_borderless_webview_window | 创建无系统标题栏的 WebView 窗口 | | get_window_hwnd | 仅无边框窗口可通过此函数获取 HWND 供 Win32 API 使用 | | set_protocol_service_path | 替代旧版 create_local_server,将本地文件夹挂载为内置协议根 | | yaml_set / yaml_get | 在数据目录读写 YAML 配置 | | getPath / getLocale / get_displays_info | 获取常用系统路径、系统界面语言(BCP47)、多显示器信息 | | clear_data_directory | 清空本应用数据目录(需携带确认令牌) | | jadeview_version | 读取 JadeView 自身版本字符串 | | register_url_scheme 等 | 自定义协议注册 / 文件关联 | | register_global_hotkey 等 | 全局热键,收到 global-hotkey 事件 | | 系统托盘相关 | 托盘图标、菜单、事件(见 SDK 文档 "系统托盘" 分栏) |
API 变更对照
| v1.x 旧接口 | v2.0 新接口 | 说明 | | create_local_server | set_protocol_service_path | 本地文件夹挂载为内置协议根 | | remove_titlebar / borderless / no_center | frame_style + x/y=-1 | 统一窗口边框样式 | | (新增) | register_global_hotkey | 全局热键注册 | | (新增) | register_url_scheme | 自定义协议注册 | | (新增) | yaml_set / yaml_get | 内置 YAML 配置读写 | | (新增) | get_displays_info | 多显示器信息查询 | | (新增) | get_window_hwnd | 获取 Win32 HWND 句柄 | | (新增) | 系统托盘系列 API | 图标 / 菜单 / 通知 / 事件 |
破坏性变更
- 字段移除:旧版 remove_titlebar、borderless、no_center 已移除,改用 frame_style 和 x/y=-1 居中;create_local_server 废弃,替换为 set_protocol_service_path
- 初始化签名升级:JadeView_init 从旧版变为 6 参数(新增 app_name / app_signature / single_instance 必填)
- WebView 与窗口一一对应:统一暴露 window_id;navigate_to_url 等 API 均通过 window_id 标识目标窗口
- 单实例模式:single_instance=1 时,第二次启动将命令行转发至已有实例,触发 second-instance 事件
- 统一数据目录:默认为 %LOCALAPPDATA%\{app_signature}_data,作为 WebView2 会话与配置存储基准
▌ 核心 API 参考
WebViewWindowOptions — 窗口配置
字段顺序必须与 JadeView.h 一致,少填 / 多填 / 类型错位会导致静默读错内存。
| 字段 | 说明 | | title | 窗口标题栏文字 | | width / height | 初始尺寸(像素) | | resizable | 是否允许调整尺寸 | | frame_style | 边框样式:normal / no-titlebar / borderless / title-overlay(Windows 专属) | | transparent | 是否透明背景 | | background_color | 窗口背景色(如 #1A1A2E) | | theme | 主题:Light / Dark / System | | maximized / fullscreen | 启动时最大化 / 全屏 | | x / y | 窗口坐标,均设 -1 时系统自动居中 | | always_on_top | 置顶显示 | | focus | 打开后是否获取键盘焦点 | | hide_window | 创建但不立即显示(预加载) | | use_page_icon | 使用网页 favicon 作为窗口图标 | | content_protection [NEW] | 防录屏 / 截屏保护(v2.0 新增) | | auto_save_state [NEW] | 自动记忆窗口位置和大小,450ms 防抖落盘(v2.0 新增) | | min_width / min_height / max_width / max_height | 最小 / 最大允许尺寸 |
WebViewSettings — 网页行为控制
传 NULL 表示全用默认。
| 字段 | 说明 | | autoplay | 媒体自动播放 | | background_throttling | 后台时降低定时器 / 动画频率(节能) | | disable_right_click | 禁用网页右键菜单 | | ua | 自定义 User-Agent | | preload_js | 页面加载前注入的 JavaScript 代码 | | allow_fullscreen | 允许网页使用全屏 API | | postmessage_whitelist | postMessage 转发白名单,值为 UTF-8 字符串;event.origin 等于该字符串或其以此为后缀时放行;NULL 时不放行任何来源;set_protocol_service_path 加载的内置静态页不受此限制 |
核心 C 函数
JadeView_init — 初始化运行时
启动库内部的 GUI 线程和事件循环,登记应用名、数据目录、单实例设置。调用成功后,还需等 app-ready 事件。
[C++] 纯文本查看 复制代码 int32_t JadeView_init(
int32_t enable_devmod, // 开发能力开关(DevTools 等),正式发布传 0
const char* log_path, // 日志文件路径;NULL = 不写文件
const char* data_directory, // 数据根路径;NULL = 系统默认位置
const char* app_name, // 应用显示名,必填,用于协议 / 通知等
const char* app_signature, // 应用唯一标识,必填,至少 6 字符
int32_t single_instance // 非 0:整机只允许一个进程;再开转发命令行
);
返回值:1 = 已启动 GUI 但未就绪,须等 app-ready;0 = 启动失败(参数错或作为第二实例被踢)。
app-ready 事件返回值
| 情况 | window_id | event_data | | 正常启动完成 | 1 | 文本 success | | app_name / app_signature 校验失败 | 0 | JSON:{"ok":false,"code":"...","message":"..."} | | GUI 线程崩溃 | 0 | 纯文字错误说明 |
必须在 JadeView_init 之前就注册 app-ready(jade_on("app-ready", ...)),否则会漏掉第一条通知。
run_message_loop — 运行消息循环
在"exe 自己跑消息循环"的旧集成方式中可能用到。DLL 嵌入场景下,循环已在 JadeView_init 起好的线程中跑,一般不用调。
[C++] 纯文本查看 复制代码 int32_t run_message_loop(void);
cleanup_all_windows — 清理全部窗口
关闭所有 JadeView 窗口、收尾资源、让事件循环结束,相当于退出前清理。
[C++] 纯文本查看 复制代码 int32_t cleanup_all_windows(void);
// 返回值:1 = 已发起关闭与清理;0 = 失败(尚未完成初始化)
SDK 生态
| SDK | 状态 | 适用场景 | | Web SDK(JS/TS) | 稳定 | WebView 内的 IPC 通信接口(jade.invoke / jade.expose) | | Python SDK2 | v2.0 新增 | ctypes 封装,支持窗口 / IPC / 托盘 / 通知 / 对话框 | | Python SDK | 稳定 | v1.x 绑定,窗口管理与 IPC 路由 | | 易语言 SDK | 已更新 | 专为易语言开发者设计,对接 v2.0 全量 API | | 火山视窗 SDK | 已更新 | 窗口、WebView、IPC、托盘、通知和对话框完整支持 |
下载包文件
| 文件 / 目录 | 说明 | | jadeview.dll | 核心运行时(< 1MB) | | JadeView.h | C 头文件,结构体声明(字段顺序以此为准) | | sdk/web/ | Web SDK(JS/TS) | | sdk/python/ | Python SDK(v1.x 绑定) | | sdk/python2/ [NEW] | Python SDK2(v2.0 全新) | | sdk/elanguage/ | 易语言 SDK | | sdk/volcano/ | 火山视窗 SDK | | docs/ | 离线 API 文档 | | examples/ | 各语言示例项目 |
▌ JAPK 打包格式
JAPK 是 JadeView 专属的应用资源包格式,将前端资源打包为单个 .japk 文件(签名效验机制,防篡改,隐私安全加密),分发简单、加载快速、支持混淆与签名。
打包方式
| 方式 | 命令 / 工具 | 内容保护 | 签名 | 适用场景 | | Electron ASAR | asar pack my-app app.japk | 明文 | 无 | 开发测试 | | JadePack(非签名) | 图形界面,一键构建 | XOR 混淆 | 无 | 基础保护需求 | | JadePack(签名) | 图形界面,勾选签名 | 混淆 + 签名校验 | 有 | 生产环境,防篡改 |
加载方式
JadeView 通过 set_protocol_service_path API 加载 JAPK 包,API 返回协议 URL 用于 WebView 导航:
[C++] 纯文本查看 复制代码 #include "jadeview.h"
void load_japk_example() {
char url_buffer[256];
const char* japk_path = "C:\\path\\to\\your\\app.japk";
int32_t result = set_protocol_service_path(
japk_path,
url_buffer,
sizeof(url_buffer)
);
if (result == 1) {
printf("协议 URL: %s\n", url_buffer);
// 使用 url_buffer 导航 WebView
}
}
注意:JadeView 完全兼容 Electron ASAR 格式,使用 @electron/asar 创建的包可直接加载。
打包前无需特殊配置文件,原始目录树结构会被保留。
▌ SDK 快速入门
易语言示例
以下为易语言 SDK 封装后的实际调用方式,函数名遵循易语言命名风格。
| 窗口程序集名 | 保 留 | 保 留 | 备 注 | | 程序集1 | | | | | 变量名 | 类 型 | 数组 | 备 注 | | JadeView | JadeView | | | 托盘 | jade托盘类 | | | 集_托盘id | 整数型 | | | 集_热键id | 整数型 | |
JadeView. 注册程序事件 ("app-ready", &JadeView准备就绪 )JadeView. 注册程序事件 ("window-all-closed", &事件_所有窗口关闭 )JadeView. 注册程序事件 ("global-hotkey", &全局热键事件 ) JadeView. ipc_订阅 ("win:minimize", &ipc_最小化 )JadeView. ipc_订阅 ("win:toggle_maximize", &ipc_最大化切换 )JadeView. ipc_订阅 ("win:close_last", &ipc_关闭窗口 ) JadeView. 初始化 (是否为调试版 (), 取运行目录 () + "\log.txt", 取运行目录 (), "web", "ceshi_demo", ) JadeView消息循环 ()返回 (0 )|
| JadeView准备就绪 | | | |
| 成功否 | 逻辑型 | | | | err | 文本型 | | | |
| 变量名 | 类 型 | 静态 | 数组 | 备 注 | | 窗口设置 | JadeView窗口设置 | | | | 视窗设置 | JadeView视窗设置 | | | | 载入url | 文本型 | | | | 窗口id | 整数型 | | |
如果真 (成功否 )  载入url = JadeView创建本地服务 (取运行目录 () + "\web" ) 窗口设置.标题 = GBK文本到UTF8文本 ("我的应用" ) 窗口设置.宽度 = 1280  窗口设置.高度 = 800  窗口设置.边框样式 = #标题栏_无标题栏_无边框  窗口设置.透明背景 = 假  窗口设置.X坐标 = -1  窗口设置.Y坐标 = -1  窗口设置.使用页面图标 = 真  视窗设置.开启右键菜单 = 假  窗口id = JadeView. 创建窗口 (载入url, , 窗口设置, 视窗设置 ) 如果真 (窗口id > 0 )  JadeView. 设置窗口背景材料 (窗口id, "mica" )
 集_托盘id = 托盘. 创建托盘 () 托盘. 设置托盘图标 (集_托盘id, 取运行目录 () + "\web\app.ico" ) 托盘. 设置托盘提示文本 (集_托盘id, "我的应用" )  集_热键id = JadeView. 注册全局热键 ( #MOD_CONTROL, #F12键 )  JadeView. 设置yaml ("app.yaml", "ui.theme", "dark" ) 调试输出 ("当前主题", JadeView. 获取yaml ("app.yaml", "ui.theme" ))  JadeView. 退出 ()调试输出 ("热键触发", msg )|
| ipc_最小化 | 整数型 | | |
| WinId | 整数型 | | | | msg | 文本型 | | | |
JadeView. 设置窗口最小化 (WinId )返回 (0 )|
| ipc_最大化切换 | 整数型 | | |
| WinId | 整数型 | | | | msg | 文本型 | | | |
如果 (JadeView. 获取窗口最大化状态 (WinId ))  JadeView. 设置窗口还原 (WinId ) JadeView. 设置窗口最大化 (WinId )返回 (0)|
| ipc_关闭窗口 | 整数型 | | |
| WinId | 整数型 | | | | msg | 文本型 | | | |
JadeView. 销毁窗口 (WinId )返回 (0 )
Python SDK2
jadeview 2.0 的 Python 绑定库,基于 ctypes 封装 DLL,API 命名与前端 JS API 保持一致。
安装
[Bash shell] 纯文本查看 复制代码 pip install jadeview # 或 uv add jadeview
模块总览
| 模块 | 导入 | 功能 | | jadeview | import jadeview | 初始化、消息循环、清理 | | jadeview.window | from jadeview import window | 窗口创建与管理 | | jadeview.webview | from jadeview import webview | 导航、JS 执行、缩放 | | jadeview.ipc | from jadeview import ipc | 事件订阅、IPC 通信 | | jadeview.dialog | from jadeview import dialog | 系统对话框 | | jadeview.tray | from jadeview import tray | 系统托盘 | | jadeview.notification | from jadeview import notification | 系统通知 | | jadeview.tools | from jadeview import tools | 工具函数(路径 / 语言 / YAML / 热键等) | | jadeview.events | from jadeview import events | 事件名称常量 |
基础生命周期示例
[Python] 纯文本查看 复制代码 import jadeview
from jadeview import events
def on_ready(window_id, data):
win_id = jadeview.window.create_webview_window(
"https://example.com",
title="Hello JadeView",
width=1024, height=768,
)
def on_all_closed(window_id, data):
jadeview.cleanup()
jadeview.ipc.on(events.APP_READY, on_ready)
jadeview.ipc.on(events.WINDOW_ALL_CLOSED, on_all_closed)
jadeview.init("MyApp", "myapp1", enable_devmod=True)
jadeview.run()
常用 API 速查
| 分类 | 函数 | 说明 | | 事件 | ipc.on(event, callback) | 注册事件回调(APP_READY / WINDOW_CLOSING / GLOBAL_HOTKEY 等) | | 窗口 | window.create_webview_window(url, ...) | 创建 WebView 窗口,支持 title / theme / transparent 等参数 | | 窗口 | window.set_window_focus(window_id) | 设置窗口焦点 | | 窗口 | window.set_window_backdrop(win_id, type) | 设置背景效果(mica / acrylic,需透明窗口) | | IPC | ipc.register_ipc_handler(name, handler) | 注册 IPC 通道处理器,处理前端 invoke 请求 | | IPC | ipc.send_ipc_message(window_id, channel, data) | Python 向 WebView 前端推送消息 | | 对话框 | dialog.show_open_dialog(window_id, ...) | 同步打开文件选择对话框 | | 对话框 | dialog.show_save_dialog(window_id, ...) | 同步保存文件对话框 | | 托盘 | tray.tray_create() / tray_destroy(id) | 创建 / 销毁系统托盘 | | 托盘 | tray.tray_set_menu_items(id, items) | 设置托盘右键菜单(item_type: 0=普通 1=子菜单 2=分隔线) | | 通知 | notification.show_notification(title, ...) | 显示系统通知(支持 body / button / action) | | 工具 | tools.set_protocol_service_path(path) | 将本地目录挂载为协议根路径 | | 工具 | tools.jadeview_version() | 获取 JadeView 版本号 | | 工具 | tools.get_locale() | 获取系统语言(BCP47) | | 工具 | tools.yaml_set / yaml_get(file, key, val) | YAML 配置持久化读写(自动存储在应用数据目录) | | 工具 | tools.register_global_hotkey(mod, key) | 注册全局热键 → GLOBAL_HOTKEY 事件 | | 工具 | tools.register_url_scheme(scheme) | 注册自定义 URL 协议(HKCU) | | 工具 | tools.register_file_association(ext, desc) | 关联文件扩展名打开方式 |
▌ 版本更新日志
v2.0.0(当前版本,架构级升级)
新增(11项)
- 全新 API 架构,统一 WebViewWindowOptions 结构体
- 系统托盘(图标 / 菜单 / 通知 / 事件)
- 全局热键 register_global_hotkey + global-hotkey 事件
- 内置 YAML 配置读写 yaml_set / yaml_get
- 多显示器信息查询 get_displays_info
- 自定义 URL 协议注册 register_url_scheme
- 获取原生 Win32 HWND:get_window_hwnd
- 防录屏保护 content_protection
- 窗口状态记忆 auto_save_state(450ms 防抖落盘)
- Python SDK2:基于 ctypes 的全量 v2.0 绑定
- 火山视窗 SDK 全面升级,支持托盘、通知、对话框
变更
- create_local_server 更名为 set_protocol_service_path
- JadeView_init 新增 app_name / app_signature / single_instance 三个必填参数
破坏性变更
- 移除旧版 remove_titlebar / borderless / no_center 字段,改用 frame_style + x/y=-1 居中
JadeView — 让桌面开发回归简单
https://jade.run | v2.0 在线文档
|