做桌面数据可视化，尤其是实时刷新、高帧率交互的界面，PyQtGraph里的PlotWidget是我最常掏出的一把快刀。它可能没有Matplotlib那么出名，但当你处理上万级数据点、还要流畅缩放拖动的时候，就知道这个组件有多香。这篇文章我会把PlotWidget从基础API到实战坑点完整过一遍，给刚开始用PyQt或者PySide写可视化程序的开发者一份能直接抄作业的参考。
下面进入正题。
1. 为什么是PyQtGraph和PlotWidget
1.1 PlotWidget在PyQtGraph体系里的位置
PyQtGraph是一个基于PyQt/PySide的图形库，专注科学可视化和实时图像。它底层直接走Qt的QGraphicsScene/QGraphicsView框架，绘制性能比Matplotlib高一个量级。PlotWidget是它提供的高级控件，本质上是一个QGraphicsView子类，内部管理着一个PlotItem。你可以把PlotWidget理解成“开箱即用的坐标轴画板”，它不是一次性输出图片的绘图函数，而是能嵌入Qt界面的活组件。
选型第一步，一定要先搞清楚快捷函数pyqtgraph.plot()和PlotWidget的区别。前者适合脚本里快速看个曲线，后者才适合做正式应用。因为PlotWidget是一个QWidget，可以放进布局管理器，和按钮、输入框、状态栏组合成完整的软件界面。这也是它与Matplotlib最大的定位差异：Matplotlib偏静态排版，PyQtGraph偏交互和实时。
1.2 和Matplotlib的取舍逻辑
很多人会问：我明明会Matplotlib，为什么还要学PyQtGraph？我的观点是：两者不是替代关系，而是场景不同。Matplotlib做静态排版最稳，导出论文图、拟合曲线、复杂子图布局都很好。但到了每秒刷新几十帧、鼠标拖动、缩放、局部放大这些交互需求，Matplotlib的渲染管线就扛不住了。数据量稍微一大，重绘一次就可能几百毫秒，根本没法做实时监控。
PyQtGraph也不是万能的。它在样式定制、导出矢量图、复杂图例方面比较弱。不过做采集器、示波器、监控面板、信号回放这类工具，它几乎是唯一解。后面所有示例都基于PyQtGraph的PlotWidget，搭配PySide6环境，重点展示它的实时能力和交互手感。
2. 核心细节解析与API要点
接下来从“怎么建”“怎么画”“怎么改”三个角度，把PlotWidget的常用API拆开讲。
2.1 从创建到第一条曲线
先装依赖：pip install pyqtgraph PySide6。创建最小窗口最直接的方式是这样：
import sys import pyqtgraph as pg from PySide6.QtWidgets import ( QApplication, QMainWindow, QVBoxLayout, QWidget ) import numpy as np app = QApplication(sys.argv) win = QMainWindow() central = QWidget() layout = QVBoxLayout(central) pw = pg.PlotWidget() layout.addWidget(pw) win.setCentralWidget(central) x = np.linspace(0, 10, 100) y = np.sin(x) curve = pw.plot(x, y, pen='y') win.show() sys.exit(app.exec())pw.plot()是核心入口，它返回一个PlotDataItem，后续可以反复修改这条曲线。pen参数可以用字符串指定颜色，也可以传一个QPen对象，比如pg.mkPen(color='r', width=2, style=Qt.DashLine)。
如果只想快速预览，直接pw.show()也行。但做正式界面，建议用嵌入布局的方式。这里还有一个易被忽视的点：plot()后如果不保存返回值，后面就没法更新这条曲线了。后面动态更新全靠这个返回值。
2.2 动态更新别用plot()，要setData()
这是新手最容易踩的坑。做实时刷新时，如果循环里直接调用pw.plot(newX, newY)，界面会越画越慢，因为每次plot()都创建一个新的PlotDataItem，旧的还留在场景里，内存和绘制开销会持续累积。正确做法是先用plot()拿到curve，然后在更新逻辑里调用curve.setData(x, y)。
curve = pw.plot(pen=pg.mkPen('c', width=1)) def update(): y = np.sin(x + time) * np.exp(-0.1 * x) curve.setData(x, y)setData内部复用已有的绘图项，只更新顶点数据，远比重建项高效。频繁刷新时，这个差别是肉眼可见的。
2.3 坐标轴范围的控制策略
PlotWidget默认会自动缩放，初次绘制时会把数据全部纳入视野。但实时滚动时，自动缩放不一定符合需求。比如横轴要固定显示最近100个点，纵轴要自动跟随信号变化，就需要分别控制。
pw.setXRange(0, 100, padding=0) pw.setYRange(-1.5, 1.5) pw.enableAutoRange(axis=pg.ViewBox.YAxis, enable=True)enableAutoRange可以只让Y轴自动缩放，X轴保持固定。动态滚动时，横轴范围可以这样更新：
pw.setXRange(newMax - window, newMax)另一个常用函数是setLimits，它限制用户手动缩放的最远最近范围，避免用户把图像拖到看不到的地方：
pw.setLimits(xMin=0, xMax=100000, yMin=-10, yMax=10)注意，setXRange是设定当前视野，setLimits是硬性边界，用户鼠标缩放也不会越界。做告警阈值、设备保护时，这个边界很有用。
2.4 图例、标签和标题的细节
PlotWidget自带addLegend方法，但要注意配合plot()时的name参数：
curve1 = pw.plot(x, y1, pen='r', name='信号A') curve2 = pw.plot(x, y2, pen='b', name='信号B') legend = pw.addLegend(offset=(10, 10))有一个细节容易被坑：addLegend要在所有plot()调用之后执行，否则可能拿不到条目。而且一个PlotWidget只能自动创建一个图例，想要多个图例，就得自己构造LegendItem手动添加。
坐标轴标签用pw.setLabel('bottom', text='时间', units='s')，标题用pw.setTitle('波形监控')。顶部轴和右侧轴也可以用setLabel指定。如果你不想每次散着设置，可以写一个setup函数集中处理。
2.5 鼠标交互与数据读取
PlotWidget的鼠标缩放和平移默认是打开的。鼠标滚轮缩放，左键拖动平移。如果想禁用某一方向：
pw.setMouseEnabled(x=False, y=False)更常见的是读取鼠标所在的数据坐标。用SignalProxy监听鼠标移动事件，频率限制在每秒60次左右比较平滑：
proxy = pg.SignalProxy(pw.scene().sigMouseMoved, rateLimit=60, slot=on_mouse_moved) def on_mouse_moved(evt): if pw.sceneBoundingRect().contains(evt[0]): mouse_point = pw.getPlotItem().vb.mapSceneToView(evt[0]) print(mouse_point.x(), mouse_point.y())这里的mapSceneToView会把场景坐标转换成数据坐标，直接拿到数据坐标系中的x/y。后面做十字光标时，这一步非常关键。
3. 实操过程与核心场景实现
有了前面的基础，可以拼出一个完整的实时监控Demo。下面这套结构我经常用来做示波器、波形回放、设备数据展示。
3.1 环境准备与依赖安装
推荐环境：Python 3.11 + PySide6 6.5 + PyQtGraph 0.13.3。安装时注意两点：
- pyqtgraph不会自动安装Qt绑定库，必须手动安装PySide6或PyQt5/PyQt6。
- 如果环境里装了多个Qt绑定，很可能运行时冲突，最好在一个干净环境里只保留一个。
pip install PySide6 pyqtgraph numpy用PySide6是因为它在LGPL协议下更适合商业闭源分发。如果只是自己实验，用PyQt5也可以，接口基本一致。
3.2 搭建主窗口与PlotWidget
做一个模拟示波器：左侧一个PlotWidget，右侧放开始、停止按钮和一个FPS标签。
from PySide6.QtWidgets import ( QMainWindow, QWidget, QVBoxLayout, QHBoxLayout, QPushButton, QLabel ) from PySide6.QtCore import QTimer class MainWindow(QMainWindow): def __init__(self): super().__init__() self.setWindowTitle('PlotWidget 实战') central = QWidget() self.setCentralWidget(central) layout = QHBoxLayout(central) self.plot_widget = pg.PlotWidget() layout.addWidget(self.plot_widget, stretch=3) control_panel = QWidget() v_layout = QVBoxLayout(control_panel) self.start_btn = QPushButton('开始') self.stop_btn = QPushButton('停止') self.fps_label = QLabel('FPS: 0') v_layout.addWidget(self.start_btn) v_layout.addWidget(self.stop_btn) v_layout.addWidget(self.fps_label) layout.addWidget(control_panel, stretch=1) self.curve = self.plot_widget.plot(pen='y') self.plot_widget.setLabel('bottom', '时间', units='s') self.plot_widget.setLabel('left', '幅值') self.plot_widget.setYRange(-1.5, 1.5) self.plot_widget.setXRange(0, 100, padding=0) self.timer = QTimer(self) self.timer.timeout.connect(self.update_plot) self.start_btn.clicked.connect(self.timer.start) self.stop_btn.clicked.connect(self.timer.stop) def update_plot(self): pass # 后续填充右侧面板可以是采集参数、告警阈值等，但核心交互结构是这样的。关键点是：timer只负责周期性触发更新，真正的重绘动作都在update_plot里完成。
3.3 实时刷新逻辑与性能调优
实时更新逻辑里，数据可以来自传感器、模拟计算或网络。这里用正弦波模拟：
import numpy as np time_step = 0.0 def update_plot(self): global time_step time_step += 0.05 x = np.arange(100) * 0.1 y = np.sin(2 * np.pi * 1 * time_step + x) self.curve.setData(x, y)每秒触发20次，数据量100点，PyQtGraph完全没压力。但真实采集场景里数据量可能上万，就需要关注三个点：
- 维护固定长度的数组作为环形buffer，每次只更新最新的一段数据，而不是无脑追加。
- 开启降采样。PlotWidget自带这个能力：
self.plot_widget.setDownsampling(ds=2, auto=True)auto=True时，PyQtGraph会根据显示区域自动决定降采样因子，缩放时不会把所有点都画出来。
- 避免频繁调用
setXRange。如果横轴做滚动窗口，可以在边界距离超过阈值时再更新横轴范围，减少布局重算。
3.4 添加十字光标与坐标提示
监控场景里，用户需要精确读点。添加两条InfiniteLine作为十字线，鼠标移动时更新这两条线，并把坐标值同步到界面标签。
v_line = pg.InfiniteLine(angle=90, movable=False) h_line = pg.InfiniteLine(angle=0, movable=False) self.plot_widget.addItem(v_line, ignoreBounds=True) self.plot_widget.addItem(h_line, ignoreBounds=True) info_label = QLabel('(0, 0)') def mouse_moved(self, evt): if self.plot_widget.sceneBoundingRect().contains(evt[0]): mouse_point = self.plot_widget.getPlotItem().vb.mapSceneToView(evt[0]) x, y = mouse_point.x(), mouse_point.y() v_line.setPos(x) h_line.setPos(y) info_label.setText(f'({x:.3f}, {y:.3f})') proxy = pg.SignalProxy( self.plot_widget.scene().sigMouseMoved, rateLimit=60, slot=self.mouse_moved )实现起来其实很短。SignalProxy在这里限制事件频率，避免鼠标移动过快导致界面线程CPU飙升。如果目标环境性能弱，可以把rateLimit降到30。
3.5 多曲线多子图布局
多个信号对比，一般用多个PlotWidget放在网格布局里，而不是硬塞一个PlotWidget里。共享X轴缩放时，可以连接两个ViewBox的sigXRangeChanged信号。
grid = QGridLayout() pw1 = pg.PlotWidget() pw2 = pg.PlotWidget() grid.addWidget(pw1, 0, 0) grid.addWidget(pw2, 0, 1) def sync_x_range(): range = pw1.getPlotItem().vb.viewRange()[0] pw2.setXRange(*range, padding=0) pw1.getPlotItem().vb.sigXRangeChanged.connect(sync_x_range)viewRange()返回的是((xMin, xMax), (yMin, yMax))，取索引0就是X轴范围。这个联动逻辑，做多通道对比时很常用。
4. 常见问题与排查技巧实录
我用PlotWidget的过程中踩过不少坑，下面这几个属于高频。
4.1 中文显示变成方块
- 现象：
setLabel和setTitle里的中文全部显示成方块。 - 原因：Qt默认字体可能不支持中文，或PyQtGraph的默认字体没有覆盖到坐标轴文本。
- 对策：在创建QApplication后设置全局字体：
from PySide6.QtGui import QFont app = QApplication(sys.argv) app.setFont(QFont("黑体", 10))如果只针对某个轴，可以单独设置坐标轴字体：
pw.setLabel('bottom', text='时间', units='s') pw.getPlotItem().getAxis('bottom').setTickFont(QFont("黑体", 9))不同平台中文字体名不一样，建议根据系统实际情况配置字体名。
4.2 setData后图像闪动、坐标轴乱跳
- 现象：实时刷新时波形上下跳动，Y轴范围也跟着乱变，视觉上很晃。
- 原因：Y轴开启了自动范围，数据峰值变化导致范围重算。
- 对策：明确想要的行为。固定量程的仪器，把
setYRange写死；自适应量程，可以加一个“自动范围”按钮，只在用户点击后才启用enableAutoRange，平时固定。滚动窗口的X轴同理，避免每次更新都调用setXRange，设置一个阈值，边界偏移超过阈值才移动视野。
4.3 在子线程里更新PlotWidget导致卡死或崩溃
- 现象：后台线程采集数据，然后直接调
curve.setData，界面卡顿甚至闪退。 - 原因：Qt要求所有界面操作必须在GUI主线程执行。子线程直接操作控件，属于跨线程访问，行为未定义。
- 对策：线程只负责把数据准备好，通过信号槽通知主线程更新。标准写法是用
QThread加Worker对象：
from PySide6.QtCore import QThread, QObject, Signal, Slot class Worker(QObject): data_ready = Signal(object) @Slot() def run(self): while True: # 采集或计算数据 self.data_ready.emit(y_array) worker = Worker() thread = QThread() worker.moveToThread(thread) worker.data_ready.connect(self.update_plot) thread.start()update_plot在GUI线程执行，只做setData。这样既保证采集不卡UI，又避免线程安全问题。
4.4 数据量大时拖动卡顿
- 现象：几万个点缩放平移时明显掉帧。
- 原因：Qt GraphicsView默认绘制全部数据点，点数量大时绘制开销高。
- 对策：优先开启降采样：
self.plot_widget.setDownsampling(ds=2, auto=True)百万点长的波形开启自动降采样后，拖动流畅度可以提升好几倍。也可以尝试pg.setConfigOptions(useOpenGL=True, antialias=True)开启OpenGL预览，但OpenGL模式在某些显卡上会引发渲染异常，最好做成可选开关。静态波形数据量大时，还可以先抽稀，只在显示范围变化时重算点集。
4.5 图例添加位置不更新
- 现象：调用
addLegend(offset=(10, 10))后，图例不在预期位置。 - 原因：
offset控制的是相对PlotItem的偏移量，不是绝对定位。而且图例默认跟随绘图区的右上角。 - 对策：用
offset指定相对偏移，比如(10, 10)就是离右上角10像素。如果想要完全自定义位置，可以手动构造LegendItem，再用setParentItem放进某个PlotItem中，这样布局控制会更自由。
4.6 程序退出时崩溃
- 现象：关闭主窗口时，偶尔报段错误或崩溃。
- 原因：多数情况和线程退出有关。后台线程还在跑，界面被销毁，底层事件循环争抢资源。
- 对策：在
closeEvent里先停止所有QTimer，再停止并等待子线程退出，最后调用window.close()。规范退出顺序能避免大部分崩溃。
5. 从实践里总结的几条经验
这里不是原理，而是实际项目里最值得注意的几个习惯。
第一，能不继承就不继承。很多人喜欢写class MyPlotWidget(PlotWidget):，然后把业务代码堆进去。我更推荐组合：把PlotWidget放到主界面里，单独写一个PlotManager类负责数据管理、坐标策略和事件响应，这样测试和维护都容易很多。
第二，默认参数别乱动。PyQtGraph会自动在plot()后执行一次enableAutoRange，如果你紧接着自己setRange，范围可能会被覆盖。正确的调参顺序是先创建curve，再关闭自动范围，再设置固定范围：
curve = pw.plot() pw.enableAutoRange(False) pw.setXRange(0, 100) pw.setYRange(0, 1)第三，性能调优一定要先测再改。很多人在只有几百个点的Demo里拼命优化，切到百万点数据后还是卡。稳妥做法是准备一个性能测试函数，用QElapsedTimer测setData耗时，量化对比优化前后的差别。
第四，PyQtGraph自带的examples目录是最好的学习资料。文档里每个方法大多配着示例代码，多花时间读examples，比到处搜索更高效。如果你在搭示波器、监控面板、信号回放工具或科学实验采集界面，这套交互和性能模型会很顺手。
