lightweight-charts-onesixth v2.8.1 → v3.1.1 更新总览Python 调用 TradingView 级别交互式图表不写一行 JS。 新功能总览过去 22 个版本v2.8.1 → v3.1.1新增了以下核心能力类别新增内容新 Series 类型AreaSeries面积图、OHLCBarSeries美国线、BaselineSeries基准线绘图系统Pane Primitive 架构、ToolBox on_change 多回调、跨 Pane 绘图图表 APITimeScaleApi14 方法、PriceScaleApi6 方法、chart.show(waitN)数据模型chart_model 子包声明式纯数据模型与渲染层解耦Volume/OI独立化升级一等公民CandleSeries独立 K 线系列任意 Pane 绘制同步机制sync_id 组同步时间轴秒级时间显示支持 新增 Series 类型AreaSeries — 面积图折线 渐变填充适合展示 MACD、成交量差等指标。# 创建areachart.create_area(nameMACD,color#FF9800,width2,top_color#FF9800,# 渐变上色bottom_color#FF980000,# 渐变下色带透明度relative_gradientTrue,# 相对渐变沿图表高度invert_filled_areaFalse,# 是否反转填充区域)# 数据输入 — 统一 time value 列area.set(df)# 更新area.update_bars(df)area.update_ticks(df)OHLCBarSeries — 美国线传统 OHLC 柱状图open 左 close 右适合习惯美线风格的交易者。# 创建ohlcchart.create_ohlc_bar(nameK线,up_color#26a69a,down_color#ef5350,open_visibleTrue,# 是否显示左侧 open 横线thin_barsFalse,# 细线模式)# 数据输入 — 与 Candle 完全一致time open high low closeohlc.set(df)# 样式配置 — 注意用 bar_style() 不是 candle_style()ohlc.bar_style(up_color#26a69a,down_color#ef5350)# ohlc.candle_style() ← 会抛 AttributeError提示用 bar_style()BaselineSeries — 基准线以基准值如 0 轴为界上下分色适合展示乖离率、RSI 等。# 创建bslchart.create_baseline(name乖离率,base_value0,# 基准值top_fill_color1#26a69a80,# 线上填充色top_fill_color2#26a69a40,top_line_color#26a69a,# 线上线条色bottom_fill_color1#ef535080,# 线下填充色bottom_fill_color2#ef535040,bottom_line_color#ef5350,# 线下线条色line_width2,relative_gradientTrue,)# 数据输入 — time valuebsl.set(df) 绘图系统Drawing/ToolBox架构升级ISeriesPrimitive → IPanePrimitive旧画线附着到 Series依赖 Series 数据状态空 Series 不能画线。新画线直接附着到 Pane不依赖任何 Series 数据跨 Pane 稳定。# 5 种画线类型chart.horizontal_line(price3600,color#FF9800,text阻力位,pane_index0)chart.vertical_line(time2022-02-01,color#26a69a)chart.trend_line(start(2022-02-01,3500),end(2022-02-03,3800))chart.ray_line(start(2022-02-01,3400),angle45)chart.box(top_left(2022-02-01,3900),bottom_right(2022-02-03,3400))ToolBox 回调系统旧save_drawings_under(widget)单回调绑定持久化控件。新on_change func支持多回调注册/卸载。# 新方式defon_drawings_changed(drawings:list[DrawingInfo]):save_to_db(drawings)# 自行实现持久化chart.toolbox.on_changeon_drawings_changed# 卸载chart.toolbox.on_change-on_drawings_changed# DrawingInfo 包含完整信息fordinchart.toolbox.drawings_list:print(d.id,d.type,d.points,d.pane_index,d.options)迁移指南旧 API新 APItoolbox.save_drawings_under(w)用on_change回调自行实现持久化toolbox.load_drawings(tag)用on_change回调自行实现toolbox.import_drawings(path)用on_change回调自行实现toolbox.export_drawings(path)用on_change回调自行实现内置 CtrlZ 撤销已移除需自行实现⏰ 时间轴 / 价格轴 API时间轴 — TimeScaleApi旧只有chart.fit()和chart.set_visible_range()两个方法。新chart.time_scale_api()返回TimeScaleApi实例覆盖 14 个方法。apichart.time_scale_api()# 滚动控制api.scroll_position()# 获取当前滚动位置api.scroll_to_position(0.5)# 滚动到 50% 位置api.scroll_to_real_time()# 滚动到实时数据# 范围管理api.get_visible_range()# 获取可见时间范围api.set_visible_range({from:2022-02-01,to:2022-02-03})api.get_visible_logical_range()api.set_visible_logical_range({from:0,to:100})# 视图控制api.fit_content()# 自适应所有数据# 事件订阅api.subscribe_visible_logical_range_change(callback)api.subscribe_visible_time_range_change(callback)api.subscribe_size_change(callback)# 尺寸获取api.width()价格轴 — PriceScaleApi新chart.price_scale_api(scale_id)支持左右价格轴。# 右侧价格轴apichart.price_scale_api(right)api.set_auto_scale(True)api.get_visible_range()api.set_visible_range({from:3000,to:4000})api.apply_options(scale_margin_top0.3,scale_margin_bottom0.2)api.width() Volume / OpenInterest 独立化旧Volume 和 OI 是 Candle 的附属品通过candle.attach_volume(df)挂载生命周期绑定。# ❌ 旧方式已移除candle.attach_volume(df)# 已移除candle.attach_open_interest(df)# 已移除candle.volume_config(color#26a69a)# 已移除candle.open_interest_config(color#FF9800)# 已移除新Volume 和 OI 由AbstractChart直接管理独立生命周期。# ✅ 新方式 — 图表自动创建各自独立chart.volume.set(df)# 独立设置数据chart.oi.set(df)# 独立设置数据chart.set(df)# 自动转发 candle/volume/oi# 独立配置chart.volume.price_scale(price_format{type:volume})chart.volume.price_scale_idleft# 独立删除/重置chart.volume.delete()# 只删 volume不影响 candle 和 oichart.oi.clear_data()# 只清 OI 数据迁移指南旧 API新 APIcandle.attach_volume(df)不需要chart.volume自动创建candle.attach_open_interest(df)不需要chart.oi自动创建candle.volume_config(...)chart.volume.config(...)candle.open_interest_config(...)chart.oi.config(...)candle.set(df)自动联动 volume/OI不变仍自动转发 CandleSeries — 独立 K 线系列新任意 Pane 上绘制独立 K 线无 volume/OI 绑定适合参考 K 线、对比 K 线。# 主图 K 线chart.set(main_df)# 参考 K 线独立 Panerefchart.create_candle_series(nameBTC Ref,pane_index2)ref.set(btc_df)# 所有更新方法都支持ref.update_bars(new_df)ref.update_ticks(tick_df)ref.marker(time2022-02-01,positionbelow,shapearrow_up,text买入) 同步机制sync_id旧syncchart.id依赖 chart 的 ID 配对多图表时需要先拿到对方的 ID。# ❌ 旧方式已移除chart1Chart()chart2Chart(syncchart1.id)# 依赖 chart1.id不直观新sync_id组名基于组名的解耦同步。# ✅ 新方式Chart(sync_idgroup1)# 组内全同步Chart(sync_idgroup1,sync_crosshair_onlyTrue)# 仅同步十字光标Chart(sync_idNone)# 不同步# 任意多图表同组chart1Chart(sync_idgroup1)chart2Chart(sync_idgroup1)chart3Chart(sync_idgroup1)# 三个图表联动迁移指南旧 API新 APIsyncchart.idsync_id组名syncTruesync_idTruesyncFalse/syncNonesync_idNone不同步 统一输入契约旧各 Series 数据格式不一致normal_df自动转小写/重命名列容易隐藏问题。新所有 Series 统一timevalue列列名必须精确匹配。# ✅ 新方式 — 所有 Series 共用line.set(df)# 列: time, valuearea.set(df)# 列: time, valuebaseline.set(df)# 列: time, valuehistogram.set(df)# 列: time, valuecandle.set(df)# 列: time, open, high, low, close# 列名必须精确# ❌ 错误的列名date, val, price# ✅ 正确的列名time, value, open, high, low, close迁移指南旧行为新行为date列自动改为time必须手动df.rename(columns{date: time})列名自动转小写列名必须精确匹配set()自动联动_linesLineSeries/HistogramSeries需要各自line.set(df) chart_model 子包 — 纯数据图表模型新声明式、扁平化、引用式的数据模型与渲染层解耦。适合构建复杂的多图表、多窗口仪表盘。fromlightweight_charts.chart_modelimportModel,Window,Chart,Series,Adapter# 声明式定义modelModel(windows[Window(namemain,tile(2,1))],charts[Chart(nameprice,windowmain,tile_index0),Chart(nameindicator,windowmain,tile_index1),],series[Series(namecandle,chartprice,typecandle,datacandle_df),Series(namesma20,chartprice,typeline,datasma_df,color#FF9800),Series(namevolume,chartprice,typevolume,datavol_df),Series(namersi,chartindicator,typeline,datarsi_df,color#9C27B0),],)# 构建 渲染layoutmodel.build()chartAdapter.render(layout)# 链式数据操作model[candle].set(new_df)model[volume].append(new_row)# 画线管理model.drawing.add(typehorizontal_line,price3600,color#FF9800)# 实时同步自动model.live_start(df_dict)# 启动同步线程支持 8 种 Series 类型 5 种画线 增量同步。⚠️ 当前定位参考原型API 尚未定型建议参考使用。 其他淘汰与替换类名重命名旧类名新类名LineLineSeriesHistogramHistogramSeries方法名重命名旧方法新方法series.update(s)series.update_bar(s)series.update_from_tick(s)series.update_tick(s)series.update_from_ticks(df)series.update_ticks(df)chart.update(s)chart.update_bar(s)chart.update_from_tick(s)chart.update_tick(s)chart.update_from_ticks(df)chart.update_ticks(df)chart.cumulative_volume已移除无替代参数变更旧参数变化chart.price_scale(perm_widthN)已移除官方 API 不存在此字段chart.price_scale()默认值从硬编码默认值改为None依赖旧默认值需显式传入chart._drawings列表改为chart._drawing_series字典{pane_index: DrawingSeries}chart.drawings属性保留兼容性遍历所有 pane 的 drawingchart.sync改为chart.sync_idVolumeSeries 着色要求旧cumulative_volume参数tick 无着色需求。新VolumeSeries 需要open/close列用于涨跌着色缺失时抛ValueError。# ✅ 正确用法chart.volume.update_ticks(df[[time,price,volume]])# 自动从 price 聚合 open/close 用于着色# 或直接传入带 open/close 的数据chart.volume.update_bars(df[[time,value,open,close]]) Bug 修复一览Bug影响修复版本时间轴只显示日期不显示时分秒分钟/秒级 K 线无法看时间v3.1.1candle_style()引线渲染为黑色自定义 K 线颜色时引线异常v3.1.0pop()Python 端数据不同步删除 bar 后chart.data不一致v3.0.1evaluate_js卡死消息链路窗口创建后无法更新数据v2.6.1消息循环异常终止多并发消息丢失v2.6.1CandleSeries 标记不显示marker 在独立 K 线系列上不显示v2.6.1Volume/OI 更新不转发独立 series 收不到数据更新v2.7.2ToolBox 删除顺序错误多图表时误杀其他 handlerv2.8.3HtmlTabChart 多 tab 不可见切换 tab 后 candle/legend 消失v2.8.6ReflexChart _html 内存泄漏无限增长直到 OOMv2.8.6⚡ 快速上手pipinstalllightweight-charts-onesixthfromlightweight_chartsimportChart# 5 行代码一个交互式图表chartChart()chart.set(df)# pandas DataFramechart.show(blockTrue)# 弹出窗口支持Windows / macOS / LinuxPython 3.8lightweight-charts-python — 开源项目由 community 驱动的 TradingView Lightweight Charts JS 库的 Python 封装。项目地址One-sixth/lightweight-charts-python