主题样式 (Theme Styles)¶
MonkeyQt 内置了极其强大、丰富的主题样式。它包含 67 种不同的 UI 设计风格（包括极简瑞士风、新拟物化、玻璃拟态、粗野主义、赛博朋克、HUD 科幻、墨水屏风格等），并提供了全局一键切换和自动样式应用功能。
核心概念¶
MonkeyQt 的主题样式通过以下几个核心组件协同工作：
ThemeEngine（风格引擎）：全局唯一的单例，负责管理当前活跃主题的 Design Tokens（颜色、圆角、边框、模糊度等）和构建应用级的全局样式表 (QSS)。- 自动应用机制 (
_ThemeAutoApplier)：当开启自动模式时，系统会实时检测新实例化的组件并自动为其涂装当前主题的对应样式，开发者无需手动进行二次配置。 Themed系列组件：主题引擎专为各组件定制了主题适配逻辑，以在不同主题下达到最佳的视觉渲染效果。
基础用法¶
1. 全局启用并应用主题¶
推荐使用全局便捷入口函数 use_theme，它会自动监听新创建的组件并应用样式：
import sys
from PySide6.QtWidgets import QApplication, QWidget, QVBoxLayout
from monkeyqt import use_theme, MkButton, MkInput
if __name__ == "__main__":
app = QApplication(sys.argv)
# 💡 在创建任何窗口前，指定全局主题
# 选项例如："Glassmorphism" (玻璃拟态), "Neumorphism" (新拟物化), "Cyberpunk UI" (赛博朋克)
use_theme("Glassmorphism")
window = QWidget()
window.setWindowTitle("主题应用示例")
window.resize(320, 200)
layout = QVBoxLayout(window)
layout.addWidget(MkInput("用户名"))
layout.addWidget(MkButton("确认", type="primary"))
window.show()
sys.exit(app.exec())
2. 运行时动态切换主题¶
如果需要在程序运行中（例如点击按钮时）切换主题，可以直接调用 ThemeEngine.set_theme：
from monkeyqt import ThemeEngine
# 切换到赛博朋克风格
ThemeEngine.set_theme("Cyberpunk UI")
# 恢复默认经典样式
ThemeEngine.clear_theme()
高级定制 API¶
1. 局部重写铬黄/框架配色 (Chrome Override)¶
如果你想对当前主题的标题栏（TitleBar）和侧边栏（Sidebar）进行特别的外观颜色重写，可以使用 set_theme_chrome：
from monkeyqt import set_theme_chrome
# 独立定制标题栏和侧边栏的背景色
set_theme_chrome(titlebar_bg="#1e1e2e", sidebar_bg="#181825")
# 还原到主题自带的默认分配色
from monkeyqt import clear_theme_chrome
clear_theme_chrome()
2. 排除或包含特定组件¶
如果有些特定的自定义组件您想保持自己原本的样式表 (StyleSheet) 或绘图逻辑，不被全局主题机制所覆盖，可以将其排除在外：
from monkeyqt import exclude_from_theme, include_in_theme
# 将 my_widget 及其子组件排除在主题引擎的控制之外
exclude_from_theme(my_widget)
# 重新将该组件加入主题受控范围
include_in_theme(my_widget)
内置主题选择器 (MkThemeSelector)¶
MonkeyQt 提供了一个开箱即用的主题下拉选择器 MkThemeSelector，可直接拖放到标题栏或设置面板中，实现真正的全站主题热重载。
示例代码¶
from monkeyqt import MkWindow, MkThemeSelector, MkButton
from PySide6.QtWidgets import QApplication, QFrame, QVBoxLayout
import sys
class ThemeSelectorDemo(MkWindow):
def __init__(self):
super().__init__(use_custom_title_bar=True, preset="default")
self.setWindowTitle("主题切换控制台")
self.resize(600, 400)
# 1. 实例化主题选择器并将其加入自定义标题栏中
self.selector = MkThemeSelector()
self.titlebar.center_layout.addWidget(self.selector)
# 2. 页面主体内容
content = QFrame()
layout = QVBoxLayout(content)
layout.addWidget(MkButton("主题测试按钮", type="primary"))
self.setCentralWidget(content)
if __name__ == "__main__":
app = QApplication(sys.argv)
window = ThemeSelectorDemo()
window.show()
sys.exit(app.exec())
风格视觉预览 (Style Previews)¶
以下是几款代表性主题在 MonkeyQt 组件演示大厅 (MainGallery) 下的实时渲染截图预览（点击下方小圆点可自由滑动切换）：
常用主题列表 (67 种内置设计风格)¶
以下是部分极具代表性的内置主题英文标识名与其中文显示名称：
| 英文标识键名 (Style Name) | 中文显示名称 | 视觉特征分类 |
|---|---|---|
"Minimalism & Swiss Style" |
极简瑞士风格 | 扁平/经典设计 |
"Neumorphism" |
新拟物化 | 软 UI (Soft UI) / 黏土拟态 |
"Glassmorphism" |
玻璃拟态 | 毛玻璃/背景模糊 (Spatial UI) |
"Brutalism" |
粗野主义 | 高对比度/纯黑粗边框 (New Brutalism) |
"Cyberpunk UI" |
赛博朋克 UI | 霓虹发光/高饱和度暗调 |
"HUD / Sci-Fi FUI" |
HUD 科幻界面 | 暗蓝色调/荧光线条 |
"E-Ink / Paper" |
电子墨水屏与纸质 | 黑白双色/极高文字可读性 |
"Dark Mode (OLED)" |
深色模式 OLED | 极致省电全黑模式 |
"Claymorphism" |
黏土拟态 | 立体充气感/高亮阴影对比 |
"Aurora UI" |
极光 UI | 极光梦幻渐变色调 |
"3D & Hyperrealism" |
3D与超现实 | 立体材质/光影细节 |
"Vibrant & Block-based" |
活力方块设计 | 大面积色块/高饱和色彩 |
"Accessible & Ethical" |
无障碍友好设计 | 高对比度/符合 WCAG AAA 标准 |
"Retro-Futurism" |
复古未来主义 | 80年代霓虹/CRT扫描线效果 |
"Flat Design" |
经典扁平化 | 去除投影与高亮渐变，极致扁平 |
"Skeuomorphism" |
拟物化风格 | 质感逼真/还原真实物体 |
"Liquid Glass" |
流态玻璃 | 液体流动感/毛玻璃混合效果 |
"Y2K Aesthetic" |
Y2K 潮酷美学 | 千禧年科技感/金属反光与复古酸性 |
"AI-Native UI" |
AI 原生界面 | 面向智能交互的动态布局与卡片 |
"Memphis Design" |
孟菲斯风格 | 乱中有序的几何图形与撞色搭配 |
"Pixel Art" |
像素艺术 | 怀旧像素游戏风/极简粗犷线条 |
"Spatial UI (VisionOS)" |
空间 UI (VisionOS) | 悬浮透光/三维层级深度感 |
"Vintage Analog / Retro Film" |
复古胶片色调 | 暖色噪点/拍立得与老唱片质感 |
可以在代码中使用 ThemeEngine.list_themes() 检索出全部 67+ 款可用主题的英文标识键名。