QCustomPlot 环境搭建与基础使用

QCustomPlot 环境搭建与基础使用

QCustomPlot 是一个轻量级、高性能的 Qt 图表库，广泛用于科学计算、工程监控和数据可视化场景。本文将带你从零开始搭建 QCustomPlot 开发环境，并快速上手实现第一个图表程序。

---

1. QCustomPlot 安装指南（Windows 篇）：从下载到配置 Qt 项目

步骤 1：下载 QCustomPlot

前往 QCustomPlot 官网 下载最新版源码压缩包（如 qcustomplot.tar.gz 或 .zip 文件）。

步骤 2：解压文件

将压缩包解压到本地目录，你会看到以下关键文件：

• qcustomplot.h
• qcustomplot.cpp

步骤 3：配置 Qt 项目

1. 将 qcustomplot.h 和 qcustomplot.cpp 拷贝到你的 Qt 项目目录中。
2. 在 .pro 文件中添加：

QT += core gui widgets printsupport
SOURCES += main.cpp \
           qcustomplot.cpp
HEADERS += qcustomplot.h

注意：printsupport 模块用于支持导出图表为 PDF/PNG 等格式，建议保留。

3. 重新构建项目，Qt 会自动编译 QCustomPlot 源码。

---

2. QCustomPlot 安装指南（Linux/macOS 篇）：编译、链接与环境验证

Linux（以 Ubuntu 为例）

1. 安装 Qt 开发环境（如使用 Qt Creator）：

sudo apt install qt5-default qtcreator

2. 下载并解压 QCustomPlot 源码（同 Windows 步骤）。

3. 将 qcustomplot.h 和 qcustomplot.cpp 放入项目目录，并在 .pro 文件中加入：

QT += core gui widgets printsupport
SOURCES += main.cpp qcustomplot.cpp
HEADERS += qcustomplot.h

4. 使用 qmake 和 make 构建：

qmake
make

macOS

1. 安装 Qt（推荐使用 Qt 官方安装程序）。
2. 同样将两个源文件加入项目。
3. 在 .pro 文件中确保包含 printsupport（macOS 下导出图表需要）。
4. 使用 Qt Creator 或命令行构建：

qmake -spec macx-clang
make

环境验证

构建成功后，运行程序应无链接错误。若出现 undefined reference，请检查是否遗漏 qcustomplot.cpp 或未正确包含模块。

---

3. 第一个 QCustomPlot 程序：10 分钟实现简单折线图（附完整代码）

以下是一个完整的 Qt 控制台 + GUI 示例，展示如何绘制一条正弦曲线。

main.cpp

#include <QApplication>
#include <QMainWindow>
#include "qcustomplot.h"

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    QMainWindow window;
    QCustomPlot *plot = new QCustomPlot();
    window.setCentralWidget(plot);
    window.resize(800, 600);
    window.setWindowTitle("QCustomPlot 入门示例");

    // 准备数据
    QVector<double> x(100), y(100);
    for (int i = 0; i < 100; ++i) {
        x[i] = i / 10.0;
        y[i] = qSin(x[i]);
    }

    // 添加图形
    plot->addGraph();
    plot->graph(0)->setData(x, y);
    plot->graph(0)->setPen(QPen(Qt::blue));

    // 设置坐标轴范围
    plot->xAxis->setLabel("X 轴");
    plot->yAxis->setLabel("Y 轴");
    plot->xAxis->setRange(0, 10);
    plot->yAxis->setRange(-1.2, 1.2);

    // 刷新图表
    plot->replot();

    window.show();
    return app.exec();
}

效果

运行后将显示一个窗口，其中包含一条蓝色正弦曲线，坐标轴标签清晰，范围适配。

---

4. QCustomPlot 基础架构：理解 QCPGraph、QCPAxis、QCPPlotLayout 的核心关系

QCustomPlot 的核心组件如下：

• QCustomPlot：主绘图控件，继承自 QWidget，是所有图表的容器。
• QCPGraph：表示一条数据曲线（折线图、散点图等），通过 addGraph() 创建。
• QCPAxis：坐标轴对象，每个 QCustomPlot 默认包含四个轴（上下左右），常用 xAxis 和 yAxis。
• QCPPlotLayout：布局管理器，控制子元素（如图例、标题、坐标轴）的位置和大小。

关系图示

QCustomPlot
├── QCPPlotLayout
│   ├── QCPAxis (xAxis, yAxis, ...)
│   └── QCPGraph (多条)
└── QCPAxisRect (坐标轴区域)

• 每个 QCPGraph 绑定到一个坐标轴对（默认为主轴）。
• 坐标轴范围、标签、刻度由 QCPAxis 控制。
• 所有视觉元素最终由 QCustomPlot 统一渲染。

理解这些组件的关系，有助于后续实现多图、双 Y 轴、图例定制等高级功能。

---

5. 数据加载与显示：如何将数组、列表数据快速绑定到 QCustomPlot 图表

QCustomPlot 支持多种数据输入方式，最常用的是 QVector<double>。

方法 1：使用 setData(x, y)

QVector<double> x = {1, 2, 3, 4, 5};
QVector<double> y = {2, 4, 6, 8, 10};

plot->addGraph();
plot->graph(0)->setData(x, y);

方法 2：从 C++ 数组转换

double x_raw[] = {0, 1, 2, 3};
double y_raw[] = {0, 1, 4, 9};
int n = sizeof(x_raw) / sizeof(x_raw[0]);

QVector<double> x(x_raw, n);
QVector<double> y(y_raw, n);

plot->graph(0)->setData(x, y);

方法 3：动态更新数据（实时绘图）

// 假设已有 graph
QVector<double> newX, newY;
// ... 实时采集数据
graph->setData(newX, newY);
plot->replot(); // 必须调用 replot 刷新

注意事项

• x 和 y 向量长度必须一致。
• 数据类型必须为 double（QCustomPlot 内部使用浮点运算）。
• 大量数据建议使用 QCPGraph::addData() 追加，避免频繁重建整个数据集。