Skip to content

One-sixth/lightweight-charts-python

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

302 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

📊lightweight-charts-python v3.0 🚀

cover1 cover2

lightweight-charts-python v3.0 — 基于原作者 v2.1 的特化维护版本,大幅扩展功能。

原版 v2.1 由原作者维护,此后由我接手进行深度定制和功能增强。
从接手时的 v2.5.1v3.0,经历了 15 个子版本迭代21 天密集开发,核心功能覆盖率达 ~85%

✅ 7 种 Series 类型 · TimeScaleApi · PriceScaleApi · 40 个示例 · 8 个测试套件
📖 迁移指南 v2.5→v3.0 | 快查文档 | 更新日志

English Version ReadMe: README_EN.md


🛠️尝试继续维护

本人对 TypeScript 了解比较少,主要依赖 DeepSeek AI 辅助维护
比对了大量的K线绘制库,发现 lightweight-charts-python 唯一功能足够全,性能足够强,易于嵌入QtUI的库,并且存在刚需的功能,遂尝试继续维护

当前已基本排除完bug,examples 全部例子已在windows测试通过
lightweight-chart 主库已更新到 v5.2.0,并添加了一部分v5的新功能

我的主要使用环境为 windows + python 3.13 + PySide6 + WebView,其他环境上面可能有问题。


🫡其他活跃的同类储存库,各有特别的新功能,值得尝试,我也参考了它们的代码

https://github.com/gopalparashar421/lightweight-charts-python
https://github.com/smalinin/bn_lightweight-charts-python
https://github.com/EsIstJosh/lightweight-charts-python


🚀 相比原版 v2.1 的新功能 / 变更 / 增强

以下列出本特化版本相对原作者 v2.1 的全部新增和变更内容。

🔄 架构变更

变更 原版 v2.1 本版 v3.0 说明
组合架构 CandleSeries 附属 volume/OI Volume/OI 独立化 + AbstractChart 组合管理 reset 后自动重建,常驻存在
系列管理 candle.attach_volume() chart.volume / chart.oi 自动管理 设置即用,无需手动挂载
统一输入 各系列列名不统一 统一 time + value 列名标准化
normal_df 自动小写 + date→time 不再自动转换 列名必须精确匹配
sync 同步 sync=chart.id 配对同步 sync_id='组名' 组同步 主图也能参与同步
_lines 联动 chart.set() 自动填充 line chart.set() 不再联动 _lines 需手动 line.set(df)

📝 API 重命名

原版 v2.1 本版 v3.0 说明
marker() add_marker() 添加单条标记
markers() add_markers() 批量添加标记
markers(方法名) markers(列表属性) chart.markers 查看标记列表
update() update_bar() K 线单条更新
update_from_tick() update_tick() Tick 单条更新
update_from_ticks() update_ticks() Tick 批量更新
Line / Histogram LineSeries / HistogramSeries 统一 XxxSeries 命名
toolbox.save_drawings_under() toolbox.on_change += func 回调注册方式
price_scale(perm_width=N) 已移除 无替代

✨ 新增功能

新增 Series 类型

  • AreaSeries — 面积图(折线+渐变填充)
  • OHLCBarSeries — 美国线(横向 OHLC 柱状图)
  • BaselineSeries — 基准线(以基准值为界上下分色)
  • CandleSeries — 独立 K 线系列(任意 pane,无 volume/OI)

新增 API

  • TimeScaleApichart.time_scale_api() 时间轴完整控制(14 方法)
  • PriceScaleApichart.price_scale_api(scale_id) 价格轴完整控制(6 方法)
  • build_price_scale_options() — snake_case→JS 驼峰纯函数
  • chart.fit() / chart.set_visible_range() — 视图控制
  • chart.show(wait=N) — 计时自动关闭窗口
  • chart.chart_options() — 图表级高级选项

新增图表类型

  • HtmlTabChart — 多策略 Tab 切换,init 快照重放
  • CrossProcessChart — 跨进程嵌入 Qt(Windows + Linux/X11)
  • ReflexChart — Reflex 框架嵌入
  • HTMLChart / JupyterChart / StreamlitChart / QtChart / WxChart — 多种嵌入方式

绘图系统增强

  • ToolBox 跨 Pane 绘图 — 鼠标点击自动识别目标 pane
  • Pane Primitive 架构 — Drawing 直接附着到 pane,不依赖 series 数据
  • ToolBox on_change 回调+= / -= 注册/卸载多回调
  • DrawingInfo 增强 — 新增 pane_index/time/price 字段
  • Legend OHLC 支持 — Bar/Candlestick 显示 O H L C
  • Legend 分组 — 组开关一键切换可见性

批量 & 性能

  • update_bars(df) — 批量 OHLCV 增量更新(JS 命令合并发送)
  • update_ticks(df) — 批量 Tick 增量更新
  • update_bars() 用于 Line/Histogram — 序列批量更新
  • 消息循环异常保护 — 不会因为单条消息失败而终止

其他增强

  • Histogram 任意颜色 — 每根柱子独立着色(color 列)
  • reset_sub() — 子图内容重置,保留布局
  • 网格布局系统position 参数三种格式,类似 matplotlib subplot
  • 运行时位置控制get_position() / set_position()
  • sync_id 组同步 — 替代旧配对同步
  • 8 个测试套件 — 全面覆盖资源清理 / 功能 / 数据聚合 / 位置解析等
  • 40 个示例 — 从基础到高级跨 Pane 绘图
  • 精细资源回收 — 长时间运行几乎无内存泄露
  • _remove_my_handlers() — 精确清除 handler,避免多图表误杀

🧰 主要支持环境 — PySide6、PyQt6、wxPython


⚠️ 破坏性更改:v2.5.1 → v3.0

v3.0 是 lightweight-charts-python 的第一个正式大版本,所有 Breaking Changes 已合并为一份清单。
详细迁移步骤见 MIGRATION_v2.5_to_v3.0.md,包含逐项对照和验证清单。

同步机制:sync=chart.idsync_id='组名'

# ❌ 旧写法 — 链式传递 chart.id,配对同步
chart = Chart(...)
sub = chart.create_subchart(sync=chart.id)

# ✅ 新写法 — 组名同步,主图也参与
chart = Chart(..., sync_id='main')
sub = chart.create_subchart(sync_id='main')

函数重命名

旧名称 新名称
update_from_tick() update_tick()
update_from_ticks() update_ticks()
update() / update_bar() 统一 update_bar() / update_bars()
marker() add_marker()
markers() add_markers()
markers(方法) markers(列表属性)
Line / Histogram LineSeries / HistogramSeries

类重命名

旧名称 新名称
Line LineSeries
Histogram HistogramSeries

工厂方法 create_line() / create_histogram() 名称不变,返回类型变为 LineSeries / HistogramSeries

AbstractChart 不再联动设置 _lines

chart.set(df) / chart.update_bars(df) / chart.update_ticks(df) 不再自动转发数据给 Line/Histogram 系列,需手动 line.set(df)

normal_df 移除小写转换和 date 列支持

列名必须精确匹配小写格式(time, open, high, low, close, value),不再自动转换。

# ❌ 旧写法 — 依赖自动转换
df = pd.DataFrame({'Date': dates, 'Open': ..., 'Close': ...})
chart.set(df)  # 自动转小写

# ✅ 新写法 — 列名必须精确
df = pd.read_csv('data.csv').rename(columns={'date': 'time'})
chart.set(df)

VolumeSeries / OpenInterestSeries 统一使用 value 列

独立创建时使用 value 列(不再用 volume / open_interest 列名)。通过 chart 调用时自动转发,无感知。

参数移除

参数 说明
price_scale(perm_width=N) 已移除,无替代
cumulative_volume 已移除,VolumeSeries 始终自动求和
toolbox.save_drawings_under() 改为 toolbox.on_change += func
toolbox.load_drawings() / import_drawings() / export_drawings() 已移除,用 on_change 自行实现

🤖建议让 AI编程助手 先阅读 QUICK_REFERENCE.md 文件,快速了解全项目


使用PYPI安装

pip install lightweight-charts-onesixth

使用源码安装

pip install https://github.com/One-sixth/lightweight-charts-python

构建

构建本包,需要安装有 node.js 环境,需要调用 npm 命令

先构建 JS bundle 库。

下载node包的依赖

npm install @rollup/plugin-typescript --save-dev
npm audit fix --force

构建和复制成品到python源码目录

npx rollup -c rollup.config.js
cp dist/bundle.js lightweight_charts/js/bundle.js

构建 whl 包

python -m build

构建完成的whl包在dist目录中


核心 API 速查

方法 说明
chart.set(df) 设置 K线数据
chart.update_bar(series) 更新最后一根 K线
chart.update_tick(series) 从逐笔成交更新 K线
chart.add_marker(time, ...) 添加价格标记
chart.marker_auto_scale(enable) 控制标记是否参与价格轴缩放
chart.pop(count) 从末尾移除 N 个数据点
chart.create_line(name, ...) 创建折线指标(返回 LineSeries)
chart.create_histogram(name, ...) 创建柱状图指标(返回 HistogramSeries)
chart.create_area_series(name, ...) 创建面积图
chart.create_ohlc_bar_series(name, ...) 创建美国线
chart.create_baseline_series(name, ...) 创建基准线
chart.create_subchart(...) 创建子面板
chart.create_price_line(price, ...) 创建价格线
chart.horizontal_line(price, ...) 创建水平线
chart.vertical_span(start, end, ...) 创建垂直高亮区间
chart.get_position() 获取图表渲染位置 (x, y, width, height) 百分比
chart.set_position(x, y, width, height) 动态设置图表渲染位置
chart.audit(use_js=False) 资源审计(Python 侧)
chart.audit(use_js=True) 资源审计(JS 侧,TOML 格式)
chart.reset() 重置图表到初始状态
chart.screenshot(...) 截图(支持 add_top_layer 和 include_crosshair)
chart.price_scale(price_format=...) 配置价格坐标轴
chart.time_scale_api() 时间轴 API(滚动/范围/事件订阅)
chart.price_scale_api(scale_id) 价格轴 API(选项/范围/尺寸)

🎯 高级 API:TimeScaleApi & PriceScaleApi

基础功能(配置、数据设置)使用上面的 Python 函数即可。
如需事件回调更精细的控制,请使用以下 API:

# 时间轴 API
chart.time_scale_api().scroll_to_real_time()
chart.time_scale_api().subscribe_visible_logical_range_change(handler)

# 价格轴 API(默认右侧)
chart.price_scale_api().width()
chart.price_scale_api().set_auto_scale(True)

# 价格轴 API(指定左侧)
chart.price_scale_api('left').apply_options(scale_margin_top=0.1)
API 方法 说明
TimeScaleApi scroll_position() 获取滚动位置
scroll_to_position(pos) 滚动到指定位置
scroll_to_real_time() 滚动到实时数据
fit_content() 数据适应视口
get_visible_range() 获取可见范围
set_visible_range(range) 设置可见范围
width() 获取宽度
subscribe_visible_logical_range_change(handler) 订阅逻辑范围变化
subscribe_visible_time_range_change(handler) 订阅时间范围变化
subscribe_size_change(handler) 订阅尺寸变化
PriceScaleApi apply_options(**kwargs) 应用选项
options() 获取选项
width() 获取宽度
set_auto_scale(on) 设置自动缩放

📖 详见 QUICK_REFERENCE.md 的 3.8.1 和 3.8.2 章节


文档与支持

建议通过 examples 例子来学习,ReadMe 下方有大量参考代码和画廊
若要了解全部功能,可以阅读 QUICK_REFERENCE.md 文件,我尽量让它包含了所有功能的详细说明和示例代码


免责声明: 本包为独立开发,未经 TradingView 背书、赞助或批准。作者与 TradingView 无任何官方关系,本包不代表 TradingView 的观点或立场。


📦 chart_model — 图表数据模型简易实现模板(原型)

本仓库的 chart_model/ 子包是一个纯数据层的图表模型声明式实现模板

它不是供你直接 pip install 使用的库,而是提供一个简易可参考的原型实现

from chart_model import Model, Window, Chart, Series, Adapter

model = Model(
    windows=[Window(name='main', display_name='主窗口')],
    charts=[Chart(name='price', display_name='价格', window='main', interval='1day')],
    series=[Series(name='candle', display_name='K线', chart='price', pane=0, type='candle')],
)
model['candle'].set(df)
layout = model.build(live=True)
chart = Adapter.render(layout)

💡 设计理念

⚠️ 注意: chart_model 目前只提供了基本功能支持,API 可能尚未定型,后续可能会调整。

建议参考其实现思路和设计模式来了解如何组织图表数据层,但不太推荐直接使用。 如果你的项目需要一个图表数据层架构,让 AI 参考这里的实现,按你的需求生成一份更合适的版本。

📍 位置:chart_model/(本仓库子目录)
📄 设计文档:chart_model/CHART_MODEL_DESIGN.md
⚡ 3 个示例:01_hello_world / 02_multi_window_dashboard / 03_drawing_live


完整示例目录

序号 示例名称 功能说明
1 1_setting_data 基础数据设置
2 2_live_data 实时 K线更新
3 3_tick_data Tick 数据更新
4 4_line_indicators 折线指标 SMA
5 5_styling 样式定制
6 6_callbacks 回调事件
7 7_multi_pane 多面板图表
8 8_volume_open_interest 成交量+持仓量
9 9_multi_chart 多 Chart 实例
10 10_persistent_legend 常驻图例
11 11_vertical_span 垂直区间高亮
12 12_audit 资源审计
13 13_batch_update 批量更新 API
14 14_set_period 时间周期锁定
15 15_pyside6_simple PySide6 集成
16 16_pyside6_race PySide6 性能测试
18 18_hovered_series_on_top 悬停系列置顶
19 19_timescale_options 时间轴选项
20 20_tick_mark_density 刻度密度控制
21 21_marker_auto_scale 标记自动缩放
22 22_pop 移除数据点
23 23_crosshair_move 十字光标事件
24 24_price_format 价格格式设置
25 25_screenshot_enhanced 增强截图
26 26_series_batch_update 序列批量更新
27 27_reflex_chart Reflex 集成
28 28_cross_process_chart 跨进程嵌入 Qt
29 29_grid_layout 网格布局系统
30 30_table_component 表格组件(自选股/持仓管理)
31 31_chart_sync 图表同步功能(时间轴+十字光标)
32 32_html_tab_chart HtmlTabChart 多策略 Tab 切换
33 33_reset_sub reset_sub 子图内容重置
34 34_candle_series CandleSeries 独立K线系列
35 35_line_markers Line / Histogram 系列标记(marker)
36 36_histogram_colors Histogram 任意颜色(per-bar 着色)
37 37_more_series_types AreaSeries / OHLCBarSeries / BaselineSeries 新系列
38 38_drawing_multi_pane 跨 Pane 绘图:Drawing 在多个面板间分布
39 39_legend_group Legend 分组:组开关 + 个人眼睛切换
40 40_toolbox_multi_pane ToolBox 跨 Pane 绘图:3 pane 绘图工具箱

共 40 个示例(v3.0)

示例截图展示

以下为所有示例的截图位置,可根据实际效果替换图片

示例 1:显示 CSV 数据

import pandas as pd
from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    df = pd.read_csv('ohlcv.csv')
    chart.set(df)
    chart.show(block=True)

显示CSV数据


示例 2:实时更新 K线

import pandas as pd
from time import sleep
from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    df1 = pd.read_csv('ohlcv.csv')
    df2 = pd.read_csv('next_ohlcv.csv')
    chart.set(df1)
    chart.show()
    for _, bar in df2.iterrows():
        chart.update_bar(bar)
        sleep(0.1)

实时K线更新


示例 3:从 Tick 数据更新

import pandas as pd
from time import sleep
from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    chart.set(pd.read_csv('ohlc.csv'))
    chart.show()
    for _, tick in pd.read_csv('ticks.csv').iterrows():
        chart.update_tick(tick)
        sleep(0.03)

Tick数据更新


示例 4:折线指标(SMA)

import pandas as pd
from lightweight_charts import Chart

def calculate_sma(df, period=50):
    return pd.DataFrame({
        'time': df['date'],
        f'SMA {period}': df['close'].rolling(period).mean()
    }).dropna()

if __name__ == '__main__':
    chart = Chart()
    df = pd.read_csv('ohlcv.csv')
    chart.set(df)
    line = chart.create_line('SMA 50')
    line.set(calculate_sma(df, 50))
    chart.show(block=True)

折线指标


示例 5:样式定制

import pandas as pd
from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    df = pd.read_csv('ohlcv.csv')
    chart.layout(background_color='#090008', text_color='#FFFFFF')
    chart.candle_style(up_color='#00ff55', down_color='#ed4807')
    chart.watermark('1D', color='rgba(180,180,240,0.7)')
    chart.set(df)
    chart.show(block=True)

样式定制


示例 6:回调事件

import pandas as pd
from lightweight_charts import Chart

def on_search(chart, searched_string):
    new_data = get_bar_data(searched_string, chart.topbar['timeframe'].value)
    if not new_data.empty:
        chart.topbar['symbol'].set(searched_string)
        chart.set(new_data)

if __name__ == '__main__':
    chart = Chart(toolbox=True)
    chart.events.search += on_search
    chart.topbar.textbox('symbol', 'TSLA')
    chart.topbar.switcher('timeframe', ('1min', '5min', '30min'))
    chart.set(get_bar_data('TSLA', '5min'))
    chart.show(block=True)

回调事件


示例 7:多面板图表

import pandas as pd
from lightweight_charts import HTMLChart

def demo():
    chart = HTMLChart(
        width=1200, height=800,
        position=111,                   # 图表位置 (网格格式)
        pane_index=0,                   # 面板索引
        marker_auto_scale=True          # 标记是否自动缩放
    )
    df = pd.read_csv('ohlcv.csv')
    chart.set(df)
    line7 = chart.create_line('SMA 7', color='red')
    line7.set(df[['date', 'close']].rename(columns={'close': 'SMA 7'}))
    chart.show()

if __name__ == '__main__':
    demo()

多面板图表


示例 8:成交量 + 持仓量

import pandas as pd
from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart(toolbox=True)
    df = generate_data()  # 包含 open_interest 列
    chart.set(df)
    chart.show(block=True)

成交量持仓量


示例 9:多 Chart 实例

import asyncio
from threading import Thread
from lightweight_charts import Chart

def run_chart(chart):
    asyncio.run(chart.show_async())

if __name__ == '__main__':
    chart1 = Chart(title='AAPL')
    chart2 = Chart(title='TSLA')
    chart1.set(df1)
    chart2.set(df2)
    t1 = Thread(target=run_chart, args=(chart1,), daemon=True)
    t2 = Thread(target=run_chart, args=(chart2,), daemon=True)
    t1.start()
    t2.start()

多Chart实例


示例 10:常驻图例

import pandas as pd
from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    df = generate_data()
    chart.legend(visible=True, ohlc=True, persistent=True)
    chart.set(df)
    chart.show(block=True)

常驻图例


示例 11:垂直区间高亮

import pandas as pd
from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    df = pd.read_csv('ohlcv.csv')
    chart.set(df)
    chart.vertical_span(start_time='2024-01-05', end_time='2024-06-10', color='rgba(252,219,3,0.15)')
    chart.show(block=True)

垂直区间高亮


示例 12:资源审计

from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart(toolbox=True)
    chart.set(df)
    # 创建各种资源...
    result = chart.audit(use_js=True)  # JS侧状态检查
    print(result)
    chart.show(block=True)

资源审计


示例 13:批量更新

import pandas as pd
from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    chart.set(initial_df)
    chart.show()
    # 批量更新
    chart.update_bars(new_bars_df)
    chart.update_ticks(ticks_df)

批量更新


示例 14:时间周期锁定

import pandas as pd
from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    chart.set(df_5min)
    chart.set_period(3600)  # 锁定为1小时
    chart.set(df_30min)  # 重要:set_period 后需重新 set() 使其生效,仍按1小时显示
    chart.show(block=True)

时间周期锁定


示例 15:PySide6 集成

import sys
from PySide6.QtWidgets import QMainWindow, QVBoxLayout, QWidget
from lightweight_charts.widgets import QtChart

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.chart = QtChart()
        layout = QVBoxLayout()
        layout.addWidget(self.chart.get_webview())
        self.chart.set(df)

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

PySide6集成


示例 16:PySide6 性能测试

import sys
from PySide6.QtWidgets import QMainWindow
from lightweight_charts.widgets import QtChart

class SpeedRaceWindow(QMainWindow):
    def run_batch_race(self):
        start = time.perf_counter()
        self.chart.update_bars(new_bars)
        elapsed = time.perf_counter() - start
        print(f'update_bars: {elapsed:.4f}s')

PySide6性能测试


示例 18:悬停系列置顶

from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    chart.chart_options(hovered_series_on_top=True)  # v5.2.0+
    chart.set(df)
    chart.show(block=True)

悬停系列置顶


示例 19:时间轴选项

from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    chart.time_scale(
        right_offset_pixels=50,
        enable_conflation=True,
        precompute_conflation_on_init=True
    )
    chart.set(large_df)
    chart.show(block=True)

时间轴选项


示例 20:刻度密度控制

from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    chart.price_scale(tick_mark_density=2.5)  # v5.2.0+
    chart.set(df)
    chart.show(block=True)

刻度密度控制


示例 21:标记自动缩放

from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart(marker_auto_scale=False)
    chart.set(df)
    chart.add_marker(time='2024-01-15', position='above', text='Event')
    chart.show(block=True)

标记自动缩放


示例 22:移除数据点

from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    chart.set(df)
    chart.pop(50)  # 移除最后50个数据点
    chart.show(block=True)

移除数据点


示例 23:十字光标事件

def on_crosshair_move(chart, payload):
    dt = pd.to_datetime(payload['time'], unit='s')
    print(f'{dt} | price = {payload.get("price")}')

if __name__ == '__main__':
    chart = Chart()
    chart.events.crosshair_move += on_crosshair_move
    chart.set(df)
    chart.show(block=True)

十字光标事件


示例 24:价格格式设置

from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    chart.set(df)
    chart.price_scale(price_format={'type': 'base', 'base': 100, 'precision': 2})
    chart.show(block=True)

价格格式设置


示例 25:增强截图

from lightweight_charts import Chart
import time

if __name__ == '__main__':
    chart = Chart()
    chart.set(df)
    chart.watermark('截图演示')
    chart.show(block=False)
    time.sleep(2)
    img = chart.screenshot(add_top_layer=True, include_crosshair=True)
    with open('screenshot.png', 'wb') as f:
        f.write(img)

增强截图


示例 26:序列批量更新

from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart()
    chart.set(df)
    line = chart.create_line('SMA 20')
    line.update_bars(sma_data)  # 批量更新序列
    chart.show(block=True)

序列批量更新


示例 27:Reflex 集成

import reflex as rx
from lightweight_charts import ReflexChart

chart = ReflexChart(width=1000, height=600, auto_flush=True)
chart.set(pd.read_csv('ohlcv.csv'))

class ChartState(rx.State):
    def tick(self):
        chart.update(_next_bar())
        return chart.flush()

Reflex集成


示例 28:跨进程嵌入 Qt

from PySide6.QtWidgets import QMainWindow
from lightweight_charts import CrossProcessChart

class MainWindow(QMainWindow):
    def __init__(self):
        self.chart = CrossProcessChart(parent=self, width=800, height=500)
        self.chart.set(df)

跨进程嵌入Qt


示例 29:网格布局

from lightweight_charts import Chart

if __name__ == '__main__':
    chart1 = Chart(position=221)  # 2行2列第1个
    chart2 = chart1.create_subchart(position=222)
    chart3 = chart1.create_subchart(position=223)
    chart4 = chart1.create_subchart(position=224)
    chart1.set(df)
    chart1.show(block=True)

网格布局


示例 30:表格组件

from lightweight_charts import Chart

if __name__ == '__main__':
    chart = Chart(width=1000, height=600)
    chart.set(df)
    
    # 创建自选股表格
    watchlist = chart.create_table(
        width=0.22,
        height=0.4,
        headings=('Symbol', 'Price', 'Chg%', 'Volume'),
        widths=(0.35, 0.25, 0.2, 0.2),
        alignments=('left', 'right', 'right', 'right'),
        position=(0.02, 0.1),  # 使用相对坐标 (x, y),范围 0-1
        draggable=True,
        func=on_watchlist_click
    )
    
    # 添加数据
    watchlist.new_row('AAPL', '198.50', '+1.2%', '12.5M')
    watchlist.new_row('GOOGL', '141.80', '-0.8%', '8.2M')
    watchlist.new_row('MSFT', '420.30', '+2.1%', '15.8M')
    
    # 设置样式
    watchlist.header(color='rgba(70, 130, 180, 0.8)', text_color='#FFFFFF')
    watchlist.rows[0].background_color('rgba(0, 255, 0, 0.1)')
    
    chart.show(block=True)

position 参数说明:

格式 示例 说明
元组 (x, y) (0.02, 0.1) 推荐:相对坐标,范围 0-1
元组 (x, y) (100, 50) 像素坐标,值 >= 1 时视为像素
字符串(已废弃) 'left', 'right' 不推荐,会触发 DeprecationWarning,等效于 (0, 0)

表格组件


示例 31:图表同步

from lightweight_charts import Chart

if __name__ == '__main__':
    # 创建主图表 - 使用 2x2 网格布局
    chart = Chart(width=1200, height=800, title='Chart Sync Demo', position=(2, 2, 1))
    
    # 创建右侧子图表(完全同步时间轴和十字光标)
    subchart_right = chart.create_subchart(
        position=(2, 2, 2),
        sync_id=chart.id,           # 同步到主图表
        sync_crosshairs_only=False  # 完全同步
    )
    
    # 创建底部子图表(仅同步十字光标)
    subchart_bottom = chart.create_subchart(
        position=223,            # 等同于 (2, 2, 3)
        width=2.0,               # 横跨两列
        sync_id=chart.id,
        sync_crosshairs_only=True  # 仅同步十字光标
    )
    
    chart.set(df)
    subchart_right.set(df2)
    subchart_bottom.set(df3)
    chart.show(block=True)

sync_id 参数说明:

参数 类型 说明
sync_id boolstr True 同步到父图表;字符串为目标图表的 id
sync_crosshairs_only bool True 仅同步十字光标,时间轴独立

图表同步


示例 32:HtmlTabChart(多策略 Tab 切换)

from lightweight_charts import HtmlTabChart

chart = HtmlTabChart(width=1200, height=800)

# 策略1:均线交叉
chart.set_name('均线交叉策略')
chart.set(df1)
chart.set_trades(trades1)
chart.set_performance_metrics(perf1, '均线交叉策略')
chart.set_parameters_list(params1)
chart.new_window()  # 切换到下一个策略

# 策略2:布林带
chart.set_name('布林带策略')
chart.set(df2)
chart.set_trades(trades2)
chart.set_performance_metrics(perf2, '布林带策略')
chart.set_parameters_list(params2)

chart.export('multi_charts.html')

HtmlTabChart 功能:

功能 说明
多策略切换 左侧边栏切换不同策略的 K 线图
技术指标 支持 SMA、布林带等指标叠加
买卖标记 开仓/平仓箭头标记
交易明细 表格展示交易记录,双击跳转
绩效指标 夏普比率、最大回撤、胜率等
策略参数 显示每个策略的配置参数
图例显示 左上角显示所有指标名称

改自 smalinin/bn_lightweight-charts-python 的 HtmlChart_BN

HtmlTabChart


示例 33:reset_sub(子图内容重置)

from lightweight_charts import Chart

chart = Chart(width=1400, height=900, position=(2,2,1), toolbox=True)
sub_a = chart.create_subchart(position=(2,2,2), toolbox=True, sync_id=chart.id)
sub_b = chart.create_subchart(position=(2,2,3), sync_id=chart.id)
sub_c = chart.create_subchart(position=(2,2,4), toolbox=True)  # 不同步

# 填充数据
chart.set(bars_main); sub_a.set(bars_a); sub_b.set(bars_b); sub_c.set(bars_c)

# reset sub_b → 清除全部内容,保留布局
sub_b.reset_sub()

# 重新填充 → 子图可重用
sub_b.set(new_bars)

# reset 主图 → 也不影响其他子图
chart.reset_sub()
chart.set(new_bars)

reset_sub 功能:

清除范围 说明
K线/成交量/持仓量数据 clear_data()
折线/柱状图系列 Line.delete() / Histogram.delete()
价格线 PriceLine.delete()
标记 clear_markers()
绘图 Drawing.delete()
表格 Table.delete()
ToolBox DrawingTool 事件 + ContextMenu + commandFunction + DOM
TopBar Widget 回调 + DOM
Legend crosshair 订阅 + DOM
Events JSEmitter 事件订阅
syncCharts 双向解关联 + 重建
handlers 按 salt 匹配清理

reset 后子图可重新填充使用,十字光标和时间轴同步自动恢复

reset_sub


示例 34:CandleSeries(独立K线系列)

import pandas as pd
from lightweight_charts import Chart

# 主K线
chart = Chart(width=1400, height=900)
chart.set(df_main)

# 参考K线(独立 pane)
ref = chart.create_candle_series(
    name='参考品种',
    pane_index=1,
    up_color='rgba(0, 150, 255, 0.8)',
    down_color='rgba(255, 100, 0, 0.8)',
)
ref.set(df_reference)       # 初始数据
ref.update_bar(new_bar)         # 更新/追加
ref.update_bars(df_more)   # 批量追加
ref.add_marker(...)             # 打标记

chart.show(block=True)

CandleSeries 功能:

功能 说明
create_candle_series() 创建独立K线(无 volume/open interest)
set(df) 设置初始 OHLC 数据
update(series) 更新最新一根 bar 或追加新 bar
update_bars(df) 批量更新多根 bar
add_marker(...) 在独立K线上打标记
delete() 删除系列并清理 JS 对象
pane_index 控制绘制在哪个 pane

独立K线适用于参考K线、对比K线等场景,支持与主K线同步十字光标

CandleSeries


示例 35:Line / Histogram 系列标记

from lightweight_charts import Chart

chart = Chart(width=1200, height=700, title='Line Series Markers Demo')
chart.set(candle_df)

# 在 Line 上打标记
line20 = chart.create_line('SMA20', color='#2196F3', width=2)
line20.set(sma20)
line20.add_marker(dates[25], 'below', 'circle', '#2196F3', 'SMA20 Cross')

# 在 Histogram 上打标记
hist = chart.create_histogram('Volume', color='rgba(100,100,200,0.5)', pane_index=1)
hist.set(vol_df)
hist.add_marker(dates[5], 'below', 'circle', '#9C27B0', 'Vol Spike')

# 批量打标记
line20.add_markers([
    {'time': dates[35], 'position': 'below', 'shape': 'arrow_up', 'color': '#00BCD4', 'text': 'Batch 1'},
    {'time': dates[45], 'position': 'above', 'shape': 'arrow_down', 'color': '#00BCD4', 'text': 'Batch 2'},
])

chart.show(block=True)

支持标记的系列:

系列 add_marker() add_markers()
CandleSeries(主 K 线)
LineSeries(折线)
HistogramSeries(柱状图)
HistogramSeries(柱状图)

Line Series Markers


示例 36:Histogram 任意颜色(per-bar 着色)

from lightweight_charts import Chart

chart = Chart(width=1200, height=700, title='Histogram Custom Colors Demo')
chart.set(candle_df)

# DataFrame 中包含 color 列,每根柱子独立着色
delta_df = pd.DataFrame({
    'time': dates,
    'value': delta,          # 正值=买方强,负值=卖方强
    'color': colors,         # 每根柱子对应一个颜色
})

hist = chart.create_histogram(
    name='Volume Delta',
    color='rgba(100,200,100,0.5)',
    pane_index=1,
)
# 注意:chart.set() 不会转发 color 列,histogram 必须单独 set()
hist.set(delta_df)

chart.show(block=True)

per-bar 着色要点:

要点 说明
color DataFrame 中包含 color 列即可自动着色
chart.set() 不转发 color 列,histogram 必须单独 set()
正负值 支持正负值双向着色(如 Volume Delta:买方→暖色,卖方→冷色)

Histogram Colors


示例 37:新 Series 类型(Area / OHLC Bar / Baseline)

from lightweight_charts import Chart

chart = Chart(width=1200, height=800, title='New Series Types Demo')
chart.set(df)

# 1. AreaSeries — 面积图(折线+渐变填充)
area = chart.create_area_series(
    name='SMA 20 (Area)',
    color='#2196F3',
    top_color='rgba(33, 150, 243, 0.35)',
    bottom_color='rgba(33, 150, 243, 0.0)',
)
area.set(sma20_df)

# 2. OHLCBarSeries — 美国线(OHLC 横向柱状图)
ohlc_bar = chart.create_ohlc_bar_series(
    name='OHLC Bar',
    up_color='#26A69A',
    down_color='#EF5350',
    pane_index=1,
)
ohlc_bar.set(df)

# 3. BaselineSeries — 基准线(以基准值为界上下分色)
baseline = chart.create_baseline_series(
    name='RSI Deviation',
    baseline_value=0,
    topLineColor='#26A69A',
    bottomLineColor='#EF5350',
    pane_index=2,
)
baseline.set(rsi_df)

chart.show(block=True)

新 Series 类型一览:

类型 工厂方法 适用场景
AreaSeries create_area_series() 面积图:均线、波动率等趋势填充
OHLCBarSeries create_ohlc_bar_series() 美国线:K 线的另一种画法
BaselineSeries create_baseline_series() 基准线:RSI 偏差、盈亏等以零轴为界的指标
legend=False 所有系列均支持 隐藏辅助系列(背景带、辅助线等)不显示在图例中

New Series Types


示例 38:跨 Pane 绘图

from lightweight_charts import Chart

# 3 个 pane 的绘图演示
chart = Chart(width=1200, height=800, title='Drawing Series Multi-Pane', toolbox=True)
chart.legend(visible=True)
chart.set(df)

# Pane 0: K线 + 水平线 + 趋势线 + Box
chart.horizontal_line(price=200, color='orange', width=2, text='均价')
chart.trend_line(start_time, start_price, end_time, end_price, color='#1E80F0')
chart.box(start_time, start_price, end_time, end_price, color='#E91E63')

# Pane 1: 柱状图 + 射线 + 水平线
hist = chart.create_histogram('RSI Dev', pane_index=1)
chart.ray_line(start_time, value=50, color='gray', pane_index=1)
chart.horizontal_line(price=70, color='red', pane_index=1)

# Pane 2: 折线 + 垂直线
sma = chart.create_line('SMA 50', pane_index=2)
chart.vertical_line(time=key_time, color='#FF5722', pane_index=2)

chart.show(block=True)

跨 Pane 绘图


示例 39:Legend 分组

from lightweight_charts import Chart

chart = Chart()
chart.legend(visible=True, ohlc=True, percent=True, lines=True)
chart.set(df)

# group='MA' 的均线组:同一行显示,♦ MA 组开关一键切换
sma20 = chart.create_line('SMA 20', color='yellow', width=1, group='MA')
ema50 = chart.create_line('EMA 50', color='cyan', width=1, group='MA')

# group='MOM' 的动量组
roc = chart.create_line('ROC 10', color='red', width=1, group='MOM')
mom = chart.create_line('MOM 10', color='green', width=1, group='MOM')

# 无组的独立显示
rsi = chart.create_line('RSI 14', color='purple', pane_index=1)

chart.show(block=True)

Legend 交互:

  • 组开关:点击一键切换组内所有 series 可见性
  • 👁 个人眼睛:切换单个 series,同步更新组开关状态
  • 支持跨 pane 同名分组

Legend 分组


示例 40:ToolBox 跨 Pane 绘图

from lightweight_charts import Chart
from lightweight_charts.toolbox import DrawingInfo

chart = Chart(width=1200, height=800, title='ToolBox Multi-Pane', toolbox=True)
chart.set(df)

# 创建 3 个 pane
sma = chart.create_line('SMA 7', color='red', pane_index=0)
hist = chart.create_histogram('SMA 20', color='#9B59B6', pane_index=1)
rsi = chart.create_line('RSI', color='#26A69A', pane_index=2)

# 注册绘图变化回调(自动携带 pane_index)
def on_drawings_change(drawings: list[DrawingInfo]):
    for d in drawings:
        print(f'pane={d.pane_index}  type={d.type}  '
              f'time=[{d.start_time}, {d.end_time}]')

chart.toolbox.on_change += on_drawings_change

chart.show(block=True)

ToolBox 跨 Pane 特性:

  • ToolBox UI 固定在 Pane 0
  • 鼠标点击哪个 pane 就在哪个 pane 上创建 drawing
  • 回调中自动携带 pane_index 信息

ToolBox 跨 Pane


About

Python framework for TradingView's Lightweight Charts JavaScript library.

Resources

License

Stars

4 stars

Watchers

1 watching

Forks

Packages

 
 
 

Contributors