PyQtGraph实战:自定义绘制大数据量K线指标图
发布时间:2026/11/21 15:27:15来源:尧图网络
从项目需求落地到自定义绘图这次我想完整地聊一聊怎么用 PyQtGraph 画一张能扛住大数据量的 K 线指标图。标题里的“四”意味着这是 PyQtGraph 应用系列的第 4 篇前面几篇把 GraphicsView 基础、Item 体系和信号机制都讲得差不多了所以这篇文章直接进实战蜡烛图本体、均线、成交量、MACD 同屏联动以及数据量变大之后到底怎么优化。我会把我踩过的坑和最后采用的代码一起放出来有需要的可以直接抄。先用一个真实场景开头。之前接了个内部看盘工具客户要求主图、成交量、MACD 三个区域同时展示数据源是最近 15 万根 5 分钟线。第一版我用 matplotlib 硬画窗口一拖动就卡到没法看缩放到某段K线时 CPU 直接跑满。后来把图形层迁移到 PyQtGraph同样的数据量、同样的交互在普通办公机上也能稳定运行在 60 帧附近。这个差距不是一两倍而是量级上的差异。如果你也在为 K 线图卡顿头疼这篇文章应该能给你一个可靠的解决路径。1. 先从需求说起为什么 K 线图必须自定义绘制1.1 用普通折线画 K 线问题出在哪很多人第一次接触 PyQtGraph 时会自然想到用PlotWidget.plot()把 OHLC 数据转换成折线或者用官方自带的BarGraphItem画出蜡烛实体。这两种思路都能在屏幕上“出来”一张图但和真正的 K 线需求差得比较远。K 线有开盘价、收盘价、最高价、最低价四个维度而且每个交易日/分钟周期的数据是独立的形状不是一条连续曲线。如果用折线去连视觉上完全不对。用BarGraphItem虽然能画出实体但影线很难做而且BarGraphItem对超大数据量的绘制优化有限15 万根K线一放上去拖动缩放时照样掉帧。另外还有一个隐蔽的问题K 线图的数据量是随周期增长的。日线一年才 240 根左右但分钟线一个月就可能超过 6000 根一年下来 7 万根很常见。如果绘制函数里每次paint都遍历全部数据那么无论底层是 Qt 还是别的图形库CPU 开销都会线性上涨。真正适合 K 线图的方案是把它当作一个整体 Item 提交给 GraphicsView在paint()里按可视区域只画当前这一屏这才是 PyQtGraph 正确打开方式。1.2 PyQtGraph 绘制模型和我们的解决思路PyQtGraph 的底层是 Qt 的 GraphicsView 框架。简单理解就是画面里有很多 Item每个 Item 自己负责绘制视口发生滚动或缩放时ViewBox 只通知可见范围内的 Item 重绘。只要 Item 的boundingRect()边界范围计算正确Qt 图形栈会自动裁剪把不可见部分的绘制直接砍掉。这个机制天生适合行情图因为 K 线数据虽然可能有几十万根但屏幕上同时可见的往往只有几十到几百根只要绘制函数只处理可见区间帧率就能稳定住。所以我的思路很明确自己写一个CandlestickItem继承pyqtgraph.GraphicsObjectpaint()函数里用QPainter直接绘制蜡烛实线和影线只在当前 ViewBox 可视区域内循环绘制而不是每次全部遍历成交量、MACD 等指标放到独立的 PlotItem 里通过setXLink与主图绑定联动时间轴用时间戳作为 X 轴配DateAxisItem自动生成日期刻度。1.3 运行环境和整体效果说明我本地的测试环境是 Python 3.10 PyQt5 5.15 PyQtGraph 0.13.3Windows 11 办公机。安装依赖很简单pip install PyQt5 pyqtgraph numpy下面的代码我会按“数据准备 - 自定义蜡烛图 - 指标计算 - 多图布局 - 鼠标交互 - 性能优化”的顺序推进。最终的窗口里会包含主K线图、成交量副图和 MACD 副图三个区域共享 X 轴鼠标在主图上方移动时显示跟随十字线并在右上角显示当前光标所指 K 线的 OHLC 信息。因为文章篇幅关系UI 细节没有做得很花哨但结构足够作为你项目的基础框架。2. 数据准备OHLC 数据如何变成一根蜡烛2.1 数据格式约定和时间戳的选择先解决一个容易忽略的问题X 轴数据应该用整数索引还是时间戳。我建议直接用时间戳Unix 秒。这样后续接真实行情接口、CSV、本地数据库时数据列不需要额外转换。PyQtGraph 的DateAxisItem可以直接按照时间戳生成日期刻度不需要你手工维护刻度列表。使用索引作为 X 轴固然方便但最后还得映射回时间字符串反而增加一层自定义轴的工作。下面是一段用于生成演示数据的函数。它生成从 2023 年开始的 2000 个“交易日”数据字段保持常见行情接口的命名顺序时间戳、开盘、最高、最低、收盘、成交量。import numpy as np import pyqtgraph as pg from datetime import datetime, timedelta from PyQt5 import QtCore, QtGui, QtWidgets def make_demo_data(n2000): rng np.random.default_rng(7) t int(datetime(2023, 1, 1).timestamp()) gap 24 * 3600 ts [] opens [] highs [] lows [] closes [] volumes [] base 100.0 for _ in range(n): o base * (1 rng.normal(0, 0.008)) c o * (1 rng.normal(0, 0.02)) h max(o, c) * (1 abs(rng.normal(0, 0.005))) l min(o, c) * (1 - abs(rng.normal(0, 0.005))) v rng.integers(30_000, 300_000) ts.append(t) opens.append(o) highs.append(h) lows.append(l) closes.append(c) volumes.append(v) t gap base c return (np.array(ts), np.array(opens), np.array(highs), np.array(lows), np.array(closes), np.array(volumes))时间戳我有意用本地时区生成。因为 PyQtGraph 的DateAxisItem在生成轴刻度文本时默认走本地时区如果你导入的数据是 UTC 时间在 UTC8 的环境下会发现日期偏移了 8 小时。遇到这种问题第一反应不应该是去改显示函数而是检查数据源里的时间戳到底是不是 UTC。2.2 蜡烛的视觉构成和坐标映射一根标准的 K 线由两部分组成实体和影线。在 Qt 的坐标系统里实体的 X 范围是“当前K线中心点左右各扩一半宽度”Y 范围是开盘价到收盘价影线则是从最高价到最低价的一条竖直直线。我们的 X 轴单位是秒所以蜡烛宽度不能写死。日线一根是 86400 秒如果宽度写 0.7那画出来的实体就是一根几乎看不见的竖线。要解决这个问题最直接的做法是从相邻两根K线的时间差里动态计算宽度bar_width (ts[1] - ts[0]) * 0.6这个方案对日线、分钟线、小时线都适用。如果数据里有停牌导致的空档某个相邻间隔会异常变大用首间距算可能会让某些蜡烛偏宽。针对这种场景更严格的做法是改用索引爪坐标再自己写一个时间刻度轴但日常大部分行情数据都是等间隔序列先用一个间距定宽度没问题。2.3 涨跌颜色和绘制约定颜色习惯我默认按 A 股惯例收盘价大于等于开盘价则画红色收盘价小于开盘价则画绿色。欧美市场通常是绿涨红跌你可以通过两个静态常量把颜色抽出来后续改 UI 主题时只动一处UP_COLOR #ff4136 DOWN_COLOR #3d9970到这里一根蜡烛需要的一切都齐了时间戳的 X 坐标、开盘/收盘决定实体 Y 范围、最高/最低决定影线 Y 范围、涨跌决定刷色。下面就可以把这些映射落进paint()函数里。3. 手写 CandlestickItem 的核心代码3.1 继承 GraphicsObject 后必须实现的两个方法pyqtgraph.GraphicsObject是 QtQGraphicsObject的轻量封装它不要求你先画到一个临时图形对象里而是让你在一个paint()方法里直接绘制。继承它之后最少要实现两个方法boundingRect()返回 Item 在数据坐标系中的范围。ViewBox 用这个范围做裁剪和碰撞检测。paint(p, *args)真正画图的地方。p是一个已经完成坐标变换的QPainter它里面的坐标系已经是数据坐标系。只要这两个方法正确PyQtGraph 就能把 Item 放进场景里正常呈现。3.2 一个完整的 CandlestickItem 类下面这个类是我在实际项目里的简化版本。它接收的是形状为(N, 5)的 numpy 数组列顺序是(时间戳, 开盘, 最高, 最低, 收盘)。import bisect import pyqtgraph as pg from PyQt5 import QtCore, QtGui UP_COLOR #ff4136 DOWN_COLOR #3d9970 class CandlestickItem(pg.GraphicsObject): def __init__(self, dataNone): super().__init__() self.data np.zeros((0, 5), dtypefloat) if data is None else data self._bounds QtCore.QRectF() self._update_bounds() def set_data(self, data): self.prepareGeometryChange() self.data data self._update_bounds() self.update() def _update_bounds(self): if self.data.size 0: self._bounds QtCore.QRectF() return xs self.data[:, 0] highs self.data[:, 2] lows self.data[:, 3] self._bounds QtCore.QRectF( xs.min(), lows.min(), xs.max() - xs.min(), highs.max() - lows.min(), ) def boundingRect(self): return self._bounds def paint(self, p, *args): if self.data.size 0: return # 只绘制可见区间 vb self.getViewBox() if vb is None: return visible vb.viewRect() left visible.left() right visible.right() ts_list self.data[:, 0] start max(0, bisect.bisect_left(ts_list, left) - 1) end min(len(self.data), bisect.bisect_right(ts_list, right) 1) if start end: return # 蜡烛宽度取前两个时间戳的间距日线就是 86400 * 0.6 if len(self.data) 1: half_width (self.data[1][0] - self.data[0][0]) * 0.3 else: half_width 0.3 p.setRenderHint(QtGui.QPainter.Antialiasing, False) for row in self.data[start:end]: t, o, h, l, c row color UP_COLOR if c o else DOWN_COLOR pen pg.mkPen(color) p.setPen(pen) p.setBrush(pg.mkBrush(color)) # 影线 p.drawLine(QtCore.QPointF(t, l), QtCore.QPointF(t, h)) # 实体 if abs(c - o) 1e-8: p.drawLine(QtCore.QPointF(t - half_width, o), QtCore.QPointF(t half_width, o)) else: rect QtCore.QRectF( t - half_width, min(o, c), half_width * 2, abs(c - o), ) p.drawRect(rect)这里有几个细节值得说明。第一为什么要用p.setRenderHint(QtGui.QPainter.Antialiasing, False)K 线图本身是横平竖直的几何图形不需要抗锯齿关闭之后不仅绘制速度更快而且能避免放大缩小时出现边缘发虚、颜色发浅的情况。第二paint()里不应该把整个数据集循环一遍。我用bisect基于当前 ViewBox 的左右范围算出可见区间的起止索引只画这一小段。这正是大数据量下不掉帧的核心手段之一。第三drawRect要求QRectF的宽高为正数。如果收盘价等于开盘价直接画一条水平线表示“一字横盘”即可不要试图画一个零高度的矩形Qt 在部分平台上对零宽高矩形的渲染行为不一致。3.3 boundingRect 和 prepareGeometryChange 的真正作用boundingRect()返回的范围必须覆盖 Item 所有可能画出来的像素区域。我计算时用的是total_min_low到total_max_high覆盖住全部数据范围。如果这个范围算小了ViewBox 会认为 Item 只占屏幕的一部分滚动到边缘时图形会被错误裁剪甚至完全消失算大了则问题不大只是多占一点潜在绘制区域。set_data()开头那个prepareGeometryChange()一定要记得调用。它告诉 Qt 图形框架这个 Item 的几何边界要变了请把旧位置先清理掉。不调用它更新数据后屏幕上会留下残影而且越拖越明显。这是我第一次写自定义 Item 时踩得最深的坑查了半天才发现是少了一句通知。3.4 鼠标悬停显示 OHLC 信息的小扩展有了 Item 之后我们可以在主图上加一个跟随光标的十字线和信息文本。这里用SignalProxy降低信号频率避免鼠标移动时高频触发计算info_text pg.TextItem(anchor(0, 1), color#ffffff, fill(0, 0, 0, 160)) p_main.addItem(info_text, ignoreBoundsTrue) vline pg.InfiniteLine(angle90, movableFalse) hline pg.InfiniteLine(angle0, movableFalse) p_main.addItem(vline, ignoreBoundsTrue) p_main.addItem(hline, ignoreBoundsTrue) def on_mouse_moved(evt): pos evt[0] if not p_main.sceneBoundingRect().contains(pos): return view_pos p_main.vb.mapSceneToView(pos) x view_pos.x() y view_pos.y() vline.setPos(x) hline.setPos(y) idx bisect.bisect_left(ts, x) if idx len(ts): idx len(ts) - 1 if idx 0: return dt_str datetime.fromtimestamp(ts[idx]).strftime(%Y-%m-%d) info_text.setText( f{dt_str} O:{opens[idx]:.2f} H:{highs[idx]:.2f} fL:{lows[idx]:.2f} C:{closes[idx]:.2f}, ) info_text.setPos(ts[idx], highs[idx]) proxy pg.SignalProxy(p_main.scene().sigMouseMoved, rateLimit30, sloton_mouse_moved)这里有一个性能和逻辑上的细节bisect_left(ts, x)是二分查找对于几十万条时间戳都能在微秒级完成完全不用担心拖慢帧率。但如果数据量极大p_main.sceneBoundingRect().contains(pos)缓存一个矩形区域也够用。PyQtGraph 的SignalProxy宝贵在它会自动丢帧鼠标快速移动时不用每个 move 事件都执行完整绘制。4. 多指标同屏成交量、均线、MACD 的布局与联动4.1 用 GraphicsLayoutWidget 划分三个 PlotItem单张图上只有 K 线显然不够实战里通常要同时看成交量、MACD 这类的辅助指标。布局我用pg.GraphicsLayoutWidget它相当于一个二维表格每一行放一个 PlotItem。主图占第 0 行成交量占第 1 行MACD 占第 2 行。win pg.GraphicsLayoutWidget() win.resize(1200, 900) date_axis pg.DateAxisItem(orientationbottom) p_main win.addPlot(row0, col0, axisItems{bottom: date_axis}) p_vol win.addPlot(row1, col0) p_macd win.addPlot(row2, col0) p_vol.setXLink(p_main) p_macd.setXLink(p_main) # 主图和成交量图底部轴隐藏由 MACD 图统一显示时间刻度 p_main.hideAxis(bottom) p_vol.hideAxis(bottom) p_main.getAxis(bottom).setHeight(0) p_vol.getAxis(bottom).setHeight(0) # 左轴宽度统一保证三张图的数据区在垂直方向上对齐 for p in [p_main, p_vol, p_macd]: p.getAxis(left).setWidth(80)setXLink(p_main)是关键。它把自己的 X 轴 ViewBox 绑定到主图的 X 轴主图缩放、滚动副图自动跟随。Y 轴仍然是独立的这是最理想的状态副图可以保持自己的价格/数值尺度互不干扰。为什么大多数做图表的人会忽略左轴宽度对齐这个问题因为如果主图左侧价格轴显示“100、110、120”而成交量轴显示“1.5万、3万”它们的默认宽度不同会导致三张图的数据区在垂直方向上错开。实际上用GraphicsLayoutWidget时虽然每个 PlotItem 占一列但 axis 宽度不同会让内部绘图区宽度不一致。把所有左轴统一宽度是让多图“无缝咬合”最便宜的方案。4.2 指标计算MA 和 MACD 的基本实现MA 简单滑动窗口求平均。MACD 则分三步计算快线 EMA(12) 与慢线 EMA(26) 的差值得到 DIF再对 DIF 取 EMA(9) 得到 DEA最后柱状图数值为2 * (DIF - DEA)。def calc_ma(values, period): result np.full(len(values), np.nan) total 0.0 for i, v in enumerate(values): total v if i period: total - values[i - period] if i period - 1: result[i] total / period return result def calc_ema(values, period): alpha 2.0 / (period 1.0) result np.zeros_like(values) result[0] values[0] for i in range(1, len(values)): result[i] alpha * values[i] (1.0 - alpha) * result[i - 1] return result def calc_macd(closes): dif calc_ema(closes, 12) - calc_ema(closes, 26) dea calc_ema(dif, 9) hist 2.0 * (dif - dea) return dif, dea, hist这段代码没有用外部 TA-Lib因为我们要展示的是绘制流程不是算法性能。实际项目中如果对计算速度有要求可以用 pandas 的ewm()或者 TA-Lib计算结果是一致的。4.3 把指标画到图表上主图上叠加均线可以用p_main.plot()。注意 MA 前period-1个位置是nan直接传给plot()会导致线的起点位置接到错误的地方所以只传有效区间ma5 calc_ma(closes, 5) ma20 calc_ma(closes, 20) valid5 ~np.isnan(ma5) valid20 ~np.isnan(ma20) p_main.plot(ts[valid5], ma5[valid5], penpg.mkPen(#f39c12, width1.2), nameMA5) p_main.plot(ts[valid20], ma20[valid20], penpg.mkPen(#3498db, width1.2), nameMA20) p_main.addLegend(offset(10, 10))成交量副图用BarGraphItem。为了让上涨和下跌的柱子颜色分开我把成交量按涨跌拆成两个BarGraphItem这样比给同一个 Item 传复杂的brushes数组更高效bar_w (ts[1] - ts[0]) * 0.6 up_mask closes opens down_mask ~up_mask vol_up pg.BarGraphItem( xts[up_mask], heightvolumes[up_mask], widthbar_w, penNone, brushpg.mkBrush(UP_COLOR), ) vol_down pg.BarGraphItem( xts[down_mask], heightvolumes[down_mask], widthbar_w, penNone, brushpg.mkBrush(DOWN_COLOR), ) p_vol.addItem(vol_up) p_vol.addItem(vol_down)MACD 副图画的是 DIF、DEA 两条线和红绿柱状图dif, dea, hist calc_macd(closes) hist_up hist 0 hist_down hist 0 macd_up pg.BarGraphItem( xts[hist_up], heighthist[hist_up], widthbar_w, penNone, brushpg.mkBrush(UP_COLOR), ) macd_down pg.BarGraphItem( xts[hist_down], heighthist[hist_down], widthbar_w, penNone, brushpg.mkBrush(DOWN_COLOR), ) p_macd.addItem(macd_up) p_macd.addItem(macd_down) p_macd.plot(ts, dif, pen#ffffff, nameDIF) p_macd.plot(ts, dea, pen#ffff00, nameDEA) p_macd.addLegend(offset(10, 10))这里有一个 Micro 层面的性能决策MACD 柱状图也是用BarGraphItem而不是自己再写一个 item。因为柱子的绘制形态固定官方组件已经够用。真正耗时、需要自定义绘制的只有 K 线本体。4.4 三个图联动时容易出现的坐标轴问题当主图、成交量、MACD 都使用setXLink绑定后整体交互会非常顺滑。但有一点必须注意X 轴的单位时间戳是秒DateAxisItem默认会按本地时区生成刻度文本。如果你的数据源是常见的行情 CSV里面是字符串日期请先统一转成数值时间戳不要用字符串做 X 轴。字符串排序既慢日期轴也无法正确生成刻度。如果发现主图和副图的数据区没有垂直对齐先检查是不是左轴宽度不一致如果某个副图的外框和主图差了一条细线通常是因为按钮区域的setDefaultPadding或者setContentsMargins不一致。这些问题只要统一左轴宽度和布局边距就能解决。5. 大数据量下的绘制优化与踩坑记录5.1 只画可见区域把 paint 变成局部绘制我在第 3 节的CandlestickItem.paint()已经写了可见区间裁剪这里展开讲一下为什么这是最核心的一招。15 万根K线的数据量如果每次重绘都遍历 15 万次QPainter.drawRect一次全量绘制的开销大概在几十毫秒甚至上百毫秒。但屏幕宽度如果只能显示 300 根K线那么你实际只需要绘制这 300 根多画的 14.97 万根都被 Qt 的图形栈拒绝在裁剪区域之外但 CPU 开销仍然白白发生在paint()内部。所以要在自己的代码里提前裁掉。具体的做法我已经写出来了从当前ViewBox.viewRect()拿到左边界和右边界然后用bisect定位数据区间。这样每次paint()的循环次数只取决于屏幕宽度和缩放比例和总数据量没有关系。我实测在 15 万根 5 分钟线上把这段裁剪逻辑去掉前后的帧率差距在 8 倍以上。5.2 静态图用 QPicture 缓存实时图慎用PyQtGraph 官方示例里有一个常见的优化套路在set_data()时把绘制过程录制到QPicture对象里然后paint()里直接p.drawPicture()。这个对静态数据非常有效因为录制一次之后每次重绘只是一次简单的图元重放。但我个人建议实时行情场景不要用QPicture。因为每来一根新K线你都要重新录制整个可见范围或不完整数据段录制的开销会均摊到每个刷新周期上反而没有直接绘制快。我的取舍是离线读取历史K线数据基本不变用 QPicture 缓存实时推送、滚动窗口更新用 5.1 的局部绘制方式不缓存两者的共同前提都是boundingRect()正确、paint()轻量。下面是一个简化的性能对比方便你按项目类型选型场景全量绘制局部绘制QPicture 缓存静态历史数据慢快且每次重绘仍会遍历可见区间最快录制一次即可实时增量数据很慢快适合高频刷新每来一笔都要重录不划算超高缩放/滚动很慢快二分定位索引开销可忽略看数据是否变化静态数据很稳5.3 我在实测中遇到过的三个坑第一个坑是prepareGeometryChange()容易漏。更新self.data后如果没有告诉 Qt “几何范围变了”ViewBox 里保存的旧边界还在。你看到的症状是内容已经变了但鼠标缩放时图形闪烁、残留、甚至出现“拖影”。解决方式就是在set_data()里第一行调用它。第二个坑是p_main.plot(ts, ma5, ...)直接传了含nan的数组。PyQtGraph 对nan的连接策略有时候会画出奇怪的线段。“指标在最初几根没有值”这个问题不能指望图表库自动处理最好自己把有效区间筛出来再传。第三个坑是鼠标十字线用错了坐标转换。正确的做法是拿到scenePos()后用plot_item.vb.mapSceneToView(scenePos)把它转换成数据坐标再设置 InfiniteLine 的位置。如果直接用scenePos设置你会看到十字线出现在完全不合理的屏幕位置上。5.4 实时推送时的更新策略实时行情来时不要每次拿到新 tick 就重新创建一个 CandlestickItem应该复用一个实例调用它的set_data()方法刷新。均线曲线同理预先创建好PlotDataItem然后用setData()更新坐标值。这样可以避免 Item 频繁创建和销毁带来的内存抖动。一个简化的回调结构可以是def update_quote(new_row): # new_row: (ts, open, high, low, close, volume) candle.set_data(np.vstack([candle.data, new_row[:5]])) closes np.append(closes, new_row[4]) ma5 calc_ma(closes, 5) valid ~np.isnan(ma5) ma5_curve.setData(ts[valid], ma5[valid])在窗口化的行情里还可以加一个“只保留最近 500 根”的滚动切片逻辑data data[-500:]Y 轴可以调用p_main.enableAutoRange(axisy)让它自动跟随最新价格区间也可以根据当前可见K线的高低点手工设置setYRange。我个人习惯用后者先算出当前可见区间内 high 的最大值和 low 的最小值再上下加 5% 的边距这样画面不会因为一根异常大阳线而瞬间拉飞。这次从自定义 K 线 Item 到多副图联动再到性能优化基本上把我在做行情工具时遇到的完整链路走了一遍。如果你准备在自己的项目里直接用 PyQtGraph 画 K 线我的建议是先不要急着塞一堆指标第一步把 CandlestickItem 单独跑通用几千根数据验证悬停和缩放第二步再引入成交量、MACD 布局最后再考虑大数据量优化和实时刷新。分阶段调试出问题时很快能定位到是绘制的问题、布局的问题还是性能的问题。我每次接新的行情项目时都这么干实践证明这是最快能落地的方式。
网站建设高端定制企业官网