[PyQt/qt_material] 解决 QComboBox 下拉列表过长且 setMaxVisibleItems 失效的问题

1. 问题描述

在使用 qt_material 对 PyQt/PySide 程序进行美化时，遇到以下异常行为：

• 场景：QComboBox 包含大量数据项（如 100+ 项）。
• 预期：通过 combo.setMaxVisibleItems(10) 限制下拉列表显示的高度，超出部分显示滚动条。
• 实际：下拉列表（Popup）忽略了最大显示项数的限制，直接铺满屏幕甚至超出屏幕高度。
• 尝试无效：
  • 设置 setMaxVisibleItems 无效。
  • 设置 CSS max-height 在某些情况下无效。
  • 通过 qt_material 的 extra 参数传入样式有时不生效（权重问题）。

2. 原因分析

此问题的根源在于 qt_material 强制使用了 Qt 的 Fusion 风格（app.setStyle('Fusion')）。

1. Fusion 风格特性：默认情况下，Fusion 风格将 QComboBox 的下拉列表视为 "Popup"（弹出菜单） 模式。
2. 渲染逻辑冲突：在 "Popup" 模式下，Qt 的底层绘制引擎倾向于利用屏幕所有可用空间来展开列表，从而忽略了 QComboBox 的 maxVisibleItems 属性以及 CSS 中的部分高度限制。
3. 为什么重启只加载 CSS 却正常？：如果不应用 qt_material (不切换到 Fusion)，程序默认使用系统风格（如 WindowsVista），系统风格通常严格遵守 maxVisibleItems，因此表现正常。

3. 解决方案

通过 QSS 属性 combobox-popup: 0; 强制改变 QComboBox 的渲染模式。

• combobox-popup: 0：告诉 Qt 样式引擎，不要将此下拉列表作为系统级的“弹窗菜单”处理，而是将其作为标准的 ListView 处理。这样它就会严格遵守盒模型（Box Model）和 maxVisibleItems 限制。

代码实现

由于 qt_material 内部样式生成的复杂性，直接通过 extra 参数注入有时会失败。最稳妥的方式是在应用主题后，手动追加样式补丁。

import sys
from PyQt5.QtWidgets import QApplication, QComboBox
from qt_material import apply_stylesheet

app = QApplication(sys.argv)

# 1. 应用 qt_material 主题
# 这步操作内部会执行 app.setStyle('Fusion')，导致下拉框高度失控
apply_stylesheet(app, theme='default.xml')

# 2. 定义修正样式（核心修复代码）
# combobox-popup: 0; 关闭弹窗模式，恢复对 setMaxVisibleItems 的支持
fix_style = """
QComboBox {
    combobox-popup: 0;
}
"""

# 3. 将修正样式追加到现有样式表中
# 注意：必须是追加 (+)，不能覆盖
app.setStyleSheet(app.styleSheet() + fix_style)

# --- 测试代码 ---
combo = QComboBox()
combo.addItems([f"Item {i}" for i in range(100)])

# 设置最大可见项数为 10
# 在应用 fix_style 后，此设置将正常生效
combo.setMaxVisibleItems(10)

combo.show()
sys.exit(app.exec_())

4. 关键点总结

• 失效原因：Fusion Style 默认开启了 combobox-popup: 1。
• 核心属性：combobox-popup: 0;。
• 最佳实践：不要完全依赖库的参数（如 extra），在样式表加载完毕后，手动追加（Append）特定补丁样式能确保最高的优先级和兼容性。