智学文枢：主题管理

主题管理（theme_manager.py：暗黑主题加载与 QSS 体系）

一句话摘要：智学文枢采用"暗黑优先"的单主题策略，ThemeManager 在应用启动时把一份集中维护的 dark.qss 整份灌进 QApplication，用 QSS 选择器与 objectName 体系统一全局视觉，彻底告别每个控件手写内联样式的维护噩梦。

一、引言

先问第一性问题：桌面应用的"主题"到底解决什么根本问题？

一个界面由几十个控件组成：按钮、输入框、表格、滚动条、下拉框……如果每个控件的颜色都靠代码里 setStyleSheet(…) 内联写死，会出现什么？三个页面、三个按钮，三个不同的蓝色；想全局换一个主色调，要翻遍几十个文件；新手看不懂老手写的颜色常量，干脆再发明一套。

第一性原理的答案是：视觉样式必须集中管理，通过"选择器"按控件身份批量套用。这正是 QSS（Qt Style Sheets）的定位——语法模仿 CSS，配合 Qt 的对象树和 objectName，用一条规则命中一批控件。而 ThemeManager 的职责就一句话：把主题文件加载进应用。

智学文枢的选择是"暗黑优先"：以暗色为唯一出厂主题，把全部样式收敛进 dark.qss。这不是偷懒，而是把"主题"当作一个可扩展的抽象层——今天只有 dark.qss，明天加一个 light.qss，切换逻辑只需在 ThemeManager 里多写几行。

二、核心原理

2.1 QSS 怎么工作：选择器 + 声明块

QSS 的渲染路径是：Qt 在绘制控件时，把控件类型、objectName、属性、伪状态（hover、checked、pressed、disabled 等）和样式表匹配，命中的声明块逐条生效。常用选择器：

2.2 setStyleSheet 的作用域

app.setStyleSheet(qss) 是应用级样式：整棵控件树生效，子控件可以覆盖但默认继承。相比每个控件各自 setStyleSheet，应用级样式的好处是单一数据源——改一处，全局变。

2.3 调色板：Catppuccin Mocha 风格

dark.qss 用了一套低饱和、高对比的暗色调色板：

#mermaid-svg-mI9ixMPkszKWL1w1{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-mI9ixMPkszKWL1w1 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-mI9ixMPkszKWL1w1 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-mI9ixMPkszKWL1w1 .error-icon{fill:#552222;}#mermaid-svg-mI9ixMPkszKWL1w1 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-mI9ixMPkszKWL1w1 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-mI9ixMPkszKWL1w1 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-mI9ixMPkszKWL1w1 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-mI9ixMPkszKWL1w1 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-mI9ixMPkszKWL1w1 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-mI9ixMPkszKWL1w1 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-mI9ixMPkszKWL1w1 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-mI9ixMPkszKWL1w1 .marker.cross{stroke:#333333;}#mermaid-svg-mI9ixMPkszKWL1w1 svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-mI9ixMPkszKWL1w1 p{margin:0;}#mermaid-svg-mI9ixMPkszKWL1w1 .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-mI9ixMPkszKWL1w1 .cluster-label text{fill:#333;}#mermaid-svg-mI9ixMPkszKWL1w1 .cluster-label span{color:#333;}#mermaid-svg-mI9ixMPkszKWL1w1 .cluster-label span p{background-color:transparent;}#mermaid-svg-mI9ixMPkszKWL1w1 .label text,#mermaid-svg-mI9ixMPkszKWL1w1 span{fill:#333;color:#333;}#mermaid-svg-mI9ixMPkszKWL1w1 .node rect,#mermaid-svg-mI9ixMPkszKWL1w1 .node circle,#mermaid-svg-mI9ixMPkszKWL1w1 .node ellipse,#mermaid-svg-mI9ixMPkszKWL1w1 .node polygon,#mermaid-svg-mI9ixMPkszKWL1w1 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-mI9ixMPkszKWL1w1 .rough-node .label text,#mermaid-svg-mI9ixMPkszKWL1w1 .node .label text,#mermaid-svg-mI9ixMPkszKWL1w1 .image-shape .label,#mermaid-svg-mI9ixMPkszKWL1w1 .icon-shape .label{text-anchor:middle;}#mermaid-svg-mI9ixMPkszKWL1w1 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-mI9ixMPkszKWL1w1 .rough-node .label,#mermaid-svg-mI9ixMPkszKWL1w1 .node .label,#mermaid-svg-mI9ixMPkszKWL1w1 .image-shape .label,#mermaid-svg-mI9ixMPkszKWL1w1 .icon-shape .label{text-align:center;}#mermaid-svg-mI9ixMPkszKWL1w1 .node.clickable{cursor:pointer;}#mermaid-svg-mI9ixMPkszKWL1w1 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-mI9ixMPkszKWL1w1 .arrowheadPath{fill:#333333;}#mermaid-svg-mI9ixMPkszKWL1w1 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-mI9ixMPkszKWL1w1 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-mI9ixMPkszKWL1w1 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-mI9ixMPkszKWL1w1 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-mI9ixMPkszKWL1w1 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-mI9ixMPkszKWL1w1 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-mI9ixMPkszKWL1w1 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-mI9ixMPkszKWL1w1 .cluster text{fill:#333;}#mermaid-svg-mI9ixMPkszKWL1w1 .cluster span{color:#333;}#mermaid-svg-mI9ixMPkszKWL1w1 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-mI9ixMPkszKWL1w1 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-mI9ixMPkszKWL1w1 rect.text{fill:none;stroke-width:0;}#mermaid-svg-mI9ixMPkszKWL1w1 .icon-shape,#mermaid-svg-mI9ixMPkszKWL1w1 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-mI9ixMPkszKWL1w1 .icon-shape p,#mermaid-svg-mI9ixMPkszKWL1w1 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-mI9ixMPkszKWL1w1 .icon-shape .label rect,#mermaid-svg-mI9ixMPkszKWL1w1 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-mI9ixMPkszKWL1w1 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-mI9ixMPkszKWL1w1 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-mI9ixMPkszKWL1w1 :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

类型选择器

objectName 选择器

伪状态

QApplication.setStyleSheet

QSS 样式表全局注册

控件绘制时匹配

QPushButton 等

#Sidebar / #Header / #ContentArea

:hover / :checked / :disabled

按对象树继承生效

三、代码实现

3.1 ThemeManager：整个主题层只有 19 行

"""主题管理器 — 加载并应用QSS暗黑主题"""
import os
from PySide6.QtWidgets import QApplication

class ThemeManager:
"""管理应用主题（暗黑优先）"""

DARK_QSS_PATH = os.path.join(os.path.dirname(__file__), "dark.qss")

def apply_theme(self, app: QApplication):
"""加载dark.qss并应用到QApplication"""
try:
with open(self.DARK_QSS_PATH, "r", encoding="utf-8") as f:
qss = f.read()
app.setStyleSheet(qss)
except FileNotFoundError:
pass # 主题文件不存在时使用默认样式

源码位置：ui/theme/theme_manager.py L1-L19

四个细节值得记住：

3.2 应用启动时的一次性注入

# 加载暗黑主题
self.theme_manager = ThemeManager()
self.theme_manager.apply_theme(self)

源码位置：app/application.py L45-L47

主题在 MainWindow 创建之前加载，保证窗口一出现就是暗色，没有"先亮后暗"的闪烁。

3.3 全局样式与侧边栏样式节选

/* — 全局 — */
QWidget {
background-color: #1e1e2e;
color: #cdd6f4;
font-family: "Microsoft YaHei UI", "Segoe UI", sans-serif;
font-size: 14px;
}

/* — 侧边栏 — */
#Sidebar {
background-color: #181825;
border-right: 1px solid #313244;
}

#Sidebar QPushButton {
text-align: left;
padding: 12px 20px;
border: none;
border-radius: 6px;
color: #a6adc8;
background: transparent;
font-size: 14px;
}

#Sidebar QPushButton:hover {
background-color: #313244;
color: #cdd6f4;
}

#Sidebar QPushButton:checked {
background-color: #45475a;
color: #89b4fa;
border-left: 3px solid #89b4fa;
}

源码位置：ui/theme/dark.qss L6-L43

这段是 QSS 层次设计的教科书：全局 QWidget 兜底字体和底色；#Sidebar 划定区域；#Sidebar QPushButton 用后代选择器统一导航按钮；hover/checked 伪状态给出交互反馈，选中态用左侧 3px 高亮条提示当前位置。

3.4 主按钮与输入框的高光细节

QPushButton#PrimaryButton {
background-color: #89b4fa;
color: #1e1e2e;
border: none;
font-weight: bold;
}

QLineEdit:focus, QTextEdit:focus, QPlainTextEdit:focus, QComboBox:focus {
border-color: #89b4fa;
}

源码位置：ui/theme/dark.qss L147-L156、L167-L169

聚焦态统一用强调色描边，用户"光标在哪"一目了然——暗色主题里，边框是比阴影更可靠的层级信号。

MainWindowThemeManagerApplication(QApplication)main.pyMainWindowThemeManagerApplication(QApplication)main.py#mermaid-svg-CrZ0AFlUAl3DkwjZ{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-CrZ0AFlUAl3DkwjZ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .error-icon{fill:#552222;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .marker.cross{stroke:#333333;}#mermaid-svg-CrZ0AFlUAl3DkwjZ svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-CrZ0AFlUAl3DkwjZ p{margin:0;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-CrZ0AFlUAl3DkwjZ text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-CrZ0AFlUAl3DkwjZ .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-CrZ0AFlUAl3DkwjZ #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .sequenceNumber{fill:white;}#mermaid-svg-CrZ0AFlUAl3DkwjZ #sequencenumber{fill:#333;}#mermaid-svg-CrZ0AFlUAl3DkwjZ #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .messageText{fill:#333;stroke:none;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .labelText,#mermaid-svg-CrZ0AFlUAl3DkwjZ .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .loopText,#mermaid-svg-CrZ0AFlUAl3DkwjZ .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-CrZ0AFlUAl3DkwjZ .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .noteText,#mermaid-svg-CrZ0AFlUAl3DkwjZ .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .actorPopupMenu{position:absolute;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-CrZ0AFlUAl3DkwjZ .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-CrZ0AFlUAl3DkwjZ .actor-man circle,#mermaid-svg-CrZ0AFlUAl3DkwjZ line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-CrZ0AFlUAl3DkwjZ :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}样式表注册到整棵控件树窗口绘制时按 QSS 渲染暗色Application(argv)theme_manager.apply_theme(self)读 dark.qss (utf-8)app.setStyleSheet(qss)MainWindow() + show()

四、设计权衡 / 踩坑记录

4.1 为什么不在每个控件内联 setStyleSheet

代码库里确实存在内联样式（如 StatCard 的 self.setStyleSheet(f"…")，见 dashboard_page.py），但只用于动态拼色（统计卡片的数值颜色随状态变化）。其余静态样式全部收敛到 QSS。这条分界线是刻意的：静态样式进主题文件，动态样式才进代码。

4.2 权衡：单主题暗黑优先，而非亮/暗双主题

任务标题写"亮/暗色切换"，但当前版本是"暗黑优先"单主题。这是有意的取舍：

• 教育类工具面向长时间盯屏场景，暗色降低视觉疲劳；
• 单主题省去"双主题回归测试"与"动态切换时的控件重建"成本；
• 架构上已留好扩展位：ThemeManager 只要再加一个 LIGHT_QSS_PATH 和 apply_theme(app, name) 即可支持切换，QSS 全量集中是前提。

4.3 坑：字体族与打包路径

QSS 里写了 font-family: "Microsoft YaHei UI"，但 Windows 各版本字体名有差异（Microsoft YaHei vs Microsoft YaHei UI），所以写了备选 "Segoe UI", sans-serif。另外 DARK_QSS_PATH 基于 __file__ 定位，PyInstaller 打包后 __file__ 指向 _internal 下的实际路径，配合打包配置能正常找到 dark.qss——这也是为什么主题文件必须与应用代码同目录打包。

4.4 权衡：为什么用 QSS 而不是 QPalette

Qt 官方推荐 QPalette 做深色模式（能跟随系统），但 QPalette 对"圆角、内边距、边框线"这类细节无能为力。教育工具需要卡片圆角、表格斑马纹、滚动条细条化这些视觉定制，QSS 的表达力远超调色板。代价是渲染路径稍重，但对桌面应用毫无感知。

五、小结

• ThemeManager 只做一件事：读 dark.qss → app.setStyleSheet()，全部 19 行；
• QSS 用"类型 + objectName + 伪状态"选择器批量套样式，暗黑调色板（Catppuccin 风格）集中维护；
• 主题文件与代码同目录、__file__ 定位，兼顾源码运行与打包部署；utf-8 显式声明避免中文注释出错；
• 单主题暗黑优先是当前取舍，ThemeManager 的结构天然支持未来扩展亮色主题；
• 静态样式进 QSS、动态样式留代码，是代码库里两条并行不悖的样式路径。