PyQt5表格中如何实现单元格文本超长自动换行并自适应行高？

Question

在PyQt5的QTableWidget或QTableView中，当单元格文本较长时，默认会截断显示（省略号），既不自动换行也不调整行高，严重影响可读性。开发者常尝试调用`setWordWrap(True)`或设置`QTableWidgetItem.setTextAlignment()`，却发现换行无效；或手动调用`resizeRowsToContents()`，但该方法仅对已显式启用换行且内容已渲染的单元格生效，首次加载、动态更新或含富文本/HTML内容时仍显示不全。更棘手的是，QTableView配合自定义QStyledItemDelegate时，若未重写`sizeHint()`返回合理高度，行高无法随多行文本动态伸缩；而QTableWidget又缺乏对`sizeHint`的细粒度控制。此外，在启用了水平滚动或设置了固定列宽的场景下，换行逻辑易被忽略，导致布局错乱。如何在保持性能的前提下，实现**文本超长时自动折行 + 行高精准适配 + 支持动态刷新与多字体混排**，是实际开发中高频且易踩坑的核心问题。

Answer 1

```html

一、现象层：为什么 setTextAlignment + setWordWrap 无效？

根本原因在于：QTableWidgetItem 的 setWordWrap(True) 仅影响渲染逻辑，但 不触发行高重计算，且 QTableWidget 默认禁用单元格换行策略。调用 setTextAlignment() 仅改变对齐方式，与文本布局无关。此外，若列宽未约束（如未设 setColumnWidth() 或 resizeColumnToContents()），Qt 会优先横向扩展而非折行。

二、机制层：Qt 文本布局与尺寸协商的双重路径

• QTableWidget 路径：依赖 QTableWidgetItem::sizeHint()（只读，不可重写），实际由 QTableView::sizeHintForColumn() 和内部 QAbstractItemView::doItemsLayout() 协同决定；
• QTableView + Delegate 路径：完全由 QStyledItemDelegate.sizeHint() 控制——这是唯一可编程干预行高的入口点；
• 关键约束：换行生效需同时满足 列宽固定/受限 + delegate 启用 rich text 渲染 + sizeHint 返回含垂直裕量的 QSize。

三、实践层：四套工业级解决方案对比

方案	适用控件	是否支持 HTML/多字体	动态刷新成本	性能评级（1–5★）
① QTableWidget + resizeRowsToContents() + 列宽锁定	QTableWidget	✅（需 setHtml()）	中（O(n²) 行遍历）	★★☆
② 自定义 Delegate + QTextDocument 布局	QTableView	✅✅（原生支持）	低（按需 sizeHint 缓存）	★★★★★
③ QStyledItemDelegate 子类 + 动态 fontMetrics	QTableView	✅（需手动解析富文本）	中（每 cell 一次 QFontMetrics::boundingRect）	★★★★
④ 混合代理：HTML 渲染 + 静态高度预估 + 异步重排	QTableView	✅✅✅（完整 CSS 支持）	极低（首次缓存+增量更新）	★★★★★

四、代码层：QStyledItemDelegate 实现多字体自适应换行（核心示例）

class RichTextDelegate(QStyledItemDelegate):
    def __init__(self, parent=None):
        super().__init__(parent)
        self._cache = {}  # (text, width, font) → height

    def paint(self, painter, option, index):
        text = index.data(Qt.DisplayRole) or ""
        if not text:
            super().paint(painter, option, index)
            return
        doc = QTextDocument()
        doc.setDefaultFont(option.font)
        doc.setHtml(text)  # ✅ 原生支持 <b>、<span style="font-size:12pt">
        doc.setTextWidth(option.rect.width())
        painter.save()
        painter.translate(option.rect.topLeft())
        doc.drawContents(painter)
        painter.restore()

    def sizeHint(self, option, index):
        text = index.data(Qt.DisplayRole) or ""
        key = (text, option.rect.width(), option.font.toString())
        if key in self._cache:
            return QSize(option.rect.width(), self._cache[key])
        
        doc = QTextDocument()
        doc.setDefaultFont(option.font)
        doc.setHtml(text)
        doc.setTextWidth(option.rect.width())
        height = ceil(doc.size().height()) + 6  # +6 px vertical padding
        self._cache[key] = height
        return QSize(option.rect.width(), height)

五、进阶层：解决“水平滚动干扰换行”的隐藏陷阱

当启用 horizontalScrollBarPolicy(Qt.ScrollBarAsNeeded) 时，option.rect.width() 在 sizeHint() 中可能返回视口宽度而非列宽，导致换行失效。正确做法是：在 delegate 构造时传入 column_widths: List[int]，并在 sizeHint() 中使用 column_widths[index.column()] 替代 option.rect.width()。同时，监听 QHeaderView::sectionResized 信号清空缓存。

六、性能层：百万级数据下的优化策略

1. 启用 QTableView.setUniformRowHeights(True)（若行高差异 ≤ 2px）；
2. 对 sizeHint 结果做 LRU 缓存（@lru_cache(maxsize=1000)）；
3. 避免在 paint() 中重复创建 QTextDocument，复用实例并调用 clear()；
4. 对纯文本场景，用 QFontMetrics.boundingRect() 替代 QTextDocument（快 8×）；
5. 动态更新时，仅重排可见区域（visualRect() + rowsAboutToBeInserted）。

七、验证层：自动化断言检查清单

• ✅ 所有含 <br> 或空格的长文本在固定列宽下至少显示 2 行；
• ✅ <span style="color:red;font-weight:bold"> 渲染无截断；
• ✅ 插入新行后，resizeRowsToContents() 或 delegate 自动响应；
• ✅ 水平滚动至末列，换行行为不突变；
• ✅ 连续 1000 次 setData() 后 UI 帧率 ≥ 55 FPS（实测工具：QApplication.processEvents() + time.time()）。

八、架构层：面向未来的可扩展设计

建议将文本布局逻辑抽象为独立服务：

1. TextLayoutEngine：统一处理 HTML / Markdown / plain text；
2. HeightCacheManager：支持内存/磁盘两级缓存 + TTL 失效；
3. AdaptiveDelegate：继承自 QStyledItemDelegate，注入 layout engine；
4. 预留 onFontChanged 信号，支持运行时全局字体切换；
5. 集成 QQuickWidget 备选路径，为未来 Qt6 迁移铺路。

九、避坑层：高频错误模式速查表

错误模式	症状	修复指令
未调用 doc.setTextWidth()	始终单行显示	必须在 paint & sizeHint 中设置
delegate 未安装到 view（setItemDelegate()）	样式不变	检查是否遗漏 view.setItemDelegate(RichTextDelegate(view))
QTableWidget 使用 setItem 后未调用 resizeRowsToContents()	首次加载不换行	改为 insertRow() + setItem() + resizeRowsToContents()

十、演进层：从 PyQt5 到 PyQt6 / PySide6 的平滑迁移路径

PyQt6 中 QStyledItemDelegate.sizeHint() 签名变为 sizeHint(self, option: QStyleOptionViewItem, index: QModelIndex) → QSize，需适配类型注解；QTextDocument.setHtml() 对 SVG 内联支持增强；推荐采用 QGuiApplication.font() 统一获取系统字体，替代硬编码 font。迁移时应优先重构 delegate，再逐步替换 widget 类型。

```