Qt-Material 项目：为 PyQt/PySide 应用添加 Material Design 风格

项目概述

Qt-Material 是一个为 PySide6、PySide2、PyQt5 和 PyQt6 提供 Material Design 风格样式表的项目。它可以让你的 Qt 应用界面获得类似 Google Material Design 的现代化视觉效果，包括丰富的颜色主题、动画效果和一致的 UI 元素设计。

核心功能

1. 多种预设主题：提供 19 种内置主题（9 种深色和 10 种浅色）
2. 自定义主题支持：可以创建和使用自己的颜色主题
3. 运行时主题切换：支持应用运行期间动态更换主题
4. 密度缩放：调整 UI 元素的紧凑程度
5. 特殊按钮样式：提供危险、警告、成功等特殊状态按钮
6. 字体自定义：可修改应用的默认字体

安装与基本使用

安装非常简单，只需使用 pip 命令：

pip install qt-material

基本使用示例：

import sys
from PySide6 import QtWidgets
from qt_material import apply_stylesheet

app = QtWidgets.QApplication(sys.argv)
window = QtWidgets.QMainWindow()

# 应用深色蓝绿色主题
apply_stylesheet(app, theme='dark_teal.xml')

window.show()
app.exec_()

主题系统

查看可用主题

from qt_material import list_themes

print(list_themes())

输出示例：

['dark_amber.xml', 'dark_blue.xml', 'dark_cyan.xml', ..., 'light_teal.xml', 'light_yellow.xml']

创建自定义主题

1. 使用 [Material Design 颜色工具] 选择配色方案
2. 导出为 Android XML 格式
3. 保存为 .xml 文件
4. 在代码中引用自定义主题文件

示例主题文件格式：

<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>

高级功能

特殊按钮样式

extra = {
    'danger': '#dc3545',    # 红色危险按钮
    'warning': '#ffc107',   # 黄色警告按钮
    'success': '#17a2b8',   # 绿色成功按钮
    'font_family': 'Roboto' # 自定义字体
}

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

使用特殊按钮样式：

button.setProperty('class', 'danger')  # 设置为危险按钮

自定义样式表

可以创建自定义 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')

运行时主题切换

继承 QtStyleTools 类实现运行时主题切换：

from qt_material import QtStyleTools

class MainWindow(QMainWindow, QtStyleTools):
    def __init__(self):
        super().__init__()
        # 初始化UI...
        self.apply_stylesheet(self, 'dark_teal.xml')

导出主题

可以将主题导出为独立的 QSS 和资源文件，用于非 Python 环境：

from qt_material import export_theme

export_theme(
    theme='dark_teal.xml',
    qss='dark_teal.qss',
    rcc='resources.rcc',
    output='theme',
    prefix='icon:/',
    extra={'font_family': 'monoespace', 'density_scale': '0'}
)

密度缩放

通过 density_scale 参数调整 UI 元素的紧凑程度：

extra = {'density_scale': '-2'}  # 值范围通常为 -3 到 +3
apply_stylesheet(app, 'default', extra=extra)

常见问题

QMenu 样式问题

不同 Qt 后端和操作系统对 QMenu 的渲染方式不同，可以通过额外参数调整：

extra['QMenu'] = {
    'height': 50,
    'padding': '50px 50px 50px 50px'  # 上、右、下、左
}

最佳实践

1. 导入顺序：确保在导入 PyQt/PySide 之后再导入 qt_material
2. 主题预览：使用示例程序预览所有主题效果
3. 自定义主题：从现有主题开始修改，逐步调整颜色
4. 性能考虑：复杂的自定义样式可能会影响界面响应速度

Qt-Material 为 Python Qt 应用提供了简单而强大的 Material Design 实现方式，通过灵活的配置选项，开发者可以轻松创建美观、现代的应用程序界面。