QCustomPlot入门-EW帮帮网

QCustomPlot 是一个基于 Qt 的 C++ 绘图库，专注于高效、美观的 2D 数据可视化。进入QCustomPlot下载页，下载最新的完整包（包含：源码、文档、示例）。

一、核心架构设计

1. 分层架构模型

层级	主要组件	职责说明
用户接口层	QCustomPlot 类	提供顶层API，管理所有子组件
逻辑控制层	坐标轴系统、图例管理器、布局系统	处理业务逻辑和交互控制
数据管理层	QCPDataContainer 及其派生类	高效存储和检索绘图数据
渲染绘制层	QCPPainter、OpenGL后端	执行实际绘图操作
交互处理层	鼠标/键盘事件处理器、选择系统	处理用户交互行为

2. 模块依赖关系

3.完整渲染流程

二、核心类介绍

1.核心类关系图

2.核心类方法详解

1). QCustomPlot（主控件）

关系：

包含多个 QCPLayer（图层）
管理 QCPLayoutElement（布局元素）
持有 QCPAbstractPlottable（可绘图对象）

关键方法：

// 图形管理
QCPGraph* addGraph(QCPAxis* keyAxis, QCPAxis* valueAxis);
void removePlottable(QCPAbstractPlottable* plottable);

// 坐标轴访问
QCPAxis* xAxis, *yAxis;  // 主坐标轴
QCPAxis* axis(QCPAxis::AxisType type);

// 重绘控制
void replot(QCustomPlot::RefreshPriority priority = rpRefreshHint);

2). QCPAbstractPlottable（绘图基类）

子类：折线图(QCPGraph)、曲线图(QCPCurve)、柱状图(QCPBars)、QCPStatiBox(盒子图)、QCPColorMap(色谱图)、QCPFinancial(金融图)。

核心方法：

// 数据绑定
virtual void setData(QSharedPointer<QCPDataContainer> data);

// 视觉样式
void setPen(const QPen& pen);
void setBrush(const QBrush& brush);

// 坐标轴关联
void setKeyAxis(QCPAxis* axis);
void setValueAxis(QCPAxis* axis);

3). QCPGraph（折线图）

扩展方法：

// 线型设置
void setLineStyle(QCPGraph::LineStyle ls);  // lsLine, lsStepLeft, lsNone等

// 散点样式
void setScatterStyle(const QCPScatterStyle& style);

// 数据填充
void addData(const QVector<double>& keys, const QVector<double>& values);
void data()->removeBefore(double key);  // 删除指定范围前的数据

不同于Graph，其他的Plottable需要用new进行构造，而不是用addCurve、addBars等函数创建。已经存在的Plottable可以通过 QCustomPlot ::plottable(int index)访问，plottable的数量可以用　　QCustomPlot::plottableCount访问。

    ui->widget1->xAxis->setLabel("x");
    ui->widget1->yAxis->setLabel("y");
    ui->widget1->xAxis->setRange(0,10);
    ui->widget1->yAxis->setRange(0,10);
    QCPBars *myBars = new QCPBars(ui->widget1->xAxis, ui->widget1->yAxis);
    // now we can modify properties of myBars:
    myBars->setName("Bars Series 1");
    QVector<double> keyData;
    QVector<double> valueData;
    keyData << 1 << 2 << 3;
    valueData << 2 << 4 << 8;
    myBars->setData(keyData, valueData);

    ui->widget1->setInteractions(QCP::iRangeDrag | QCP::iRangeZoom | QCP::iSelectPlottables);

    ui->widget1->replot();

4). QCPAxis（坐标轴）

关联类：

QCPGrid（网格）
QCPAxisTicker（刻度生成器）

关键方法：

// 范围控制
void setRange(double lower, double upper);
void setRange(const QCPRange& range);

// 刻度配置
void setTicker(QSharedPointer<QCPAxisTicker> ticker);  // 时间/对数/文本刻度
void setTickLabels(bool show);

// 标签设置
void setLabel(const QString& text);
void setLabelFont(const QFont& font);

5). QCPLayoutElement（布局元素）

子类：

QCPAxisRect（坐标轴矩形）
QCPLayoutGrid（网格布局）
QCPLegend（图例）

核心方法：

// 尺寸控制
void setMinimumSize(const QSize& size);
void setMaximumSize(const QSize& size);

// 边距设置
void setMargins(const QMargins& margins);

6. QCPAbstractItem（自定义图元）

子类示例：

QCPItemText（文本标签）
QCPItemLine（参考线）
QCPItemRect（矩形框）

通用方法：

// 位置锚点
QCPItemPosition* position(const QString& name);  // 例如 "start", "end"

// 样式设置
void setPen(const QPen& pen);
void setBrush(const QBrush& brush);

7.QCPLayer图层

管理图层元素（QCPLayerable），所有可显示的对象都是继承自图层元素。

QCustomPlot 内置了一套默认图层系统，用于组织不同类型的绘图元素。理解这些默认图层对于有效控制绘图顺序和元素管理非常重要。

默认图层层次结构（从底到顶）

background - 最底层，适合放置背景元素
grid - 网格线层
main - 主图层，大多数plottables的默认层
axes - 坐标轴层
legend - 图例层
overlay - 最顶层，适合放置覆盖元素

各默认图层的典型内容

图层名称	包含元素	默认模式
background	背景矩形、背景图片等	lmLogical
grid	网格线	lmLogical
main	图形(QCPGraph)、柱状图(QCPBars)等	lmLogical
axes	坐标轴、轴标签、刻度	lmBuffered
legend	图例及其项	lmBuffered
overlay	顶层标注、浮动元素	lmLogical

访问和操作默认图层

// 获取特定默认图层
QCPLayer *gridLayer = customPlot->layer("grid");
QCPLayer *mainLayer = customPlot->layer("main");

// 检查图层是否存在
if (customPlot->hasLayer("legend")) {
    qDebug() << "存在legend图层";
}

// 获取所有图层列表
QList<QCPLayer*> allLayers = customPlot->layers();

// 获取图层在堆叠顺序中的索引
int layerIndex = customPlot->layerToIndex(mainLayer);

默认图层的重要特性

自动创建：当创建QCustomPlot实例时，所有默认图层会自动创建
绘制顺序：图层的绘制顺序由QCustomPlot::mLayers列表决定，索引0最先绘制

默认分配：

QCPGraph *graph = customPlot->addGraph();  // 自动添加到"main"层
QCPItemText *text = new QCPItemText(customPlot);  // 自动添加到"overlay"层

模式设置：
- lmLogical：直接绘制，无缓冲
- lmBuffered：离屏缓冲后绘制（适合复杂静态内容）

三、QCustomPlot 基础入门

1. 安装与配置

源码集成

下载最新版 QCustomPlot 官网
将 qcustomplot.h 和 qcustomplot.cpp 添加到项目

在 .pro 文件中添加：

QT += printsupport widgets
SOURCES += qcustomplot.cpp
HEADERS += qcustomplot.h

2. 基本绘图流程

1）初始化

QCustomPlot *customPlot = new QCustomPlot(parent);
customPlot->setInteractions(QCP::iRangeDrag | QCP::iRangeZoom);

2）‌数据图形绘制
添加图形对象并绑定数据：

customPlot->addGraph();  
QVector<double> xData = {1,2,3}, yData = {10,20,15};  
customPlot->graph(0)->setData(xData, yData);  // 数据绑定‌

4）‌坐标轴配置
设置坐标轴范围和标签：

customPlot->xAxis->setLabel("时间（秒）");  
customPlot->yAxis->setLabel("温度（℃）");  
customPlot->xAxis->setRange(0, 5);  
customPlot->yAxis->setRange(0, 30);  // 动态范围‌

4）渲染与更新
调用 replot() 重绘图形：

customPlot->replot();  // 强制刷新画布‌

完整示例代码

#include "qcustomplot.h"

// 在窗口构造函数中
QCustomPlot *customPlot = new QCustomPlot(this);
setCentralWidget(customPlot);

// 添加数据
QVector<double> x(101), y(101);
for (int i=0; i<101; ++i) {
  x[i] = i/50.0 - 1; // -1 到 1
  y[i] = x[i]*x[i];  // 抛物线
}

// 创建图形
customPlot->addGraph();
customPlot->graph(0)->setData(x, y);

// 设置坐标轴标签
customPlot->xAxis->setLabel("x");
customPlot->yAxis->setLabel("y");

// 自动缩放
customPlot->rescaleAxes();

// 重绘
customPlot->replot();

四、核心功能详解

1. 多种图形类型

折线图

customPlot->addGraph();
customPlot->graph(0)->setData(x, y);
customPlot->graph(0)->setPen(QPen(Qt::blue));

散点图

customPlot->addGraph();
customPlot->graph(0)->setData(x, y);
customPlot->graph(0)->setScatterStyle(QCPScatterStyle::ssCircle);
customPlot->graph(0)->setLineStyle(QCPGraph::lsNone);

柱状图

QCPBars *bars = new QCPBars(customPlot->xAxis, customPlot->yAxis);
bars->setData(x, y);
bars->setWidth(0.2); // 柱宽

热力图

QCPColorMap *colorMap = new QCPColorMap(customPlot->xAxis, customPlot->yAxis);
colorMap->data()->setSize(200, 200)

QCustomPlot入门