简介：针对Qt控件文本行间距调整的示例项目包，面向需要精细控制QLabel、QTextBrowser、QTextEdit文字排版与阅读体验的Qt开发者。包内通过一个完整可运行工程演示了三种控件的行距设置思路：QLabel借助setStyleSheet的line-height属性，QTextBrowser与QTextEdit则利用QTextDocument的setDefaultBlockFormat配合QTextBlockFormat行高因子；界面文件与图片资源一并提供，便于直接对照显示效果。压缩包共44个文件，以cpp/h源文件、ui界面定义、qrc资源文件为主，并包含生成的exe、obj、pdb等构建产物，整体约26.37MB，目录结构清晰，可在VS2017与Qt5.14.2环境下打开解决方案编译运行。目前已有1363人学习下载，适合初中级Qt开发者快速掌握文本布局控制方法，规避行间距调整不生效的常见问题，并迁移到日志展示、富文本编辑等实际场景。源码中的样式表和QTextDocument配置均可直接复用，有助于提升多行文本界面的可读性。
1. QtLabelLineSpacing 到底解决什么：QLabel 多行文本的行距之痛
做 Qt 桌面端时，我经常要在卡片、列表项、弹窗说明里放多行文本。用 QLabel 一摆，setWordWrap(true)一开，文字确实换行了，但行跟行之间挤得几乎没有缝隙。去查 QLabel 的成员函数，setText、setAlignment、setIndent全都有，唯独没有setLineSpacing。如果你还要在这种标签下面放一组按钮，整个 Qt 界面设计的排版就变得很难看。
这个问题背后其实藏着一个更麻烦的点：Qt Widgets 的 QLabel 并不是一个“不支持行距”的控件，而是它把行距控制能力放到了QTextDocument和QTextBlockFormat::setLineHeight这一层，对外没有暴露。于是大部分人会去 QSS 里写line-height，结果样式表里根本没有这个属性；有人去改字体、加 padding，也只是把整个标签撑大，行间距还是没动。
QtLabelLineSpacing.zip这个技术方向要解决的就是这件事：在不换用 QTextEdit、不放弃 QLabel 的前提下，把多行文本的行距真正调出来，并且能动态控制。它适合所有 Qt Widgets 从业者阅读，尤其适合正在封装自定义控件、做报表卡片、或者被“QSS 行高不生效”坑过的人。下面我按从原理到实现、再到踩坑的顺序，把这一整套做法讲清楚。
2. 先理解 QLabel 的行距机制：为什么 QSS 不管用、setLineHeight 在哪一层生效
2.1 QLabel 没有 setLineSpacing 接口，但富文本路径绕得过去
QLabel 对外只给了很少几个文本控制接口，setText和setWordWrap是最常用的。它内部其实维护了一个只读的 QTextDocument，由 QLabel 自己的私有布局类负责排版和绘制。QTextDocument 本身是支持行距控制的，但 QLabel 没有把这个能力暴露成公开 API。
这意味着你要么绕过 QLabel 的接口，直接给它喂“带行距信息的富文本”，让内部的 QTextDocument 自己解析；要么干脆把文本排版接管过来，自己用绘图事件画。前者的最小验证代码非常简单，一段 HTML 就能看出差别：
#include <QApplication> #include <QLabel> int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label; label.setTextFormat(Qt::RichText); label.setWordWrap(true); label.setText( "<p style=\"line-height:180%;\">" "第一行：这是标题行<br>" "第二行：这段描述用于观察行距是否变大。<br>" "第三行：如果 180% 生效，这里明显会宽松很多。" "</p>"); label.resize(360, 160); label.show(); return app.exec(); }这段代码的逻辑是先强制setTextFormat(Qt::RichText)，让 QLabel 把字符串当富文本解析，而不是当作纯文本原样显示；然后用<p style="line-height:180%">把行距设成字体行高的 1.8 倍。<br>负责在同一个段落内换行，这样三行文本会共享同一个段落属性，行距才会一致。
参数说明：line-height的 180% 是相对当前字体行高算的，100% 就是默认行高，200% 就是两倍行距。这个值由 QLabel 内部的 QTextDocument 读取，最终落到段落块格式上。如果你把它改成 100%，标签会立刻变得紧凑；改成 200%，三行文本的高度会明显增加。实际操作时可以先从 130% 起步，再按视觉效果微调。
2.2 setLineHeight 是真正的主角：三类行高参数拆解
富文本里line-height之所以能生效，是因为 Qt 的富文本解析器最终会把 CSS 里的行高信息转成一个底层对象：QTextBlockFormat。这个对象有一个关键方法setLineHeight(qreal height, int heightType)，它才是行距控制的真正入口。
line-height不是简单的一个“间距像素值”，它分四种模式，其中三种在实际工作中最常用：
| heightType 取值 | 含义 | 典型用法 |
|---|---|---|
ProportionalHeight | 行高按字体行高的百分比计算 | 100 是单倍行距，150 是 1.5 倍，适合常规文本 |
FixedHeight | 每行行高固定为指定像素值 | 适合等宽排版、坐标轴刻度、行高必须严格一致的场景 |
MinimumHeight | 行高保证至少为指定像素 | 防止行高因字体变大而塌陷 |
LineDistanceHeight | 在默认行高之上额外增加间距 | 微调行距，常见取 4~10 像素 |
我一般会把ProportionalHeight当成首选，因为它跟着字体走，用户换了系统字体或者改了缩放，行距比例不会崩。FixedHeight看着省心，但一旦字体被放大，两行文字就可能互相裁剪，这是个很典型的翻车点。LineDistanceHeight适合做精细微调，比如默认行距已经不错了，只差那么几像素的呼吸感。
2.3 为什么 QSS 里写 line-height 会翻车
很多新人第一次遇到这个问题，第一反应是去样式表里写：
QLabel { line-height: 180%; }结果编译不报错，程序也能跑，行距就是纹丝不动。原因在于 QSS 是 Qt Style Sheet 的缩写，它服务的是 QStyle 系统，负责的是控件的外观，比如背景色、边框、圆角。而 QLabel 的文本内容排版是由内部 QTextDocument 负责的，这两条链路根本不互通。
QTextDocument 解析的是富文本标签和样式属性，QSS 解析器看见line-height会直接忽略，因为它不在 QSS 支持的属性列表里。如果你之前也这么写过，建议记住一个判断方法：凡是和文字排版有关的属性，先查 Qt 富文本支持的 CSS 子集；凡是和控件外观有关的属性，才去查 QSS 文档。文字行距属于前者，别走错门。
3. 用 QtLabelLineSpacing 跑通最小工程：三套可复制的实现
3.1 最小工程结构：pro 文件与入口代码这样组织
无论你手上拿到的是别人打包好的 QtLabelLineSpacing 示例工程，还是想自己重新实现，一个能跑起来的 Widgets 工程结构越简单越好。常见做法是只保留四个文件，杜绝多余干扰：
| 文件 | 作用 |
|---|---|
QtLabelLineSpacing.pro | qmake 工程文件，声明 Qt 模块和源码 |
main.cpp | 程序入口，构建测试窗口 |
mainwindow.h | 主窗口声明（可选，示例越小越好） |
mainwindow.cpp | 主窗口实现（可选） |
我这个方案里，主窗口直接用一个 QWidget 容器代替，省掉 ui 文件，减少追代码的负担。pro 文件是最容易出问题的地方，参考写法如下：
QT += core gui widgets CONFIG += c++17 TARGET = QtLabelLineSpacing TEMPLATE = app SOURCES += \ main.cppQT += widgets这一行必须存在。如果你用的是 Qt 5.15.2 的 MSVC 2019 64 位套件，gui和widgets都不能少；只写QT += core gui构建时很容易报找不到 QWidget 头文件的错误。CONFIG += c++17是给新一点的自绘代码用的，如果你只跑富文本方案，C++14 也行。
3.2 方案 A：富文本 HTML 的 line-height 直接驱动 QLabel
这是最省事的一种做法，适合文本内容基本固定、不需要动态调整行距的界面。直接改main.cpp就能复现：
#include <QApplication> #include <QLabel> #include <QVBoxLayout> #include <QWidget> int main(int argc, char *argv[]) { QApplication app(argc, argv); QWidget window; window.setWindowTitle(QStringLiteral("QtLabelLineSpacing - HTML 方案")); QVBoxLayout *layout = new QVBoxLayout(&window); layout->setContentsMargins(24, 24, 24, 24); QLabel *cardLabel = new QLabel(&window); cardLabel->setTextFormat(Qt::RichText); cardLabel->setWordWrap(true); cardLabel->setText( "<p style=\"line-height:170%;\">" "第一行：卡片标题，用来模拟多行信息展示。<br>" "第二行：这里是描述内容，行距由 line-height 控制。<br>" "第三行：改成 170% 后，阅读压力明显下降。" "</p>"); layout->addWidget(cardLabel); window.resize(420, 220); window.show(); return app.exec(); }这段代码的逻辑是：QVBoxLayout 负责把标签撑满窗口宽度，setTextFormat(Qt::RichText)是开关，必须放在setText之前；line-height写在<p>标签上，而不是<span>上，因为 Qt 富文本解析器对块级元素的行高支持更可靠。
参数说明：170%是我在普通 Windows 界面下常用的值。如果你做的是数据密集的表格或日志面板，可以降到 130%；如果做的是面向用户的欢迎页、引导说明，180%~200% 反而更有呼吸感。要注意<br>必须放在<p>内部，否则换行后的文本会被算成新段落，行距表现会不一致。
3.3 方案 B：QTextDocument 生成文本块，走 LineDistanceHeight
HTML 方案虽然简单，但它有个隐患：Qt 各版本对富文本 CSS 的解析宽严不同，同一个line-height:170%在 Qt 5.12 和 Qt 6.2 上可能表现不一样。如果你需要更确定的像素级控制，常见做法是绕过字符串解析，直接用代码操作 QTextDocument 和 QTextBlockFormat。
#include <QApplication> #include <QLabel> #include <QTextDocument> #include <QTextCursor> #include <QTextBlockFormat> #include <QPixmap> #include <QPainter> void applyLineSpacingByDocument(QLabel *label, int extraSpacingPx) { if (!label) return; // 1. 构造独立文档，把标签当前文本拿进来 QTextDocument doc; QTextBlockFormat blockFormat; blockFormat.setLineHeight(extraSpacingPx, QTextBlockFormat::LineDistanceHeight); QTextCursor cursor(&doc); cursor.insertBlock(blockFormat); cursor.insertText(label->text()); // 2. 把排版结果绘制成透明位图 QPixmap pixmap(doc.size().toSize()); pixmap.fill(Qt::transparent); QPainter painter(&pixmap); doc.drawContents(&painter); painter.end(); // 3. 用位图替换原来的文本显示 label->setText(QString()); label->setPixmap(pixmap); } int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label; label.setText(QStringLiteral("第一行文字\n第二行文字\n第三行文字")); applyLineSpacingByDocument(&label, 10); label.resize(300, 140); label.show(); return app.exec(); }这段代码的关键步骤有三个。第一步，把原有文本塞进 QTextDocument，通过cursor.insertBlock(blockFormat)让当前块携带行距属性。这里用的是LineDistanceHeight，语义是在默认行高之上额外增加间距，参数值10就是额外增加 10 像素，视觉上比 HTML 方案更容易预估。
第二步比较反直觉：QLabel 没有暴露注入 QTextDocument 的接口，所以我用doc.drawContents把排版好的文档直接画到 QPixmap 上，再通过setPixmap显示。这等于让 QTextDocument 当排版引擎，QLabel 只做一个图像容器。代价是文本不再可选，也不会响应鼠标选择事件，所以它更适合固定样式的信息卡、徽标、流程提示。
参数建议：extraSpacingPx取 6~10 比较合适。小于 4 基本看不出变化，大于 16 会让整块文本看起来松散。窗口宽度变化后位图大小不会自适应，所以需要自己监听 resize 事件重新生成，这个边界必须知道。
3.4 方案 C：自绘 QLabel，把行距变成可动态调整的像素值
如果你最终要的是一个能像setLineSpacing(12)这样直接调用的控件，那就要走 Qt 绘图路线，自己接管 paintEvent。这是三种方案里最灵活、也最可控的一种，适合封装成项目通用组件。
#include <QApplication> #include <QLabel> #include <QPainter> #include <QTextLayout> #include <QTextOption> class LineSpacingLabel : public QLabel { public: explicit LineSpacingLabel(const QString &text, QWidget *parent = nullptr) : QLabel(text, parent) {} void setLineSpacing(int px) { m_extraSpacing = px; update(); // 触发重绘，行距立即生效 } protected: void paintEvent(QPaintEvent *) override { QPainter painter(this); painter.setFont(font()); painter.setPen(palette().color(QPalette::WindowText)); QRectF rc = contentsRect(); QTextLayout layout(text(), font()); QTextOption option; option.setWrapMode(QTextOption::WrapAtWordBoundaryOrAnywhere); layout.setTextOption(option); layout.beginLayout(); qreal y = 0; while (true) { QTextLine line = layout.createLine(); if (!line.isValid()) break; line.setLineWidth(rc.width()); line.setPosition(QPointF(0, y)); y += line.height() + m_extraSpacing; if (y > rc.height()) break; } layout.endLayout(); painter.translate(rc.topLeft()); layout.draw(&painter, QPointF(0, 0)); } private: int m_extraSpacing = 6; }; int main(int argc, char *argv[]) { QApplication app(argc, argv); LineSpacingLabel label(QStringLiteral("第一行：自绘控件\n第二行：行距可变\n第三行：每次重绘都生效")); label.setLineSpacing(12); label.resize(320, 130); label.show(); return app.exec(); }这段代码的核心是QTextLayout。它负责把字符串按给定宽度拆成视觉行，每一行以 QTextLine 对象表示。line.height()返回当前行的高度，我在它后面加上m_extraSpacing，这就相当于给每一行追加了额外行距。beginLayout和endLayout是 QTextLayout 排版过程的固定头尾，漏掉其中一个都会导致崩溃或白屏。
参数说明：m_extraSpacing的单位是像素，setLineSpacing(12)表示每行之间多出 12 像素。你别小看这个数字，12 像素在 96 DPI 的屏幕上已经能让文本变得非常宽松。这个方法的好处是不依赖富文本解析，也不生成位图，所以窗口拉伸后文本依然能按新宽度重新排版。缺点是QLabel原有的setPixmap、对齐方式等能力需要自己补，它更适合从零封装专用控件。
4. 行高参数怎么调才对：单位换算、富文本对齐与 QSS 补偿
4.1 三种行高类型的适用边界
在实际项目里，行距参数不是越大越好，也不是统一用ProportionalHeight就行。我把三类常用参数的边界整理成一张表，方便你选型：
| 行高类型 | 参数含义 | 推荐值 | 适合场景 | 注意点 |
|---|---|---|---|---|
ProportionalHeight | 字体行高的百分比 | 130~180 | 普通文本、卡片说明 | 跟随字体缩放，DPI 变化不会崩 |
FixedHeight | 固定像素行高 | 16~24 | 等宽文本、坐标轴 | 字体变大后行会互相覆盖 |
LineDistanceHeight | 额外间距像素 | 4~10 | 在默认行距基础上微调 | 值太小看不出变化，太大显得空 |
预览时我建议先设成ProportionalHeight看大方向，再切换到LineDistanceHeight做微调。比如 UI 稿要求正文行距是“默认行高再多 8 像素”，那就直接上LineDistanceHeight；如果 UI 稿要求“1.5 倍行距”，就用ProportionalHeight，避免自己用像素去反推。
4.2 富文本模式下 alignment 失效，用 text-align 找回来
这是 QLabel 用富文本行距时最容易踩的暗坑：代码里明明调了setAlignment(Qt::AlignCenter)，结果换成带line-height的 HTML 文本后，水平居中变成了左对齐。原因在于富文本段落自带对齐属性，它优先于 QLabel 的 alignment 设置在内部生效。
解决的写法是在段落样式里同时声明对齐方式：
label->setAlignment(Qt::AlignCenter); label->setTextFormat(Qt::RichText); label->setText( "<p style=\"line-height:160%; text-align:center;\">" "居中的标题<br>" "居中的描述信息" "</p>");参数说明：text-align:center只对块级元素<p>有效，别再试图把它放到<span>上。setAlignment(Qt::AlignCenter)依然保留，它控制的是整个 QLabel 内容在控件中的垂直位置，而text-align控制的是段落内部文字在容器宽度内的水平位置，两者各管一段，缺一个都会对不齐。
4.3 想继续用 QSS？只能靠 padding 做有限补偿
如果你的项目样式已经全部写在 QSS 里，为了一个行距去改代码会觉得很别扭，那也不是完全没办法。QSS 本身不支持line-height，但可以用上下 padding 去模拟一部分视觉效果：
QLabel#cardDesc { background-color: #f8f8f8; padding: 10px 0; font-size: 13px; }这段 QSS 的padding: 10px 0只能让文本整体在标签内部上下各留 10 像素，不能让文本行与行之间的距离变大。如果只有两行文本，视觉上确实会因为上下留白而显得没那么挤；但一旦超过三行，行间缝隙还是原样。
所以我的结论很明确：QSS 里加 padding 只适合“暂时救急”，不适合作为行距方案落地。凡是要认真控制多行文本排版的地方，直接用第 3 章里的 HTML 方案或自绘方案，别在样式表里跟自己较劲。
5. QtLabelLineSpacing 常见问题与排查：5 个高频翻车点
5.1 构建报错：dependent '..\qt\5.15.2\msvc2019_64\include\qtwidgets' not found
现象：在 Qt Creator 里打开工程后，构建时直接抛错，提示找不到 qtwidgets 相关头文件，错误行里能看到类似:-1: error: dependent '..\..\..\..\..\..\qt\5.15.2\msvc2019_64\include\qtwidgets' not found的信息。
原因：这个报错几乎都是.pro文件里 Qt 模块声明写错了。最常见的是把QT += widgets拼成QT += widget，或者漏写了widgets模块；其次是用的 Qt Kit 是 MSVC 2019 64 位，但.pro里声明的路径和实际安装路径不一致。
解决：先打开.pro文件，确认存在QT += core gui widgets这一行；然后在 Qt Creator 左侧选择正确的 Kit，一般选择 Qt 5.15.2 MSVC2019 64bit；最后执行一次qmake重新解析工程。这个报错和行距代码本身没有关系，属于白盒工程最基础的环境坑。
5.2<br>分行后 line-height 不生效
现象：HTML 里写了style="line-height:180%"，但只有第一行行距变了，<br>后面的行又贴在一起。
原因：<br>是换行标签，它不改变段落结构。如果line-height写在<p>上，所有被<br>拆开的行应该共享同一行高。出现“只有第一行生效”的情况，通常是 HTML 被拼成了这样：<p style="...">第一行</p><br>第二行。第二个<br>已经跑到段落外面了，第二行文字实际成了新段落，自然不继承前一段的行高。
解决：把整个多行文本放在同一个<p>标签内，<br>只负责换行，不要用<br>去结束段落。正确模板是<p style="line-height:180%">第一行<br>第二行<br>第三行</p>。如果文本里既有段落又有行间距，那就用两个<p>分别设置margin。
5.3 QSS 里写了 line-height:150% 却没反应
现象：样式表里给 QLabel 写了line-height:150%，程序运行后行距没有任何变化，检查样式表语法也没问题。
原因：QSS 支持的属性列表集中在背景、边框、盒子模型这些外观类属性上，文本排版属性不在其中。QLabel 内部的文本是交给 QTextDocument 绘制的，QSS 和 QTextDocument 是两个独立系统，QSS 里的line-height会被直接忽略，不报错也不生效。
解决：要么把行距写进 HTML 的style里，走富文本解析；要么放弃 QSS，用第 3 章的自绘方案。如果你只能在 QSS 里操作，就用padding做整体留白应急，但必须意识到它不能控制行与行之间的距离。
5.4 开启 wordWrap 后行距突然变大
现象：setWordWrap(true)之后，带行距设置的文本在窗口换行时，行距比预期大很多，甚至出现大片空白。
原因：QTextOption的自动换行会让文本在边界处拆成多行，而每一行都携带当前块的行高属性。如果line-height设置的是FixedHeight且值偏大，那么换行行数变多后，总高度被成倍放大；另一个原因是富文本内的空格和换行混在一起，Qt 解析时把多个连续空格当成了空块，空块也按行高计算。
解决：换行场景下优先使用ProportionalHeight，不要用固定像素；同时确保 HTML 里的文本没有多余换行符和连续空格。如果一定要固定像素，就参考LineDistanceHeight的小数值方案，只加 4~8 像素额外间距，翻车概率会低很多。
5.5 高分屏下固定像素行高偏矮
现象：在 100% 缩放的显示器上行距正常，一旦程序跑到 150% 缩放的 Windows 或 macOS 高分屏上，固定像素行距的文本看起来明显变挤。
原因：ProportionalHeight是跟着字体行高走的，天然适配 DPI；但你如果用了FixedHeight或LineDistanceHeight的固定像素值，Qt 在高 DPI 下虽然会缩放字体，却不会自动缩放你设置的行距像素数，比例自然失调。
解决：涉及高分屏适配时，统一使用百分比行高。比如ProportionalHeight的 150% 在任何 DPI 下都是字体行高的 1.5 倍。如果项目必须用像素控制，可以在setLineHeight传入时乘以当前屏幕的devicePixelRatio，代码里写成int realSpacing = baseSpacing * painter.device()->devicePixelRatio();，这样能避免绝大部分高分屏翻车。
6. 验证行距是否生效与进阶：给 QLabel 加一个 setLineSpacing 接口
6.1 用手动快照对比两版行距
调行距最怕“感觉生效了”但说不清差多少。我的习惯是先给 QLabel 切两个不同行距的文本，然后调用grab()输出图片，直接看图对比：
void compareLineSpacing(QLabel *label) { label->setTextFormat(Qt::RichText); label->setText( "<p style=\"line-height:100%;\">" "单倍行距对比<br>" "第二行文字" "</p>"); label->adjustSize(); label->grab().save("spacing_100.png"); label->setText( "<p style=\"line-height:180%;\">" "一点八倍行距对比<br>" "第二行文字" "</p>"); label->grab().save("spacing_180.png"); }这段代码先用 100% 行距生成一张基准图，再用 180% 生成对比图。保存成 PNG 后，放到看图软件里直接看两张图的行间距差。如果你连肉眼看图都想省，可以写一个简单扫描逻辑，按行扫描图片中有文字的像素区域，算出各行文字之间的空白间隔，用数值判断行距是否真的从 100% 变成了 180%。这个方法不依赖 Qt 内部状态，验证的是最终像素结果，最能说明问题。
6.2 进阶：给自绘 Label 暴露 setLineSpacing 接口
第 3 章的LineSpacingLabel已经实现了行距控制，但真正要做成项目通用控件，还需要给它补齐两个设计：一个是对外暴露的行距设置接口，另一个是更新后的文本变化通知。下面这个版本是我在卡片类控件里常用的最终形态：
class LineSpacingLabel : public QLabel { Q_OBJECT public: explicit LineSpacingLabel(const QString &text, QWidget *parent = nullptr) : QLabel(text, parent) { setWordWrap(true); } void setLineSpacing(int px) { if (m_extraSpacing == px) return; m_extraSpacing = px; updateGeometry(); // 让父布局重新计算高度 update(); } protected: void paintEvent(QPaintEvent *event) override { // 按 m_extraSpacing 逐行累加 y 的排版逻辑，参考第 3 章 } private: int m_extraSpacing = 6; };setLineSpacing接口里我加了一个if (m_extraSpacing == px) return;的短路判断，这是避免重复触发重绘的小优化。项目里如果这个控件被放在列表或卡片中，每次调用setLineSpacing都会导致updateGeometry()，父级布局会重新计算控件高度，这个行为很关键：因为行距变大，控件本身的高度也变大了，你不通知布局，文本就会被底部裁掉。
调用方式很简单：
LineSpacingLabel *label = new LineSpacingLabel( QStringLiteral("标题行\n描述行\n补充信息"), this); label->setLineSpacing(12);这样你就在不引入 QTextEdit、不改变 QLabel 使用习惯的前提下，得到了一个真正支持行距的标签控件。如果你还需要文本可复制、可选择，那就说明它已经超出了 QLabel 的能力边界，应该换用只读 QTextEdit 并隐藏边框背景，不要硬撑。
我在实际项目里最开始用的是 HTML 方案，因为它改动最小；后来卡片样式越接越多，需要根据状态动态切换行距，最终还是改成了自绘方案。回头看，路径是方案 A 验证想法、方案 C 定稿落地，中间被<br>和 alignment 这两个冤家坑了不少时间。希望这篇笔记能帮你少走这段弯路，一次把 QLabel 的行距问题解决干净。
本文还有配套的精品资源，点击获取
