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. 小結