简介：针对PyQt5开发中QTableWidget控件样式设置、表头自定义与整体美化这一常见难点，这套演示Demo以QWidget嵌套QTableWidget的形式，提供了一个可直接运行的完整示例，覆盖表头视觉定制、单元格样式、选中态/悬停态等交互细节，适合正在为客户端软件进行界面美化的PyQt5开发者参考与二次开发。资源压缩包共8个文件，包含3个Python脚本（主逻辑、资源导入、界面逻辑）、1个ui界面描述文件与1个qrc资源文件，另有2张效果预览图和1张演示动图，整体仅39KB，轻量且便于阅读。目前已有3197人学习/下载。Demo实现了设计稿接近99%的美化需求，逻辑分层清晰，迁移时只需替换对应模块即可复用到完整窗口设计中；同时利用演示动图直观展示了表头排序、勾选等交互反馈，能够为开发者节省大量查询资料与反复调整的时间。无论是从零搭建还是快速接入现有窗口，都能从中获得直接可用的实现思路。
1. QTableWidget 表头自定义与美化，先决定你要改的是什么
做 PyQt5 界面，带表格的窗口是最常见的一关。数据接进去了，紧接着面对的就是 QTableWidget 表头自定义与美化：表头文字能不能换、排序箭头怎么出来、列头能不能做得像 Web 表格一样干净。这个标题背后其实是三件事——表头的外观样式、表头的交互行为，以及「看着简单、一上手就翻车」的那几个边界坑。
本文以一个可以直接运行的 QTableWidget Demo 为主线，把表头初始化、QSS 美化、点击表头排序、右键菜单、动态复杂表头逐个讲清楚。每段都带能复制的代码和参数说明，尽量让你照着抄完就能在项目里用上，而不是停留在「知道有这个东西」。
适合两种人：刚把数据填进表格、准备把界面打磨到能交给业务方看的人；以及做内部工具、需要在短时间内把表头这个细节一次做到位的开发者。下面从最基础的 API 层开始，一层层把表头剥开。
2. 表头初始化的最小 Demo：文字、字体、对齐、图标与列宽策略
2.1 搭一个能直接运行的最小表头初始化代码
大多数 pyqt5 教程讲表头就一句setHorizontalHeaderLabels，但实际项目里表头还要管字体、高度、对齐、提示信息和列宽策略。先给一个最小可运行的窗口，把表头基础设置一次列清楚：
import sys from PyQt5.QtWidgets import ( QApplication, QWidget, QTableWidget, QTableWidgetItem, QHBoxLayout, QHeaderView ) from PyQt5.QtCore import Qt from PyQt5.QtGui import QFont class HeaderDemo(QWidget): def __init__(self): super().__init__() self.setWindowTitle("QTableWidget 表头自定义 Demo") self.resize(720, 400) # 4 行 3 列，行号跟随数据一起管理 self.table = QTableWidget(4, 3, self) # 表头文字：传入几个就显示几列，长度和列数不一致时按少的来 self.table.setHorizontalHeaderLabels(["任务名称", "创建时间", "执行状态"]) # 行表头（最左侧的序号）默认显示，可留可关 # self.table.verticalHeader().setVisible(False) # 表头字体：加粗 + 12px，比默认 9px 更接近 UI 图上的效果 header_font = QFont("Microsoft YaHei", 9) header_font.setBold(True) self.table.horizontalHeader().setFont(header_font) # 表头最小高度：55px 才能放下两行内容或图标+文字 self.table.horizontalHeader().setMinimumHeight(55) layout = QHBoxLayout(self) layout.addWidget(self.table) # 填入一些示例数据，方便看表头与内容的对齐关系 for row in range(4): self.table.setItem(row, 0, QTableWidgetItem(f"任务 {row + 1}")) if __name__ == "__main__": app = QApplication(sys.argv) demo = HeaderDemo() demo.show() sys.exit(app.exec_())这段代码的核心是self.table.horizontalHeader()。QTableWidget 的表头并不是一个独立控件，真正掌控列头的是QHeaderView实例，字体、高度、拉伸模式、排序开关都挂在它上面。setHorizontalHeaderLabels只是用文本把每个 section 的 label 填上，它不会自动调整高度，也不会改变默认字体。
参数说明里有两个细节容易忽略。第一，setHorizontalHeaderLabels(["任务名称", "创建时间", "执行状态"])传入的列表只有 3 项，表格有 3 列时刚好一一对应；如果列表长度大于列数，多出来的项会被丢掉，小于列数，多余的列头显示为空，不会报错。第二，setMinimumHeight(55)不是设置固定高度，而是给表头一个最小高度下限。默认表头高度由字体和 padding 决定，一旦设置了最小高度，字号变化时表头只增不减，视觉上更稳定。如果改成setFixedHeight(55)，表头就完全不能根据内容自适应了，遇到新字体或换行文本反而容易截字。
2.2 表头字体、高度、对齐与图标的组合设置
在实际项目中，表头文字普遍需要加粗，部分列还要带上提示信息或小图标。下面这段是常用组合，可以直接合并到上文 Demo 的__init__里：
header = self.table.horizontalHeader() # 对齐：表头默认居中，但有些数据列希望左对齐更符合阅读习惯 header.setDefaultAlignment(Qt.AlignLeft | Qt.AlignVCenter) # 给某一列表头追加提示信息：悬停时显示完整描述 item = QTableWidgetItem("执行状态") item.setToolTip("进行中 / 已完成 / 失败") self.table.setHorizontalHeaderItem(2, item) # 给表头单元格放图标 + 文字，常用于状态列、导出列 from PyQt5.QtGui import QIcon icon_item = QTableWidgetItem("执行状态") icon_item.setIcon(QIcon(":/icons/status.png")) self.table.setHorizontalHeaderItem(2, icon_item)setDefaultAlignment设置的是整个表头的默认对齐方式，注意它跟内容单元格的setTextAlignment是两套体系。表头默认是居中，多数场景可以不管；如果某列的数据是长文本，把表头改成左对齐会更像报表工具。setHorizontalHeaderItem比setHorizontalHeaderLabels更灵活，因为QTableWidgetItem本身能带图标、提示、字体和背景数据，适合单独定制某一列。
这里有个顺序问题：先setHorizontalHeaderLabels再setHorizontalHeaderItem(2, ...)，后者会覆盖第三列的文本；反过来先设置 item 再传入 labels，第三列又会被 labels 覆盖。我一般把全部列名写在一个列表里统一管，只有需要图标或提示的列才单独再 set 一次 item。图标资源要用 Qt 的资源系统编译进 .qrc，或者用绝对路径先验证效果，贴QIcon(":/icons/status.png")在工程里没加资源时会直接显示空白，这不是表头的问题，是资源路径没配好。
2.3 列宽与拉伸策略：Interactive / Stretch / ResizeToContents 怎么组合
表头好不好看，七分在列宽策略。QHeaderView 的setSectionResizeMode支持五种模式，实际会用到的主要是下面四种：
| 模式 | 行为 | 适合场景 | QSS 配合注意点 |
|---|---|---|---|
QHeaderView.Interactive | 用户可手动拖动列宽，程序也可 setColumnWidth | 常规数据列，宽度需要随时调整 | 表头样式正常显示，默认模式 |
QHeaderView.Stretch | 列宽按剩余空间平均分配，用户不能拖 | 只读展示型表格，不希望用户打乱布局 | 列头背景会被拉伸，圆角效果不明显 |
QHeaderView.ResizeToContents | 列宽自动适配内容宽度 | ID、状态、时间这类内容长度固定的列 | 内容变更后宽度会跳动，表头 QSS 背景随宽度变化 |
QHeaderView.Fixed | 固定宽度，用户不可拖，程序可改 | 控制按钮列、序号列 | 与setColumnWidth配合最稳定 |
常见做法是混合使用：ID 列和状态列用ResizeToContents，操作按钮列用Fixed配固定宽度，中间大段内容列用Interactive，最后一列再用setStretchLastSection(True)吃掉剩余空间。示例：
header = self.table.horizontalHeader() header.setSectionResizeMode(0, QHeaderView.ResizeToContents) # 任务名称列自适应 header.setSectionResizeMode(1, QHeaderView.Interactive) # 创建时间列可拖动 header.setSectionResizeMode(2, QHeaderView.Fixed) # 执行状态列固定 self.table.setColumnWidth(2, 100) header.setStretchLastSection(True)setStretchLastSection(True)和setSectionResizeMode(最后一列, QHeaderView.Stretch)效果类似，但前者不会改掉你给最后一列设的固定宽度语义，只是让它吃掉窗口右侧的空白。这里的坑在于：ResizeToContents的列在数据刷新后宽度会自己跳，如果你再手动setColumnWidth，反而会被内容自适应再次覆盖。凡是希望列宽完全可控的列，优先用Interactive或Fixed，不要把所有列都设成ResizeToContents。
做完这一层的配置，表头至少能看了：文字明确、高度合适、列宽不打架。但要达到「美化」的程度，还得上 QSS，那是下一章的事。
3. QSS 美化 QHeaderView：section 样式、圆角与排序箭头的完整写法
3.1 一套能直接复制的浅色表头 QSS 骨架
QSS 美化表头的核心选择器是QHeaderView::section，它对应表头里每个独立的列块。直接给一套我常用的浅色方案，背景用渐变，视觉上比纯色多一点点层次：
HEADER_QSS = """ QTableWidget { background: #ffffff; alternate-background-color: #f7f9fc; } /* 表头单元格：渐变背景 + 底部边线 */ QHeaderView::section { background: qlineargradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #f7f9fc, stop: 1 #e9edf4 ); color: #333a45; border: none; border-right: 1px solid #d5dbe3; border-bottom: 1px solid #d5dbe3; padding: 4px 8px; font-weight: 600; } /* 左上角那个小方块：不设置会留一块灰白，很扎眼 */ QTableCornerButton::section { background: #e9edf4; border: none; border-right: 1px solid #d5dbe3; border-bottom: 1px solid #d5dbe3; } /* 排序箭头：默认箭头很粗，换上细一点的三角图片更好看 */ QHeaderView::up-arrow { image: url(:/icons/arrow_up.png); width: 10px; height: 10px; } QHeaderView::down-arrow { image: url(:/icons/arrow_down.png); width: 10px; height: 10px; } """这套 QSS 的作用对象是QTableWidget本身。样式表写在表格上，表头和内容单元格都会生效；如果单独self.table.horizontalHeader().setStyleSheet(HEADER_QSS)，效果通常会不稳定——后面会解释原因。qlineargradient是从上到下的两段渐变，stop:0是顶部颜色，stop:1是底部颜色，改成深色主题时只要替换这四个色值。
边框那块是表头美化的重点。QHeaderView::section默认带一套平台相关的边框，直接写border: none去掉四周，再用border-right和border-bottom补上细线，就能得到类似 Excel 那种只保留分隔线的效果。这里不用border: 1px solid #d5dbe3，是因为它会把四个方向都画上边线，section 之间会出现双线。
3.2 选择器作用范围：为什么 QSS 会「时灵时不灵」
很多人在这一步翻车：样式表明明写了，表头却还是老样子，或者换个窗口就丢了。常见原因有两个。第一，QSS 写在了单独创建的QHeaderView对象上，Qt 官方文档对QHeaderView单独 setStyleSheet 的支持并不如主视图稳定，特别是表头重新布局、排序状态切换时，样式会回退到默认值。第二，样式表作用在QTableWidget上，但选择器只写了::section，没有加QTableWidget QHeaderView这种父子限定，一旦表格套在容器里或被样式表里的其他规则覆盖，优先级就会乱。
稳妥写法是全局样式走app.setStyleSheet，局部 Demo 则把 QSS 挂在QTableWidget自身，并使用带层级的完整选择器：
QTableWidget QHeaderView::section { background: #f0f2f5; }这样写能明确限定「这个表格里的表头」，不会被其他部件的 QSS 规则影响。左上角那个小方块对应的是QTableCornerButton::section，很多初始美化遗漏了它，结果整张表头换了颜色，角落里还留一块默认灰白色块，一眼就能看出没打磨完。
3.3 圆角与悬停变色：两个「看得见但很难做对」的特效
先泼盆冷水：QHeaderView::section的border-radius在多数 Qt 版本上可用，但展示效果非常有限。原因是 section 之间紧挨着，圆角被相邻 section 的背景遮住，只有最左和最右两列各自露出一两个角。要用圆角做出「药丸形表头」，必须配合 section 之间的间距，但 Qt QSS 不支持给 section 设 margin，所以实际很少有人能把表头圆角做好。我的建议是：能不用就不用，把精力放在分隔线的粗细和颜色对比上，效果更稳定。
悬停变色是另一个经典陷阱。不少人尝试写QHeaderView::section:hover { background: ... }，但 section 的渲染不走常规 QSS 伪状态，在 Windows 和 Linux 的不同 Qt 版本下表现不一致，经常整块不生效。这属于 Qt 表头样式的黑匣子区域，别在伪状态上死磕。要稳定的悬停效果，用事件过滤器监听表头 viewport 的鼠标移动，再手动刷新对应 section：
from PyQt5.QtCore import QEvent, Qt class HeaderHoverFilter: def __init__(self, table): self.table = table self.hover_col = -1 self.header = table.horizontalHeader() # 给表头 viewport 安装事件过滤器 self.header.viewport().installEventFilter(self) def eventFilter(self, obj, event): if obj is self.header.viewport(): if event.type() == QEvent.MouseMove: # 把 viewport 坐标换算成逻辑 section pos = event.pos() col = self.header.logicalIndexAt(pos) # 恢复上一次高亮 if self.hover_col != -1 and self.hover_col != col: self.header.updateSection(self.hover_col) if col != self.hover_col: self.hover_col = col self.header.updateSection(col) # 触发重绘 elif event.type() == QEvent.Leave: if self.hover_col != -1: self.header.updateSection(self.hover_col) self.hover_col = -1 return False这段代码的思路是：表头自身的viewport()会持续收到鼠标移动事件，logicalIndexAt把鼠标坐标换算成当前列号，然后只对那一列调用updateSection重绘。重绘时，section 会根据当前hover_col是否等于自身列号来决定用哪种背景。但要注意，这段代码只是重绘触发机制，真正的高亮背景还要配合在样式里给「正在悬停的列」加状态，实际操作中我会在paintSection的子类实现里读取hover_col，或者用setStyleSheet动态切换该列的 QSS。对 Demo 来说，建议先不做悬停，把渐变背景、分隔线、排序箭头调清晰，比追一个不稳定的 hover 效果更有性价比。
4. 点击表头排序、拖拽重排与右键菜单：行为层的自定义方案
4.1 setSortingEnabled(True) 与数字排序的坑
表头交互里使用频率最高的是排序。self.table.setSortingEnabled(True)一行代码就能让点击表头排序，但随后你会遇到一个很经典的翻车现场：列里的数字是 2、10、100，排完序变成 2、100、10。原因是QTableWidgetItem默认按字符串比较，10 排在 2 前面，100 又排在 10 前面，这是字符串字典序，不是数值序。
解决办法是给这列换一个自定义 item 类型，重载比较逻辑：
from PyQt5.QtWidgets import QTableWidgetItem class NumericItem(QTableWidgetItem): """按数值大小比较的表格项""" def __lt__(self, other): try: return float(self.text()) < float(other.text()) except ValueError: # 文本列退回字符串比较，避免抛异常导致崩溃 return self.text() < other.text()用的时候把数字列全部存成NumericItem，其他列继续用普通QTableWidgetItem。这里有一个容易被忽略的隐患：float(self.text())对空字符串和"未知"这类内容会抛异常，必须在外面接try/except，否则一排序整个界面就崩。更稳妥的方案是在__init__里把原始值用Qt.UserRole存起来，比较时优先读 UserRole：
class SafeNumericItem(QTableWidgetItem): def __init__(self, text, sort_key=None): super().__init__(text) if sort_key is None: try: sort_key = float(text) except ValueError: sort_key = text self.setData(Qt.UserRole, sort_key) def __lt__(self, other): left = self.data(Qt.UserRole) right = other.data(Qt.UserRole) # 数值和字符串混排时，把字符串排到数值后面 if isinstance(left, float) and isinstance(right, float): return left < right return str(left) < str(right)这种写法在数据刷新时也适用：setItem新值的同时更新 UserRole，排序键始终是干净的。另外提醒一句，开启排序后再调setSortingEnabled(False)，表头上次点击留下的排序箭头通常不会自动消失，用户会以为排序还在生效。需要显式隐藏：
header = self.table.horizontalHeader() header.setSortIndicatorShown(False) # 隐藏排序箭头 header.setSortIndicator(-1, Qt.AscendingOrder) # 复位指示状态setSortIndicatorShown(False)是隐藏箭头的可靠手段，单纯设置setSortIndicator(-1, ...)在某些 Qt 版本上对「上一次的排序状态」没有彻底清理，两者配合才稳妥。
4.2 拖拽表头与列索引错位的代价
想让表头像 Excel 一样可以拖动换位，代码很简单：
header = self.table.horizontalHeader() header.setSectionsMovable(True)拖动本身没有任何报错，但数据逻辑会变得非常绕。QHeaderView 维护的是逻辑索引，拖动改变的是视觉索引。比如你把第三列拖到第一列的位置，界面看起来整列都过去了，表格的column(0)仍然是原来的第一列；如果你按视觉位置对setItem传列号，数据会串到别列去。对很多新手来说，这就是「数据自己长了脚」的灵异事件。
解决思路有两条。一是不用 QHeaderView 自带的拖拽，改成关闭setSectionsMovable(False)，用右键菜单里的「列显隐」代替重排，交互确定性强，代码也简单。二是如果一定支持拖拽，监听sectionMoved，自行维护一个视觉索引到逻辑索引的映射表，每次setItem前用映射换算列号：
self.visual_to_logical = list(range(self.table.columnCount())) header.sectionMoved.connect(self.on_section_moved) def on_section_moved(self, logical, old_visual, new_visual): # 从视觉索引中移除旧位置，插入新位置 self.visual_to_logical.pop(old_visual) self.visual_to_logical.insert(new_visual, logical)这段映射代码能解决「新增列、更新单元格」时索引错位，但还远远不够：表头文字、提示信息、列宽设置都要跟着 visual 索引走，等于自己管理一套列元数据。对大多数业务系统，拖拽重排的收益远小于它带来的潜在 bug。我在项目里一律关掉拖拽，把「显示哪些列」的控制权交给右键菜单，用户一样能自定义视图，代码里少掉一大块状态同步的复杂度。如果你非要支持拖拽，务必在 Demo 阶段就把这个映射机制写进基类，而不是等项目做大了再补。
4.3 右键菜单实现列显隐与列宽重置
右键菜单是表头自定义里性价比最高的交互。它不改变数据索引，只控制列的可见性，操作结果直观，回退也容易。先给表格设置右键菜单策略，再连接信号弹菜单：
from PyQt5.QtWidgets import QMenu, QAction from PyQt5.QtCore import Qt self.table.setContextMenuPolicy(Qt.CustomContextMenu) self.table.customContextMenuRequested.connect(self.show_header_menu) def show_header_menu(self, pos): # 判断点击位置是否在表头区域，不是表头就不弹 header = self.table.horizontalHeader() if not header.geometry().contains(pos): return menu = QMenu(self) for col in range(self.table.columnCount()): label = self.table.horizontalHeaderItem(col).text() action = QAction(label, self.table) action.setCheckable(True) # 当前可见的列，勾选置为 True action.setChecked(not self.table.isColumnHidden(col)) # 用 lambda 包一层，避免闭包共享 col 变量 action.toggled.connect( lambda checked, c=col: self.table.setColumnHidden(c, not checked) ) menu.addAction(action) # 重置列宽：把 Interactive 列恢复到默认宽度 reset_action = QAction("重置列宽", self.table) reset_action.triggered.connect(lambda: self.reset_column_widths()) menu.addSeparator() menu.addAction(reset_action) menu.exec_(self.table.mapToGlobal(pos)) def reset_column_widths(self): header = self.table.horizontalHeader() for col in range(self.table.columnCount()): if header.sectionResizeMode(col) == QHeaderView.Interactive: self.table.setColumnWidth(col, 120)这段代码有三个容易翻车的点。第一，header.geometry().contains(pos)用来确保右键点的是表头而不是数据区，pos是相对于表格左上角的坐标，header.geometry()也是表格坐标系，能直接比较。第二，lambda 里不写c=col的话，所有 action 都引用循环结束后的最后一个 col，这是 Python 闭包经典坑。第三，setColumnHidden只隐藏列，不删除数据，隐藏后再显示，列内容和列宽都会原样返回，这是它比拖拽重排安全得多的根本原因。列宽重置只针对Interactive列，Stretch和ResizeToContents列的宽度本来就不由用户控制，贸然setColumnWidth反而会被模式覆盖。
这样一组菜单加下来，表头就有了接近专业工具的基础交互：点击排序、列显隐、重置列宽。做完这一层，表头的「自定义」才算是完整了。
5. 表头自定义避坑清单：QSS 不生效、排序错乱与动态复杂表头
5.1 QSS 写了但表头还是老样子的两种来源
现象：样式表里清楚写了QHeaderView::section { background: #f0f2f5; }，运行后表头背景完全没有变化。
原因排查要分两步走。第一步，样式表是不是被后面的规则覆盖了。setStyleSheet是整体替换，不是追加。如果你在__init__第一段设置表头 QSS，后面另一行代码又对整个窗口调了一次setStyleSheet，前面的表头样式就被整段冲掉。解决：把所有 QSS 集中到一个常量或独立.qss文件，最后统一app.setStyleSheet，避免零散设置互相覆盖。
第二步，用了 QSS 不支持的属性。Qt 样式表支持的属性是固定的子集，不支持box-shadow、margin（部分绘制场景忽略）、opacity这些 Web CSS 常有的属性。一个属性写错，Qt 不一定报错，但会直接跳过整条规则，导致你看到的现象是「代码明明写了，效果完全没有」。解决：凡是样式没生效，先把自定义属性逐个删掉，留下最基础的background和color验证；能显示了再加边框、渐变，一次加一个，别一次写一整段后再排查。表头 QSS 和内容单元格 QSS 最好分开两个常量管理，内容单元格的属性波动大，很容易把表头规则顺带带歪。
5.2 排序打开后更新数据行「瞬移」的踩坑
现象：开启setSortingEnabled(True)后，程序在指定行setItem更新数据，界面里的行却突然跳到了另一个位置，看起来像数据插错了行，甚至像丢了数据。
原因：QTableWidget 在setSortingEnabled(True)状态下，任何setItem都可能触发一次重新排序。你更新的是第 3 行，但排序键变了，这一行马上被移动到新的视觉位置。你再用保存下来的 row 索引去读数据，读到的是原来的第 5 行内容，于是产生了「数据错乱」的错觉。
解决：批量写数据前先关闭排序，写完后恢复：
self.table.setSortingEnabled(False) for row in range(len(rows)): self.table.setItem(row, col, QTableWidgetItem(value)) self.table.setSortingEnabled(True)这样做的代价是用户当前看到的排序方向会丢失，恢复 True 后表格按默认顺序展示。如果想保留用户上次的排序状态，得在关闭前记录sortIndicatorSection和sortIndicatorOrder，写完数据再恢复。另外要养成一个习惯：排序开启的表格里，业务定位不要依赖 row 索引，而是用某列的唯一 ID 去重新查找行位置。写一个find_row_by_id(id_col, value)工具函数遍历查找，比记住 row 号可靠得多，否则排序一变，所有「按行号操作」的逻辑全部作废。
5.3 多行表头与动态复杂表头：QTableWidget 的原生边界
现象：需求要两级表头，比如「销售数据」下面分「华东 / 华南 / 华北」三个子列，QTableWidget 的表头做不到单元格合并。
原因：QTableWidget 的表头本质是一组独立 section，每个 section 只有一个 label，没有「跨列合并单元格」的能力。想绕过这个限制，业界有三种常见方案，我按实现成本从低到高排一下：
方案一，文本换行伪装。给表头文本塞一个\n，让一个 section 显示两行文字，比如"销售数据\n华东"。代码量最小，但两行不会跨列合并，视觉上只是「变高的表头」，适合不想大动干戈的 Demo。
方案二，表格上方叠一个 QWidget 当「伪二级表头」。在 QTableWidget 顶部放一个高度固定的 QFrame，按列宽等分放几个 QLabel，第一层标签显示「销售数据」，下面才是真正的表头。这个方案能做出真正意义上的合并表头，但列宽一变，上方的 QLabel 宽度必须跟着同步，需要在sectionResized信号里重排。
方案三，换 QTableView 加自定义 QHeaderView。这是做产品级复杂表头的正道：
from PyQt5.QtWidgets import QHeaderView from PyQt5.QtGui import QPainter, QPen from PyQt5.QtCore import QRect class DoubleLineHeader(QHeaderView): def __init__(self, orientation, parent=None): super().__init__(orientation, parent) self.setDefaultAlignment(Qt.AlignCenter) def paintSection(self, painter, rect, logicalIndex): painter.save() # 第一行：主标题后缀 main_text = self.model().headerData(logicalIndex, self.orientation(), Qt.DisplayRole) # 第二行：子标题后缀（约定用 | 分隔） sub_text = self.model().headerData( logicalIndex, self.orientation(), Qt.UserRole ) or "" painter.setPen(QPen(Qt.black)) mid = rect.height() // 2 painter.drawText(QRect(rect.left(), rect.top(), rect.width(), mid), Qt.AlignCenter, str(main_text)) painter.drawText(QRect(rect.left(), rect.top() + mid, rect.width(), rect.height() - mid), Qt.AlignCenter, str(sub_text)) painter.restore()这段代码的核心是重写paintSection，在传入的rect里分两次drawText。第一行画 DisplayRole 的主标题，第二行画 UserRole 里的副标题。列号通过logicalIndex传入，数据源仍然走模型，不需要手工对齐列宽，这是它比方案二稳定的根本原因。代价是你得把数据源从 QTableWidget 换成 QTableView + QAbstractTableModel，模型层要自己维护headerData，工作量上了一个台阶。对只有两级表头的场景，我的建议是：列表短且基本不滚动的界面用方案二，数据量大或列可能动态增减的用方案三，方案一只适合临时展示。
5.4 表头文字显示 column_1 的三种来源
现象：表格运行起来，表头没有自定义文字，显示的是column_1、column_2这类默认列名。
来源有三个，按排查顺序列出来。第一，最直白的原因：setHorizontalHeaderLabels压根没调用。QTableWidget 默认会给每一列生成column_N的表头，只有显式设置后才会替换。第二，调用顺序错了：先执行setHorizontalHeaderLabels，后面又setModel或setColumnCount重设了列结构，默认表头又回来了。解决：把表头文字设置放在所有列结构和模型操作之后，或者封装一个refresh_headers()方法，列结构一变就调用它。第三，模型路径出问题：你用的是setModel方式，setHorizontalHeaderLabels只对 QTableWidget 自带的内部模型生效，换成 QTableView 后表头文字完全由模型的headerData决定。如果你在移植 QTableView，第一件事就是别指望 setHorizontalHeaderLabels，老老实实重写模型里的headerData(section, orientation, role)。
6. 表头截图验证脚本：把样式回归做进开发流程
美化类代码有个特点：改一个色值，肉眼看着不对，再改回来，但没人说得清「哪里不对」。表头样式更是如此，section 的背景渐变、排序箭头、边框粗细，这些细节在代码里很难靠 review 发现。我后来养成一个习惯：给表头写一个独立的截图验证脚本，把每次调整后的效果存成图片，对比着看。
脚本思路很简单：创建一份和真实窗口同尺寸的表格，加载同一套 QSS，填充固定测试数据，显示后截屏保存 PNG：
from PyQt5.QtWidgets import QApplication, QWidget, QTableWidget, QTableWidgetItem, QHBoxLayout from PyQt5.QtCore import Qt def dump_header_snapshot(qss_text, output_path="header_check.png"): app = QApplication.instance() or QApplication([]) w = QWidget() w.resize(720, 400) table = QTableWidget(5, 3, w) table.setHorizontalHeaderLabels(["任务名称", "创建时间", "执行状态"]) table.setStyleSheet(qss_text) header = table.horizontalHeader() header.setMinimumHeight(55) header.setStretchLastSection(True) # 固定测试数据：覆盖数字、长文本、空值三种情况 for row in range(5): table.setItem(row, 0, QTableWidgetItem(f"任务 {row + 1}")) table.setItem(row, 1, QTableWidgetItem("2024-11-02")) table.setItem(row, 2, QTableWidgetItem(["进行中", "已完成", "失败"][row % 3])) layout = QHBoxLayout(w) layout.addWidget(table) w.show() app.processEvents() pixmap = w.grab() # 把窗口内容绘制成 QPixmap pixmap.save(output_path) # 输出 PNG，用图片查看器对比 w.close() if __name__ == "__main__": dump_header_snapshot(HEADER_QSS)这个脚本的价值在于回归对比。你把HEADER_QSS存在项目里一份基线版本，每次改表头样式都重新生成一张 PNG。新旧两张图放一起，用看图软件逐像素对比，或者更省事一点，直接读两张图片的像素字节做 hash 比较。要保证对比有意义，表格尺寸、测试数据、字体必须固定，窗口缩放逻辑不能参与其中。带着这份截图再去看用户提的「表头丑」，你会飞快定位到是高度、颜色还是间距的问题，而不是坐在那里反复改代码重启看效果。
最后分享一个个人习惯：凡是涉及表头的需求，我先问一句「表头要不要排序，要不要拖拽，要不要右键菜单」，把这三个问题的答案定下来，再动手写代码。排序会影响 item 类型的选择，拖拽会影响索引设计，右键菜单影响列管理方式。先想清楚行为再谈美化，能省掉后期大量返工。希望帮到你。
本文还有配套的精品资源，点击获取
