PySide6中QFontMetrics绘制多行文本时行间距额外空间问题排查

阿华AIGC实验室

2026-4-27

解答：QFontMetrics多行文本边界矩形额外高度的来源

你遇到的这个额外像素（或浮点数值）问题，本质上是Qt字体排版引擎的自动对齐规则和字体内部排版特性共同作用的结果，下面分两种情况详细解释：

一、整数像素版本(QFontMetrics)的1像素额外空间

看你的测试代码，单行文本高度是17，两行却得到35而不是34，这个额外的1像素来自：

整数像素对齐要求：在非高DPI屏幕下，Qt会强制文本的基线、行高对齐到整数像素位置。当计算多行文本的整体边界时，引擎会向上取整调整整体高度，确保文本块在视觉上不会出现模糊或错位。
文本块的整体边距：boundingRect对于多行文本的计算，不是简单的单行高度叠加——它会为整个文本块添加微小的顶部/底部边距，保证文本在容器中的视觉对齐，这个边距在单行文本中不明显，但多行时会累积体现。

你可以验证：metrics.lineSpacing()等于ascent() + descent() + leading()（14+3+0=17），但两行的实际高度是17*2 +1，这个1就是对齐和边距的总和。

二、浮点版本(QFontMetricsF)的数值差异

切换到QFontMetricsF后，数值差异依然存在，比如两行文本高度是34.8125，而理论计算的lineSpacing()*2是34.46875，这个差值来自：

字体的行间隙(Line Gap)：Qt的leading()是lineSpacing() - height()，但部分字体内部还存在未被leading()完全覆盖的行间隙，当排版多行文本时，引擎会把这个间隙计算到整体边界中。
文本布局的原点调整：boundingRect的计算会基于文本块的排版原点，而非单行的顶部，因此会包含额外的微小偏移，导致整体高度和理论叠加值不一致。

三、如何查看和控制这个额外空间？

1. 查看额外空间的具体数值

你可以通过计算多行与单行高度的差值来直接获取：

# 整数版本
single_height = metrics.boundingRect(0,0,100,100,0,'A').height()
multi_height = metrics.boundingRect(0,0,100,100,0,'A\nB').height()
extra_space = multi_height - single_height*2
print(extra_space) # 输出1

# 浮点版本
single_height_f = metrics.boundingRect(QRectF(0,0,100,100),0,'A').height()
multi_height_f = metrics.boundingRect(QRectF(0,0,100,100),0,'A\nB').height()
extra_space_f = multi_height_f - single_height_f*2
print(extra_space_f) # 输出约1.1875

2. 精确控制行间距的方法

如果需要完全符合预期的行间距，不要依赖boundingRect的自动计算，推荐两种方式：

手动绘制并控制行位置

直接使用QPainter逐行绘制，用lineSpacing()精确控制行间距：

from PySide6.QtGui import QPainter, QFont, QFontMetrics
from PySide6.QtWidgets import QWidget, QApplication

class TextWidget(QWidget):
    def paintEvent(self, event):
        painter = QPainter(self)
        font = QFont()
        metrics = QFontMetrics(font)
        lines = ['A', 'B']
        y = 0
        for line in lines:
            # 用ascent()确保文本基线对齐
            painter.drawText(10, y + metrics.ascent(), line)
            y += metrics.lineSpacing() # 精确控制行间距

if __name__ == "__main__":
    app = QApplication([])
    w = TextWidget()
    w.show()
    app.exec()

这种方式下，两行文本的总高度会是metrics.lineSpacing() + metrics.height()，完全符合理论计算值。

使用QTextLayout进行精确排版

对于复杂文本布局，QTextLayout可以让你完全控制每一行的排版参数：

from PySide6.QtGui import QTextLayout, QTextOption, QFont, QFontMetricsF
from PySide6.QtWidgets import QApplication

app = QApplication([])
font = QFont()
layout = QTextLayout("A\nB", font)
layout.setTextOption(QTextOption(QTextOption.AlignLeft))
layout.beginLayout()
while True:
    line = layout.createLine()
    if not line.isValid():
        break
    line.setLineWidth(100)
layout.endLayout()

# 获取精确的边界矩形
bounding_rect = layout.boundingRect()
print(bounding_rect.height()) # 这个值会更接近理论计算的34.046875