PyQtGraph多图表自定义：布局、联动与性能优化-代码聚汇网

PyQtGraph做多图表绘制这事，圈子里聊得不少，但真能讲清楚自定义门道的文章不多。PyQtGraph本身是一个基于PyQt/PySide的纯Python绘图库，底层跑在OpenGL和NumPy上，绘制效率和交互响应都比Matplotlib高出一个量级，特别适合实时数据流、高频刷新的场景。如果你做的是传感器采集、交易行情、示波器类工具，或者任何需要同时盯好几路波形、又嫌Matplotlib卡到没法用的界面工具，PyQtGraph都是绕不开的选择。

我之前在《PyQtGraph应用（一）》和《PyQtGraph应用（二）》里粗略聊过基础绘图和性能优化，这篇专门拆自定义多图表这块。我强烈建议所有准备在PyQtGraph上做复杂界面的朋友，都花点时间把多图表布局和坐标轴联动这些机制吃透，因为后续做任何正经工具都会碰到。

1. 多图表绘制的整体思路与方案选型

先说结论：PyQtGraph绘制多图表，主流的做法是使用GraphicsLayoutWidget而不是传统的QWidget + QVBoxLayout。这个区别很关键，很多人第一次用PyQtGraph，习惯性地拿Qt的布局容器往里塞PlotWidget，结果图表一多，缩放、联动、坐标轴对齐全乱套。原因在于GraphicsLayoutWidget是一个GraphicsView体系下的组件，图表直接作为PlotItem挂在一个统一场景里，它们天然共享坐标系变换和渲染上下文，性能和同步性都远好于堆叠多个独立视图。

1.1 为什么优先选择GraphicsLayoutWidget

GraphicsLayoutWidget听起来像布局，实际上它是一个基于QGraphicsScene的渲染容器。所有PlotItem其实都是GraphicsObject，在同一个场景里做排版和绘制。这意味着：

一是布局效率高。多个图表塞在一个场景里，而不是创建多个QGraphicsView实例，内存占用和事件分发开销都小得多。实时刷新时需要重绘的只是场景里的item，不会有多个视图各自创建OpenGL上下文的问题。

二是坐标联动天然方便。因为多个PlotItem都在同一个场景里，想要它们共享X轴缩放或Y轴范围，只需要设置setXLink或者setYLink，底层会在同一个视图中同步坐标变化，不需要自己处理sigXRangeChanged信号再手动去setRange。

三是样式统一容易。背景色、边框线宽、刻度字体这些，既可以在每个PlotItem上单独设置，也可以直接改场景的默认配置，批量生效。

当然，GraphicsLayoutWidget也有它的脾气。它对布局的控制是“格子化”的，通过addPlot(row, col)来定位，而不是Qt布局那种流式排布。如果你需要极其复杂的非规则布局，比如跨行跨列的表格，addPlot(0, 0, colspan=2)是支持的，但灵活性确实不如专门做布局的Qt组件。

1.2 GraphicsView与PlotWidget的本质区别

在PyQtGraph里，PlotWidget是GraphicsView + PlotItem的封装，而GraphicsLayoutWidget是GraphicsView + GraphicsLayout，GraphicsLayout里可以有多个PlotItem。我见过不少项目把单个PlotWidget单独排进QGridLayout，做一个四宫格的多图表界面，能跑，但明显有两个问题：

第一，每个PlotWidget都有自己的坐标轴和ViewBox，做X轴联动时要手动处理信号，用户拖动其中一个图表时，其他图表响应有肉眼可见的延迟。第二，四个PlotWidget各自创建自己的渲染上下文，内存开销大，而且嵌入普通QWidget布局后，缩放和滚动需要用QScrollArea之类处理，非常别扭。

所以我后来的项目，凡是涉及两个以上图表的场景，一律改用GraphicsLayoutWidget。这个选择做了之后，坐标联动成了几行代码的事，用户体验舒服太多了。

1.3 自定义方案的整体设计思路

在做自定义多图表之前，我建议你先在纸上把图表的功能需求列出来，不急着写代码。你至少要明确这几个问题：

你要同时展示多少路数据，图表之间是否共享X轴或Y轴范围，是否需要十字光标跨图表联动，是否需要点击图表进行框选放大的交互，以及是否有动态追加数据的需求。

这些问题的答案直接决定了GraphicsLayoutWidget的布局矩阵、坐标轴联动策略和交互处理方案。举一个我在实践中最常见的方案：上方一个大图表显示整体趋势，下方三个小图表显示不同维度的细节数据，四个图表共享X轴，缩放任意一个，其他三个也跟着缩放。这样既能看清全局，又能对比细节。下面我会沿着这套方案，把用到的核心组件逐个拆开讲清楚。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 核心组件的自定义细节与实操要点

要在PyQtGraph里做真正“自定义”的多图表，不是拖几个默认控件就完事，需要把PlotItem、ViewBox、AxisItem、LegendItem这些组件都摸透，知道它们各自的职责和自定义入口。默认生成一个PlotItem确实很快，但深度定制都是从修改这些组件的属性开始的。

2.1 PlotItem与ViewBox的关系

PlotItem是一个“容器型”对象，它内部默认包含一个ViewBox和若干AxisItem。你在PlotItem上调用plot()，实际上是往它的ViewBox里添加PlotDataItem。理解这个层级关系很重要，因为分布在不同层操作，效果完全不同：

在PlotItem层设置setTitle、setLabel、showGrid、addLegend，影响的是整个图表的标题、坐标轴标签、网格和图例。
在ViewBox层设置setXRange、setYRange、setMouseEnabled、setAspectLocked，影响的是绘图区域的坐标范围、鼠标交互和宽高比锁定。

我见过不少人想锁定Y轴不让用户缩放，在PlotItem上调来调去都不生效，其实是找错了层级。正确做法是拿到viewbox再设置：

python复制plot_item = layout_widget.addPlot(row=0, col=0)
view_box = plot_item.getViewBox()
view_box.setMouseEnabled(x=True, y=False)  # 只允许X轴缩放
view_box.setYRange(0, 10, padding=0)       # Y轴锁定范围

这个细节非常重要。自定义交互的第一原则就是找对操作层级，不然代码写得再对也不生效。

2.2 坐标轴自定义：刻度、标签与位置

坐标轴是图表里信息密度最高的元素之一，也是最常需要自定义的地方。在PyQtGraph里，坐标轴其实是AxisItem对象，你可以通过getAxis('bottom')或getAxis('left')拿到。

我常用的几个坐标轴自定义场景：

自定义刻度标签，默认情况下坐标轴会根据数据范围自动算刻度，比如X轴是时间戳时，默认刻度显示为一串数字，人看得很费劲。这时可以用setTicks手动指定刻度：

python复制axis_bottom = plot_item.getAxis('bottom')
ticks = [(timestamp1, time_str1), (timestamp2, time_str2), ...]
axis_bottom.setTicks([ticks])

调整坐标轴文字大小和颜色：

python复制axis_bottom.setTextPen('#FF9800')
axis_bottom.setStyle(tickFont=QFont('Arial', 10), tickTextOffset=6)

新增额外坐标轴，比如双Y轴场景，右侧Y轴显示另一路数据的量纲。PyQtGraph里最简单的方式是在同一个PlotItem上添加第二个ViewBox：

python复制view2 = plot_item.getViewBox().scene().addItem(plot_item.getViewBox())
# 在图表右侧新建ViewBox来承载第二个坐标轴

这里的操作稍微偏门，如果你需要双Y轴，建议直接查setRightAxis或者用ViewBox嵌套方案，默认的single-ViewBox模式不支持直接在右侧挂一个独立量纲的Y轴。

刻度个数控制，数据量大的时候，坐标轴刻度容易挤成一团。用setTickSpacing手动控制主刻度和次刻度的间隔：

python复制axis_bottom.setTickSpacing(level=0, spacing=100)
axis_bottom.setTickSpacing(level=1, spacing=50)

level=0对应主刻度，level=1对应次刻度，spacing单位是数据坐标系下的值。

2.3 图例、颜色与线型的自定义

多图表场景下，图例的重要性不亚于坐标轴。每个PlotItem可以有自己的图例，addLegend(offset=(10, 10))返回一个LegendItem对象。你要注意图例默认只显示传入plot()时name参数指定的曲线，不传name是不会有图例条目的。

我习惯在一个统一的位置给所有图表的图例做统一样式，而不是每个PlotItem用默认样式。

python复制legend = plot_item.addLegend(offset=(10, 10))
legend.setBrush(QBrush(QColor(30, 30, 30, 180)))   # 半透明背景
legend.setPen(QPen(QColor(200, 200, 200), 1))     # 边框
legend.setTextColor('#FFFFFF')

颜色和线型这些，麻烦的地方在于多图表界面上必须保证“远看能分区，近看能辨认”。我的经验是：不同图表之间优先使用完全不同色相的颜色，比如白、青、橙、粉，同图表内多条曲线则用同一色相不同明度。另外虚线、点划线这些线型可以用来区分场景中相同颜色的数据：

python复制pen_main = pg.mkPen(color='#00E5FF', width=2, style=Qt.DashLine)
plot_item.plot(x_data, y_data, pen=pen_main, name='参考线')

2.4 GraphicsLayoutWidget布局管理自定义

多图表布局最核心的就是addPlot的行列参数。比如四宫格布局：

python复制pw = pg.GraphicsLayoutWidget()
pw.addPlot(row=0, col=0)
pw.addPlot(row=0, col=1)
pw.addPlot(row=1, col=0)
pw.addPlot(row=1, col=1)

addPlot还支持合并单元格：

python复制# 第一行第一列到第一行第二列，占两列宽度，一般用来做总览大图
big_plot = pw.addPlot(row=0, col=0, colspan=2)

布局对象还提供setRowStretchFactor和setColumnStretchFactor来控制行高列宽比例。我实际用下来，setRowStretchFactor特别适合“上方大图，下方细节图”这种视觉比例要求严格的场景。

有一点要提醒：GraphicsLayoutWidget默认是自动撑满父控件的，你只需要把它作为主窗口的central widget或者塞进一个无布局的容器里即可，不要给它外面再套一层复杂的布局嵌套，容易把场景尺寸搞乱。

3. 实操过程与核心环节实现

我先说一个完整可跑的案例，然后逐段解释关键代码的意图和参数选择逻辑。这个例子里包含四个图表：一个总览趋势图，三个细节图，支持X轴联动、十字光标跨图表追踪、图例与网格统一配置。这是我在实际项目中反复用到的一套“母版”结构。

3.1 初始化窗口与GraphicsLayoutWidget

python复制import sys
import numpy as np
import pyqtgraph as pg
from PyQt5.QtWidgets import QApplication, QMainWindow
from PyQt5.QtCore import Qt
from PyQt5.QtGui import QColor, QFont

class MultiChartWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle('PyQtGraph 多图表自定义示例')
        self.resize(1280, 860)

        self.central_widget = pg.GraphicsLayoutWidget()
        self.central_widget.setBackground('#101820')
        self.setCentralWidget(self.central_widget)

        self._setup_plots()

    def _setup_plots(self):
        # 上方总览图，横跨两列
        self.overview_plot = self.central_widget.addPlot(row=0, col=0, colspan=2)
        # 下方三个细节图
        self.detail_plot_1 = self.central_widget.addPlot(row=1, col=0)
        self.detail_plot_2 = self.central_widget.addPlot(row=2, col=0)
        self.detail_plot_3 = self.central_widget.addPlot(row=3, col=0)
        ...

窗口背景我用的是#101820，一个偏深蓝的墨色，这个颜色在暗色主题下既能避免刺眼，又不至于让深色曲线消失。真正做产品时，背景色和曲线颜色需要有对比度计算，不能随意拍脑袋。比如深色背景下避免用纯黑或深蓝曲线，浅色背景下避免用白和黄曲线。

3.2 统一配置图表坐标轴与网格

每个PlotItem在创建后单独设样式太啰嗦。我习惯写一个_configure_plot(plot_item, title, ylabel)辅助函数，把坐标轴、网格、颜色一次配好：

python复制def _configure_plot(self, plot_item, title, ylabel):
    plot_item.setTitle(title, color='#FFFFFF', size='12pt')
    plot_item.showGrid(x=True, y=True, alpha=0.3)
    plot_item.setLabel('bottom', '时间', color='#CCCCCC', font-size='10pt')
    plot_item.setLabel('left', ylabel, color='#CCCCCC', font-size='10pt')
    plot_item.getAxis('bottom').setTextPen('#CCCCCC')
    plot_item.getAxis('left').setTextPen('#CCCCCC')
    plot_item.getAxis('bottom').setStyle(tickFont=QFont('Arial', 9))
    plot_item.getAxis('left').setStyle(tickFont=QFont('Arial', 9))
    plot_item.setMouseEnabled(x=True, y=False)

这里有一个取舍：底部三个细节图共享X轴时间，所以我对y方向直接禁用了鼠标缩放，避免用户把三条曲线拉到不同的Y范围，导致对比失去意义。总览图则可以自由缩放X轴，但Y轴也锁定为自适应。

setLabel不是简单给坐标轴贴个字符串，它内部会自动在主坐标轴旁边放置一个轴标签。如果哪天你发现坐标轴标签旋转了90度或位置不对，多半是offset参数没配好，一般axisItems的标签位置调整需要setLabel后通过plotItem.layout手动调整。

3.3 创建多数据集并绘制

数据我使用模拟的numpy数据，比较接近真实波形，而不是简单正弦波，这样能看到高频噪声下PyQtGraph的渲染表现：

python复制def _generate_data(self):
    t = np.linspace(0, 100, 5000)
    trend = np.sin(t / 10) * 5 + 10
    detail1 = np.sin(t / 2) * 2 + np.random.normal(0, 0.8, t.size)
    detail2 = np.cos(t / 3) * 1.5 + np.random.normal(0, 0.6, t.size)
    detail3 = np.sin(t / 5) * 3 + np.random.normal(0, 1.0, t.size)
    return t, trend, detail1, detail2, detail3

def _setup_plots(self):
    ...
    t, trend, d1, d2, d3 = self._generate_data()

    pen_trend = pg.mkPen(color='#FFD740', width=2)
    pen_d1 = pg.mkPen(color='#00E5FF', width=1.5)
    pen_d2 = pg.mkPen(color='#FF6E40', width=1.5)
    pen_d3 = pg.mkPen(color='#76FF03', width=1.5)

    self.overview_plot.plot(t, trend, pen=pen_trend, name='整体趋势')
    self.detail_plot_1.plot(t, d1, pen=pen_d1, name='细节一')
    self.detail_plot_2.plot(t, d2, pen=pen_d2, name='细节二')
    self.detail_plot_3.plot(t, d3, pen=pen_d3, name='细节三')

关于笔宽的选择：总览图的笔宽我用的2，细节图用1.5。这是有原因的。总览图显示的是低频宏观趋势，线太细在深色背景下会显得“飘”，加粗后视觉重量更稳。细节图包含大量噪声，线宽如果和总览图一样，高频抖动会让画面变得很吵，细一点反而清晰，还能突出噪声的纹理特征。

关于数据量：这里5000个点对PyQtGraph来说是小意思。我之前用setData刷新10万点都能保持60fps，前提是你要用numpy数组而不是Python list。PyQtGraph的绘制路径是直接把numpy数组的指针传给底层OpenGL/VBO，Python list会先复制成numpy再传，性能不是一个量级。所以，能传numpy绝不传list。

3.4 X轴联动：一个千分位细节的实现

这是多图表里最常用的交互之一。用户拖动总览图的时间轴，下方三个细节图跟着缩放；反过来，用户缩放细节图，总览图也应该同步。在PyQtGraph里，这个功能只需要一行代码：

python复制self.detail_plot_1.setXLink(self.overview_plot)
self.detail_plot_2.setXLink(self.overview_plot)
self.detail_plot_3.setXLink(self.overview_plot)

setXLink本质是把子图表的ViewBox和主图表的ViewBox绑定到同一个X轴坐标系统。底层原理是：当主ViewBox的X范围改变时，PyQtGraph会向所有linked的ViewBox广播范围变化事件，每个linked ViewBox自动调用setRange同步更新。这个机制是在C语言层面的事件分发循环里完成的，效率极高，所以你几乎感觉不到延迟。

细节一：X轴联动只同步范围，不会同步padding。如果你在主图表上设置了setXRange(0, 100, padding=0.05)，子图表只继承0到100的范围，但那5%的padding自己在子图表上不生效。所以我的习惯是直接在创建坐标轴时统一定义range，而不是依赖联动时padding透传。

细节二：联动关系是单向的。上面代码中setXLink会把三个细节图绑定到总览图，此时你缩放细节图，总览图不会跟着动。如果你希望总览图也跟随细节图缩放，需要反过来给总览图设置setXLink(detail_plot_1)，但二者同时设置会形成循环依赖，PyQtGraph内部会通过事件循环标志位防止死循环，但我建议你规划好联动的“主从”方向，不要搞成网状循环。

细节三：有些场景需要“总览图能缩放、细节图X随动，但总览图不被细节图反向影响”，实现方式就是上面这种单向绑定。有些场景则希望总览图永远显示全部数据，不管细节图怎么缩放，这时就需要把总览图X轴范围锁死，同时设置setMouseEnabled(x=False)。

3.5 添加跨图表的十字光标

跨图表光标是高频需求。鼠标在某个图表上移动时，所有图表同步显示一条竖直的参考线，标出同一时间点的数据值。实现原理不复杂：创建一个pg.InfiniteLine，鼠标移动时更新它的setPos，所有相关图表共享这条线，等效于“跨图表坐标映射”。

python复制self.v_line = pg.InfiniteLine(angle=90, movable=False, pen=pg.mkPen('#FFFFFF', width=1, style=Qt.DashLine))
self.h_line = pg.InfiniteLine(angle=0, movable=False, pen=pg.mkPen('#FFFFFF', width=1, style=Qt.DashLine))

for plot_item in [self.overview_plot, self.detail_plot_1, self.detail_plot_2, self.detail_plot_3]:
    plot_item.addItem(self.v_line, ignoreBounds=True)
    plot_item.addItem(self.h_line, ignoreBounds=True)

def mouse_moved(self, evt):
    if self.overview_plot.sceneBoundingRect().contains(evt.pos()):
        mouse_point = self.overview_plot.getViewBox().mapSceneToView(evt.pos())
        self.v_line.setPos(mouse_point.x())

ignoreBounds=True很关键。不加这个参数，InfiniteLine会被算入ViewBox的自动范围，导致图表在初始状态下为了显示这条线而自动扩大Y轴范围，一开程序图表就有大片留白。加上后，这条线只在视觉层出现，不参与数据范围计算。

有一个小坑：mapSceneToView返回的坐标是在当前ViewBox坐标系下的，如果你的ViewBox做了setAspectLocked或者其他坐标变换，实际坐标可能和你预期的不一样。多图表场景坐标轴联动之后，我希望光标在所有图表上显示同一X位置，所以都基于overview_plot做坐标映射，细节图也直接引用overview_plot的坐标值，不各自重新映射。

3.6 动态追加数据与自动滚动

很多真实场景不是静态画完就好，而是边采集边显示，比如声卡波形、金融行情。PyQtGraph里动态追加数据的标准姿势是用PlotDataItem的setData方法，而不是反复调用plot()去新建曲线：

python复制self.curve = self.detail_plot_1.plot(pen=pen_d1)
buffer = np.zeros(1000)

def update(self, new_sample):
    buffer[:-1] = buffer[1:]
    buffer[-1] = new_sample
    self.curve.setData(buffer)
    self.detail_plot_1.getViewBox().setXRange(len(buffer)-200, len(buffer), padding=0)

为什么用setData而不是plot()：plot()每次都会创建一个新的PlotDataItem并添加到场景中，旧的item不会自动移除，多次调用后场景里积累大量无用的item，内存上涨只是小事，真正严重的是场景重绘时需要遍历所有item来确定绘制顺序，垃圾item多了，帧率会掉。

为什么自己做滚动buffer而不依赖内部编译buffer：PyQtGraph的PlotDataItem.setData本身是smart append的，但你要滚动显示一个固定窗口的波形，推荐自行维护一个定长的numpy数组，然后整段setData。这样做的好处是数据清洗逻辑和界面显示逻辑完全解耦，未来要接多路数据源时，各自的滚动逻辑互不干扰。

性能细节：setData触发的重绘是整图重绘。如果你图表里有多条曲线，其中一条setData全量更新，其他曲线也会顺带重绘一次。如果只有一条曲线高频更新，影响很小。如果多条曲线高频更新不同数据，建议用pg.GraphicsLayoutWidget的setOpenGL(True)开启OpenGL加速，或者把每条曲线的setData调用合并到同一个事件循环里，即用QTimer定时批量更新，而不是每个数据点来一次。

4. 交互配置与高级联动技巧

到了这一节，多图表的基础架构已经搭好了，剩下的是和用户交互体验密切相关的配置。PyQtGraph默认的鼠标交互是左键拖拽平移、右键缩放、滚轮按锚点缩放。做多图表界面时，默认交互不一定适合业务。我常用的一套自定义交互配置如下。

4.1 限制缩放方向与范围

做股票行情、监控大屏这类界面，我一般是禁止Y轴缩放，只允许X轴缩放。但有些场景比如对比不同传感器量程的数据，则希望Y轴能缩放但禁止平移。这些需要针对每一个ViewBox分别配置：

python复制for plot_item in [self.overview_plot, self.detail_plot_1, self.detail_plot_2, self.detail_plot_3]:
    vb = plot_item.getViewBox()
    vb.setMouseEnabled(x=True, y=False)
    vb.setXRange(0, 100, padding=0.02)
    vb.setYRange(-5, 15, padding=0.1)

setMouseEnabled的参数控制的是鼠标拖拽和滚轮事件是否参与坐标范围计算。设为False的轴，鼠标在它上面的拖拽和滚轮都会被忽略，坐标范围只会被代码里的setRange/setXRange控制。

范围限制这块有个细节，PyQtGraph没有内置的“最小值-最大值”硬限制API，你必须自己在sigXRangeChanged信号里做拦截：

python复制def on_range_changed(self):
    x_min, x_max = self.overview_plot.getViewBox().viewRange()[0]
    if x_max - x_min < 5:
        self.overview_plot.getViewBox().setXRange(x_min, x_min + 5, padding=0)

如果你不拦截，用户能把X轴缩放到极小范围，坐标轴上只显示一两个数据点，整个界面就会失去可用性。

4.2 自定义缩放锚点与拖拽行为

PyQtGraph默认的鼠标滚轮缩放是以鼠标位置为锚点，这在多图表联动时会有问题。比如你的鼠标在detail_plot_1上滚动，因为X轴联动，其他图表也跟着缩放，但每个图表缩放时都用自己的鼠标位置作为锚点，导致不同图表缩放后X轴的起点和终点都不一致，视觉上会“错位”。

解决方案是强制所有子图表在有鼠标事件时，统一基于overview_plot的当前X范围中心作为缩放锚点：

python复制for plot_item in [self.detail_plot_1, self.detail_plot_2, self.detail_plot_3]:
    plot_item.getViewBox().setXLink(self.overview_plot)

# 在overview_plot上自定义滚轮事件：中心锚点缩放
def wheel_event(evt, vb):
    center = (vb.viewRange()[0][0] + vb.viewRange()[0][1]) / 2
    scale = 0.9 if evt.angleDelta().y() > 0 else 1.1
    half_width = (vb.viewRange()[0][1] - vb.viewRange()[0][0]) * scale / 2
    vb.setXRange(center - half_width, center + half_width, padding=0)

这段拦截了默认的缩放行为，统一以中心为焦点。监控类界面里，用户更习惯“中心缩放”，因为没有鼠标悬停位置做参照物时中心最稳定。不过你如果做的是操作类工具，比如示波器，用户反而希望以鼠标位置为锚点来放大波形细看，这时候你就别全局覆盖，针对不同功能的图表用不同的交互策略即可。

4.3 背景色与网格透明度协调

这一步看似是样式细节，但实际上直接影响多图表下的判读效率。坐标轴的网格透明度、坐标轴颜色和背景颜色搭配，直接决定用户能否快速区分多个图表。

我推荐“同一图表内网格同色系，不同图表之间网格至少有一个明度维度上的区别”。比如总览图网格透明度0.25，细节图网格透明度0.15，这样视觉上既有层次感，又不会让细节图网格太抢戏。

还有一点容易被忽略：多图表共用一个GraphicsLayoutWidget时，网格线和坐标轴文字是分别绘制在每个PlotItem上的，但它们共享同一个场景。如果某个PlotItem的网格透明度设成0，它的网格不会出现在最终截图中，这对制作报告图表其实是个便利，你可以一键隐藏某几个图表的网格。

4.4 图形面积填充与阴影效果

多图表场景中，除了折线，我经常还会在曲线下方填充半透明色块，辅助判断面积和趋势。PyQtGraph的fillLevel参数可以做到：

python复制plot_item.plot(t, trend, pen=pen_trend, fillLevel=0.0, fillBrush=pg.mkBrush('#FFD740', width=0.5))

fillLevel填0.0表示填充到Y=0的位置，会自动计算曲线和0线之间的区域。这个功能需要注意的是：如果曲线数据全是负值，填充区域在0线下，视觉上会顶到坐标轴之外，造成观感混乱。所以使用填充前，最好先对数据做基线平移。

阴影效果在PyQtGraph里需要多画一条半透明的粗曲线模拟：

python复制shadow_pen = pg.mkPen(color=(0, 200, 255, 40), width=8)
plot_item.plot(t, trend, pen=shadow_pen)
plot_item.plot(t, trend, pen=pen_trend)

先画宽而透明的底影，再画细而清晰的线。这个小技巧在深色背景上尤其好用，会让曲线有一种发光感，实时监控界面经常用这种风格。

5. 常见问题与排查技巧实录

多图表开发过程中，我踩过的坑不少，这里挑几个典型的记录下来，基本覆盖了PyQtGraph常用操作的大部分雷区。如果你在开发中也碰到了下面某一个现象，可以直接定位原因。

5.1 坐标轴联动失效

症状：设置了setXLink，但拖动主图表时子图表不动。排查思路：先检查是否在setupUi阶段就设置了XLink。如果你在后续代码里手动设置过子图表的setXRange，这不会破坏XLink；但如果你对子图表的ViewBox调用了setMouseEnabled并且在某个信号里又手动设置了它的X范围，这会和XLink产生竞争关系。

最常见的还是循环调用链错误。比如我早期的版本，在子图表的sigXRangeChanged信号里回调总览图setXRange，同时总览图的这个信号又去设置子图表范围，两边互相触发，结果PyQtGraph内部的blockSignals机制并不总能完全防止死循环。后来我统一用setXLink，彻底不自己写信号回调，问题消失。

5.2 多图表拖动时有“跳动”或“回弹”现象

症状：拖动图表时，曲线往回弹或者跳变。原因基本是setXRange被高频调用，且两个联动ViewBox的padding参数不一致。比如主图表setXRange(0, 100, padding=0.02)，子图表setXRange(0, 100, padding=0.05)，联动时事件里每一步都在互相纠正padding，表现为一种“打摆子”的抖动。

解决办法：所有X联动的ViewBox统一padding参数。最稳的做法是全部设成padding=0，需要留边距的，在主图表上设置后，子图表不要单独设置padding。

5.3 坐标轴刻度文字重叠

症状：X轴是时间戳，缩放后刻度标签交错重叠，密密麻麻看不清。原因：默认刻度间隔是自动算的，时间戳数据跨度大时，刻度间距和标签字符长度不匹配。处理办法是我上面提过的setTickSpacing。但我要补充一个更简洁的方案：对时间轴，直接把坐标轴显示格式通过setTicks定制成HH:mm:ss，而不是用时间戳数字：

python复制ticks = [(t[i], time.strftime('%H:%M:%S', time.localtime(t[i]))) for i in range(0, len(t), step)]
axis.setTicks([ticks])

注意setTicks的step要和图表宽度匹配，否则放大后没有刻度，缩小后刻度太密。我的实践是在sigXRangeChanged里动态重算step。这是一种比较聪明的做法，能保证任何缩放级别下刻度都不重叠。

5.4 绘制大量数据点后界面卡顿

现象：数据增多以后，拖动、缩放变得卡顿。原因不是PyQtGraph不支持大数据量，而是使用方式不对。排查重点：

第一，你是否在每次setData时传入了Python的list而不是numpy.ndarray？list会触发一层额外的类型转换。第二，你是否创建了过多无用的PlotDataItem而不是复用同一个并调用setData？第三，后台线程是否在主线程里直接调用setData？这会导致UI线程阻塞。

我自己踩过最大的坑是：以为开线程pyqtgraph就能自动避让GIL，结果在后台线程里直接curve.setData，GUI线程和后台线程同时争夺Python解释器，界面整个卡死。正确姿势是在后台线程只做数据运算，通过QTimer在主线程里定期setData，或者用pyqtgraph的SignalProxy做事件合并，把高频数据流压成低频率刷新：

python复制proxy = pg.SignalProxy(signal_emitter, rateLimit=30, slot=update_plot)

SignalProxy会在指定时间窗内合并多次信号，保证UI更新频率不超过限制。这是我做高频数据采集的常用标配。

5.5 导出图片时坐标轴丢失或背景透明

多图表界面做报告截图时，经常要导出一张完整图表。PyQtGraph的exportImage可以导出，但有很多坑：

一是导出范围默认只包含场景内可见部分，如果你有图表因窗口尺寸关系被裁剪，导出的图也缺一块。解决方法是临时把窗口尺寸设置到足够大，导出后再恢复。二是背景透明问题。GraphicsLayoutWidget的setBackground设成None时，导出背景是透明的，但你在QMainWindow里设了setStyleSheet，这个样式表的背景色仍会被带进导出图片里，非常隐蔽。三是导出图片中坐标轴文字可能出现模糊，这是因为默认导出DPI设置偏低，需要手动设置高DPI。

python复制from pyqtgraph.exporters import ImageExporter
exporter = ImageExporter(self.central_widget)
exporter.params['width'] = 2400
exporter.export('chart.png')

5.6 多个图表共享图例造成的命名冲突

多图表如果要共享一个图例，直接用addLegend各加各的，会出现两个图例框，比较丑。我的做法是使用LegendItem手动创建，统一放在场景左上角：

python复制legend = pg.LegendItem(offset=(20, 20))
legend.setParentItem(self.overview_plot.getViewBox())
legend.addItem(self.overview_plot.curves[0], '趋势')
legend.addItem(self.detail_plot_1.curves[0], '细节一')

LegendItem可以直接添加任意PlotDataItem并自定义名字，而不局限于某个PlotItem自己的图例。这需要在曲线创建时保留对应的PlotDataItem句柄。相比每个图表各挂一个图例，这种统一图例在多图表报告中更专业，也不会因为图表尺寸小导致图例挤压数据区域。

6. 一套完整的模板代码

最后放出我工作中一直在用的一套基础模板。它融合了上述所有讨论：多图表布局、X轴联动、自定义视口配置、跨图表光标、动态更新、统一样式。你可以直接复制改几个参数就用在项目里。

python复制import sys
import numpy as np
import pyqtgraph as pg
from PyQt5.QtWidgets import QApplication, QMainWindow
from PyQt5.QtCore import Qt, QTimer
from PyQt5.QtGui import QColor, QFont


class RealTimeMultiChart(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle('多图表实时监控模板')
        self.resize(1280, 860)

        self.chart_widget = pg.GraphicsLayoutWidget()
        self.chart_widget.setBackground('#101820')
        self.setCentralWidget(self.chart_widget)

        self._build_plots()
        self._link_axes()
        self._create_cursor()
        self._start_timer()

    def _build_plots(self):
        self.overview = self.chart_widget.addPlot(row=0, col=0, colspan=2)
        self.detail1 = self.chart_widget.addPlot(row=1, col=0)
        self.detail2 = self.chart_widget.addPlot(row=2, col=0)

        for plot_item, title, ylabel in [
            (self.overview, '总览', '幅值A'),
            (self.detail1, '通道1', '幅值B'),
            (self.detail2, '通道2', '幅值C'),
        ]:
            plot_item.setTitle(title, color='#FFFFFF', size='11pt')
            plot_item.showGrid(x=True, y=True, alpha=0.25)
            plot_item.setLabel('bottom', '时间', color='#CCCCCC')
            plot_item.setLabel('left', ylabel, color='#CCCCCC')
            axis = plot_item.getAxis('bottom')
            axis.setStyle(tickFont=QFont('Arial', 9))
            axis.setTextPen('#CCCCCC')
            plot_item.getAxis('left').setStyle(tickFont=QFont('Arial', 9))
            plot_item.getAxis('left').setTextPen('#CCCCCC')
            plot_item.getViewBox().setMouseEnabled(x=True, y=False)

        self.data_length = 2000
        t = np.linspace(0, 100, self.data_length)
        self.curve1_data = np.sin(t / 3.0) * 2.0 + np.random.normal(0, 0.4, t.size)
        self.curve2_data = np.cos(t / 5.0) * 1.5 + np.random.normal(0, 0.3, t.size)

        self.curve1 = self.overview.plot(t, self.curve1_data, pen=pg.mkPen('#FFD740', width=2), name='总览曲线')
        self.curve2 = self.detail1.plot(t, self.curve1_data, pen=pg.mkPen('#00E5FF', width=1.5), name='通道1')
        self.curve3 = self.detail2.plot(t, self.curve2_data, pen=pg.mkPen('#FF6E40', width=1.5), name='通道2')

    def _link_axes(self):
        self.detail1.setXLink(self.overview)
        self.detail2.setXLink(self.overview)

    def _create_cursor(self):
        self.vline = pg.InfiniteLine(angle=90, movable=False, pen=pg.mkPen('#FFFFFF', width=1, style=Qt.DashLine))
        self.hline = pg.InfiniteLine(angle=0, movable=False, pen=pg.mkPen('#FFFFFF', width=1, style=Qt.DashLine))
        for plot_item in [self.overview, self.detail1, self.detail2]:
            plot_item.addItem(self.vline, ignoreBounds=True)
            plot_item.addItem(self.hline, ignoreBounds=True)

        self._proxy = pg.SignalProxy(self.chart_widget.scene().sigMouseMoved, rateLimit=60, slot=self._on_mouse_moved)

    def _on_mouse_moved(self, event):
        pos = event[0]
        if self.overview.sceneBoundingRect().contains(pos):
            point = self.overview.getViewBox().mapSceneToView(pos)
            self.vline.setPos(point.x())
            self.hline.setPos(point.y())

    def _start_timer(self):
        self.frame_index = 0
        self.timer = QTimer()
        self.timer.timeout.connect(self._update_data)
        self.timer.start(50)

    def _update_data(self):
        self.frame_index += 1
        t = np.linspace(self.frame_index * 0.1, self.frame_index * 0.1 + 100, self.data_length)
        new1 = np.sin(t / 3.0) * 2.0 + np.random.normal(0, 0.4, t.size)
        new2 = np.cos(t / 5.0) * 1.5 + np.random.normal(0, 0.3, t.size)
        self.curve1.setData(t, new1)
        self.curve2.setData(t, new1)
        self.curve3.setData(t, new2)


if __name__ == '__main__':
    app = QApplication(sys.argv)
    window = RealTimeMultiChart()
    window.show()
    sys.exit(app.exec_())

这段代码的逻辑非常清晰。_build_plots负责布局和外观，_link_axes负责联动，_create_cursor负责跨图表坐标追踪，_update_data模拟实时数据源。每一块的边界很清楚，你接真实数据源时只需要替换_update_data里的数据生成逻辑即可。

你可以把QTimer的间隔从50ms改成10ms测试一下性能，我是实测能跑的，只要你的数据源是真numpy数组且数据量不爆炸，10ms刷新也不会有明显卡顿。如果你发现超过10ms就有肉眼可见的掉帧，优先检查后台线程阻塞了主线程，而不是怀疑PyQtGraph的渲染能力。

7. 最后几个经验提醒

多图表自定义这件事，我觉得最值钱的不是代码写法，而是方法论。几个关键原则用一句话总结：能复用的曲线绝不新建，能联动的坐标轴绝不手写回调，能批量配置的样式绝不搞逐图表散弹枪；遇到卡顿先查numpy、线程和事件合并，不要一上来就怀疑绘图库性能。

PyQtGraph看起来是个轻量级库，但它内部的坐标系、事件分发、场景管理机制非常严谨，值得花时间深入。你一旦掌握了ViewBox的坐标映射原理，很多交互的高级玩法都能实现出来，比如点击取点、区域框选联动、不同图表不同坐标轴映射等等。

后续我会专门写一篇关于PyQtGraph性能优化与多线程数据流集成的专栏，到时会把OpenGL加速、缓冲池管理、以及我在这套模板上做过的压力测试数据分享出来。这个模板你先拿去用，有问题随时回来翻这一篇文章的排查章节，肯定能解决多数情况。

PyQtGraph多图表自定义：布局、联动与性能优化