Python PyQt/PySide 实现 QTableView 首列冻结代码示例

在日常桌面 GUI 软件开发中，当表格列数较多时，水平滚动会导致左侧关键字段（例如编号、名称等）移出视野。在 Qt 的官方控件库中，QTableView 原生并没有提供直接类似 setFrozenColumn(0) 的单一属性配置开关。解决该问题的标准官方范式是：在主表格上方覆盖一个次级辅助表格视图（Frozen View），二者共享同一个数据模型与选择模型，并同步垂直滚动条和行高，从而在视觉与交互上实现类似电子表格软件的“冻结窗格”效果。

一、双视图重叠与模型共享架构

为了直观理解冻结首列的实现原理，首先需要明确双层 QTableView 的组织关系。整个组件由一个继承自 QTableView 的主控件统一封装，内部创建一个辅助的冻结表格。两者在数据、选择状态和几何布局上的协作关系如下：

图 1：QTableView 首列冻结的双层视图重叠与模型共享结构图

二、实现步骤分解与核心技术细节

要构建一个无抖动、响应灵敏且行为正常的冻结表格，开发流程主要分为四个阶段：

1. 主控件初始化与辅助视图创建：继承 QTableView，将其实例命名为自定义控件（例如 FreezeTableWidget），并在构造函数中以当前主控件作为父对象，初始化内部的 self.frozen_view = QTableView(self)。
2. 外观裁剪与无关元素隐藏：冻结表格只需要展示第 0 列。我们需要通过循环遍历模型中第 1 列到最后一列，依次调用 self.frozen_view.setColumnHidden(col, True) 将它们隐藏。同时隐藏冻结表格的水平滚动条、垂直滚动条，以及水平/垂直表头的对应部分，避免出现边框加粗或双重表头错位。
3. 双向信号绑定（滚动与选择同步）：主表格垂直滚动条发生变动时，需要驱动冻结表格垂直滚动条到对应数值；反之亦然。同时，两者的 selectionModel() 必须完全共享，确保鼠标选中某一行或某个单元格时，主表和冻结表的高亮范围完全一致。
4. 重写尺寸变化与几何更新事件：重写主表格的 resizeEvent、moveCursor 等关键方法。当窗口拉伸或主表列宽变化时，动态计算主表第 0 列的实际像素宽度，并调用 setGeometry 将冻结视图精确放置在主表格视口（viewport）的左侧区域。

图 2：QTableView 冻结首列实现的四项核心操作顺序

三、事件与同步机制详细说明

在冻结列实现中，最容易被忽视的是光标移动（键盘方向键导航）与行高/列宽变更时的几何自适应。当用户在主表格中用方向键连续向右移动时，主表格视口会向右滚动，此时如果不干涉 moveCursor 逻辑，当光标再次移回第 0 列时，第 0 列可能被冻结表格完全覆盖，导致主视图试图将第 0 列滚入可见区域而发生视觉冲突。

图 3：垂直滚动同步与表头尺寸联动事件流图

四、完整可运行代码示例

以下代码同时兼容 PyQt5、PyQt6、PySide2 以及 PySide6（仅需调整顶部的导入模块）。示例中包含一个内置演示数据集，直观展示 20 列、100 行数据在横向滚动时首列始终固定的实际效果：

import sys

# 本示例以 PyQt5 为例，若使用 PyQt6 或 PySide6，只需替换 QtWidgets、QtCore、QtGui 的导入来源
try:
    from PyQt5.QtWidgets import (
        QApplication, QTableView, QHeaderView, QAbstractItemView, QWidget, QVBoxLayout
    )
    from PyQt5.QtGui import QStandardItemModel, QStandardItem
    from PyQt5.QtCore import Qt
except ImportError:
    from PySide6.QtWidgets import (
        QApplication, QTableView, QHeaderView, QAbstractItemView, QWidget, QVBoxLayout
    )
    from PySide6.QtGui import QStandardItemModel, QStandardItem
    from PySide6.QtCore import Qt


class FreezeTableWidget(QTableView):
    """
    支持首列冻结的自定义 QTableView。
    核心思想：在主表上方层叠一个只显示第 0 列的辅助 QTableView，并绑定模型、选择状态与滚动条。
    """
    def __init__(self, model):
        super().__init__()
        self.setModel(model)

        # 1. 创建子表控件并依附在主表视口之上
        self.frozen_table_view = QTableView(self)
        self.init_frozen_table()

        # 2. 监听表头尺寸调整信号，以便动态同步列宽和行高
        self.horizontalHeader().sectionResized.connect(self.update_section_width)
        self.verticalHeader().sectionResized.connect(self.update_section_height)

        # 3. 关联滚动条（垂直方向联动）
        self.frozen_table_view.verticalScrollBar().valueChanged.connect(
            self.verticalScrollBar().setValue
        )
        self.verticalScrollBar().valueChanged.connect(
            self.frozen_table_view.verticalScrollBar().setValue
        )

    def init_frozen_table(self):
        """配置冻结列视图的基础属性"""
        self.frozen_table_view.setModel(self.model())
        self.frozen_table_view.setSelectionModel(self.selectionModel())
        self.frozen_table_view.setFocusPolicy(Qt.NoFocus)

        # 隐藏冻结表的滚动条，避免双滚动条遮挡
        self.frozen_table_view.setVerticalScrollBarPolicy(Qt.ScrollBarAlwaysOff)
        self.frozen_table_view.setHorizontalScrollBarPolicy(Qt.ScrollBarAlwaysOff)

        # 隐藏水平表头，由主表格水平表头统一提供显示与交互
        self.frozen_table_view.horizontalHeader().setVisible(True)
        self.frozen_table_view.horizontalHeader().setSectionResizeMode(QHeaderView.Fixed)

        # 样式微调：设置右边框线条，使冻结列与滚动内容有清晰的分界
        self.frozen_table_view.setStyleSheet("""
            QTableView {
                border: none;
                border-right: 2px solid #52677D;
                background-color: #FAF5F4;
                selection-background-color: #52677D;
            }
        """)

        # 仅显示第 0 列，隐藏其余所有列
        for col in range(1, self.model().columnCount()):
            self.frozen_table_view.setColumnHidden(col, True)

        self.frozen_table_view.setColumnWidth(0, self.columnWidth(0))
        self.viewport().stackUnder(self.frozen_table_view)

    def update_section_width(self, logical_index, old_size, new_size):
        """当主表第 0 列调整宽度时，同步调整冻结表的列宽与布局"""
        if logical_index == 0:
            self.frozen_table_view.setColumnWidth(0, new_size)
            self.update_frozen_table_geometry()

    def update_section_height(self, logical_index, old_size, new_size):
        """当行高被拖动改变时，保持冻结表与主表行高一致"""
        self.frozen_table_view.setRowHeight(logical_index, new_size)

    def resizeEvent(self, event):
        """窗口或控件尺寸变动时重新计算几何范围"""
        super().resizeEvent(event)
        self.update_frozen_table_geometry()

    def update_frozen_table_geometry(self):
        """核心布局方法：将冻结表定位到主表的视口左上角"""
        # 获取表头与边框宽度
        v_header_width = self.verticalHeader().width() if self.verticalHeader().isVisible() else 0
        frame_width = self.frameWidth()
        col_0_width = self.columnWidth(0)

        # 计算并设置冻结表格的实际像素坐标
        self.frozen_table_view.setGeometry(
            v_header_width + frame_width,
            frame_width,
            col_0_width,
            self.viewport().height() + self.horizontalHeader().height()
        )

    def moveCursor(self, cursor_action, modifiers):
        """
        键盘导航支持：当按方向键左移超出视口时，确保平滑滚动，不发生跳跃
        """
        current = super().moveCursor(cursor_action, modifiers)
        if (cursor_action == QAbstractItemView.MoveLeft and
                current.column() > 0 and
                self.visualRect(current).topLeft().x() < self.columnWidth(0)):
            # 保证主表向左滚回时，被冻结列遮挡的第 1 列也能正常显露
            new_pos = (self.horizontalScrollBar().value() +
                       self.visualRect(current).topLeft().x() -
                       self.columnWidth(0))
            self.horizontalScrollBar().setValue(new_pos)
        return current


# --- 运行测试程序 ---
if __name__ == "__main__":
    app = QApplication(sys.argv)

    # 构造测试数据模型：100 行，20 列
    rows = 100
    cols = 20
    model = QStandardItemModel(rows, cols)

    # 设置表头
    headers = [f"固定首列 (ID)"] + [f"数据指标_{i}" for i in range(1, cols)]
    model.setHorizontalHeaderLabels(headers)

    # 填充数据
    for r in range(rows):
        item_0 = QStandardItem(f"ITEM-{r + 1:04d}")
        model.setItem(r, 0, item_0)
        for c in range(1, cols):
            item = QStandardItem(f"val_{r}_{c}")
            model.setItem(r, c, item)

    # 创建并展示表格
    table = FreezeTableWidget(model)
    table.setWindowTitle("Python PyQt/PySide 实现 QTableView 首列冻结示例")
    table.resize(850, 480)
    table.show()

    sys.exit(app.exec_() if hasattr(app, "exec_") else app.exec())

五、注意事项与生产实践要点

在实际项目集成该方案时，需关注以下三项工程细节：

• 模型变更通知：如果后续动态调用了 model.insertRows() 或 model.removeRows()，由于双方共享同一个 model，数据会实时同步，但行高重置（如使用 resizeRowsToContents）必须同时在主表和冻结表上执行一次，或统一通过 verticalHeader().sectionResized 信号自动同步。
• 右侧分割线视觉强化：冻结列与滑动区域之间建议增加明显的边框分界线（如代码中的 border-right: 2px solid #52677D;），以便让用户一眼识别出“这是固定列”，增强交互体验。
• 多列冻结扩展性：如果后续业务需要冻结前 N 列，只需将代码中的 setColumnHidden(col, True) 范围改为从第 N 列开始，并将 update_frozen_table_geometry 中的宽度累加前 N 列的总和即可无缝扩展。

图 4：首列冻结功能三层架构要素核对总结图