如何为QTableWidget实现冻结列功能（无需使用QTableView）

该方案完全匹配Excel、MS Access的冻结列交互效果，解决双独立QTableWidget滚动不同步的问题，效果与Qt官方QTableView冻结列示例完全一致。

核心实现逻辑 #

传统双QTableWidget方案出现滚动不同步的核心原因是两个控件为平级独立布局，信号传递存在事件队列延迟，且尺寸校准不实时。本方案做如下调整解决该问题：

• 冻结列对应的QTableWidget直接作为主表格的子控件，叠加在主表格视口左侧置顶显示，不加入独立布局层级
• 双向绑定主表格与冻结列的垂直滚动条数值，消除单向同步的延迟差
• 拦截主表格的尺寸变化、列宽/行高调整、排序、选择变更事件，实时同步状态到冻结列，不依赖异步信号传递
• 重写尺寸、滚动相关事件回调，每次主表格状态变更时立刻校准冻结列的位置与大小，从根源避免错位

可运行代码（PyQt5 实现，C++可直接按逻辑转写） #

from PyQt5.QtCore import Qt
from PyQt5.QtWidgets import QTableWidget, QTableWidgetItem, QAbstractItemView

class FrozenColumnTable(QTableWidget):
    def __init__(self, *args, frozen_col_count=1, **kwargs):
        super().__init__(*args, **kwargs)
        self.frozen_col_count = max(0, frozen_col_count)
        # 初始化冻结列表格，作为主表格的子控件
        self.frozen_tw = QTableWidget(self)
        self._init_frozen_table()
        self._bind_sync_signals()

    def _init_frozen_table(self):
        # 冻结列基础属性对齐主表格
        self.frozen_tw.setColumnCount(self.frozen_col_count)
        self.frozen_tw.verticalHeader().hide()
        self.frozen_tw.setHorizontalScrollBarPolicy(Qt.ScrollBarAlwaysOff)
        self.frozen_tw.setVerticalScrollBarPolicy(Qt.ScrollBarAlwaysOff)
        self.frozen_tw.setSelectionMode(self.selectionMode())
        self.frozen_tw.setSelectionBehavior(self.selectionBehavior())
        self.frozen_tw.setEditTriggers(self.editTriggers())
        self.frozen_tw.setFocusPolicy(Qt.StrongFocus)
        # 调整视口层级：冻结列在主表格视口上方、水平表头下方
        self.frozen_tw.viewport().stackUnder(self.horizontalHeader().viewport())
        self.viewport().stackUnder(self.frozen_tw)
        self._sync_frozen_geometry()
        self._sync_frozen_content()

    def _bind_sync_signals(self):
        # 双向同步垂直滚动条，消除延迟
        self.verticalScrollBar().valueChanged.connect(self.frozen_tw.verticalScrollBar().setValue)
        self.frozen_tw.verticalScrollBar().valueChanged.connect(self.verticalScrollBar().setValue)
        # 同步行列尺寸变化
        self.horizontalHeader().sectionResized.connect(self._on_col_resized)
        self.verticalHeader().sectionResized.connect(lambda row, _, h: self.frozen_tw.setRowHeight(row, h))
        # 同步选择状态
        self.itemSelectionChanged.connect(self._sync_selection)
        # 同步排序后内容
        self.horizontalHeader().sortIndicatorChanged.connect(self._on_sort_changed)

    def _on_col_resized(self, col, _, new_w):
        if col < self.frozen_col_count:
            self.frozen_tw.setColumnWidth(col, new_w)
        self._sync_frozen_geometry()

    def _on_sort_changed(self, *args):
        self._sync_frozen_content()
        self.frozen_tw.horizontalHeader().setSortIndicator(*args)

    def _sync_selection(self):
        self.frozen_tw.clearSelection()
        for item in self.selectedItems():
            if item.column() < self.frozen_col_count:
                target = self.frozen_tw.item(item.row(), item.column())
                if target:
                    target.setSelected(True)

    def _sync_frozen_content(self):
        self.frozen_tw.setRowCount(self.rowCount())
        # 同步行高
        for row in range(self.rowCount()):
            self.frozen_tw.setRowHeight(row, self.rowHeight(row))
        # 同步冻结列单元格内容与属性
        for col in range(self.frozen_col_count):
            self.frozen_tw.setColumnWidth(col, self.columnWidth(col))
            for row in range(self.rowCount()):
                src_item = self.item(row, col)
                if not src_item:
                    continue
                new_item = QTableWidgetItem(src_item.text())
                new_item.setFlags(src_item.flags())
                new_item.setData(Qt.UserRole, src_item.data(Qt.UserRole))
                new_item.setForeground(src_item.foreground())
                new_item.setBackground(src_item.background())
                self.frozen_tw.setItem(row, col, new_item)

    def _sync_frozen_geometry(self):
        # 计算冻结列位置与尺寸，完全贴合主表格
        total_frozen_w = 0
        for col in range(self.frozen_col_count):
            total_frozen_w += self.columnWidth(col)
        self.frozen_tw.setGeometry(
            self.verticalHeader().width() + self.frameWidth(),
            self.frameWidth(),
            total_frozen_w,
            self.viewport().height() + self.horizontalHeader().height()
        )

    def setItem(self, row, col, item):
        super().setItem(row, col, item)
        # 新增单元格时自动同步到冻结列
        if col < self.frozen_col_count and self.frozen_tw.rowCount() > row:
            sync_item = QTableWidgetItem(item.text())
            sync_item.setFlags(item.flags())
            sync_item.setData(Qt.UserRole, item.data(Qt.UserRole))
            self.frozen_tw.setItem(row, col, sync_item)

    def setFrozenColumnCount(self, count):
        # 对外接口：动态修改冻结列数量
        self.frozen_col_count = max(0, count)
        self.frozen_tw.setColumnCount(self.frozen_col_count)
        self._sync_frozen_content()
        self._sync_frozen_geometry()

    def resizeEvent(self, event):
        super().resizeEvent(event)
        self._sync_frozen_geometry()

    def scrollTo(self, index, hint=QAbstractItemView.EnsureVisible):
        super().scrollTo(index, hint)
        self._sync_frozen_geometry()

扩展说明 #

• 如需实现冻结列的编辑、右键菜单、表头点击等交互，直接将frozen_tw的对应信号透传到主表格逻辑即可，交互体验与普通列无差异
• 若需要自定义单元格样式，可在_sync_frozen_content方法中补充样式同步逻辑
• 该方案滚动同步精度与原生控件一致，不会出现滚动错位、延迟问题

内容的提问来源于stack exchange，提问作者Marçal Xena