Lightweight Charts™ 从 v2 迁移到 v3 完全指南：Time Scale API 重构与双价格刻度体系

前端图表库金融科技数据可视化【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址https://gitcode.com/gh_mirrors/li/lightweight-charts点击查看免费下载Lightweight Charts™ 3.0 是该项目一次重要的 API 版本升级核心改进包括支持两个价格刻度Price Scale与重构 Time Scale API。为了让 API 更加清晰一致官方选择引入破坏性变更因此本指南基于当前仓库中 website/versioned_docs/version-4.1/migrations/from-v2-to-v3.md 这份迁移文档逐项给出从 v2 到 v3 的迁移规则、新旧代码对照与底层实现依据帮助你理解为什么这样改以及如何一次性迁移到位。读完本文你将掌握可见时间范围订阅 API 的迁移方法左右双价格刻度的配置方式overlay 系列与价格刻度移动的正确写法以及哪些旧 API 仍可用、哪些必须立刻迁移。Time Scale API订阅方法迁移到timeScale()变更背景在 v2 中处理可见时间范围变化需要直接调用图表对象上的订阅方法// v2 旧写法 chart.subscribeVisibleTimeRangeChange(func); chart.unsubscribeVisibleTimeRangeChange(func);这些方法挂在 chart 对象上与 3.0 新 API 的整体形态不一致。因此 3.0 将这些方法迁移到 ITimeScaleApi 接口中图表上通过chart.timeScale()获取该 API 对象。迁移规则迁移时只需做如下替换chart.subscribeVisibleTimeRangeChange→chart.timeScale().subscribeVisibleTimeRangeChangechart.unsubscribeVisibleTimeRangeChange→chart.timeScale().unsubscribeVisibleTimeRangeChange在 v2 到 v3 的迁移文档基础上还可以进一步利用 3.0 新增的**逻辑范围Logical Range**订阅方法它们与可见时间范围订阅一同挂在 ITimeScaleApi 上ITimeScaleApi.subscribeVisibleLogicalRangeChangeITimeScaleApi.unsubscribeVisibleLogicalRangeChange源码佐证订阅方法都挂在 ITimeScaleApi 上从当前仓库的接口定义可以印证这一点。src/api/itime-scale-api.ts 中同时声明了四组订阅方法subscribeVisibleTimeRangeChange(handler: TimeRangeChangeEventHandlerHorzScaleItem)与unsubscribeVisibleTimeRangeChange(handler)subscribeVisibleLogicalRangeChange(handler: LogicalRangeChangeEventHandler)与unsubscribeVisibleLogicalRangeChange(handler)其中TimeRangeChangeEventHandler的签名是(timeRange: IRangeHorzScaleItem | null) void即回调收到的参数是包含from和to的对象而LogicalRangeChangeEventHandler的回调参数类型为LogicalRange | null两个数值索引组成的范围。两者的回调参数都可能为null图表无可见数据时因此在处理器中务必做空值判断。对应的实现类位于 src/api/time-scale-api.ts四个方法一一对应实现说明这套 API 在 3.0 中是完全成形的正式能力而不仅仅是文档占位。实际使用示例// v3 新写法 function myVisibleTimeRangeChangeHandler(newVisibleTimeRange) { if (newVisibleTimeRange null) { // 图表没有可见数据处理 null 情况 return; } // 处理新的可见时间范围 console.log(newVisibleTimeRange.from, newVisibleTimeRange.to); } chart.timeScale().subscribeVisibleTimeRangeChange(myVisibleTimeRangeChangeHandler); // 不再需要时记得退订 chart.timeScale().unsubscribeVisibleTimeRangeChange(myVisibleTimeRangeChangeHandler);在 v3 中推荐结合subscribeVisibleLogicalRangeChange监听逻辑索引范围变化再配合chart.timeScale().getVisibleRange()、getVisibleLogicalRange()读取当前范围详见 src/api/itime-scale-api.ts。注意getVisibleRange()无法外推时间只会基于当前已存在的数据返回范围若你已有足够信息自行估算索引可改用setVisibleLogicalRange。双价格刻度Two Price Scales从priceScale.position到leftPriceScale/rightPriceScale变更背景3.0 最大的架构改进是图表默认拥有两个预定义价格刻度left和right。所有普通系列默认挂载到右侧价格刻度right你也可以把系列挂载到左侧left。同时你可以通过给系列设置自定义priceScaleId来创建任意数量的 overlay叠加价格刻度。官方文档 website/versioned_docs/version-4.1/price-scale.md 对此有专门说明只有left和right价格刻度能够显示在图表上所有 overlay 价格刻度都是隐藏的若要修改左侧刻度用leftPriceScale选项右侧刻度用rightPriceScale选项overlay 刻度的默认选项用overlayPriceScales选项。官方深知破坏性变更的代价因此并未立刻移除旧 API而是将其标记为已弃用deprecated——大多数常见场景下旧代码仍可继续运行。唯一的例外是移动价格刻度位置这一场景见下文旧 API 已不再支持必须迁移。默认行为不变如果没有指定任何价格刻度选项行为与 v2 完全一致图表右侧显示价格刻度所有系列默认挂载到它上面。从当前仓库源码可以确认这一默认值src/api/options/chart-options-defaults.ts 中定义了overlayPriceScales: { ...priceScaleOptionsDefaults, // 默认不可见 }, leftPriceScale: { ...priceScaleOptionsDefaults, visible: false, // 左侧刻度默认隐藏 }, rightPriceScale: { ...priceScaleOptionsDefaults, visible: true, // 右侧刻度默认可见 }, defaultVisiblePriceScaleId: right, // 未指定 priceScaleId 的系列挂到 right而价格刻度选项的默认值定义在 src/api/options/price-scale-options-defaults.ts包含autoScale: true、mode: PriceScaleMode.Normal、invertScale: false、scaleMargins底部 0.1、顶部 0.2、tickMarkDensity: 2.5等。底层机制上src/model/chart-model.ts 的defaultVisiblePriceScaleId()方法会结合leftPriceScale.visible与rightPriceScale.visible决定新系列挂载到哪一侧当两侧可见性不同、只有一侧可见时新系列自动挂到可见的那一侧两侧可见性相同时使用defaultVisiblePriceScaleId选项默认right。这与迁移文档中默认行为不变的描述完全吻合。左侧价格刻度Left Price Scale旧写法v2const chart LightweightCharts.createChart(container, { priceScale: { position: left, }, });新写法v3const chart LightweightCharts.createChart(container, { rightPriceScale: { visible: false, }, leftPriceScale: { visible: true, }, });然后在创建系列时指定目标价格刻度const histSeries chart.addHistogramSeries({ priceScaleId: left, });旧 API 完全支持这种场景但未来版本会移除该支持建议尽快迁移。无价格刻度No Price Scale旧写法v2const chart LightweightCharts.createChart(container, { priceScale: { position: none, }, });新写法v3const chart LightweightCharts.createChart(container, { leftPriceScale: { visible: false, }, rightPriceScale: { visible: false, }, });同样新版本通过旧 API 仍支持此场景但该支持将在未来版本移除。注意left和right两个预定义刻度无法被删除只能通过visible: false隐藏见 website/versioned_docs/version-4.1/price-scale.md 中Removing a price scale一节。创建 overlay叠加系列旧写法v2const histogramSeries chart.addHistogramSeries({ overlay: true, });新写法v3const histogramSeries chart.addHistogramSeries({ // 或者为所有 overlay 系列使用同一个自定义 id priceScaleId: , });priceScaleId: 空字符串即可创建一个 overlay 价格刻度多个 overlay 系列若希望共享同一刻度应使用同一个非空自定义 ID如volume这样系列会挂到已存在的同名价格刻度上。从源码看src/model/pane.ts 的_insertDataSource会先按 ID 查找价格刻度找不到时才以overlayPriceScales默认选项创建新的价格刻度这正是同名共享、不同名新建的实现基础。同样地旧 API 支持此场景但未来会被移除。将价格刻度从右侧移到左侧或反向——必须迁移的场景旧写法v2const chart LightweightCharts.createChart(container); const mainSeries chart.addLineSeries(); // ... chart.applyOptions({ priceScale: { position: left, }, });新写法v3const chart LightweightCharts.createChart(container); const mainSeries chart.addLineSeries(); // ... chart.applyOptions({ leftPriceScale: { visible: true, }, rightPriceScale: { visible: false, }, }); mainSeries.applyOptions({ priceScaleId: left, });这是文档中唯一一个新版本不再通过旧 API 支持的场景旧的priceScale.position动态切换写法在 v3 中已失效。如果你正在使用这种写法必须立即迁移否则图表显示将不符合预期。动态切换的底层依据可从 src/model/series.ts 看到当priceScaleId通过applyOptions改变时模型会调用moveSeriesToScale把系列从原刻度迁移到新刻度。也就是说v3 中移动价格刻度的本质是同时调整刻度的可见性与系列的挂载目标两件事。迁移检查清单旧 APIv2新 APIv3旧 API 状态chart.subscribeVisibleTimeRangeChange(fn)chart.timeScale().subscribeVisibleTimeRangeChange(fn)已迁移需改代码chart.unsubscribeVisibleTimeRangeChange(fn)chart.timeScale().unsubscribeVisibleTimeRangeChange(fn)已迁移需改代码新增能力chart.timeScale().subscribeVisibleLogicalRangeChange(fn)3.0 新增priceScale: { position: left }leftPriceScale.visible: truerightPriceScale.visible: false系列设置priceScaleId: left已弃用仍可用但建议迁移priceScale: { position: none }leftPriceScale.visible: falserightPriceScale.visible: false已弃用仍可用但建议迁移overlay: truepriceScaleId: 或自定义非空 ID已弃用仍可用但建议迁移运行期applyOptions({ priceScale: { position } })applyOptions切换左右刻度可见性 系列applyOptions({ priceScaleId })不再支持必须迁移关键源码位置速查迁移文档原文website/versioned_docs/version-4.1/migrations/from-v2-to-v3.mdTime Scale API 接口定义src/api/itime-scale-api.ts含全部订阅/退订方法与 range 读写方法Time Scale API 实现src/api/time-scale-api.ts图表默认选项左右刻度可见性与defaultVisiblePriceScaleIdsrc/api/options/chart-options-defaults.ts价格刻度选项默认值src/api/options/price-scale-options-defaults.ts新系列默认挂载逻辑defaultVisiblePriceScaleIdsrc/model/chart-model.ts系列迁移价格刻度moveSeriesToScalesrc/model/series.tsoverlay 价格刻度创建与共享逻辑src/model/pane.ts价格刻度通用概念文档website/versioned_docs/version-4.1/price-scale.md小结v3 的这次破坏性变更整体遵循新能力完整落地、旧能力逐步退场的策略Time Scale 的可见范围订阅方法已强制迁移到chart.timeScale()上同时新增了逻辑范围订阅双价格刻度体系则以左右两个预定义刻度 任意 overlay 刻度的新模型取代了单一的priceScale.position配置除运行时移动价格刻度外其余旧写法目前仍可用但已弃用。建议在下一个发布周期内将代码统一迁移到新 API避免未来版本移除旧支持后产生故障。赞分享前端图表库金融科技数据可视化【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址https://gitcode.com/gh_mirrors/li/lightweight-charts点击查看免费下载相关推荐CANN/GE LLM-DataDist接口列表LLM DataDist接口列表 LLM DataDist大模型分布式集群和数据加速组件提供了集群KV数据管理能力支持全量图和增量图分离部署。 支持的产品前端图表库金融科技数据可视化CNPPopupController实战案例构建精美iOS应用弹窗界面CNPPopupController实战案例构建精美iOS应用弹窗界面 CNPPopupController是一款简单而多功能的iOS弹窗控制器能帮助开发者前端图表库金融科技数据可视化vit_srelpos_small_patch16_224.sw_in1k部署指南轻量级ViT模型的工业级应用优化vit_srelpos_small_patch16_224.sw_in1k部署指南轻量级ViT模型的工业级应用优化 vit_srelpos_small_pat前端图表库金融科技数据可视化上一篇突破物理仿真边界Genesis v0.2.1如何让机器人完成后空翻与流体交互下一篇攻克Gopeed Docker部署Token配置难题从踩坑到精通创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考