简介一份基于QT与QCustomPlot实现瀑布图的示例工程面向需要掌握交互式二维图表开发的C/QT开发者尤其适合入门QCustomPlot自定义绘图也适用于财务分析、项目管理等需要呈现数据变化场景的交叉领域。示例基于随机数模拟数据用矩形高度表示数值、颜色区分正负完整覆盖数据结构设计、坐标轴与图层配置、逐层绘制、连接线生成以及定时器驱动的动态递增效果。压缩包共36个文件、约6.08MB以cpp/h源代码、qcustomplot扩展库、ui界面、pro工程文件和Makefile为主并附有release/debug目录和可执行exe既可直接观察运行效果也便于对照源码断点调试。工程同时提供MinGW与MSVC两种构建配置代码按功能模块拆分适合在不同环境中编译学习。该demo已有7812人学习除核心绘图外还演示了鼠标点击事件与信息提示可将瀑布图绘制流程迁移到财务变更、任务统计等业务中。1. QT 瀑布图 Demo 值不值得下载先看它解决了什么问题做信号采集、频谱分析或串口数据监控时最头疼的不是把数据画成折线而是要把“时间维度的变化趋势”压缩到一张图里。普通曲线图只能看到当前帧历史信息全靠滚轮回放频谱图又只给瞬时状态看不出某个频点随时间的能量起伏。这个基于 QCustomPlot 的瀑布图 Demo就是把二维数组按行刷新、按列平移用颜色映射振幅做出类似声呐或频谱仪那种“从上往下流动”的实时效果。适合正在做上位机、数据可视化或通信调试工具的开发者拿来改一改就能嵌进自己的工程。先给结论这个 Demo 的核心不是画图而是把 QCustomPlot 当成一个高性能画布自己管理颜色查找表和缓存队列。实测在 QCustomPlot 的 QCPColorMap 基础上做增量更新一个 512x1024 的瀑布图帧率能稳定在 30 帧以上CPU 占用比直接 QPainter 逐像素绘制低一个量级。下面从工程结构、核心类、运行步骤到二次开发完整拆一遍。2. 技术选型与工程结构为什么选 QCustomPlot 而不是 QPainter2.1 为什么是 QCustomPlot一个被低估的实时绘图控件QCustomPlot 是 Qt 生态里少有的“开箱即用”的 2D 绘图库只有一个 .h 和 .cpp拷贝到工程里就能编译。它底层的 QCPColorMap 专门为二维数据设计支持颜色渐变、坐标轴映射和增量重绘比自己在 QWidget 里逐个像素绘制高效得多。瀑布图的本质就是“新数据推入、旧数据下移、整体重渲”QCustomPlot 的 QCPColorMap 恰好支持 setData 整体替换和 setKeyAxisRange 控制窗口天然适合做这种滚动效果。有人会问QPainter 也能画为什么要用第三方库?QPainter 画瀑布图要自己维护一个环形缓冲区、自己写颜色映射、自己处理坐标换算和重绘效率代码量 800 行起步而且每帧全量重绘CPU 烧得厉害。QCustomPlot 把这些都封装好了你要做的只是决定“数据矩阵长什么样”和“颜色怎么映射”开发效率和运行效率都高。2.2 目录结构与关键文件拿到源码后解压出来大概是这样的结构waterfall_demo/ ├── CMakeLists.txt # 或 .pro看 Qt 版本 ├── main.cpp # 入口创建窗口 ├── mainwindow.h # 主窗口头文件 ├── mainwindow.cpp # 主窗口实现包含瀑布图逻辑 ├── waterfallplot.h # 瀑布图封装类核心 ├── waterfallplot.cpp # 瀑布图实现 └── qcustomplot.h/.cpp # 第三方库源码无需编译修改如果你的解压包里没有 CMakeLists.txt 而是 .pro 文件说明作者用的是 qmake 工程在 Qt Creator 里直接打开 .pro 就能跑。核心要关注的是 waterfallplot.h/cpp它把 QCustomPlot 封装成了一个“可复用控件”换项目时把这个文件拷走再带上 qcustomplot 两件套就行。2.3 瀑布图的数据模型行列含义与坐标系瀑布图的数据本质是一个二维数组行代表时间或扫描序号列代表频率或位置。每一行是一帧数据当新一帧到来时整个矩阵向上滚动一行新数据插入底部或顶部旧数据被推出窗口。在这个 Demo 中QCPColorMap 的 keyAxis 是 x 轴比如时间或频率valueAxis 是 y 轴比如频率或通道数据值映射到颜色。一个容易搞混的点瀑布图的“滚动方向”和 QCPColorMap 的 data 定义方向可能相反。常见做法是让 keyAxis 为行索引valueAxis 为列索引setData 时传一个 QCPColorMapData 对象里面存 QVector 数组。数组的行列要和坐标系对齐否则图会上下颠倒或左右翻转这是新手最容易踩的坑后面避坑章节详细说。3. 核心模块拆解QCPColorMap 增量刷新与颜色映射3.1 初始化创建 QCPColorMap 并绑定轴先看 waterfallplot.cpp 里的初始化代码这是整个瀑布图的起点void WaterfallPlot::initPlot(QCustomPlot* plot) { // 创建颜色映射图层 colorMap new QCPColorMap(plot-xAxis, plot-yAxis); plot-addPlottable(colorMap); // 设置数据矩阵尺寸rows时间帧数, cols频率点数 int rows 512; int cols 1024; colorMap-data()-setSize(rows, cols); // 设置坐标范围key 是行索引value 是列索引 colorMap-data()-setRange(QCPRange(0, rows), QCPRange(0, cols)); // 设置颜色渐变蓝 - 绿 - 黄 - 红 QCPColorGradient gradient; gradient.setColorStopAt(0.0, QColor(#000080)); gradient.setColorStopAt(0.3, QColor(#0080FF)); gradient.setColorStopAt(0.6, QColor(#00FF00)); gradient.setColorStopAt(0.9, QColor(#FFFF00)); gradient.setColorStopAt(1.0, QColor(#FF0000)); colorMap-setGradient(gradient); // 设置颜色标尺 colorScale new QCPColorScale(plot); plot-plotLayout()-addElement(0, 1, colorScale); colorScale-setDataRange(QCPRange(0, 100)); colorMap-setColorScale(colorScale); }关键点在于 setSize 和 setRange。setSize 决定矩阵维度setRange 告诉 QCustomPlot 这个矩阵对应画布上的哪个坐标区间。这里 rows512 表示缓存 512 帧cols1024 表示每帧 1024 个数据点。颜色渐变用 setColorStopAt 控制五个关键位置实际效果可以根据需求换成热力图或灰度图。3.2 数据更新滚动刷新而不是全量重建瀑布图最讲究的是更新效率。如果每帧都 new 一个 QCPColorMapData性能一定崩。正确做法是复用同一个 data 对象手动搬移行数据再调用 emit dataChanged 通知重绘。void WaterfallPlot::updateData(const QVectordouble newFrame) { // 获取底层数据对象 QCPColorMapData* data colorMap-data(); // 获取矩阵行列数 int rows >mkdir build cd build qmake ../waterfall_demo.pro make -j$(nproc) ./waterfall_demo如果你的系统缺少 qmake改成 cmake 流程mkdir build cd build cmake ../ -DCMAKE_PREFIX_PATH/path/to/qt make -j$(nproc) ./waterfall_demo4.2 运行效果与自检方法启动程序后会看到一个可交互的瀑布图窗口支持鼠标滚轮缩放、拖拽平移和悬停显示数值。信号源由 QTimer 定时触发每 10ms 生成一帧正弦波噪声数据传入 updateData你能清楚看到一条正弦波在瀑布图上呈波纹状往下流动。自检瀑布图是否正确的标准很简单一是在数据源中注入一个持续单频信号瀑布图应出现一条稳定的竖直条纹若 x 轴是频率或水平条纹若 y 轴是频率条纹不漂移说明时间对齐正确二是注入幅度突变颜色跳变应发生在同一列而非整行扩散否则说明行列方向反了或是数据搬移方向错了。4.3 常见问题与排查三个必踩的坑坑一图是上下颠倒的现象数据越新图反而越在下部流动方向反了。原因row 0 决定画布顶部还是底部取决于 QCPColorMap 内部对 keyAxis 反向的设置。解决检查 keyAxis 是否设置了 setRangeReversed或者在搬移数据时把 newFrame 写入行 0 而不是行 rows-1。二选一不要同时改。坑二颜色全是蓝色或全红色现象整张图只有一个颜色看不到层次。原因数据范围与 setDataRange 不匹配所有值都小于最小值或大于最大值被钳位到端点颜色。解决先调用 rescaleDataRange 看整个数据范围是多少然后把 setDataRange 设为略宽于实际范围的数值或者打印数据最大最小值确认数据是否有效。坑三更新一帧后整张图闪一下才出现现象每次更新有闪烁图面不稳定。原因调用了 plot-replot() 而不是 QCustomPlot::rpQueuedReplot或者直接用了>public slots: void onDataFrameReady(const QVectordouble frame); // 调用处例如串口接收线程 connect(serialPort, QSerialPort::readyRead, this, []() { QByteArray bytes serialPort-readAll(); // 解析 bytes 成 QVectordouble长度对齐 cols QVectordouble frame parseFrame(bytes); emit dataFrameReady(frame); });注意串口接收频率和 QTimer 触发频率不一致时需要在 WaterfallPlot 内部做一个环形缓冲区分避免 UI 线程被高频信号卡顿。常见做法是设置一个 QTimer 定时从环形缓冲取最新帧每 30ms 更新一次这样 UI 始终有响应。5.2 改颜色映射从热力图变成灰度图或自定义色标QCustomPlot 的 QCPColorGradient 支持任意颜色停靠点改成灰度图只需两个停靠点gradient.setColorStopAt(0.0, QColor(#000000)); gradient.setColorStopAt(1.0, QColor(#FFFFFF));改成类似声呐的“黄绿蓝”只需要调整停靠点的位置和颜色。还有一个技巧用 setNanHandling 和 setNanColor 处理无效数据比如串口解析错误时的 NaN 值避免整个图面上出现莫名的黑色或白色块。5.3 增加拖拽选频功能点击查看某个频点的历史曲线瀑布图的典型交互是“选中某一行查看该行对应的时间序列”。QCustomPlot 内置了 QCPCurve 可以叠加到 colorMap 上思路是在鼠标点击位置插入一条垂直或水平的十字线并弹出现行数据的 QCPCurve 曲线图。代码量不大但涉及坐标转换用 colorMap-keyAxis()-pixelToCoord 把画布坐标映射回数据坐标再通过>QCPColorMapData* data colorMap-data(); QFile file(waterfall_export.csv); file.open(QIODevice::WriteOnly); QTextStream out(file); for (int y 0; y style="width:16px;margin-left:4px;vertical-align:text-bottom;cursor:text;" />