QPainter文本绘制进阶：精准区域控制与智能换行策略

1. 从基础到进阶：QPainter文本绘制核心问题

在Qt自定义UI开发中，文本绘制是最基础却最容易踩坑的功能点。很多开发者最初接触QPainter::drawText()时，往往满足于简单的单行文本渲染，直到遇到实际项目中的三大经典难题：

1. 文本溢出：当文字内容超过限定区域宽度时，默认会直接截断或溢出显示
2. 布局失控：需要动态调整控件高度以适应不同长度的文本内容
3. 性能瓶颈：复杂文本布局（如富文本）导致渲染效率下降

我曾在开发一个智能信息卡片组件时，就遇到过这样的场景：卡片宽度固定为300px，但内容可能是10个字的标题，也可能是200字的产品描述。最初使用最简单的drawText实现，结果长文本直接溢出到相邻控件区域，导致整个界面布局混乱。

1.1 Qt文本绘制的基础方案

先快速回顾三种基础实现方式。最简方案是使用带Qt::TextWordWrap标志的drawText：

cpp复制QRectF rect(0, 0, 300, 300);
QString text = "This is a long text...";
painter.drawText(rect, Qt::TextWordWrap, text);

这种方式适合固定高度的容器，但存在明显缺陷：

• 无法精确控制换行位置
• 当文本超过容器高度时，底部内容会被裁剪
• 不支持复杂文本格式（如混合字体样式）

第二种方案通过QTextOption提供更灵活的换行策略：

cpp复制QTextOption option;
option.setWrapMode(QTextOption::WrapAtWordBoundary);
painter.drawText(rect, text, option);

这里WrapMode有几个关键选项：

• NoWrap：禁止换行（默认）
• WordWrap：在单词边界换行
• WrapAnywhere：任意位置换行
• WrapAtWordBoundaryOrAnywhere：优先在单词边界换行

2. 动态高度计算与精准布局

实际项目中最棘手的问题是：如何让控件高度自动适应文本内容？这需要结合QFontMetrics进行精确测量。

2.1 文本测量基础技术

通过QFontMetrics可以获取关键文本尺寸信息：

cpp复制QFontMetrics metrics(painter.font());
int singleLineHeight = metrics.height();  // 单行文本高度
int textWidth = metrics.horizontalAdvance(text);  // 文本总宽度

当我们需要在固定宽度区域内显示文本时，可以这样计算所需高度：

cpp复制int requiredHeight = 0;
int availableWidth = 300;

if(textWidth <= availableWidth) {
    requiredHeight = singleLineHeight;
} else {
    int lineCount = ceil(textWidth / (double)availableWidth);
    requiredHeight = lineCount * singleLineHeight;
}

但这种方法存在明显误差，因为它假设所有行的文本都完全填满宽度。实际换行后的文本布局往往会有空白区域。

2.2 精确的多行文本高度计算

更准确的方案是使用QTextLayout进行专业排版计算：

cpp复制QTextLayout layout(text, painter.font());
QTextOption option;
option.setWrapMode(QTextOption::WordWrap);
layout.setTextOption(option);

layout.beginLayout();
qreal height = 0;
while(true) {
    QTextLine line = layout.createLine();
    if(!line.isValid()) break;
    
    line.setLineWidth(availableWidth);
    line.setPosition(QPointF(0, height));
    height += line.height();
}
layout.endLayout();

这种方式的优势在于：

• 考虑字体metrics的实际测量值
• 处理标点符号、空格等特殊字符更精确
• 支持混合字体和复杂文本方向

3. 高级文本布局策略

当需要实现更复杂的文本布局时（如图文混排、富文本显示），就需要用到QTextDocument这套专业排版引擎。

3.1 使用QTextDocument实现富文本

cpp复制QTextDocument doc;
doc.setDefaultFont(painter.font());
doc.setDefaultTextOption(textOption);
doc.setHtml("<b>Hello</b> <i>World</i>");

doc.setTextWidth(availableWidth);
qreal docHeight = doc.size().height();

painter.translate(0, 0);
doc.drawContents(&painter);

关键点在于：

• 通过setTextWidth设置文档宽度
• size()返回的height是自动计算的总高度
• 支持HTML标签、CSS样式等富文本特性

3.2 性能优化技巧

在需要频繁刷新的场景下（如实时数据展示），文本布局可能成为性能瓶颈。以下是几个实测有效的优化方案：

1. 缓存布局结果：对静态文本内容，只需在首次计算布局
2. 分级渲染：对超长文本可以先渲染可视区域
3. 字体预处理：提前创建并复用QFont对象

cpp复制// 缓存示例
struct CachedText {
    QString content;
    QSizeF size;
    QPixmap cache;
};

void renderText(QPainter* painter, const CachedText& cached) {
    if(cached.size != painter->viewport().size()) {
        // 重新计算布局
    } else {
        painter->drawPixmap(0, 0, cached.cache);
    }
}

4. 实战：智能标签组件的完整实现

结合上述技术，我们来实现一个完整的智能标签组件。该组件需要：

• 宽度固定，高度自适应
• 支持文本自动换行
• 带背景色和圆角边框
• 优化渲染性能

4.1 类定义与成员变量

cpp复制class SmartLabel : public QWidget {
    Q_OBJECT
public:
    explicit SmartLabel(QWidget* parent = nullptr);
    void setText(const QString& text);
    
protected:
    void paintEvent(QPaintEvent*) override;
    QSize sizeHint() const override;

private:
    QString m_text;
    QSize m_cachedSize;
    mutable QPixmap m_cache;
    bool m_cacheValid = false;
    
    void updateLayout(const QSize& available);
};

4.2 核心绘制逻辑

cpp复制void SmartLabel::paintEvent(QPaintEvent*) {
    QPainter painter(this);
    
    if(!m_cacheValid || m_cachedSize != size()) {
        updateLayout(size());
    }
    
    // 绘制背景
    painter.setRenderHint(QPainter::Antialiasing);
    painter.setBrush(QColor(240, 240, 245));
    painter.drawRoundedRect(rect(), 8, 8);
    
    // 绘制缓存文本
    painter.drawPixmap(0, 0, m_cache);
}

void SmartLabel::updateLayout(const QSize& available) {
    m_cache = QPixmap(available);
    m_cache.fill(Qt::transparent);
    
    QPainter cachePainter(&m_cache);
    QTextDocument doc;
    doc.setDefaultFont(font());
    
    QTextOption option;
    option.setWrapMode(QTextOption::WrapAtWordBoundary);
    doc.setDefaultTextOption(option);
    
    doc.setPlainText(m_text);
    doc.setTextWidth(available.width() - 20);  // 留边距
    
    doc.drawContents(&cachePainter);
    m_cachedSize = available;
    m_cacheValid = true;
    
    updateGeometry();  // 触发sizeHint更新
}

4.3 动态布局处理

cpp复制QSize SmartLabel::sizeHint() const {
    if(!m_cacheValid) {
        const_cast<SmartLabel*>(this)->updateLayout(QSize(width(), 1000));
    }
    
    QTextDocument doc;
    doc.setDefaultFont(font());
    doc.setPlainText(m_text);
    doc.setTextWidth(width() - 20);
    
    return QSize(width(), doc.size().height() + 20);
}

这个实现的关键优势在于：

1. 使用QTextDocument自动处理所有文本布局
2. 通过缓存机制避免重复计算
3. 正确的sizeHint实现让父布局能自动调整高度

5. 疑难问题解决方案

在实际项目中，还会遇到一些特殊场景需要处理：

5.1 混合字体文本高度计算

当文本中包含不同字号的文字时（如标题+正文），简单的QFontMetrics计算会产生偏差。这时需要：

cpp复制QTextDocument doc;
doc.setHtml("<h1>Title</h1><p>Content...</p>");
doc.setTextWidth(width());

qreal totalHeight = 0;
for(QTextBlock block = doc.begin(); block != doc.end(); block = block.next()) {
    QTextLayout* layout = block.layout();
    totalHeight += layout->boundingRect().height();
}

5.2 文本省略与截断处理

在空间有限时，可能需要显示省略号：

cpp复制QFontMetrics metrics(font());
QString elidedText = metrics.elidedText(text, Qt::ElideRight, availableWidth);

对于多行文本省略，需要更复杂的处理：

cpp复制QTextLayout layout(text, font());
layout.setTextOption(option);

QStringList lines;
layout.beginLayout();
while(true) {
    QTextLine line = layout.createLine();
    if(!line.isValid() || lines.count() >= maxLines) break;
    
    line.setLineWidth(width());
    QString lineText = text.mid(line.textStart(), line.textLength());
    if(lines.count() == maxLines - 1) {
        lineText = metrics.elidedText(lineText, Qt::ElideRight, width());
    }
    lines.append(lineText);
}
layout.endLayout();

6. 性能对比与方案选型

不同方案在1000次文本布局操作中的耗时对比（测试环境：i7-11800H）：

选择建议：

• 简单文本：优先使用drawText+QTextOption
• 动态布局：使用QTextLayout精确控制
• 富文本：必须使用QTextDocument
• 性能敏感：采用预渲染+缓存策略

在最近的一个工业HMI项目中，我们通过将关键文本控件改为缓存方案，界面刷新率从30fps提升到了60fps，效果非常明显。特别是在使用嵌入式设备（如树莓派）时，这种优化更为重要。