jadeui 2.3.3

Python SDK for JadeView - Create desktop applications with WebView

JadeUI

Python SDK for JadeView - 使用 Web 技术构建桌面应用

---

JadeUI 是 JadeView 的 Python SDK，让你可以使用 Python + Web 技术构建现代桌面应用程序。

特性

• WebView 窗口 - 使用 HTML/CSS/JS 构建 UI
• 现代外观 - 支持 Windows 11 Mica/Acrylic 效果
• 主题切换 - Light/Dark/System 主题
• IPC 通信 - Python 与前端双向通信
• 对话框 API - 文件选择、消息框 (v1.3.0+)
• 通知 API - Windows 原生桌面通知 (v1.3.0+)
• 系统托盘 - 托盘图标、提示与右键菜单 (v2.2.4+)
• 全局热键 - 应用在后台也能响应的快捷键 (v2.2.4+)
• 剪贴板 / 系统信息 - 剪贴板读写、显示器/语言/系统路径 (v2.2.4+)
• 窗口增强 - 缩放、任务栏进度/闪烁、DevTools、内容保护等 (v2.2.4+)
• YAML 存储 / 系统集成 - 持久化存储、开机自启、文件图标、NTP 网络时间 (v2.3.0+)
• 窗口集成增强 - 不进任务栏、不抢焦点、窗口层级、HWND 反查窗口 ID (v2.3.0+)
• 打包体积 - 极小的依赖，打包后体积仅有8MB左右

本版本对应 JadeView 原生 v2.3.0 (Build 26G02)。从 2.2.4 升级的变更与实机验收结果详见 docs/UPGRADE_v2.3.0.md。

安装

pip install jadeui

CLI 快速开始

安装后可使用统一命令行工具 jadeui：

jadeui init my-app --frontend html   # 也可选 vue / react
cd my-app
jadeui doctor                        # 检查 Python / DLL / Nuitka / Node+asar
jadeui run                           # 开发运行
jadeui japk                          # 前端打包为明文 app.japk（需 @electron/asar）
jadeui build                         # 宿主打包为 exe（默认 Nuitka）
jadeui build --packager pyinstaller  # 可选 PyInstaller

常用子命令：init / run / doctor / japk / build / download / clean。

旧入口 jadeui-download、jadeui-clean 仍然可用。

项目元数据（可选）读 pyproject.toml：CLI 显式参数优先，其次 [tool.jadeui]，再回退 [project].name（例如 jadeui build 的默认输出名）。与 uv / conda 等共用同一份 pyproject.toml 时互不冲突——JadeUI 只使用 [tool.jadeui] 命名空间。

JadeView DLL 更新规则

JadeUI SDK 只会在已适配的 JadeView API 版本内自动选择最新构建号。例如 2.3.0.26G02 可以自动更新到同一 tag 下的后续 build，但不会自动跨到 2.4 或其它 release tag。

jadeui download                 # 下载当前 SDK 适配版本的最新 build
jadeui download --build 26G02   # 固定下载指定 build
# 兼容旧命令:
jadeui-download

当前按 Python 解释器架构选择上游原生包：

• Windows: x86 / x64 / arm64，下载 JadeView_win_{arch}_*.zip，加载 JadeView_{arch}.dll

跨 minor/major 的原生版本升级（如 2.2 -> 2.3）可能包含 ABI/API 变化，必须由 SDK 显式适配后再升级。

快速开始

CLI 脚手架

jadeui init my-app --frontend html
cd my-app
jadeui run

最简模式

from jadeui import Window

Window(title="Hello JadeUI", url="https://example.com").run()

本地应用（自动检测 web 目录）

from jadeui import Window

Window(title="My App").run()  # 自动加载 web/index.html

完整模式（多窗口、全局事件）

from jadeui import JadeUIApp, Window

app = JadeUIApp()

@app.on_ready
def on_ready():
    Window(title="Window 1", url="https://example.com").show()
    Window(title="Window 2", url="https://google.com").show()

app.run()

示例项目

查看 examples 目录获取完整示例：

示例	说明
simple	最简示例 - 几行代码创建应用
calculator	基础计算器，展示窗口创建和 IPC 通信
backdrop_demo	Windows 11 Mica/Acrylic 背景效果
router_demo	内置路由系统实现多页面应用
custom_template	自定义 HTML 模板和样式
vue_app	Vue.js + JadeUI 集成示例
dialog_notification_demo	对话框与桌面通知 (v1.3.0+)
p3_demo	系统托盘 / 全局热键 / 剪贴板 / 系统信息 / 窗口增强 (v2.2.4+)
v23_demo	YAML 存储 / 窗口层级 / 文件图标 / NTP / 拖拽事件 (v2.3.0+)

效果预览

Simple	Calculator	Backdrop

Router	Custom Template	Vue App

API 文档

完整文档请访问: https://jade.run/python-sdk

前端资源包（JAPK）

JAPK 打包的是 HTML/CSS/JS 等前端资源（不是 Python exe）。官方说明见 JAPK 文档。

方式	工具	说明
明文 ASAR 兼容包	jadeui japk（底层 @electron/asar）	开发/内部工具，命令行可用
混淆 / 签名包	JadePack 桌面客户端	生产推荐（签名包为 AES-256-GCM + Ed25519）

# 需先安装 Node.js，并执行: npm install -g @electron/asar
jadeui japk                      # 默认 web -> dist/app.japk
jadeui japk --src web -o dist/app.japk

运行时可用目录、.japk 路径或内存加载：

from jadeui import Window

Window(title="My App").run(japk="dist/app.japk")

打包发布（宿主 exe）

默认使用 Nuitka 将 Python 宿主打包为独立可执行文件；也可用 PyInstaller。
缺少打包器时会自动安装（nuitka>=4.0 或 PyInstaller，可用 --no-auto-deps 关闭）：

jadeui build app.py -o your_app
jadeui build app.py -o your_app --packager pyinstaller

兼容旧脚本：python scripts/build.py your_app.py -o your_app（内部转发到同一实现）。

系统要求

• 操作系统: Windows 10/11
• Python: 3.7+
• Python 架构: Windows 支持 x86 / x64 / arm64。JadeUI 会按 Python 解释器架构下载匹配的 JadeView 原生库。

官方 JadeView 暂未提供 Linux 原生库（仍在开发中），当前 SDK 仅支持 Windows。

使用注意

• 单次 jade.invoke payload 建议不超过 1000KB。实测 1023KB 可用，但精确 1MiB payload 加上 IPC 封装后会超过 JadeView bridge 的消息上限并被拒绝；更大的数据应使用分片或文件传递。

许可证

MIT License

链接

• Python SDK 文档
• JadeView 官网
• GitHub
• PyPI