Qt-Material 使用指南:为 PySide2/PySide6/PyQt5/PyQt6 应用一键套上 Material Design 皮肤

原创2026-10-14 22:16:081,460 阅读
文章标签:UI组件桌面应用设计系统

Qt-Material 使用指南:为 PySide2/PySide6/PyQt5/PyQt6 应用一键套上 Material Design 皮肤

Qt-Material 是一款面向 PySide6、PySide2、PyQt5 与 PyQt6 的 Material Design 风格 QSS 样式库:只需调用一个函数,即可让整个 Qt 应用获得接近 Google Material Design 规范的外观,并支持运行时换肤、主题导出、密度调节等进阶能力。本文将基于官方 README 与仓库源码,从安装、基础用法、主题体系、自定义扩展、运行时换肤、主题导出到常见问题排查,为你提供一份可直接落地的完整实践指南。

安装与前置条件

安装方式与绝大多数 Python 包一致:

pip install qt-material

从仓库的 setup.py 可以看到项目的运行时依赖只有一个 Jinja2,Python 要求不低于 3.7;样式表正是通过 Jinja2 模板渲染生成的(见下文“样式表是如何生成的”)。安装后,包内自带了 Roboto 字体族(见 qt_material/fonts/roboto,含 Regular、Bold、Italic、Condensed 等 16 个 .ttf 文件)、18 个预置主题 XML、一套 SVG 图标源文件以及样式模板 qt_material/material.css.template。

需要注意导入顺序:qt_material 必须在 PySide 或 PyQt 之后导入。仓库源码 qt_material/init.py 会在导入时检测 sys.modules 中是否已存在 PySide2/PySide6/PyQt5/PyQt6;如果四个 Qt 绑定都未导入,模块会打印警告 qt_material must be imported after PySide or PyQt!,且 GUI 相关能力(如字体注册、图标路径注入)会被关闭。

快速上手:三行代码应用主题

创建一个窗口并应用主题的最小示例:

import sys
from PySide6 import QtWidgets
# from PySide2 import QtWidgets
# from PyQt5 import QtWidgets
from qt_material import apply_stylesheet

# create the application and the main window
app = QtWidgets.QApplication(sys.argv)
window = QtWidgets.QMainWindow()

# setup stylesheet
apply_stylesheet(app, theme='dark_teal.xml')

# run
window.show()
app.exec_()

核心 API 是 apply_stylesheet(app, theme=..., ...),其完整签名(qt_material/init.py)为:

apply_stylesheet(app, theme='', style=None, save_as=None,
                 invert_secondary=False, extra={}, parent='theme',
                 css_file=None)

各参数作用如下:

参数 说明
app QApplication(或任意 QWidget,例如运行时换肤时的主窗口)
theme 主题文件,可以是内置主题名(如 dark_teal.xml),也可以是 default / default_dark / default_light 等快捷别名或本地 XML 路径
style 可选的 Qt 基础样式(如 Fusion),通过 app.setStyle(style) 设置
save_as 将渲染出的样式表写入指定文件
invert_secondary 浅色主题专用,交换次要色的亮/暗版本
extra 附加配置字典(强调色、字体、密度等,后文详述)
parent 生成主题图标资源的输出目录(默认 theme)
css_file 追加的自定义 QSS 文件,支持 {QTMATERIAL_XXX} 环境变量占位符

主题的渲染流程在 build_stylesheet()(qt_material/init.py)中完成:先解析主题 XML 并注册字体,再调用 set_icons_theme() 生成与主题色匹配的 SVG 图标,最后用 Jinja2 渲染 material.css.template 得到最终样式表。每次应用主题时图标都会被按当前主题色重新生成——这也解释了为什么主题切换如此“无缝”。

内置主题一览

库内置了 18 个主题 XML,存放在 qt_material/themes。可以用 list_themes() 直接获取完整列表:

from qt_material import list_themes

list_themes()

输出:

['dark_amber.xml',
 'dark_blue.xml',
 'dark_cyan.xml',
 'dark_lightgreen.xml',
 'dark_pink.xml',
 'dark_purple.xml',
 'dark_red.xml',
 'dark_teal.xml',
 'dark_yellow.xml',
 'light_amber.xml',
 'light_blue.xml',
 'light_cyan.xml',
 'light_cyan_500.xml',
 'light_lightgreen.xml',
 'light_pink.xml',
 'light_purple.xml',
 'light_red.xml',
 'light_teal.xml',
 'light_yellow.xml']

可以看到主题分深色(dark_*)与浅色(light_*)两族,此外还有若干带 _500 后缀的变体(如 light_cyan_500.xml、light_blue_500.xml),对应 Material Design 色板的 500 号色阶。list_themes() 的源码实现(qt_material/init.py)就是列出 themes 目录下所有以 .xml 结尾的文件并排序,因此你也可以把自建主题 XML 放进该目录参与枚举。

theme 参数还支持三个快捷别名,其映射关系定义在 get_theme()(qt_material/init.py)中:

  • default_dark / default_dark.xml → 映射到 dark_teal.xml;
  • default_light / default_light.xml / default.xml / default → 映射到 light_cyan_500.xml,并自动设置 invert_secondary=True。

如果传入的字符串是一个已存在的文件路径,则直接按自定义主题文件解析;否则在包内 themes 目录下查找。主题文件不存在时会打印警告并返回 None,apply_stylesheet 检测到空结果会直接返回,不会破坏现有样式。

自定义颜色:从 Material Color Tool 到主题文件

每个主题就是一个 Android 风格 XML 资源文件,包含 7 个颜色条目:

<!--?xml version="1.0" encoding="UTF-8"?-->
<resources>
<color name="primaryColor">#00e5ff</color>
<color name="primaryLightColor">#6effff</color>
<color name="secondaryColor">#f5f5f5</color>
<color name="secondaryLightColor">#ffffff</color>
<color name="secondaryDarkColor">#e6e6e6</color>
<color name="primaryTextColor">#000000</color>
<color name="secondaryTextColor">#000000</color>
</resources>

参考仓库内置的 qt_material/themes/dark_teal.xml 与 qt_material/themes/light_red.xml,可以看到两种风格的典型取值差异:深色主题的 secondaryColor/secondaryDarkColor 是深灰系(如 #232629/#31363b),而浅色主题则是浅灰与白色系(如 #f5f5f5/#ffffff/#e6e6e6)。

各颜色条目的语义如下:

条目 语义
primaryColor 主色:按钮、选中态、输入框边框、Tab 高亮等强调元素
primaryLightColor 主色的亮版本:选中背景、悬停高亮
secondaryColor 次要色:菜单、弹层、正文背景
secondaryLightColor 次要色的亮版本:边框、分割线、禁用态
secondaryDarkColor 次要色的暗版本:窗口、控件底色
primaryTextColor 主色背景之上的文字颜色
secondaryTextColor 次要色背景之上的文字颜色

生成方式:访问 Material 官方 Color Tool,选择配色后导出为 Android XML 格式,把得到的内容保存成 my_theme.xml(放在当前工作目录即可),然后直接传入:

apply_stylesheet(app, theme='dark_teal.xml')

解析逻辑在 get_theme() 中:使用 xml.dom.minidom 读取文件,收集所有 <color> 标签的 name 与文本值,得到主题颜色字典;随后把 7 个颜色分别写入环境变量 QTMATERIAL_XXX(详见下文),并写入 QTMATERIAL_THEME。

浅色主题的 invert_secondary

浅色主题应用时需要额外传入 invert_secondary=True:

apply_stylesheet(app, theme='light_red.xml', invert_secondary=True)

原因同样在 get_theme() 中:浅色主题的 secondaryLightColor(亮)与 secondaryDarkColor(暗)需要交换,才能让背景、边框、控件底色在浅色模式下呈现正确对比。这个参数对深色主题没有影响。

环境变量:主题色的“只读镜像”

每次应用主题后,库会把当前主题色同步写入进程环境变量,仅供查询/引用,不建议修改:

环境变量 说明 示例
QTMATERIAL_PRIMARYCOLOR 主色 #2979ff
QTMATERIAL_PRIMARYLIGHTCOLOR 主色的亮版本 #75a7ff
QTMATERIAL_SECONDARYCOLOR 次要色 #f5f5f5
QTMATERIAL_SECONDARYLIGHTCOLOR 次要色的亮版本 #ffffff
QTMATERIAL_SECONDARYDARKCOLOR 次要色的暗版本 #e6e6e6
QTMATERIAL_PRIMARYTEXTCOLOR 主色背景上的文字色 #000000
QTMATERIAL_SECONDARYTEXTCOLOR 次要色背景上的文字色 #000000
QTMATERIAL_THEME 当前使用的主题名 light_blue.xml

这些变量的写入点在 qt_material/init.py。它们最重要的用途是在自定义 QSS 中以 {QTMATERIAL_PRIMARYCOLOR} 占位符引用主题色,让自定义样式自动跟随当前主题(见下文“自定义样式表”)。此外,样式模板本身也通过 os.environ 传递渲染变量,运行时动态换肤依赖这一机制。

强调色按钮与自定义字体

extra 字典允许注入强调色与字体配置:

extra = {

    # Button colors
    'danger': '#dc3545',
    'warning': '#ffc107',
    'success': '#17a2b8',

    # Font
    'font_family': 'Roboto',
}

apply_stylesheet(app, 'light_cyan.xml', invert_secondary=True, extra=extra)

三种强调色作用于带对应 class 属性的 QPushButton:

pushButton_danger.setProperty('class', 'danger')
pushButton_warning.setProperty('class', 'warning')
pushButton_success.setProperty('class', 'success')

Qt-Material 强调色按钮示例(danger / warning / success)

在样式模板 qt_material/material.css.template 中,.danger、.warning、.success 类被定义为透明背景的彩色文字,并附带禁用态样式:禁用时颜色与边框变为 40% 透明度(opacity(0.4) 过滤器),flat 按钮禁用态背景为 10% 透明度。

extra 中可用的键与默认值(定义于 build_stylesheet,qt_material/init.py)整理如下:

extra 键 默认值 说明
danger #dc3545 danger 按钮强调色
warning #ffc107 warning 按钮强调色
success #17a2b8 success 按钮强调色
font_family Roboto 全局字体族,模板中作用于 * 选择器
font_size 未设置(模板默认 13px) 全局字号,参与密度计算
line_height 未设置(模板默认 13px) 全局行高,参与密度计算
density_scale 0 密度缩放系数(见下文)
button_shape default 按钮形状,可选 default(圆角 4px)或 rounded(胶囊形)

关于字体需要说明:仓库自带 Roboto 字族(qt_material/fonts/roboto),apply_stylesheet 在渲染前会通过 add_fonts()(qt_material/init.py)调用 QFontDatabase.addApplicationFont 将全部 .ttf 注册到 Qt 字体库。因此即便系统未安装 Roboto,指定 'font_family': 'Roboto' 也能正常生效;如果你想换用其他字体(例如运行时示例中的 Raleway),需要自行用 QFontDatabase.addApplicationFont('Raleway-Regular.ttf') 加载(见 examples/runtime/runtime.py)。

自定义样式表:扩展而非覆盖

库允许通过 css_file 参数在渲染好的样式表之后追加自定义 QSS,实现局部覆盖。先在项目目录编写 custom.css,注意使用双花括号转义、并用环境变量占位符引用主题色:

QPushButton {{
  color: {QTMATERIAL_SECONDARYCOLOR};
  text-transform: none;
  background-color: {QTMATERIAL_PRIMARYCOLOR};
}}

.big_button {{
  height: 64px;
}}

然后在应用主题时挂载:

apply_stylesheet(app, theme='light_blue.xml', css_file='custom.css')

自定义的类样式通过 setProperty 应用到控件:

self.main.pushButton.setProperty('class', 'big_button')

Qt-Material 自定义样式表效果(大按钮 big_button)

实现层面,apply_stylesheet(qt_material/init.py)会读取 css_file 内容并执行 .format(**os.environ),把 {QTMATERIAL_PRIMARYCOLOR} 等占位符替换为当前主题色,再拼接到完整样式表之后调用 app.setStyleSheet()。这正是上一节环境变量机制的关键应用。

样式表也可以完全在运行时手动追加:

stylesheet = app.styleSheet()
with open('custom.css') as file:
    app.setStyleSheet(stylesheet + file.read().format(**os.environ))

配套的完整可运行示例见 examples/runtime/custom_css.py(它演示了用 css_file='custom.css' 挂载自定义样式,并给按钮设置 big_button 类)与 examples/runtime/custom.css。

样式表是如何生成的

material.css.template 是一份约 1400 行的 Jinja2 模板(qt_material/material.css.template),覆盖了 QWidget、QPushButton、QLineEdit、QComboBox、QSpinBox、QTabBar、QMenu、QTableWidget、QProgressBar、QSlider、QCheckBox、QRadioButton 等几乎所有常用控件。模板中的关键渲染机制:

  • 颜色值直接以 {{primaryColor}} 等形式注入;
  • 自定义 Jinja2 过滤器 opacity(值) 把十六进制色转成带透明度的 rgba(...),用于悬停、禁用等状态(实现见 qt_material/init.py);
  • 过滤器 density(值, density_scale, border, scale, ...) 负责密度计算(实现见 qt_material/init.py),几乎每个控件的尺寸、内边距、行高都经过它换算;
  • 模板头部按环境变量注入字体族、字号、行高,并设置 selection-background-color 为 primaryLightColor、selection-color 为 primaryTextColor。

理解模板结构后,你可以直接阅读甚至复制 qt_material/material.css.template 作为自定义样式的参考基准。

运行完整示例与测试主题

仓库提供了一套覆盖几乎所有控件的演示窗口(官方截图见上文的 dark/light 主题演示),既可以预览全部主题,也适合现场调色创建新主题:

git clone https://github.com/UN-GCPDS/qt-material.git
cd qt-material
python setup.py install
cd examples/full_features
python main.py --pyside6

Qt-Material 深色主题全控件演示

examples/full_features/main.py 支持通过命令行参数选择 Qt 绑定:--pyside2、--pyside6、--pyqt5、--pyqt6;不带参数则会提示必须在参数中包含其一。该示例展示了更多能力:

  • extra 默认配置(强调色、Roboto 字体、density_scale='0'、button_shape='default');
  • 继承 QtStyleTools 后调用 add_menu_theme(主题菜单)、add_menu_density(密度菜单)与 show_dock_theme(调色停靠面板);
  • 使用 qt_material:/logo/logo.svg 等资源前缀加载仓库自带的 SVG 图标(assets/logo.svg);
  • 通过 QTimer 定时截图保存到 screenshots/ 目录,可批量生成各主题截图。

运行时换肤:QtStyleTools

qt_material.QtStyleTools 是一个必须与 QMainWindow 一同继承的混入类,用于在运行时通过 apply_stylesheet() 切换主题:

class RuntimeStylesheets(QMainWindow, QtStyleTools):

    def __init__(self):
        super().__init__()
        self.main = QUiLoader().load('main_window.ui', self)

        self.apply_stylesheet(self.main, 'dark_teal.xml')
        # self.apply_stylesheet(self.main, 'light_red.xml')
        # self.apply_stylesheet(self.main, 'light_blue.xml')

QtStyleTools 的完整实现位于 qt_material/init.py,其关键方法:

方法 用途
apply_stylesheet(parent, theme, invert_secondary, extra, callable_) 应用主题到指定控件;theme='default' 时清空样式表(恢复默认外观)
add_menu_theme(parent, menu) 向指定 QMenu 注入“主题切换”菜单项(含 default + 全部 18 个内置主题)
add_menu_density(parent, menu) 注入密度菜单,范围为 -3 到 3
show_dock_theme(parent) 显示调色停靠面板(qt_material/dock_theme.ui),可实时修改 7 个主题色
set_extra(extra) 设置运行时使用的 extra 配置(set_extra_colors 已废弃)
update_theme(parent) 将当前调色结果写入 my_theme.xml 并重新应用

把这三个运行时示例放在一起对比即可掌握完整用法:

注意 QtStyleTools 内部对所有 Qt 绑定 API 做了兼容处理(同时适配传统 camelCase 与 PySide6 的 snake_case, true_property 导入模式),因此同一份运行时代码在四个绑定下都能工作。

在菜单中集成主题切换

想要给项目加一个可切换全部默认主题的 stylesheets 菜单,只需在 __init__ 中调用 add_menu_theme:

class RuntimeStylesheets(QMainWindow, QtStyleTools):

    def __init__(self):
        super().__init__()
        self.main = QUiLoader().load('main_window.ui', self)

        self.add_menu_theme(self.main, self.main.menuStyles)

add_menu_theme(qt_material/init.py)会创建互斥的 QActionGroup,为 default 及 list_themes() 返回的每个主题生成一个可勾选的 QAction,默认勾选 default(即不启用任何样式);用户切换菜单项后触发 update_theme_event(qt_material/init.py),它会读取当前勾选的密度与主题,对 light_ 开头的主题自动设置 invert_secondary=True,并带着 extra_values 重新应用主题。

用调色面板创建新主题

show_dock_theme 提供一个可浮动的调色停靠面板,用于实时修改主题并在运行时创建新主题;修改结果可通过 update_theme 保存为当前目录下的 my_theme.xml:

class RuntimeStylesheets(QMainWindow, QtStyleTools):

    def __init__(self):
        super().__init__()
        self.main = QUiLoader().load('main_window.ui', self)

        self.show_dock_theme(self.main)

面板中每个颜色按钮都会打开 QColorDialog 取色(见 set_color,qt_material/init.py);勾选“light theme”复选框后点击保存,update_theme(qt_material/init.py)会把 7 个颜色写成标准的 my_theme.xml 并立即重新应用。注意该文件的写入路径是当前工作目录,方便直接复用。

导出主题:脱离 Python 也能使用

export_theme 可以把任意主题(含图标)导出为纯本地文件,供 Qt 应用只依赖本地资源使用,甚至用于非 Python 环境(如 C++):

from qt_material import export_theme

extra = {

    # Button colors
    'danger': '#dc3545',
    'warning': '#ffc107',
    'success': '#17a2b8',

    # Font
    'font_family': 'monoespace',
    'font_size': '13px',
    'line_height': '13px',

    # Density Scale
    'density_scale': '0',

    # environ
    'pyside6': True,
    'linux': True,

}

export_theme(theme='dark_teal.xml',
             qss='dark_teal.qss',
             rcc='resources.rcc',
             output='theme',
             prefix='icon:/',
             invert_secondary=False,
             extra=extra,
            )

执行后会生成三个产物:

  1. dark_teal.qss——渲染完成的样式表(源码中把模板里的 icon:/ 替换为 prefix 指定的前缀);
  2. resources.rcc——Qt 资源集合文件,按 prefix 与 file 两个 qresource 分组罗列图标与 qss;
  3. theme/ 目录——按当前主题色重绘的全部 SVG 图标,内含 disabled/、primary/ 两个子目录(生成逻辑见 qt_material/resources/generate.py 的 ResourseGenerator)。

导出物的目录结构可从 examples/exporter 直观看到:exporter.py 与 sss.py 是两个调用示例,dark_teal.qss、resources.rcc 与 theme/ 就是导出的成品。

导出的文件可以这样集成进一个独立的 PySide6 应用:

import sys

from PySide6 import QtWidgets
from PySide6.QtCore import QDir
from __feature__ import snake_case, true_property

# Create application
app = QtWidgets.QApplication(sys.argv)

# Load styles
with open('dark_teal.qss', 'r') as file:
    app.style_sheet = file.read()

# Load icons
QDir.add_search_path('icon', 'theme')

# App
window = QtWidgets.QMainWindow()
checkbox = QtWidgets.QCheckBox(window)
checkbox.text = 'CheckBox'
window.show()
app.exec()

关键点在于:qss 中所有图标引用都以 icon:/ 开头,因此需要 QDir.add_search_path('icon', 'theme') 把 theme 目录注册为 icon 搜索前缀。这套方案不依赖 qt-material 库本身,因此同样适用于 C++ 等非 Python 的 Qt 项目。

密度缩放:Density Scale

extra 支持通过 density_scale 整体调整控件的紧凑程度,默认值为 0:

extra = {

    # Density Scale
    'density_scale': '-2',
}

apply_stylesheet(app, 'default', invert_secondary=False, extra=extra)

其底层实现是模板中的 density 过滤器(qt_material/init.py):所有控件的尺寸/间距都会执行 value + (density_interval * density_scale) - border*2 的计算,其中不同控件使用不同的 density_interval(字号 1、行高 8、常规间距 4 等),最终值不低于下限 min_=4。因此正数让界面更宽松、负数更紧凑,并且对字号、行高、控件高度、内边距全局生效。

在运行时示例中,add_menu_density 会生成从 -3 到 3 共 7 档的密度菜单项(qt_material/init.py),与主题菜单联动——这正是 examples/full_features/main.py 中“密度”菜单的来源。

常见问题排查:QMenu 渲染差异

QMenu 在不同 Qt 后端、不同操作系统甚至不同基础样式(如 Fusion)下的渲染差异很大。为此 extra 专门支持 QMenu 参数来覆盖菜单项的高度与内边距;这些参数不参与密度缩放:

extra['QMenu'] = {
    'height': 50,
    'padding': '50px 50px 50px 50px',  # top, right, bottom, left
}

apply_stylesheet 在处理 extra 时(qt_material/init.py)会把 QMenu 字典展开为 qmenu_height 与 qmenu_padding 两个模板变量,并置 QMenu=True 作为模板条件开关;模板 qt_material/material.css.template 中 QMenu::item 的默认高度是 28|density(density_scale)px、内边距按不同绑定分支取值(PySide6/PyQt6 与 PyQt5 为 0px 24px 0px 8px,PySide2 为 0px 32px 0px 32px),一旦启用 QMenu 配置即改用你指定的值。

若你的应用菜单在不同平台上表现不一致,优先通过该参数固定菜单项尺寸,并针对目标平台分别测试。

小结

Qt-Material 把 Material Design 风格化繁为简:apply_stylesheet 一行接入,list_themes 一键枚举 18 套内置主题,extra 字典覆盖强调色/字体/密度/按钮形状,QtStyleTools 提供菜单换肤与实时调色面板,export_theme 则把整套主题固化为 qss + rcc + 图标目录,可脱离 Python 供任何 Qt 技术栈复用。建议从 examples/full_features/main.py 起步观察全貌,再结合 qt_material/init.py 与 qt_material/material.css.template 深入定制属于你自己的主题。

登录后查看全文
qt-material