PrismQML（棱镜映界）

简体中文 | English

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

PrismQML（棱镜映界）Fluent 与 Neobrutalism 皮肤对比

  • 安装：pip install prismqml
  • 适合：想用 Python + QML 做现代桌面应用，同时需要统一控件、主题 token、运行时换肤和跨平台窗口能力的项目。
from prismqml import setSkin, Skin
setSkin(Skin.NEOBRUTALISM)   # 一行切换整个应用的设计语言

✨ 特性

  • 🎨 多皮肤引擎：同一套控件，setSkin() 一键切换流畅设计 / 新粗野主义 / 复古票据，支持 light/dark
  • 🧩 token 驱动架构：颜色、几何、阴影全走 token —— 新增皮肤几乎零控件改动
  • ⚡ 纯 QML 渲染：无帧率限制，120fps+ 流畅动画
  • 🐍 PySide6 原生：无缝集成，Python 侧管理业务逻辑，不碰 C++
  • 📦 控件齐全：按钮 / 输入 / 卡片 / 对话框 / 表格 / 图表 / 导航等全套
  • 💾 配置系统：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+）。

开发模式安装：

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

🚀 快速开始

from prismqml import App, Window, WindowType

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

# 添加导航页面
window.addPage(HomePage, "Home", "首页")
window.addPage(SettingsPage, "Settings", "设置")

window.show()
app.exec()

🏗️ 架构

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, Window, 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)    # 新粗野：粗黑边、硬阴影、橙撞色

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

import PrismQML
Rectangle {
    radius: Enums.isNeobrutalism ? 0 : 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 持久化：默认存储于 ~/.prismqml/app.json
  • 原子写入：先写临时文件再替换，防止断电数据丢失
  • QML 桥接：通过 ConfigManager 单例暴露为 QML Property
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

导航

NavigationBar · NavigationView · Pivot · Breadcrumb · Windows

特效

Shadow · ShadowedRectangle · ColorOverlay · GaussianBlur

完整组件清单见各 controls/ 子目录的 qmldir。ComboBox、Slider 等与 QtQuick 原生同名的组件需经子模块目录导入。

🧰 开发产物

本地构建产物和缓存统一写入仓库根目录 .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 300 -- python -m pytest tests/ -v
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.

Copyright © 2026 aki-riko.

🙏 Credits

Project links

Data verified by PyPI on Aug 16, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.4.2.8)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for aki_riko from gravatar.com aki_riko

Credits

Author: aki-riko

GitHub Statistics

Data verified by PyPI on Aug 16, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT License)

Requires

Python >=3.9

Provides Extra

macos dev rust

Tags

qml fluent neobrutalism vintage-ticket ui pyside6 qt design skin

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

prismqml-0.4.0.4.tar.gz (2.6 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

prismqml-0.4.0.4-cp39-abi3-win_amd64.whl (4.9 MB view details)

Uploaded CPython 3.9+Windows x86-64

prismqml-0.4.0.4-cp39-abi3-manylinux_2_28_x86_64.whl (5.1 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.28+ x86-64

prismqml-0.4.0.4-cp39-abi3-macosx_11_0_arm64.whl (5.0 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

File details

Details for the file prismqml-0.4.0.4.tar.gz.

File metadata

  • Download URL: prismqml-0.4.0.4.tar.gz
  • Upload date:
  • Size: 2.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for prismqml-0.4.0.4.tar.gz
Algorithm Hash digest
SHA256 68dcd5f22498fd5bcff230709d583fdd4cf9be6f98a47e117c71337953dba2cd
MD5 7e9527d4460ce47cf9a409bf4f42d94e
BLAKE2b-256 dcd817a8af1ad4a706bf26e8625a1f4df07c68faea00ca0f4975ced88dcc512a

See more details on using hashes here.

Provenance

The following attestation bundles were made for prismqml-0.4.0.4.tar.gz:

Publisher: release.yml on aki-riko/PrismQML

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file prismqml-0.4.0.4-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: prismqml-0.4.0.4-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 4.9 MB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for prismqml-0.4.0.4-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 23d250ce6768b29514a2a1c24def77931a1c31c77b0466c8fafe199d38b838e9
MD5 78f6bd3c6d1eb054730bb01efc4696bd
BLAKE2b-256 022bdf7254856821beb1e2f4140b2197bbc74694d4429c924e7867cb39969efb

See more details on using hashes here.

Provenance

The following attestation bundles were made for prismqml-0.4.0.4-cp39-abi3-win_amd64.whl:

Publisher: release.yml on aki-riko/PrismQML

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file prismqml-0.4.0.4-cp39-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for prismqml-0.4.0.4-cp39-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 10163c8d00df377cfd558d119abeb026c53baeb3bb5453cee9b87eee1f87e1f0
MD5 17471e531b22e89f8c6ff7b3c0c409e8
BLAKE2b-256 dc3c23461c22987c45524ca92230ed2a26c1d573b3715b19bc8e49ec226aa84f

See more details on using hashes here.

Provenance

The following attestation bundles were made for prismqml-0.4.0.4-cp39-abi3-manylinux_2_28_x86_64.whl:

Publisher: release.yml on aki-riko/PrismQML

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file prismqml-0.4.0.4-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for prismqml-0.4.0.4-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d97052a1e50b2bc6269b0d44373f3dd0d4a87e445b7d8610be986ba39b3c50f3
MD5 c48326698aafc3ed4f3a3bb3d74d530b
BLAKE2b-256 c346c84edae4c9daec1de6dbfdd24bf93e074dd9eba1d26178b1a71c2f209106

See more details on using hashes here.

Provenance

The following attestation bundles were made for prismqml-0.4.0.4-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on aki-riko/PrismQML

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.4.2.8

4 files

0.4.2.7

4 files

0.4.2.6

4 files

0.4.2.3

4 files

0.4.2.1

4 files

0.4.1.5

4 files

0.4.1.4

4 files

0.4.1.3

4 files

0.4.0.8

4 files

0.4.0.6

4 files

0.4.0.5

4 files

This release

0.4.0.4 This release

4 files

0.4.0.3

4 files

0.4.0.1

4 files

0.3.4.4

4 files

0.3.4.2

4 files

0.3.4.1

4 files

0.3.3.14

4 files

0.3.3.9

4 files

0.3.3.7

4 files

0.3.3.4

4 files

0.3.3.3

4 files

0.3.3.2

4 files

0.3.3.1

4 files

0.3.2.18

4 files

0.3.2.17

4 files

0.3.2.16

4 files

0.3.2.15

4 files

0.3.2.14

4 files

0.3.2.13

4 files

0.3.2.12

4 files

0.3.2.11

4 files

0.3.2.10

4 files

0.3.2.9

4 files

0.3.2.7

4 files

0.3.2.6

4 files

0.3.2.5

4 files

0.3.2.4

4 files

0.3.2.3

4 files

0.3.2.2

4 files

0.3.2.1

4 files

0.3.1.45

4 files

0.3.1.43

4 files

0.3.1.41

4 files

0.3.1.40

4 files

0.3.1.39

4 files

0.3.1.38

4 files

0.3.1.36

4 files

0.3.1.35

4 files

0.3.1.34

4 files

0.3.1.33

4 files

0.3.1.32

4 files

0.3.1.31

4 files

0.3.1.30

4 files

0.3.1.29

4 files

0.3.1.28

4 files

0.3.1.27

4 files

0.3.1.26

4 files

0.3.1.25

4 files

0.3.1.24

4 files

0.3.1.23

4 files

0.3.1.22

4 files

0.3.1.21

4 files

0.3.1.20

4 files

0.3.1.19

4 files

0.3.1.18

4 files

0.3.1.16

4 files

0.3.1.15

4 files

0.3.1.14

4 files

0.3.1.13

4 files

0.3.1.12

4 files

0.3.1.11

4 files

0.3.1.10

4 files

0.3.1.9

4 files

0.3.1.8

4 files

0.3.1.7

4 files

0.3.1.6

4 files

0.3.1.5

4 files

0.3.1.4

4 files

0.3.1.3

4 files

0.3.1.1

4 files

0.2.24.13

4 files

0.2.24.12

4 files

0.2.24.9

4 files

0.2.24.8

4 files

0.2.24.7

4 files

0.2.24.6

4 files

0.2.24.5

4 files

0.2.24.3

4 files

0.2.24.2

4 files

0.2.24.1

4 files

0.2.24

4 files

0.2.23

4 files

0.2.22

4 files

0.2.19

4 files

0.2.18

4 files

0.2.17

4 files

0.2.16

4 files

0.2.15

4 files

0.2.14

4 files

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