Metadata-Version: 2.4
Name: jadeui
Version: 2.3.3
Summary: Python SDK for JadeView - Create desktop applications with WebView
Project-URL: Homepage, https://jade.run
Project-URL: Documentation, https://jade.run/python-sdk
Project-URL: Repository, https://github.com/ArcletProject/jadeui
Project-URL: Issues, https://github.com/ArcletProject/jadeui/issues
Author: JadeView Team
License: MIT
Keywords: desktop,gui,jadeui,jadeview,ui,webview
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.7
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: imageio; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: pyinstaller
Requires-Dist: pyinstaller>=6.0; extra == 'pyinstaller'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/light.svg" alt="JadeUI Logo" width="120">
</p>

<h1 align="center">JadeUI</h1>

<p align="center">
  <strong>Python SDK for JadeView - 使用 Web 技术构建桌面应用</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/jadeui/"><img src="https://img.shields.io/pypi/v/jadeui.svg" alt="PyPI version"></a>
  <a href="https://pypi.org/project/jadeui/"><img src="https://img.shields.io/pypi/pyversions/jadeui.svg" alt="Python versions"></a>
</p>

---

JadeUI 是 [JadeView](https://jade.run) 的 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](docs/UPGRADE_v2.3.0.md)。

## 安装

```bash
pip install jadeui
```

## CLI 快速开始

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

```bash
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。

```bash
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 脚手架

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

### 最简模式

```python
from jadeui import Window

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

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

```python
from jadeui import Window

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

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

```python
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](./examples) 目录获取完整示例：

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

### 效果预览

| Simple | Calculator | Backdrop |
|:---:|:---:|:---:|
| ![Simple](assets/simple.png) | ![Calculator](assets/calculator_iiBxCxUko6.png) | ![Backdrop](assets/backdrop_demo.png) |

| Router | Custom Template | Vue App |
|:---:|:---:|:---:|
| ![Router](assets/router_demo.png) | ![Custom](assets/custom_demo.png) | ![Vue](assets/vueapp.png) |

## API 文档

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

## 前端资源包（JAPK）

JAPK 打包的是 **HTML/CSS/JS 等前端资源**（不是 Python exe）。官方说明见 [JAPK 文档](https://jade.run/docs/api/japk)。

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

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

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

```python
from jadeui import Window

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

## 打包发布（宿主 exe）

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

```bash
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 文档](https://jade.run/python-sdk)
- [JadeView 官网](https://jade.run)
- [GitHub](https://github.com/HG-ha/Jadeui)
- [PyPI](https://pypi.org/project/jadeui/)

