PySide6带复选框的多选QComboBox开发问题求助

问题概述 #

开发支持多选的自定义QComboBox时遇到两个核心问题：

• 下拉列表内复选框与选项文本视觉重叠
• 勾选选项后，组合框主显示区域未更新选中项，始终显示占位文本

原实现代码 #

import sys
from PySide6.QtCore import Qt, QEvent, QTimer
from PySide6.QtGui import QIcon
from PySide6.QtWidgets import QComboBox, QListView, QStyledItemDelegate, QApplication, QStyle, QStyleOptionViewItem, QStyleOptionComboBox, QStylePainter


class CheckComboBox(QComboBox):
    """
    A QComboBox allowing multiple item selection.
    """

    class ComboItemDelegate(QStyledItemDelegate):
        """
        Helper styled delegate to draw checkboxes and item text properly, avoiding overlap.
        """

        def paint(self, painter, option, index):
            style = option.widget.style() if option.widget is not None else QApplication.style()

            option = QStyleOptionViewItem(option)
            option.showDecorationSelected = True

            # Get the rectangle for the checkbox
            check_rect = style.subElementRect(QStyle.SE_ItemViewItemCheckIndicator, option, None)

            # Adjust the text rectangle so it doesn't overlap with the checkbox
            option.rect.setLeft(check_rect.right() + 5)

            # Draw the item (checkbox + text)
            super(CheckComboBox.ComboItemDelegate, self).paint(painter, option, index)

    def __init__(self, parent=None, placeholderText="", separator=", ", **kwargs):
        super(CheckComboBox, self).__init__(parent, **kwargs)
        self.setFocusPolicy(Qt.StrongFocus)
        self.__popupIsShown = False
        self.__blockMouseReleaseTimer = QTimer(self, singleShot=True)
        self.__initialMousePos = None
        self.__separator = separator
        self.__placeholderText = placeholderText
        self.setView(QListView())  # Use QListView for the combo box drop-down
        self.__updateItemDelegate()
        self.update_checked_items()  # Ensure the placeholder text is initially set

    def mousePressEvent(self, event):
        """Reimplemented."""
        self.__popupIsShown = False
        super(CheckComboBox, self).mousePressEvent(event)
        if self.__popupIsShown:
            self.__initialMousePos = event.globalPosition().toPoint()
            self.__blockMouseReleaseTimer.start(QApplication.doubleClickInterval())

    def showPopup(self):
        """Reimplemented."""
        super(CheckComboBox, self).showPopup()
        view = self.view()
        view.installEventFilter(self)
        view.viewport().installEventFilter(self)
        self.__popupIsShown = True

    def hidePopup(self):
        """Reimplemented."""
        self.view().removeEventFilter(self)
        self.view().viewport().removeEventFilter(self)
        self.__popupIsShown = False
        self.__initialMousePos = None
        super(CheckComboBox, self).hidePopup()
        self.view().clearFocus()

    def eventFilter(self, obj, event):
        """Reimplemented."""
        if self.__popupIsShown and event.type() == QEvent.MouseButtonRelease:
            model = self.model()
            index = self.view().currentIndex()
            state = model.data(index, Qt.CheckStateRole)
            model.setData(index, Qt.Checked if state == Qt.Unchecked else Qt.Unchecked, Qt.CheckStateRole)
            self.view().update(index)
            self.update_checked_items()  # Update the combo box text when the state changes
            return True
        return super(CheckComboBox, self).eventFilter(obj, event)

    def update_checked_items(self):
        """Update the combo box display with selected items or placeholder text."""
        checked = self.checkedIndices()
        if checked:
            items = [self.itemText(i) for i in checked]
            self.setCurrentText(self.__separator.join(items))
        else:
            self.setCurrentText(self.__placeholderText)

    def paintEvent(self, event):
        """Reimplemented."""
        painter = QStylePainter(self)
        option = QStyleOptionComboBox()
        self.initStyleOption(option)
        painter.drawComplexControl(QStyle.CC_ComboBox, option)
        checked = self.checkedIndices()
        if checked:
            items = [self.itemText(i) for i in checked]
            option.currentText = self.__separator.join(items)
        else:
            option.currentText = self.__placeholderText
        option.currentIcon = QIcon()
        painter.drawControl(QStyle.CE_ComboBoxLabel, option)

    def itemCheckState(self, index):
        """
        Return the check state for item at `index`.
        """
        state = self.itemData(index, role=Qt.CheckStateRole)
        if isinstance(state, int):
            return Qt.CheckState(state)
        return Qt.Unchecked

    def setItemCheckState(self, index, state):
        """
        Set the check state for item at `index` to `state`.
        """
        self.setItemData(index, state, Qt.CheckStateRole)

    def checkedIndices(self):
        """
        Return a list of indices of all checked items.
        """
        return [i for i in range(self.count()) if self.itemCheckState(i) == Qt.Checked]

    def setPlaceholderText(self, text):
        """
        Set the placeholder text.
        """
        if self.__placeholderText != text:
            self.__placeholderText = text
            self.update_checked_items()

    def placeholderText(self):
        """
        Return the placeholder text.
        """
        return self.__placeholderText

    def wheelEvent(self, event):
        """Reimplemented."""
        event.ignore()

    def __updateItemDelegate(self):
        self.setItemDelegate(CheckComboBox.ComboItemDelegate(self))


def example():
    app = QApplication(list(sys.argv))
    cb = CheckComboBox(placeholderText="Select Me")
    model = cb.model()
    cb.addItem("First")
    cb.setItemCheckState(0, Qt.Unchecked)
    cb.addItem("Second")
    cb.setItemCheckState(1, Qt.Unchecked)
    cb.addItem("Third")
    cb.setItemCheckState(2, Qt.Unchecked)
    cb.show()
    cb.raise_()
    return app.exec()


if __name__ == "__main__":
    sys.exit(example())

具体修复步骤 #

1. 修复复选框与文本重叠问题 #

原委托的paint方法错误地修改了整个Item的绘制区域，导致复选框和文本的布局混乱。正确做法是单独绘制复选框和文本，手动调整文本区域避开复选框：

class ComboItemDelegate(QStyledItemDelegate):
    def paint(self, painter, option, index):
        style = option.widget.style() if option.widget else QApplication.style()
        opt = QStyleOptionViewItem(option)
        self.initStyleOption(opt, index)

        # 绘制Item背景（保留原有选中样式）
        style.drawPrimitive(QStyle.PE_PanelItemViewItem, opt, painter, option.widget)

        # 获取复选框区域并绘制
        check_rect = style.subElementRect(QStyle.SE_ItemViewItemCheckIndicator, opt, option.widget)
        check_state = index.data(Qt.CheckStateRole) or Qt.Unchecked
        opt.state |= QStyle.State_On if check_state == Qt.Checked else QStyle.State_Off
        style.drawPrimitive(QStyle.PE_IndicatorItemViewCheck, opt, painter, option.widget)

        # 调整文本区域，与复选框保持间距
        text_rect = opt.rect
        text_rect.setLeft(check_rect.right() + 8)

        # 绘制Item文本
        style.drawItemText(painter, text_rect, Qt.AlignLeft | Qt.AlignVCenter,
                           option.widget.palette(), option.widget.isEnabled(),
                           opt.text, QPalette.Text)

2. 修复显示区域不更新问题 #

原update_checked_items调用setCurrentText会触发QComboBox内部状态变更，干扰自定义的paintEvent逻辑。只需直接触发重绘即可，因为paintEvent已经会根据选中项生成显示文本：

def update_checked_items(self):
    """Update the combo box display with selected items or placeholder text."""
    self.update()  # 直接触发重绘，paintEvent会处理文本显示

同时，在手动修改选中状态时也要触发更新：

def setItemCheckState(self, index, state):
    self.setItemData(index, state, Qt.CheckStateRole)
    self.update_checked_items()  # 触发界面刷新

完整修复后的代码 #

import sys
from PySide6.QtCore import Qt, QEvent, QTimer
from PySide6.QtGui import QIcon, QPalette
from PySide6.QtWidgets import QComboBox, QListView, QStyledItemDelegate, QApplication, QStyle, QStyleOptionViewItem, QStyleOptionComboBox, QStylePainter


class CheckComboBox(QComboBox):
    """
    A QComboBox allowing multiple item selection.
    """

    class ComboItemDelegate(QStyledItemDelegate):
        """
        Helper styled delegate to draw checkboxes and item text properly, avoiding overlap.
        """

        def paint(self, painter, option, index):
            style = option.widget.style() if option.widget else QApplication.style()
            opt = QStyleOptionViewItem(option)
            self.initStyleOption(opt, index)

            # Draw item background
            style.drawPrimitive(QStyle.PE_PanelItemViewItem, opt, painter, option.widget)

            # Get checkbox rect and draw it
            check_rect = style.subElementRect(QStyle.SE_ItemViewItemCheckIndicator, opt, option.widget)
            check_state = index.data(Qt.CheckStateRole) or Qt.Unchecked
            opt.state |= QStyle.State_On if check_state == Qt.Checked else QStyle.State_Off
            style.drawPrimitive(QStyle.PE_IndicatorItemViewCheck, opt, painter, option.widget)

            # Adjust text rect to avoid checkbox overlap
            text_rect = opt.rect
            text_rect.setLeft(check_rect.right() + 8)

            # Draw item text
            style.drawItemText(painter, text_rect, Qt.AlignLeft | Qt.AlignVCenter,
                               option.widget.palette(), option.widget.isEnabled(),
                               opt.text, QPalette.Text)

    def __init__(self, parent=None, placeholderText="", separator=", ", **kwargs):
        super(CheckComboBox, self).__init__(parent, **kwargs)
        self.setFocusPolicy(Qt.StrongFocus)
        self.__popupIsShown = False
        self.__blockMouseReleaseTimer = QTimer(self, singleShot=True)
        self.__initialMousePos = None
        self.__separator = separator
        self.__placeholderText = placeholderText
        self.setView(QListView())
        self.__updateItemDelegate()
        self.update_checked_items()

    def mousePressEvent(self, event):
        self.__popupIsShown = False
        super(CheckComboBox, self).mousePressEvent(event)
        if self.__popupIsShown:
            self.__initialMousePos = event.globalPosition().toPoint()
            self.__blockMouseReleaseTimer.start(QApplication.doubleClickInterval())

    def showPopup(self):
        super(CheckComboBox, self).showPopup()
        view = self.view()
        view.installEventFilter(self)
        view.viewport().installEventFilter(self)
        self.__popupIsShown = True

    def hidePopup(self):
        self.view().removeEventFilter(self)
        self.view().viewport().removeEventFilter(self)
        self.__popupIsShown = False
        self.__initialMousePos = None
        super(CheckComboBox, self).hidePopup()
        self.view().clearFocus()

    def eventFilter(self, obj, event):
        if self.__popupIsShown and event.type() == QEvent.MouseButtonRelease:
            model = self.model()
            index = self.view().currentIndex()
            if index.isValid():
                state = model.data(index, Qt.CheckStateRole) or Qt.Unchecked
                new_state = Qt.Checked if state == Qt.Unchecked else Qt.Unchecked
                model.setData(index, new_state, Qt.CheckStateRole)
                self.view().update(index)
                self.update_checked_items()
            return True
        return super(CheckComboBox, self).eventFilter(obj, event)

    def update_checked_items(self):
        """Update the combo box display with selected items or placeholder text."""
        self.update()

    def paintEvent(self, event):
        painter = QStylePainter(self)
        option = QStyleOptionComboBox()
        self.initStyleOption(option)
        painter.drawComplexControl(QStyle.CC_ComboBox, option)

        # Generate display text
        checked = self.checkedIndices()
        if checked:
            items = [self.itemText(i) for i in checked]
            display_text = self.__separator.join(items)
        else:
            display_text = self.__placeholderText

        option.currentText = display_text
        option.currentIcon = QIcon()
        painter.drawControl(QStyle.CE_ComboBoxLabel, option)

    def itemCheckState(self, index):
        state = self.itemData(index, role=Qt.CheckStateRole)
        if isinstance(state, int):
            return Qt.CheckState(state)
        return Qt.Unchecked

    def setItemCheckState(self, index, state):
        self.setItemData(index, state, Qt.CheckStateRole)
        self.update_checked_items()

    def checkedIndices(self):
        return [i for i in range(self.count()) if self.itemCheckState(i) == Qt.Checked]

    def setPlaceholderText(self, text):
        if self.__placeholderText != text:
            self.__placeholderText = text
            self.update_checked_items()

    def placeholderText(self):
        return self.__placeholderText

    def wheelEvent(self, event):
        event.ignore()

    def __updateItemDelegate(self):
        self.setItemDelegate(CheckComboBox.ComboItemDelegate(self))


def example():
    app = QApplication(list(sys.argv))
    cb = CheckComboBox(placeholderText="Select Me")
    cb.addItem("First")
    cb.setItemCheckState(0, Qt.Unchecked)
    cb.addItem("Second")
    cb.setItemCheckState(1, Qt.Unchecked)
    cb.addItem("Third")
    cb.setItemCheckState(2, Qt.Unchecked)
    cb.show()
    cb.raise_()
    return app.exec()


if __name__ == "__main__":
    sys.exit(example())

修复效果验证 #

• 下拉列表中复选框与文本完全分离，无重叠
• 勾选/取消勾选选项时，组合框主显示区域实时更新为选中项拼接文本，未选中时显示占位文本

内容的提问来源于stack exchange，提问作者Sahal