Skip to main content

JadeUI Logo

JadeUI

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

PyPI version Python versions


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
Simple Calculator Backdrop
Router Custom Template Vue App
Router Custom Vue

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

链接

Metadata

Release files for jadeui 2.3.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jadeui 2.3.3
File Size Uploaded Provenance Actions
jadeui-2.3.3.tar.gz 103.7 kB With provenance Details for jadeui-2.3.3.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for jadeui 2.3.3
File Interpreter ABI Platform Actions
jadeui-2.3.3-py3-none-win_arm64.whl Python 3 none Windows ARM64 Details for jadeui-2.3.3-py3-none-win_arm64.whl
jadeui-2.3.3-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for jadeui-2.3.3-py3-none-win_amd64.whl

Total release size: 4.3 MB

Release files / jadeui-2.3.3.tar.gz

Download URL jadeui-2.3.3.tar.gz
Size 103.7 kB
Tags Source
SHA-256 checksum
How to use checksums
bb544d6ced2f0f184c4bf3601b8c1c5841c2e4b5a55aadcc1b3d700faaf3deec
BLAKE2b-256 checksum
How to use checksums
de422c6e150915dd23279256e6a5d11e550e3b5e35f162f09ea46098ea6d59bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Release files / jadeui-2.3.3-py3-none-win_arm64.whl

Download URL jadeui-2.3.3-py3-none-win_arm64.whl
Size 2.0 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
9ad7a03cd6a3ab7998c7b00e1bb5e90fa02fbd18fe12972c0f0416c5c2c6793e
BLAKE2b-256 checksum
How to use checksums
0e7fd0416241ac416a0eefe1d15ea7c0976e2aa593dd84b07f2d1705951ac9ce
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Release files / jadeui-2.3.3-py3-none-win_amd64.whl

Download URL jadeui-2.3.3-py3-none-win_amd64.whl
Size 2.1 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
d36fba2462014a19d8e6ac211ff1fb9c11ebdc290c7359dbf8eb0cb34f4d4a4a
BLAKE2b-256 checksum
How to use checksums
e0ea50d9410face4c2ccde4b6bb357543cee1123650ac1e7075ffbc5f20154c5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Security for jadeui 2.3.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 3 files in this release have been uploaded with provenance metadata.

Select from 3 files

Attestation for jadeui-2.3.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page