简介QCustomPlot 是 Qt 框架下功能丰富的 2D 绘图类库面向需要在 C/Qt 项目中实现数据可视化的开发者尤其适合科学计算、数据分析与工程监控等场景。资源包内含 1 个 cpp 实现文件与 1 个 h 头文件共 2 个文件压缩包约 323KB前者承载绘图核心逻辑后者提供类接口与声明可直接集成进 Qt 工程使用。该库支持线图、散点图、柱状图、饼图及组合图表并具备实时数据更新、滚动缩放、鼠标交互、自定义多轴系统、图例插件与离屏渲染等能力对大数据量绘图还提供缓存优化。目前已有 583 人学习关注适合希望快速上手高质量图表组件、减少自绘工作量的 Qt 开发者参考也可作为理解 QWidget 派生绘图组件设计与信号槽交互机制的实践素材。1. qcustomplot为什么老工程师宁愿手写 2000 行绘图代码也不换库如果你做过 Qt 桌面端的数据采集、工控上位机或者实验数据分析软件大概率绕不开一个名字qcustomplot。它就是一个单文件、无额外依赖的 Qt 绘图控件两个文件 qcustomplot.h 和 qcustomplot.cpp 拖进工程就能用编译出来不依赖任何第三方动态库。听起来很朴素但它在实时曲线、多轴联动、光标追踪这些场景里的表现比很多看起来更现代的图表库都要稳。我见过不少团队一开始用 Qt Charts后来因为刷新率上不去、定制坐标轴太别扭又灰溜溜换回 qcustomplot。这不是玄学是 qcustomplot 把「数据容器 图层 绘制」这三件事拆得很清楚你可以在任意环节插手。这篇笔记面向的是需要把 qcustomplot 真正落到项目里的人怎么集成、怎么喂数据、怎么调性能、怎么避开那些让人熬夜的坑。新手能照着跑通最小示例熟手能拿到参数边界和排查思路。2. 把 qcustomplot 集成进工程从两个文件到第一条曲线2.1 为什么是「两个文件」而不是包管理器qcustomplot 的发布形态就是一个头文件加一个源文件没有 CMake config没有 pkg-config也不需要 vcpkg 或 conan。这种分发方式在今天看起来有点原始但它解决了一个很现实的问题跨平台交叉编译时不用折腾依赖链。你在 Windows 上用 MSVC、在 Linux 上用 GCC、在嵌入式板子上用交叉工具链只要 Qt 能编过qcustomplot 就能编过。常见做法是新建一个3rdparty/qcustomplot目录把两个文件放进去然后在.pro或CMakeLists.txt里加进去。用 qmake 的话# 目录结构 project/ ├── 3rdparty/ │ └── qcustomplot/ │ ├── qcustomplot.h │ └── qcustomplot.cpp ├── main.cpp └── project.pro# project.pro 关键片段 QT printsupport INCLUDEPATH $$PWD/3rdparty/qcustomplot HEADERS $$PWD/3rdparty/qcustomplot/qcustomplot.h SOURCES $$PWD/3rdparty/qcustomplot/qcustomplot.cpp这里QT printsupport是必须的因为 qcustomplot 的导出和打印功能依赖 QtPrintSupport 模块。很多人第一次编译报一堆QPrinter未定义就是漏了这一行。用 CMake 的话对应find_package(Qt5 COMPONENTS PrintSupport REQUIRED)然后target_link_libraries里加上Qt5::PrintSupport。提示如果你用的是 Qt6模块名是Qt6::PrintSupport同时 qcustomplot 需要选支持 Qt6 的版本分支老版本在 Qt6 下会因为QRegExp等 API 移除而编译失败。2.2 最小可运行示例一条正弦曲线集成完之后先别急着上实时数据用一条静态正弦曲线验证环境。下面这段代码可以直接放进main.cpp#include QApplication #include qcustomplot.h #include cmath int main(int argc, char *argv[]) { QApplication app(argc, argv); QCustomPlot *plot new QCustomPlot(); plot-resize(800, 500); // 准备数据x 从 0 到 2π200 个点 QVectordouble x(200), y(200); for (int i 0; i 200; i) { x[i] i / 200.0 * 2 * M_PI; y[i] std::sin(x[i]); } // addGraph 返回新图层的指针后续所有样式都改它 plot-addGraph(); plot-graph(0)-setData(x, y); plot-graph(0)-setPen(QPen(Qt::blue, 2)); // 坐标轴标签 plot-xAxis-setLabel(time (s)); plot-yAxis-setLabel(amplitude); // 自动缩放并重绘 plot-rescaleAxes(); plot-replot(); plot-show(); return app.exec(); }逻辑说明addGraph()每次调用会新增一个图层并返回索引graph(0)拿到第一个图层的指针。setData接收两个QVectordouble长度必须一致否则行为未定义。rescaleAxes()会根据所有图层的数据范围自动调整四个轴的范围replot()触发一次完整重绘。参数说明setPen里的QPen控制线宽和颜色线宽建议不超过 3太粗在密集数据下会糊成一片。resize只是初始尺寸实际布局交给 Qt 的布局管理器更稳妥。2.3 用布局管理器替代手动 resize上面用resize是为了让示例最短真实项目里应该把QCustomPlot放进QVBoxLayoutQWidget *central new QWidget(); QVBoxLayout *layout new QVBoxLayout(central); QCustomPlot *plot new QCustomPlot(central); layout-addWidget(plot); layout-setContentsMargins(0, 0, 0, 0); // 去掉边距让图占满setContentsMargins(0,0,0,0)这行很关键默认边距会让图四周留白看起来像没对齐。如果你发现曲线区域比预期小一圈先检查这里。3. 实时曲线怎么喂数据性能瓶颈和三个必调参数3.1 数据追加用 addData 还是 setData静态图用setData没问题但实时曲线每秒来几百上千个点如果每次都重建整个QVector再setData内存拷贝和重绘会直接把 CPU 吃满。正确做法是用addData追加// 假设采样线程通过信号槽把新点传过来 void onNewSample(double t, double v) { plot-graph(0)-addData(t, v); // 只保留最近 10 秒的数据防止内存无限增长 plot-graph(0)-data()-removeBefore(t - 10.0); // 让 x 轴跟着滚动 plot-xAxis-setRange(t - 10.0, t); plot-replot(QCustomPlot::rpQueuedReplot); }addData是 O(1) 追加removeBefore会删掉指定 x 之前的所有点。这两个操作配合内存占用就稳定在「10 秒数据量」这个量级。setRange手动控制 x 轴窗口比rescaleAxes高效得多因为后者每次都要遍历所有数据求极值。replot(QCustomPlot::rpQueuedReplot)是重点。默认的replot()是同步立即重绘如果数据来得比屏幕刷新快会积压大量重绘请求。rpQueuedReplot把重绘请求合并到事件循环里同一帧内多次调用只重绘一次。这个参数在高速场景下能把 CPU 占用降一半以上。3.2 三个必调参数刷新率、抗锯齿、数据量参数默认值高速场景建议影响replot 模式rpRefreshHintrpQueuedReplot合并重绘降 CPUsetAntialiasedtrue数据点 5000 时设 false关抗锯齿可提速 30% 以上setNotAntialiasedElements无aeAll 或按需精细控制哪些元素不抗锯齿数据点数无限制单图层 10000超过后重绘时间非线性上升抗锯齿是双刃剑。开着的时候曲线边缘平滑但每个像素都要做混合计算。当单图层数据超过 5000 点屏幕像素已经比数据点少抗锯齿的收益趋近于零这时候关掉它plot-setNotAntialiasedElements(QCP::aeAll); // 或者只对曲线关坐标轴文字保持抗锯齿 plot-setNotAntialiasedElements(QCP::aeGraphs);数据量控制是另一个关键。我一般会在数据源侧做降采样而不是把原始点全塞进去。比如传感器 1kHz 采样但屏幕宽度只有 1000 像素那每秒最多显示 1000 个点就够了。用「每 N 个点取一个」或者「取区间最大最小」的方式降采样能大幅减轻 qcustomplot 的负担。3.3 多线程采集时的数据传递采集线程不能直接调addData因为 qcustomplot 不是线程安全的。常见做法是用信号槽把数据传到 UI 线程// 采集线程 emit newData(t, v); // UI 线程槽函数 void onNewData(double t, double v) { // 这里已经在 UI 线程可以安全操作 plot plot-graph(0)-addData(t, v); // ... 范围调整和重绘 }如果数据频率很高信号槽本身也有开销。这时候可以用一个QVectorQPointF做缓冲采集线程往里写UI 线程用定时器每 30ms 取一次批量追加// UI 线程定时器30ms 触发一次 void onFlushTimer() { QVectorQPointF batch; { QMutexLocker locker(bufferMutex); batch.swap(pendingBuffer); // 交换避免拷贝 } if (batch.isEmpty()) return; plot-graph(0)-addData(batch); // ... 范围调整和重绘 }swap比逐个拷贝快得多而且锁的持有时间极短。这个模式在 10kHz 级别的数据下也能稳住。4. 坐标轴、光标与交互那些文档没写清楚的细节4.1 多 Y 轴和轴对齐qcustomplot 支持多个 Y 轴通过axisRect()-addAxis添加// 在右侧添加第二个 Y 轴 QCPAxis *yAxis2 plot-axisRect()-addAxis(QCPAxis::atRight); plot-graph(1)-setValueAxis(yAxis2); // 第二个图层用右轴 yAxis2-setLabel(pressure (Pa));关键点是setValueAxis要把图层绑定到新轴上否则它还是用默认的左轴。多轴场景下rescaleAxes会分别缩放每个轴但如果你手动设了范围就要注意两个轴的比例关系不然曲线看起来会「错位」。4.2 光标追踪和数值显示实时监控软件里鼠标悬停显示当前值是很常见的需求。qcustomplot 用QCPItemTracer实现QCPItemTracer *tracer new QCPItemTracer(plot); tracer-setGraph(plot-graph(0)); tracer-setGraphKey(0); tracer-setStyle(QCPItemTracer::tsCircle); tracer-setPen(QPen(Qt::red)); tracer-setBrush(Qt::red); tracer-setSize(8); // 鼠标移动时更新 tracer 位置 connect(plot, QCustomPlot::mouseMove, [](QMouseEvent *event) { double x plot-xAxis-pixelToCoord(event-pos().x()); tracer-setGraphKey(x); plot-replot(QCustomPlot::rpQueuedReplot); });pixelToCoord把屏幕像素转成数据坐标setGraphKey让 tracer 吸附到曲线上最近的 x 位置。注意setGraphKey内部会做一次查找数据量大时每次鼠标移动都调用会有卡顿。优化方式是用setGraphKey之前先判断 x 是否变化超过一个阈值。4.3 导出图片和打印qcustomplot 内置了savePng、saveJpg、savePdf等方法plot-savePng(output.png, 1920, 1080, 1.0, -1, 96);参数依次是文件名、宽度、高度、缩放因子、质量-1 表示默认、分辨率。导出 PDF 时用savePdf矢量输出放大不糊。如果导出后图片空白检查是不是在replot之前调用了savePngqcustomplot 需要先完成一次绘制才能拿到有效内容。5. qcustomplot 避坑记录五个让我熬夜的瞬间5.1 曲线不显示但数据明明加进去了现象addData调用成功graph(0)-dataCount()也大于零但界面上什么都没有。原因最常见的是坐标轴范围没覆盖数据。addData不会自动调整轴范围如果 x 轴还停在 0 到 5而数据是 100 到 200自然看不见。解决要么调rescaleAxes()要么手动setRange。排查时可以先打印graph(0)-data()-valueRange()看实际数据范围再对比xAxis-range()。5.2 实时刷新时界面卡死现象数据频率一高界面就不响应鼠标点不动。原因在 UI 线程里同步replot()而且数据来得比绘制快重绘请求堆积。解决改用rpQueuedReplot并且把数据追加和重绘解耦。如果还卡检查是不是在mouseMove这类高频事件里直接调了replot()改成定时器驱动重绘。5.3 内存持续增长直到崩溃现象跑几个小时后进程内存从几十兆涨到几个 G。原因addData只加不删数据点无限累积。每个QCPGraphData占几十字节每秒 1000 点跑一天就是几千万个点。解决每次追加后调removeBefore或removeAfter只保留窗口内的数据。如果业务需要保留历史把历史数据存到文件或数据库绘图只保留可视范围。5.4 多图层时图例颜色对不上现象图例里显示的颜色和曲线实际颜色不一致。原因图例默认取的是图层的 pen 颜色但如果你在addGraph之后又改了 pen图例不会自动更新。解决改完 pen 之后调legend-update()或者plot-replot()。更稳妥的做法是先设置好样式再添加图例项。5.5 在嵌入式平台上编译报错现象交叉编译时提示QPrinter找不到或者链接时缺QtPrintSupport。原因嵌入式 Qt 裁剪时经常去掉 PrintSupport 模块但 qcustomplot 默认包含打印相关代码。解决在qcustomplot.h里找到QT_NO_PRINTER宏编译时定义它可以去掉打印相关代码。或者确认交叉编译的 Qt 配置里包含了 PrintSupport。6. 进阶技巧用自适应降采样把万点曲线压到流畅前面提到数据量是性能瓶颈但很多时候你不能在数据源侧降采样因为原始数据要存下来做分析。这时候可以在绘图侧做自适应降采样根据当前 x 轴范围只把落在可视区间的点喂给 qcustomplot并且按像素密度抽稀。核心思路是屏幕宽度 W 像素那么最多需要 W 个点就能填满。如果可视区间内有 N 个点且 N W就按 N/W 的步长抽取。但简单等步长抽取会丢掉尖峰所以更稳的做法是「分桶取极值」把数据分成 W 个桶每个桶取最大值和最小值两个点。// 自适应降采样把 raw 数据压缩到不超过 maxPoints 个点 QVectorQPointF downsample(const QVectorQPointF raw, double xMin, double xMax, int maxPoints) { QVectorQPointF result; if (raw.isEmpty()) return result; // 先筛出可视区间内的点 QVectorQPointF visible; visible.reserve(raw.size()); for (const QPointF p : raw) { if (p.x() xMin p.x() xMax) visible.append(p); } if (visible.size() maxPoints) return visible; // 分桶每桶取最大最小 int bucketCount maxPoints / 2; double bucketWidth (xMax - xMin) / bucketCount; result.reserve(maxPoints); int idx 0; for (int b 0; b bucketCount; b) { double bStart xMin b * bucketWidth; double bEnd bStart bucketWidth; double minV std::numeric_limitsdouble::max(); double maxV std::numeric_limitsdouble::lowest(); double minX bStart, maxX bStart; while (idx visible.size() visible[idx].x() bEnd) { double v visible[idx].y(); if (v minV) { minV v; minX visible[idx].x(); } if (v maxV) { maxV v; maxX visible[idx].x(); } idx; } if (minV maxV) { result.append(QPointF(minX, minV)); result.append(QPointF(maxX, maxV)); } } return result; }逻辑说明先按 x 范围过滤再判断是否需要降采样。分桶时每桶保留最大和最小两个点这样尖峰不会被抹掉。idx只前进不后退整体是 O(N) 复杂度。参数说明maxPoints一般设成绘图区宽度的 2 到 4 倍。比如绘图区 800 像素宽maxPoints设 2000 到 3200 就够了。桶数取maxPoints / 2因为每桶输出两个点。调用时机是在xAxis-rangeChanged信号里或者定时器里根据当前范围重新计算connect(plot-xAxis, QOverloadconst QCPRange::of(QCPAxis::rangeChanged), [](const QCPRange newRange) { QVectorQPointF sampled downsample(rawData, newRange.lower, newRange.upper, 2000); plot-graph(0)-setData(sampled, true); // true 表示已经排序 plot-replot(QCustomPlot::rpQueuedReplot); });setData的第二个参数alreadySorted设为true可以跳过内部排序因为我们的降采样结果天然按 x 有序。这个细节能省掉一次 O(N log N) 排序。我自己的习惯是原始数据永远保留在内存或文件里绘图只操作降采样后的副本。这样缩放、平移都不会丢精度放大到局部时降采样自动变密看起来就是原始曲线。这套方案在 100 万点级别的数据上缩放和拖动都能保持 60fps 的流畅度。唯一要注意的是降采样本身有计算开销如果数据量特别大可以在数据追加时就维护一个多级降采样结构而不是每次范围变化都重算。希望帮到你。本文还有配套的精品资源点击获取