Qt 绘画 Widget 详解：从基础到实战

在 Qt 框架中，“绘画 Widget” 是指基于 QWidget 及其子类，通过 Qt 绘图机制实现自定义图形绘制的组件。它核心解决了“默认控件无法满足个性化图形、动态效果、数据可视化”的需求——比如绘制自定义仪表盘、实时波形图、签名板、游戏角色等场景。Qt 绘图的本质是“事件驱动的按需渲染”，通过 QPainter（画笔）在 QWidget（画布）上执行绘制操作，整个过程轻量、跨平台（Windows/macOS/Linux 表现一致），且 API 设计简洁直观，是 Qt 界面开发中不可或缺的核心能力。

一、核心基础：Qt 绘图的“三驾马车”

要理解 Qt 绘画 Widget，首先需要掌握三个核心概念：QPainter、QPaintDevice、QPaintEngine。这三者构成了 Qt 绘图的底层框架，关系如同“画家（QPainter）在画布（QPaintDevice）上创作，依赖绘画技巧（QPaintEngine）实现效果”。

1. QPainter：绘图的“画笔与手”

QPainter 是 Qt 绘图的“执行者”，负责所有具体的绘制操作（如画线、画圆、填色、写文字）。它不需要手动分配/释放资源——在 paintEvent 中创建对象后，析构时会自动清理，避免内存泄漏。

核心能力：

设置绘制工具：通过 setPen()（设置轮廓样式，如线条颜色、宽度）、setBrush()（设置填充样式，如纯色、渐变）、setFont()（设置文字字体）定义绘制风格。执行绘制操作：提供 drawXXX() 系列方法，覆盖所有常见图形（如 drawLine 画直线、drawRect 画矩形、drawEllipse 画椭圆、drawText 写文字、drawPixmap 贴图片）。渲染优化：通过 setRenderHint() 开启抗锯齿（QPainter::Antialiasing）、文字平滑（QPainter::TextAntialiasing），让图形边缘更细腻（代价是轻微性能消耗，非极端场景推荐开启）。

简单示例（创建画笔）：


// 在 paintEvent 中创建 QPainter
QPainter painter(this); // “this” 指当前 Widget（画布）
painter.setRenderHint(QPainter::Antialiasing); // 开启抗锯齿

// 设置画笔（画轮廓）：红色、2px 宽、虚线
QPen pen(Qt::red, 2);
pen.setStyle(Qt::DashLine); // 虚线样式
painter.setPen(pen);

// 设置画刷（填充）：浅蓝色
QBrush brush(Qt::lightBlue);
painter.setBrush(brush);

// 画一个矩形（左上角坐标 (50,50)，宽 200，高 100）
painter.drawRect(50, 50, 200, 100);

2. QPaintDevice：绘图的“画布”

QPaintDevice 是“可被绘制的设备”的抽象基类，QWidget 正是它的子类——这也是“Widget 能被绘制”的根本原因。除了 QWidget，常见的 QPaintDevice 还包括：

QPixmap：设备相关的图像格式，适合屏幕显示（如加载图片、临时缓存绘制内容）。QImage：设备无关的图像格式，适合像素级操作（如修改图片某点颜色、图像算法处理）。QPicture：保存绘图指令的“脚本”，可再次加载并重新绘制（如保存绘制步骤，后续复用）。

对绘画 Widget 而言，QWidget 是最核心的画布——所有自定义图形最终都要绘制在 QWidget 上，才能被用户看到。

3. QPaintEngine：绘图的“底层引擎”

QPaintEngine 是 Qt 绘图的“底层渲染器”，负责将 QPainter 的指令翻译成具体平台的绘图接口（如 Windows 的 GDI、macOS 的 Quartz）。开发者无需直接操作 QPaintEngine——Qt 已封装好跨平台逻辑，确保同一套代码在不同系统上表现一致。

二、关键机制：Widget 绘图的“事件驱动”逻辑

Qt 绘画 Widget 的绘图不是“主动持续绘制”，而是“被动按需绘制”——只有当 Widget 满足“需要重绘”的条件时，才会触发绘图操作。这一机制能避免无效渲染，节省系统资源。

1. 触发重绘的场景

以下情况会让 Widget 进入“待重绘”状态：

Widget 首次显示（如窗口打开时）。Widget 被其他窗口遮挡后恢复显示（如最小化后还原）。调用 update() 或 repaint() 方法（开发者主动触发）。Widget 大小改变（如窗口拉伸时）。父 Widget 重绘时，子 Widget 也会被触发重绘。

2. 核心函数：`paintEvent()`

paintEvent() 是 QWidget 的虚函数，是 Widget 绘图的“入口”——所有自定义绘制代码都必须写在这个函数中。当 Widget 需要重绘时，Qt 会自动调用 paintEvent()，开发者只需重写它即可实现自定义图形。

注意事项：

禁止在 paintEvent() 外绘图：QPainter 必须在 paintEvent() 内创建（或关联当前 Widget 的绘图状态），否则会导致绘图失败或崩溃。避免耗时操作：paintEvent() 可能频繁触发（如动态图形每秒更新几十次），若在其中执行文件读写、复杂循环等耗时操作，会导致界面卡顿。update() 与 repaint() 的区别：
update()：延迟重绘（Qt 会合并短时间内的多次 update() 请求，只触发一次 paintEvent()），适合大多数场景，避免频繁渲染。repaint()：立即重绘（强制触发 paintEvent()），适合紧急场景（如动画帧刷新），但频繁调用可能导致闪烁，需谨慎使用。

3. 最小化示例：一个简单的绘画 Widget

下面通过一个完整示例，展示“重写 paintEvent() 实现自定义绘图”的基本流程：

步骤 1：创建自定义 Widget 类

新建一个继承 QWidget 的类 MyPaintWidget，重写 paintEvent()：


// MyPaintWidget.h
#include <QWidget>
#include <QPainter>

class MyPaintWidget : public QWidget
{
    Q_OBJECT
public:
    explicit MyPaintWidget(QWidget *parent = nullptr);

protected:
    // 重写 paintEvent 实现自定义绘图
    void paintEvent(QPaintEvent *event) override;
};

步骤 2：实现 `paintEvent()`

在 paintEvent() 中绘制“蓝色圆形+白色文字”：


// MyPaintWidget.cpp
MyPaintWidget::MyPaintWidget(QWidget *parent) : QWidget(parent)
{
    // 设置 Widget 大小（默认大小）
    setFixedSize(300, 300);
}

void MyPaintWidget::paintEvent(QPaintEvent *event)
{
    // 1. 创建画笔，关联当前 Widget（画布）
    QPainter painter(this);
    // 开启抗锯齿，让圆形边缘更平滑
    painter.setRenderHint(QPainter::Antialiasing);

    // 2. 绘制圆形（填充蓝色，无轮廓）
    QBrush brush(Qt::blue);
    painter.setBrush(brush);
    painter.setPen(Qt::NoPen); // 取消轮廓线
    // 圆形：圆心 (150,150)，半径 120
    painter.drawEllipse(150, 150, 120, 120);

    // 3. 绘制文字（白色，居中显示）
    QFont font;
    font.setPointSize(16); // 字体大小 16
    font.setBold(true); // 加粗
    painter.setFont(font);
    painter.setPen(Qt::white); // 文字颜色白色（此时 Pen 控制文字轮廓）

    // 文字区域：与 Widget 大小一致，实现居中
    QRect textRect(0, 0, 300, 300);
    painter.drawText(textRect, Qt::AlignCenter, "Qt 绘画 Widget");
}

步骤 3：使用自定义 Widget

在主窗口中添加 MyPaintWidget，运行后即可看到“蓝色圆形+居中白色文字”的效果：


// MainWindow.cpp
#include "MainWindow.h"
#include "MyPaintWidget.h"

MainWindow::MainWindow(QWidget *parent)
    : QMainWindow(parent)
{
    MyPaintWidget *paintWidget = new MyPaintWidget(this);
    setCentralWidget(paintWidget);
    setWindowTitle("简单绘画 Widget 示例");
    resize(300, 300);
}

三、核心功能：常见绘图需求的实现

Qt 绘画 Widget 支持几乎所有常见的图形绘制需求，以下是典型场景的实现方法，覆盖“基础图形、文字、图像、渐变”等核心能力。

1. 基础图形绘制

Qt 提供了 drawXXX() 系列方法，支持绘制直线、矩形、椭圆、圆弧、多边形、贝塞尔曲线等基础图形，核心参数多为 QPoint（点）或 QRect（矩形区域）。

图形类型	核心方法	关键参数说明
直线	`drawLine()`	两个 `QPoint`（起点、终点），如 `drawLine(QPoint(50,50), QPoint(250,50))`
矩形	`drawRect()`	`QRect(x, y, 宽, 高)`，如 `drawRect(50,50,200,100)`
椭圆	`drawEllipse()`	`QRect`（椭圆的外切矩形），如 `drawEllipse(100,100,200,150)`
圆弧	`drawArc()`	`QRect` + 角度（起始角度、跨度，单位：1/16 度），如 `drawArc(100,100,200,200, 9016, 18016)`（绘制右半圆）
多边形	`drawPolygon()`	`QPolygon`（多个点组成的闭合图形），如 `QPolygon({QPoint(150,50), QPoint(250,150), QPoint(50,150)})`（三角形）
贝塞尔曲线	`drawBezierCurve()`	`QPainterPath`（通过 `cubicTo()` 添加控制点），适合绘制平滑曲线

示例：绘制多种基础图形


void MyPaintWidget::paintEvent(QPaintEvent *event)
{
    QPainter painter(this);
    painter.setRenderHint(QPainter::Antialiasing);

    // 1. 画直线（红色，1px）
    painter.setPen(Qt::red);
    painter.drawLine(50, 50, 250, 50);

    // 2. 画矩形（蓝色填充，黑色轮廓）
    painter.setPen(Qt::black);
    painter.setBrush(Qt::blue);
    painter.drawRect(50, 70, 200, 80);

    // 3. 画椭圆（黄色填充，无轮廓）
    painter.setPen(Qt::NoPen);
    painter.setBrush(Qt::yellow);
    painter.drawEllipse(100, 180, 100, 60);

    // 4. 画三角形（绿色填充，黑色轮廓）
    painter.setPen(Qt::black);
    painter.setBrush(Qt::green);
    QPolygon triangle;
    triangle << QPoint(150, 260) << QPoint(200, 320) << QPoint(100, 320);
    painter.drawPolygon(triangle);
}

2. 文字绘制

文字绘制通过 drawText() 实现，核心是控制“文字内容、位置、字体、对齐方式”，适合实现“标签、数据显示”等需求。

关键控制项：

字体：通过 QFont 设置字体名称（如“微软雅黑”）、大小、粗细（QFont::Bold）、斜体（QFont::Italic）。位置与对齐：通过 QRect 定义文字的显示区域，配合 Qt::Alignment 枚举（如 Qt::AlignLeft、Qt::AlignCenter、Qt::AlignBottom）实现对齐。颜色：通过 setPen() 设置文字颜色（文字的“轮廓”即文字本身，无需画刷）。

示例：绘制带样式的文字


void MyPaintWidget::paintEvent(QPaintEvent *event)
{
    QPainter painter(this);
    painter.setRenderHint(QPainter::TextAntialiasing); // 文字抗锯齿

    // 1. 标题文字（24号、加粗、红色、居中）
    QFont titleFont("微软雅黑", 24, QFont::Bold);
    painter.setFont(titleFont);
    painter.setPen(Qt::red);
    QRect titleRect(0, 20, 300, 40); // 文字区域：宽300，高40
    painter.drawText(titleRect, Qt::AlignCenter, "Qt 绘图示例");

    // 2. 正文文字（14号、常规、黑色、左对齐）
    QFont contentFont("微软雅黑", 14);
    painter.setFont(contentFont);
    painter.setPen(Qt::black);
    QRect contentRect(30, 80, 240, 60); // 多行文字区域
    QString content = "这是一段测试文字n支持换行显示";
    painter.drawText(contentRect, Qt::AlignLeft | Qt::AlignTop, content);
}

3. 图像绘制

图像绘制主要通过 drawPixmap()（绘制 QPixmap）和 drawImage()（绘制 QImage）实现，适合加载本地图片、显示动态图像（如视频帧）。

两者区别：

QPixmap：设备相关，存储在显卡内存中，加载和显示速度快，适合屏幕显示（如 Widget 背景图、图标）。QImage：设备无关，存储在系统内存中，支持像素级操作（如修改某点颜色），适合图像处理（如灰度化、滤镜）。

示例：加载并绘制图片


void MyPaintWidget::paintEvent(QPaintEvent *event)
{
    QPainter painter(this);

    // 1. 加载本地图片（注意路径：若图片在资源文件中，路径为 ":/images/test.png"）
    QPixmap pixmap("test.png"); // 本地图片路径（需确保图片存在）
    if (pixmap.isNull()) { // 检查图片是否加载成功
        painter.drawText(50, 50, "图片加载失败");
        return;
    }

    // 2. 绘制原图（左上角 (20,20)）
    painter.drawPixmap(20, 20, pixmap);

    // 3. 绘制缩放后的图片（缩放到 100x100，左上角 (150,20)）
    painter.drawPixmap(150, 20, 100, 100, pixmap);
}

4. 渐变与纹理填充

除了纯色填充，Qt 还支持“渐变填充”和“纹理填充”，让图形更具视觉效果，适合自定义控件（如仪表盘、进度条）。

（1）渐变填充

Qt 提供四种渐变类型，核心类是 QGradient 及其子类：

线性渐变（QLinearGradient）：从一个点到另一个点的渐变（如从左到右、从上到下）。径向渐变（QRadialGradient）：从圆心到圆周的渐变（如圆形渐变）。角度渐变（QConicalGradient）：围绕圆心的环形渐变（如色轮）。锥形渐变（QGradient）：类似角度渐变，但颜色过渡更平缓。

示例：线性渐变填充矩形


void MyPaintWidget::paintEvent(QPaintEvent *event)
{
    QPainter painter(this);
    painter.setRenderHint(QPainter::Antialiasing);

    // 1. 创建线性渐变：从 (50,50) 到 (250,150)
    QLinearGradient linearGrad(QPoint(50,50), QPoint(250,150));
    // 添加颜色停止点（0.0 是起点，1.0 是终点）
    linearGrad.setColorAt(0.0, Qt::red);    // 起点红色
    linearGrad.setColorAt(0.5, Qt::yellow); // 中间黄色
    linearGrad.setColorAt(1.0, Qt::blue);   // 终点蓝色

    // 2. 用渐变作为画刷，绘制矩形
    painter.setBrush(linearGrad);
    painter.setPen(Qt::NoPen);
    painter.drawRect(50, 50, 200, 100);
}

（2）纹理填充

纹理填充是用图片作为画刷，让图形填充为“重复的图片纹理”，核心是通过 QBrush::setTexture() 设置纹理图片。

示例：纹理填充椭圆


void MyPaintWidget::paintEvent(QPaintEvent *event)
{
    QPainter painter(this);
    painter.setRenderHint(QPainter::Antialiasing);

    // 1. 加载纹理图片（小尺寸图片，会自动重复填充）
    QPixmap texture("texture.png"); // 纹理图片（如 50x50 的小图案）
    if (texture.isNull()) {
        painter.drawText(50, 50, "纹理图片加载失败");
        return;
    }

    // 2. 用纹理作为画刷，绘制椭圆
    QBrush textureBrush;
    textureBrush.setTexture(texture); // 设置纹理
    painter.setBrush(textureBrush);
    painter.setPen(Qt::black);
    painter.drawEllipse(100, 100, 200, 150);
}

四、实战进阶：动态绘图与性能优化

实际开发中，绘画 Widget 常需实现“动态效果”（如实时波形、旋转的指针），此时需兼顾“视觉流畅度”和“性能”，避免界面卡顿或闪烁。

1. 动态绘图：以“实时波形图”为例

动态绘图的核心是“定时更新数据 + 触发重绘”，通常用 QTimer 定时修改绘制数据，再调用 update() 触发 paintEvent()。

需求：绘制实时更新的正弦波形，X 轴为时间，Y 轴为振幅（-100~100）。

实现步骤：

添加成员变量：存储波形数据（QVector<QPointF>）、定时器（QTimer）、X 轴偏移量（控制波形滚动）。


// MyPaintWidget.h 中添加
private:
    QVector<QPointF> m_waveData; // 波形数据
    QTimer *m_timer;             // 定时器
    qreal m_xOffset;             // X 轴偏移量

初始化定时器与数据：定时器每秒触发 50 次（刷新频率 50Hz），每次生成一个新的正弦值，添加到数据列表中。


// MyPaintWidget.cpp 构造函数
MyPaintWidget::MyPaintWidget(QWidget *parent) : QWidget(parent)
{
    setFixedSize(600, 200);
    m_xOffset = 0;

    // 初始化定时器：50Hz 刷新
    m_timer = new QTimer(this);
    m_timer->setInterval(20); // 20ms 一次，1000/20=50Hz
    connect(m_timer, &QTimer::timeout, this, &MyPaintWidget::updateWaveData);
    m_timer->start();
}

// 定时器槽函数：更新波形数据
void MyPaintWidget::updateWaveData()
{
    // 生成正弦值（Y 轴：sin(x) * 80，范围 -80~80）
    qreal x = m_xOffset;
    qreal y = qSin(x * 0.1) * 80; // 0.1 控制波长，80 控制振幅
    // 转换为 Widget 坐标（Y 轴原点在 Widget 顶部，需反转）
    QPointF point(x, 100 - y); // 100 是 Widget 高度的一半（200/2）

    // 添加新数据，移除超出 Widget 宽度的数据（避免数据量过大）
    m_waveData.append(point);
    while (m_waveData.size() > 0 && m_waveData.first().x() < 0) {
        m_waveData.removeFirst();
    }

    // X 轴偏移量增加，实现波形滚动
    m_xOffset += 2;
    // 触发重绘
    update();
}

重写 paintEvent() 绘制波形：


void MyPaintWidget::paintEvent(QPaintEvent *event)
{
    QPainter painter(this);
    painter.setRenderHint(QPainter::Antialiasing);

    // 1. 绘制坐标轴（X 轴、Y 轴）
    painter.setPen(Qt::gray);
    painter.drawLine(0, 100, 600, 100); // X 轴（中间线）
    painter.drawLine(0, 20, 0, 180);   // Y 轴（左侧线）

    // 2. 绘制波形（蓝色，2px 宽）
    if (m_waveData.size() < 2) return; // 数据不足时不绘制
    painter.setPen(QPen(Qt::blue, 2));
    painter.drawPolyline(m_waveData.data(), m_waveData.size());
}

运行后，即可看到“蓝色正弦波形从右向左滚动”的动态效果，且数据量始终控制在 Widget 宽度范围内，避免性能下降。

2. 性能优化技巧

当绘制内容复杂（如大量图形元素）或刷新频率高（如 60Hz 动画）时，需通过以下技巧优化性能：

（1）区域重绘：只重绘变化的部分

默认 update() 会重绘整个 Widget，若只有局部变化（如波形图只有右侧新增部分变化），可通过 update(const QRect &rect) 只重绘变化区域：


// 只重绘右侧 2px 宽的区域（波形新增部分）
update(QRect(598, 0, 2, 200));

（2）双缓冲绘图：避免闪烁

Qt 对 QWidget 已默认启用双缓冲（先在内存中绘制，再一次性显示到屏幕），但自定义复杂绘制时，可手动实现双缓冲进一步优化：


void MyPaintWidget::paintEvent(QPaintEvent *event)
{
    // 1. 创建内存画布（QPixmap），大小与 Widget 一致
    QPixmap buffer(size());
    // 2. 在内存画布上绘制所有内容
    QPainter bufferPainter(&buffer);
    bufferPainter.setRenderHint(QPainter::Antialiasing);
    // ...（绘制坐标轴、波形等代码，与之前一致，只是画笔关联 buffer）

    // 3. 将内存画布一次性绘制到 Widget 上
    QPainter painter(this);
    painter.drawPixmap(0, 0, buffer);
}

（3）减少绘制指令

合并同类图形：如多个相邻的直线，可合并为 QPainterPath 一次性绘制，减少 drawLine() 调用次数。避免重复绘制：如静态背景（坐标轴）可绘制到 QPixmap 中缓存，每次重绘时直接复用，无需重新绘制背景。

（4）关闭不必要的渲染提示

抗锯齿（Antialiasing）会增加计算量，若对图形边缘精度要求不高（如工程图纸），可关闭抗锯齿：


// 关闭抗锯齿，提高绘制速度
painter.setRenderHint(QPainter::Antialiasing, false);

五、总结：Qt 绘画 Widget 的核心价值

Qt 绘画 Widget 基于 QPainter–QPaintDevice 架构，通过“事件驱动的按需渲染”实现自定义图形绘制，其核心价值体现在：

易用性：API 封装简洁，无需关注底层平台差异，同一套代码可在多系统运行。灵活性：支持从基础图形到动态波形、渐变纹理的全场景绘制需求，能满足几乎所有自定义控件开发。高性能：通过事件驱动、区域重绘、双缓冲等机制，在保证视觉效果的同时，避免无效渲染。可扩展性：可与 Qt 其他模块无缝结合（如 QTimer 实现动态效果、QThread 处理耗时数据计算、QGraphicsView 实现复杂图元交互）。

无论是开发简单的自定义按钮、复杂的仪表盘，还是实时数据可视化界面，Qt 绘画 Widget 都是最核心、最可靠的技术选择。掌握 paintEvent()、QPainter 的使用，以及动态绘图的优化技巧，就能轻松实现各类个性化图形需求。

文章版权归作者所有，未经允许请勿转载。如内容涉嫌侵权，请在本页底部进入<联系我们>进行举报投诉!

THE END