PrismQML（棱镜映界）

简体中文 | English

一套 QML 控件，多种设计语言一键切换。 PrismQML（棱镜映界）是基于 PySide6 + QML 的多皮肤 UI 引擎：同一套控件，运行时自由切换 流畅设计（Fluent Design）、新粗野主义（Neobrutalism）、复古票据（Vintage Ticket）与新拟态（Neumorphism），120fps+ 流畅动画。

PrismQML（棱镜映界）四套皮肤组件实景对比

安装：pip install prismqml
文档：aki-riko.github.io/PrismQML
适合：想用 Python + QML 做现代桌面应用，同时需要统一控件、主题 token、运行时换肤和跨平台窗口能力的项目。

from prismqml import setSkin, Skin
setSkin(Skin.NEOBRUTALISM)   # 一行切换整个应用的设计语言

✨ 特性

🎨 多皮肤引擎：同一套控件，setSkin() 一键切换流畅设计 / 新粗野主义 / 复古票据 / 新拟态，四套皮肤均支持 light/dark
🧩 token 驱动架构：颜色、几何、阴影全走 token —— 新增皮肤几乎零控件改动
⚡ 纯 QML 渲染：无帧率限制，120fps+ 流畅动画
🐍 PySide6 原生：无缝集成，Python 侧管理业务逻辑，无需为业务界面编写 C++
📦 180+ QML 类型：按钮 / 输入 / 卡片 / 对话框 / 表格 / 图表 / 导航等全套
💾 配置系统：JSON 持久化 + 原子写入 + QML Property 桥接
🔄 响应式状态：细粒度 Store 状态管理，支持 watch / batch 模式
🪟 窗口管理：多种窗口布局 + 懒加载 + 云母效果 + 系统托盘
🌍 跨平台：Windows、macOS、Linux

📦 安装

pip install prismqml

分发名与导入名一致：pip install prismqml 后 from prismqml import ...。运行环境要求 Python 3.9+ 与 PySide6 6.9+（Qt 6.9+）。 Windows 宿主在创建首个 QQuickWindow 前固定使用 D3D11；macOS 与 Linux 保留 Qt 的平台默认图形后端。

开发模式安装：

git clone https://github.com/aki-riko/PrismQML.git
cd PrismQML
pip install -e ".[dev]"

🚀 快速开始

from prismqml import App, WindowType

app = App()
window = app.create_window(WindowType.BAR)
window.setWindowTitle("我的应用")
window.resize(1200, 800)

window.show()
app.exec()

需要导航内容时，通过 window.addPage(PageClass, icon, title) 添加应用自己的页面类、页面工厂或页面实例；异步 QML 页面可使用 AsyncQmlPage。

🏗️ 架构

prismqml/
├── PrismQML/              # QML 组件（模块名 PrismQML）
│   ├── controls/           # UI 控件
│   ├── _internal/          # 内部窗口实现
│   └── PrismEnums/        # 枚举与常量
└── python/                 # Python 模块
    ├── config/             # 配置管理系统
    ├── core/               # 核心引擎（主题/日志/图标/阴影）
    ├── runtime/            # 运行时装配（注册/外观持久化边界）
    ├── window/             # 窗口管理（懒加载/云母/托盘）
    ├── state/              # 响应式状态存储
    ├── providers/          # 功能提供者（SVG/二维码/取色器）
    └── models/             # 数据模型（高性能表格）

📐 窗口类型

类型	枚举值	说明
`WindowType.BAR`	1	紧凑侧边导航（默认）
`WindowType.SPLIT`	0	展开式侧边导航
`WindowType.FILLED`	2	填充式分割窗口

from prismqml import App, WindowType

app = App()

# 紧凑侧边导航（默认）
window = app.create_window(WindowType.BAR)

# 展开式侧边导航
window = app.create_window(WindowType.SPLIT)

🎨 皮肤系统（核心）

棱镜映界的招牌能力：皮肤与明暗正交。skin 控制设计语言，theme 控制明暗，两者独立组合。

from prismqml import setSkin, Skin

setSkin(Skin.FLUENT)          # Fluent Design：圆角、模糊阴影、蓝主色
setSkin(Skin.NEOBRUTALISM)    # 新粗野：粗黑边、硬阴影、橙撞色
setSkin(Skin.VINTAGE_TICKET)  # 复古票据：暖纸、油墨细线、印章语义色
setSkin(Skin.NEUMORPHISM)     # 新拟态：同色表面、双向软阴影、凹凸交互

QML 侧通过 Enums.skin 与 Enums.isNeobrutalism / isVintageTicket / isNeumorphism 读取当前皮肤：

import PrismQML
Rectangle {
    radius: Enums.isVintageTicket ? Enums.ticket.radius : Enums.radius.small
    // 但大多数情况你无需判断——控件已自动适配皮肤
}

架构亮点：皮肤差异收敛在 token 层（颜色 / 几何 / 阴影），控件本身对皮肤无感知。新增皮肤主要扩展 token，只在阴影或交互几何确有差异时增加结构分支。

🌗 主题系统

切换主题

from prismqml import setTheme, Theme

setTheme(Theme.LIGHT)   # 浅色
setTheme(Theme.DARK)    # 深色
setTheme(Theme.AUTO)    # 跟随系统

自定义主题色

from prismqml import setAccentColor, getAccentColor

setAccentColor("#0078d4")
print(getAccentColor())  # "#0078d4"

QML 中使用

import PrismQML as Fluent

// Primary 按钮（style_primary 自动使用全局主题色）
Fluent.Button {
    text: "确定"
    style: Fluent.Enums.button.style_primary
}

// 所有主题 token 统一通过 Enums 访问
Rectangle {
    color: Fluent.Enums.accentColor
}

ComboBox、Slider 已在顶层 PrismQML 模块注册。使用 import PrismQML as Fluent 后直接写 Fluent.ComboBox / Fluent.Slider，无需导入 QtQuick.Controls 或内部目录。

⚙️ 配置系统

配置系统采用五层架构：Validator → SettingEntry → SettingsCore → AppConfig → ConfigManager

JSON 持久化：Window 设置默认存储于 ~/.prismqml/app.json
原子写入：先写临时文件再替换，防止断电数据丢失
QML 桥接：通过 ConfigManager 单例暴露为 QML Property

App() 的全局外观默认始终是 Fluent，不会再从共享文件隐式恢复其他应用的 Theme/Skin/Language/AccentColor。需要应用级外观持久化时传入独立 config_path；已有自身外观配置的宿主同时传 persist_appearance=False。

from prismqml.python.config import AppConfig, getConfigManager

# 获取配置值
config = getConfigManager()
print(config.lazyLoading)   # True
print(config.dpiScale)      # 0（跟随系统）

# 修改配置（自动保存到 JSON）
config.setDpiScale(150)

自定义配置项

from typing import ClassVar
from prismqml.python.config import (
    SettingsCore, SettingEntry, EnumEntry,
    Validator,
)


class MyAppConfig(SettingsCore):
    auto_save: ClassVar[SettingEntry] = SettingEntry(
        group="Editor", name="AutoSave",
        default=True, validator=Validator.boolean(),
    )
    font_size: ClassVar[EnumEntry] = EnumEntry(
        group="Editor", name="FontSize",
        default=14,
        validator=Validator.choice([12, 14, 16, 18, 20, 24]),
    )

📊 状态管理

Store 提供响应式状态存储，支持细粒度 watch 和批量更新：

from prismqml import Store

class AppStore(Store):
    def __init__(self):
        super().__init__("app")
        self.define("user", None)
        self.define("count", 0)

store = AppStore()

# 监听变化
store.watch("count", lambda new, old: print(f"{old} → {new}"))

# 设置值
store.set("count", 1)     # 输出: 0 → 1

# 批量更新（合并通知）
with store.batch():
    store.set("count", 10)
    store.set("user", "Alice")
# 退出 with 时统一通知

# 字典语法
store["count"] = 20
print(store["count"])      # 20

🔔 系统托盘

from prismqml import SystemTrayIcon, Icon

tray = SystemTrayIcon(icon="AppIcon.png", toolTip="我的应用")
tray.addAction(text="显示", icon="Visibility", triggered=window.show)
tray.addSeparator()
tray.addAction(text="退出", icon="Power", triggered=app.quit)
tray.show()

🧩 UI 组件

控件

Button · Card · CheckBox · ToggleSwitch · LineEdit · ComboBox · Slider · ProgressBar · SpinBox · TableView · ListView · TreeView

特效

Shadow · ShadowedRectangle · ColorOverlay · GaussianBlur

完整组件清单见在线文档。 ComboBox、Slider 已在顶层 PrismQML 模块注册；使用 import PrismQML as Fluent 后直接写 Fluent.ComboBox / Fluent.Slider。

🧰 开发产物

本地构建产物和缓存统一写入仓库根目录 .artifacts/，按用途分为：

.artifacts/cpp/：CMake 桌面、Android、iOS 构建树
.artifacts/python/：Python 构建、分发包、pytest 缓存和字节码缓存
.artifacts/rust/：Cargo target
.artifacts/docs/：MkDocs 站点

历史散落目录已移到各类别的 legacy/，不再作为新的构建入口。需要把产物放到仓库外时，设置 PRISM_ARTIFACT_ROOT；C++ 脚本仍可用 PRISM_DESKTOP_BUILD_DIR 或 PRISM_ANDROID_BUILD_DIR 单独覆盖。

🧪 测试

python scripts/test_process.py --qt-platform offscreen --timeout 480 -- python -m pytest
python scripts/test_process.py --qt-platform offscreen --timeout 180 -- python -X utf8 tests/qml/probe_all_components.py

自动化 pytest 与 QML probe 始终强制使用 offscreen，调用者已有的 windows / minimal 等平台值也会被覆盖。Windows 下 test_process.py 会把完整测试进程树放入私有 Desktop 与关闭即终止的 Job Object，因此测试 UI（包括短暂窗口）不会出现在当前用户桌面；runner 会轮询检测 Job 内持续可见窗口，检测到时记录证据并以 126 失败，正常退出或超时时确认全部后代进程归零。请勿绕过该 runner 裸跑自动化测试。单独运行标注为手工窗口测试的脚本仍可能显示 UI。C++/CTest 的真实 Windows Mica 验证说明见 cpp/README.md。

📄 License

PrismQML is licensed under the MIT License.

🙏 Credits

Design inspired by the Microsoft Fluent Design System.
Icons from Microsoft Fluent UI System Icons (MIT License).

Release files for prismqml 0.4.2.24

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

Source distribution (sdist)

Source distribution for prismqml 0.4.2.24
File	Size	Uploaded
prismqml-0.4.2.24.tar.gz	2.6 MB	Sep 11, 2026	Details

Built distributions (wheels)

Table of built distributions (wheels) for prismqml 0.4.2.24
File	Interpreter	ABI	Platform	Reset
prismqml-0.4.2.24-cp39-abi3-win_amd64.whl 4.9 MB Sep 11, 2026	CPython 3.9	abi3	Windows x86-64	Details
prismqml-0.4.2.24-cp39-abi3-manylinux_2_28_x86_64.whl 5.2 MB Sep 11, 2026	CPython 3.9	abi3	Linux glibc 2.28+ x86-64	Details
prismqml-0.4.2.24-cp39-abi3-macosx_11_0_arm64.whl 5.0 MB Sep 11, 2026	CPython 3.9	abi3	macOS 11.0+ ARM64	Details

Total release size: 17.8 MB

Release files / prismqml-0.4.2.24.tar.gz

Download URL	prismqml-0.4.2.24.tar.gz
Size	2.6 MB
Tags	Source
SHA-256 checksum How to use checksums	`fb457bd39680e9d74681624464987d20da337155b19193d0ae4c7a748b0bf7a6`
BLAKE2b-256 checksum How to use checksums	`ca1b244809c8853e370004a065714e3e8b300acf243d54465be30270c34c43e2`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/aki-riko/PrismQML
Publishing commit: github.com/aki-riko/PrismQML/tree/f1ee20280196c599e989f9661126bcf21a45f974

Workflow

Publishing configuration: github.com/aki-riko/PrismQML/blob/f1ee20280196c599e989f9661126bcf21a45f974/.github/workflows/release.yml
Publishing logs: github.com/aki-riko/PrismQML/actions/runs/34588063120/attempts/1

Artifact

Subject: prismqml-0.4.2.24.tar.gz
SHA-256 checksum: fb457bd39680e9d74681624464987d20da337155b19193d0ae4c7a748b0bf7a6 Verifying attestations

Release files / prismqml-0.4.2.24-cp39-abi3-win_amd64.whl

Download URL	prismqml-0.4.2.24-cp39-abi3-win_amd64.whl
Size	4.9 MB
Tags	CPython 3.9 Windows x86-64 abi3
SHA-256 checksum How to use checksums	`09031005c419b1143adaf42f7c7d560a9dc39a33b2d88d660fd2f6fc7355e52c`
BLAKE2b-256 checksum How to use checksums	`a64caebb69e6894413659c2031ee0f983855f21d968bb66e7eb137898c545d6b`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/aki-riko/PrismQML
Publishing commit: github.com/aki-riko/PrismQML/tree/f1ee20280196c599e989f9661126bcf21a45f974

Workflow

Publishing configuration: github.com/aki-riko/PrismQML/blob/f1ee20280196c599e989f9661126bcf21a45f974/.github/workflows/release.yml
Publishing logs: github.com/aki-riko/PrismQML/actions/runs/34588063120/attempts/1

Artifact

Subject: prismqml-0.4.2.24-cp39-abi3-win_amd64.whl
SHA-256 checksum: 09031005c419b1143adaf42f7c7d560a9dc39a33b2d88d660fd2f6fc7355e52c Verifying attestations

Release files / prismqml-0.4.2.24-cp39-abi3-manylinux_2_28_x86_64.whl

Download URL	prismqml-0.4.2.24-cp39-abi3-manylinux_2_28_x86_64.whl
Size	5.2 MB
Tags	CPython 3.9 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum How to use checksums	`47754086a205b0bb999857641d7ac11b192e212bdc6a77d0d163cad20c0c70cb`
BLAKE2b-256 checksum How to use checksums	`f73113bf3c1d8fb4ef86b9baa6a7ee5c99680b7197e8c6dbcd49b3c16e37715e`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/aki-riko/PrismQML
Publishing commit: github.com/aki-riko/PrismQML/tree/f1ee20280196c599e989f9661126bcf21a45f974

Workflow

Publishing configuration: github.com/aki-riko/PrismQML/blob/f1ee20280196c599e989f9661126bcf21a45f974/.github/workflows/release.yml
Publishing logs: github.com/aki-riko/PrismQML/actions/runs/34588063120/attempts/1

Artifact

Subject: prismqml-0.4.2.24-cp39-abi3-manylinux_2_28_x86_64.whl
SHA-256 checksum: 47754086a205b0bb999857641d7ac11b192e212bdc6a77d0d163cad20c0c70cb Verifying attestations

Release files / prismqml-0.4.2.24-cp39-abi3-macosx_11_0_arm64.whl

Download URL	prismqml-0.4.2.24-cp39-abi3-macosx_11_0_arm64.whl
Size	5.0 MB
Tags	CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`eae63118005835198e5d4d1d232bb252461a142b3f00751c0e2adaef425725e4`
BLAKE2b-256 checksum How to use checksums	`85418808c0552a8f4cf6c1ed7de6ed90a385e175593e39fb9ede0e2f55708e8b`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/aki-riko/PrismQML
Publishing commit: github.com/aki-riko/PrismQML/tree/f1ee20280196c599e989f9661126bcf21a45f974

Workflow

Publishing configuration: github.com/aki-riko/PrismQML/blob/f1ee20280196c599e989f9661126bcf21a45f974/.github/workflows/release.yml
Publishing logs: github.com/aki-riko/PrismQML/actions/runs/34588063120/attempts/1

Artifact

Subject: prismqml-0.4.2.24-cp39-abi3-macosx_11_0_arm64.whl
SHA-256 checksum: eae63118005835198e5d4d1d232bb252461a142b3f00751c0e2adaef425725e4 Verifying attestations