4. HistoryPanel 可视化

上一章 HistoryPanel（历史数据面板） 介绍了如何把多标的、多指标的历史数据对齐到同一块面板。本章说明如何直接用面板出图：与「先 to_share_frame 再手写 matplotlib」相比，HistoryPanel.plot() 根据当前 htypes 自动组合 K 线、成交量、MACD、折线等视图，使探索数据时的上下文与策略研究阶段保持一致。

4.1. hp.plot()：推荐的统一入口

项目中将 HistoryPanel.plot() 作为唯一推荐的制图入口（旧有接口若仍存在，语义上也应委托到同一套流水线）。你只需保证面板中非空且包含绘图所需的列（例如完整 OHLC 才能出蜡烛图），其余图表类型由内部根据 htypes 自动判定。

常用参数含义如下（完整签名见 HistoryPanel API）：

参数

作用概要

shares

要绘制的标的子集；默认使用面板内全部标的。

layout

多标的布局：'overlay'（同一坐标系叠加）、'stack'（分组纵向分面）、'auto'（例如 2 只标的倾向 overlay，更多则 stack）。

interactive

False 使用 matplotlib 静态图；True 使用 Plotly 交互图（缩放、平移、悬停等）。

highlight

高亮极值点等，例如 'max' / 'min' 或传入配置字典。

plotly_backend_app

仅在 interactive=True 时有效：'auto'（优先 FigureWidget，失败则回退 HTML 包装）、'FigureWidget'、'html'。

说明：当请求的标的数量较多时，实现可能会限制实际绘制的标的数量并发出警告，以避免单图过载；具体以当前版本行为为准。多标的布局的细微调整与历史修复说明见 RELEASE_HISTORY 中 2.2.x 相关条目。

4.2. 静态图与交互图

  • interactive=False（默认）：依赖 matplotlib，适合脚本批量出图、生成静态文件；不强制安装 Plotly。

  • interactive=True：依赖 plotly；在 Jupyter 中若 anywidget 与 ipywidgets 可用，通常可得到 FigureWidget，表头与坐标轴交互更完整；否则可能回退为 HTML 包装 形式，仍具备基本交互，但与 Widget 路径在体验上略有差异。

极简示例（需本地已有 OHLCV 或等价列；仅作形式演示）：

import qteasy as qt

hp = qt.get_history_data(
    htype_names='open, high, low, close, vol',
    shares='000300.SH',
    rows=120,
    as_data_frame=False,
)
fig = hp.plot()                      # 静态
# fig2 = hp.plot(interactive=True)  # 交互（需安装 plotly 等）

当主图为蜡烛图时，静态图会在时间轴最后一根 K 线上显示 OHLC 摘要；交互图默认一致，点击某根 K 线后摘要会更新为该根（面向用户的摘要文案为英文）。无完整 OHLC 时不会出现该摘要区。

4.3. 布局与多标的

  • overlay：适合对比少数标的（如两只股票）在同一价格尺度下的走势（具体是否共享 y 轴以当前实现为准）。

  • stack：每个标的（或每组）单独占一行子图，适合标的较多、避免挤在同一坐标系。

  • auto：在标的数量较少时倾向叠加，较多时倾向分面，减少手动试错。

若某版本后布局语义有调整，以对应版本的 RELEASE_HISTORY 说明为准。

4.4. 依赖与安装提示

  • 静态图：一般需要 matplotlib（与 qteasy 常用环境一致）。

  • 交互图：需要 plotly；完整 Notebook 交互体验建议同时安装 ipywidgets 与 anywidget。可选依赖的版本范围以项目 pyproject.toml 或安装文档为准，本文不逐条罗列版本号。

底层渲染模块名与扩展点仅供开发者阅读源码时使用；用户文档不展开文件级实现细节。

4.5. 小结