如何基于QStyledItemDelegate实现QListView原生风格的双行列表项绘制？

嗨，我明白你现在的困扰——作为Qt新手，要处理一堆状态标志和样式确实头疼，而且想保留QListView原生的选中、hover这些交互效果，同时实现双行文本显示对吧？其实不用从零重写所有绘制逻辑，我们可以利用Qt原生的initStyleOption来复用现有样式，只在上面叠加自定义的第二行内容，这样既能满足需求，又能保持原生的UI风格。

先说说你之前方法的问题：你先调用super().paint()让原生绘制整个item，包括你加了\n的DisplayRole，这时候原生的文本区域是按两行算的，但你再用style.subElementRect拿文本位置时，这个矩形是整个两行的区域，你手动拆分的位置就容易错位。而且这样原生绘制的第一行下面会有空行，再叠加第二行可能会有视觉重叠或者位置不对的情况。

接下来给你一个更原生的实现思路，核心是先让Qt绘制item的框架（背景、复选框、图标、选中效果），再自己控制两行文本的绘制，这样完全保留原生的交互状态，同时精准控制文本位置：

具体实现步骤（PySide6） #

首先我们定义自定义Delegate，重写paint和sizeHint方法：

from PySide6.QtWidgets import QStyledItemDelegate, QApplication, QStyle, QStyleOptionViewItem
from PySide6.QtCore import Qt, QModelIndex
from PySide6.QtGui import QPalette, QFontMetrics
import json
from datetime import datetime

# 辅助函数：字节数转可读格式
def bytes_to_readable(size):
    if size < 1024:
        return f"{size} B"
    elif size < 1024**2:
        return f"{size/1024:.1f} KB"
    elif size < 1024**3:
        return f"{size/1024**2:.1f} MB"
    else:
        return f"{size/1024**3:.1f} GB"

class CustomListDelegate(QStyledItemDelegate):
    def paint(self, painter, option, index):
        # 非第一列用原生绘制逻辑
        if index.column() != 0:
            super().paint(painter, option, index)
            return
        
        # 1. 初始化样式选项，拿到原生的所有状态（选中、hover、复选框状态等）
        opt = QStyleOptionViewItem(option)
        self.initStyleOption(opt, index)
        
        # 2. 保存原始的DisplayRole文本，清空opt.text，让原生只绘制框架（背景、复选框、图标）
        original_text = opt.text
        opt.text = ""
        style = QApplication.style() if opt.widget is None else opt.widget.style()
        style.drawControl(QStyle.CE_ItemViewItem, opt, painter, opt.widget)
        
        # 3. 计算文本绘制区域：拆分原生文本矩形为上下两行
        text_rect = style.subElementRect(QStyle.SE_ItemViewItemText, opt, opt.widget)
        font_metrics = QFontMetrics(opt.font)
        line_height = font_metrics.height()
        
        # 第一行矩形：对应原DisplayRole内容
        first_line_rect = text_rect.adjusted(0, 0, 0, -line_height)
        # 第二行矩形：对应自定义信息，加一点上下间距避免拥挤
        second_line_rect = text_rect.adjusted(0, line_height + 2, 0, 0)
        
        # 4. 绘制第一行文本（原生文件名）
        painter.save()
        # 根据item状态设置文本颜色：选中时用高亮文本色，保持原生风格
        if opt.state & QStyle.State_Selected:
            painter.setPen(opt.palette.color(QPalette.HighlightedText))
        else:
            painter.setPen(opt.palette.color(QPalette.Text))
        painter.setFont(opt.font)
        # 处理文本溢出：超出宽度时用省略号代替
        elided_first_line = font_metrics.elidedText(original_text, Qt.ElideRight, first_line_rect.width())
        painter.drawText(first_line_rect, opt.displayAlignment, elided_first_line)
        painter.restore()
        
        # 5. 处理自定义数据并绘制第二行文本
        data = json.loads(index.data(Qt.UserRole))
        size_str = bytes_to_readable(int(data['size']))
        modified_time = datetime.fromtimestamp(int(data['modify_time']))
        modified_str = f"Modified at {modified_time.strftime('%Y-%m-%d %H:%M:%S')}"
        dir_str = data['dir']
        description_text = " · ".join([size_str, modified_str, dir_str])
        
        painter.save()
        # 第二行用稍小的字体和灰色（占位符文本色），区分主次
        small_font = opt.font
        small_font.setPointSize(opt.font.pointSize() - 1)
        painter.setFont(small_font)
        # 选中状态下同样用高亮文本色，保持一致性
        if opt.state & QStyle.State_Selected:
            painter.setPen(opt.palette.color(QPalette.HighlightedText))
        else:
            painter.setPen(opt.palette.color(QPalette.PlaceholderText))
        # 同样处理文本溢出
        small_fm = QFontMetrics(small_font)
        elided_second_line = small_fm.elidedText(description_text, Qt.ElideRight, second_line_rect.width())
        painter.drawText(second_line_rect, opt.displayAlignment, elided_second_line)
        painter.restore()
        
    def sizeHint(self, option, index):
        # 重写sizeHint，设置足够的高度容纳两行文本
        original_hint = super().sizeHint(option, index)
        font_metrics = QFontMetrics(option.font)
        # 两行高度 + 额外间距，避免文本挤在一起
        original_hint.setHeight(font_metrics.height() * 2 + 6)
        return original_hint

关键细节解释 #

1. 保留原生状态：通过self.initStyleOption(opt, index)获取到item的所有原生状态（比如选中、hover、复选框是否勾选），这样style.drawControl就能正确绘制对应的样式，不用自己去判断一堆StateFlag。
2. 分离框架与文本绘制：清空opt.text后再调用原生绘制，这样Qt只会画背景、复选框、图标这些框架元素，不会干扰我们自己绘制的两行文本，解决了你之前文本位置错位的问题。
3. 文本状态适配：根据item的选中状态切换文本颜色，完全遵循原生的样式逻辑，不会出现选中后文本颜色突兀的情况。
4. 行高适配：重写sizeHint设置合适的item高度，确保两行文本都能完整显示，不会被截断。

关于你之前遇到的复选框状态问题 #

之前你自己绘制复选框但状态不更新，是因为没有正确从模型获取CheckStateRole的数据。而上面的方法中，initStyleOption已经自动从模型读取了复选框状态，style.drawControl会正确绘制复选框的选中/未选中状态，而且点击时模型的CheckStateRole会自动更新，状态就能正常同步了。

这样实现下来，你的QListView既能显示双行文本，又完全保留了原生的交互和视觉风格，不用再写“死UI”啦！

备注：内容来源于stack exchange，提问作者DPaO Chow