1. 零基础入门：认识 PyQtGraph 与基本绘图概念
PyQtGraph 是基于 Qt 的高性能绘图库，专门为 实时数据可视化 与 交互式图表 设计。它能够无缝嵌入到 PyQt/PySide 的桌面应用中，提供直观的 API 与丰富的控件，帮助你快速实现高性能的可视化场景。
在本章中，你将了解到 绘图流程、核心组件（PlotWidget、PlotItem、Curve、ViewBox 等），以及如何从零开始搭建一个简单的绘图窗口，为后续的实战应用打下坚实基础。
1.1 PyQtGraph 的定位与优势
与传统的绘图库相比，PyQtGraph 更适合实时更新场景，拥有更低的延迟和更顺滑的交互体验。它通过 Qt 的绘图能力与 GPU 加速 实现高性能渲染，能够在大数据量下保持稳定响应。
此外，跨平台兼容性强，支持 PyQt5、PyQt6、PySide2、PySide6，方便将图表嵌入现有的 PyQt 应用中进行扩展。
1.2 环境准备与安装
在开始之前，建议使用虚拟环境来管理依赖，以避免全局包冲突。创建并激活虚拟环境后，安装 PyQt 与 PyQtGraph 即可开始开发。
# 以 Python 3.x 为例
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate.bat # Windows# 安装 PyQt 与 PyQtGraph
pip install PyQt5 pyqtgraph
# 若选择 PyQt6，则
pip install PyQt6 pyqtgraph
安装完成后，即可在代码中导入 pyqtgraph 与 QtWidgets，开始构建你的第一个绘图程序。
2. PyQtGraph 基础控件与绘图流程
2.1 PlotWidget、PlotItem 与坐标系统
PlotWidget 是 PyQtGraph 提供的顶层绘图控件，内部包含一个 PlotItem，负责管理曲线、坐标轴和网格。通过简单的 plot、addItem 调用，你可以在同一个坐标系中绘制多条曲线。
理解坐标系统对后续自定义至关重要：ViewBox 提供缩放、平移、区域选择等交互能力，PlotItem 负责与 ViewBox 的配合以及数据映射。
2.2 构建你的第一个简单图表
下面示例展示了在 PyQt 应用中创建一个带有单条曲线的图表的完整流程。你可以看到从创建应用到显示 PlotWidget 的简便步骤。
import sys
from PyQt5 import QtWidgets
import pyqtgraph as pg
import numpy as npapp = QtWidgets.QApplication(sys.argv)
win = pg.PlotWidget(title="我的第一张图")
win.plot(np.linspace(0, 10, 100), np.sin(np.linspace(0, 10, 100)))
win.show()
sys.exit(app.exec_())简单且直观的 API 使你能够快速验证数据趋势，适合教学、演示及小型数据监控场景。
3. 实战：从零到一个可交互的图表
3.1 数据准备与绘线
在真实场景中，数据通常来自数组、数据框或传感器流。NumPy 与 pandas 常被用作数据源，PyQtGraph 能无缝接入两者。
下面的示例展示如何生成数据并在 PlotWidget 中绘制两条曲线，形成对比图。通过 name 属性，可在后续图例或交互中识别曲线。
import sys
from PyQt5 import QtWidgets
import pyqtgraph as pg
import numpy as npapp = QtWidgets.QApplication([])
win = pg.PlotWidget(title="Sin 与 Cos 波形")
x = np.linspace(0, 2*np.pi, 400)
y1 = np.sin(x)
y2 = np.cos(x)win.plot(x, y1, pen='r', name='sin(x)')
win.plot(x, y2, pen='g', name='cos(x)')
win.show()
app.exec_()数据对齐与长度一致性 是确保绘图正确的前提，务必确保 x、y 长度一致，且数据类型兼容。
3.2 交互功能：缩放、平移、标尺与光标
PyQtGraph 内置了丰富的交互能力：鼠标滚轮缩放、拖拽平移、以及自定义的光标标尺。你可以通过简单的设置开启或禁用特定交互模式，以提升分析效率。
下面示例展示了如何在现有 PlotWidget 上添加一个基本的交互光标，帮助你在数据上定位具体点的坐标。
from PyQt5 import QtWidgets
import pyqtgraph as pg
import numpy as npapp = QtWidgets.QApplication([])
plot = pg.PlotWidget(title="交互示例：光标定位")
plot.plot(np.linspace(0, 10, 100), np.sin(np.linspace(0, 10, 100)))
plot.showGrid(x=True, y=True, alpha=0.3)# 启用默认的鼠标交互（缩放/平移）
# 如果需要自定义，可以操作 ViewBox
plot.setMouseEnabled(x=True, y=True)app.exec_()交互性是 PyQtGraph 的核心价值，能显著提升对数据模式的理解与探索效率。
4. 实时数据绘制与性能优化
4.1 实时数据更新示例
在实时应用中，定时刷新数据是核心需求。使用 QTimer 可以周期性地拉取新数据并更新曲线数据，避免重新创建绘图对象带来的开销。
通过控制刷新频率与数据更新策略，你可以达到平滑的实时显示效果，同时保持 UI 的响应性。
from PyQt5 import QtCore, QtWidgets
import pyqtgraph as pg
import numpy as npclass LivePlot(pg.PlotWidget):def __init__(self, parent=None):super().__init__(parent)self.curve = self.plot(pen='y')self.x = np.arange(100)self.y = np.sin(self.x * 0.1)self.curve.setData(self.x, self.y)self.timer = QtCore.QTimer()self.timer.timeout.connect(self.update)self.timer.start(50)def update(self):self.y = np.roll(self.y, -1)self.y[-1] = np.random.normal()self.curve.setData(self.x, self.y)app = QtWidgets.QApplication([])
lw = LivePlot()
lw.show()
app.exec_()警惕刷新率与数据规模，当数据量较大时，考虑使用降采样、局部更新等策略，避免每次都全量重绘。
4.2 性能优化与调试技巧
性能优化的关键在于减少绘制开销。你可以通过 降采样、只刷新需要更新的区域，以及合理使用 ViewBox 的范围控制来提升帧率。
在调试阶段，开启性能分析与日志输出，有助于快速定位瓶颈，并通过合适的缓存策略提升渲染效率。
5. 高级布局与多图联动
5.1 GraphicsLayoutWidget 的布局与联动
使用 GraphicsLayoutWidget 可以实现复杂的多图布局，例如 2x2 网格、纵向和横向自适应布局，以及不同图表之间的联动。
通过在不同 PlotItem/ViewBox 上绑定同一数据源，或通过 setXLink/setYLink 等方法实现区域联动，创建仪表盘、监控界面等场景变得非常直观。
import pyqtgraph as pg
from pyqtgraph.Qt import QtGui
import numpy as npwin = pg.GraphicsLayoutWidget(show=True, title="多图联动示例")
p1 = win.addPlot(title="子图1")
p2 = win.addPlot(title="子图2")x = np.linspace(0, 10, 100)
y = np.sin(x)p1.plot(x, y, pen='r')
p2.plot(x, np.cos(x), pen='b')# 将两个子图联动：水平与垂直范围共享
p2.getViewBox().setXLink(p1.getViewBox())
p2.getViewBox().setYLink(p1.getViewBox())
QtGui.QApplication.instance().exec_()5.2 自定义主题与美化
图表的可读性受颜色、线型与网格风格影响极大。通过设置 pen、brush、symbol 等属性，以及应用全局主题，可以实现统一且美观的视觉风格。
下面的示例演示如何应用深色主题、统一网格与线条风格，提升整体观感。
pg.setConfigOptions(leftButtonPan=False) # 关闭左键平移（可选）
plot = pg.PlotWidget()
plot.plot([0,1,2], [2,5,3], pen=pg.mkPen(color='#1f77b4', width=2))
plot.showGrid(x=True, y=True, alpha=0.3)
plot.setBackground('#111') # 深色主题6. 将 PyQtGraph 集成到完整的 GUI 应用
6.1 与 PyQt5/PyQt6 的应用结构
在一个完整的桌面应用中，绘图组件通常作为 主窗口中心部件，并配合菜单、工具条和状态栏实现丰富的交互。将 PlotWidget 或 GraphicsLayoutWidget 放在布局中，能够实现高效的页面组织。
为了维护性与扩展性，建议将绘图相关的逻辑封装成独立的模块/类，通过信号与槽进行解耦，从而方便测试与二次开发。
6.2 保存与导出图表
将图表导出为 PNG、SVG、PDF 等格式，是分析报告与离线分享的常见需求。你可以使用 ImageExporter、SVGExporter 等工具对当前画布进行导出。
# 将 PlotWidget 的当前画布保存为 PNG
export_path = "plot_snapshot.png"
plot_widget = pg.PlotWidget()
plot_widget.plot([1,2,3], [4,5,6])
exporter = pg.exporters.ImageExporter(plot_widget.plotItem)
exporter.parameters()['width'] = 800
exporter.export(export_path)7. 常见问题排查与参考资源
7.1 版本兼容性与安装问题
不同的 Qt 绑定版本 对 PyQtGraph 的兼容性存在差异。当遇到 绑定冲突 时，应优先核对 PyQt5/6 版本 与 pyqtgraph 版本 的官方兼容表。
如果安装失败，确保处于独立虚拟环境中，并尝试清理缓存后重新安装，以避免缓存导致的包冲突。
7.2 调试技巧与参考资源
为了高效学习和排错，建议优先参考 PyQtGraph 官方文档、GitHub 仓库问题区 和活跃社区的示例。结合实际项目逐步练习，可以快速提升你对图表可视化的掌控能力。
