Lightweight Charts 迁移指南从 v2 到 v3 的时间刻度 API 与双价格刻度改造【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址: https://gitcode.com/gh_mirrors/li/lightweight-chartsLightweight Charts™ 3.0 带来了两项重大改进支持左右双价格刻度two price scales与时间刻度Time ScaleAPI 的重构。为了让 API 保持清晰一致官方选择允许一次破坏性变更breaking change并为此提供了详尽的迁移指南。本文以该仓库website/versioned_docs/version-4.2/migrations/from-v2-to-v3.md为骨架逐条对照旧版v2与新版v3的调用方式并结合仓库源码讲解底层实现帮助你快速、安全地把既有图表代码升级到 v3同时理解新 API 的设计动机。迁移总览v3 改变了什么v3 的核心变化可以归纳为两条主线时间刻度 API 归位处理可见时间范围变化的订阅方法从挂在chart对象上迁移到chart.timeScale()返回的 ITimeScaleApi 上并新增了基于 logical range逻辑范围的订阅方法。价格刻度从一个变成一组旧的单一priceScale选项被拆分为leftPriceScale、rightPriceScale与overlayPriceScales系列series通过priceScaleId显式指定挂载到哪条刻度。对于多数常见用法官方保留了旧 API 的兼容支持deprecated而非立即移除但明确指出这些兼容支持会在未来版本中删除个别场景如运行时把价格刻度从左移到右旧 API 已不再支持必须迁移。因此尽早迁移是稳妥的选择。迁移一时间刻度Time ScaleAPI旧 API 与新 API 的对照在 v2 中订阅可见时间范围变化事件的接口直接挂在 chart 对象上调用形式是chart.subscribeVisibleTimeRangeChange(func)。v3 为保持 API 一致性把这些方法移到了chart.timeScale()返回的时间刻度 API 对象上。升级时只需做两处机械替换// 旧v2 chart.subscribeVisibleTimeRangeChange(func); chart.unsubscribeVisibleTimeRangeChange(func);// 新v3 chart.timeScale().subscribeVisibleTimeRangeChange(func); chart.timeScale().unsubscribeVisibleTimeRangeChange(func);新增logical range 订阅除了迁移旧方法v3 的时间刻度 API 还新增了两个订阅方法用于监听可见区域的**逻辑范围logical range**变化chart.timeScale().subscribeVisibleLogicalRangeChange(handler)chart.timeScale().unsubscribeVisibleLogicalRangeChange(handler)在 ITimeScaleApi 接口源码中可以看到logical range 回调收到的是IRangenumber即{ from: number, to: number }而时间范围回调收到的是IRangeHorzScaleItem | null。二者差别在于时间范围time range直接给出可见区间两端的时间值但无法外推数据之外的时间见 getVisibleRange 的注释逻辑范围logical range给出的是基于数据索引的逻辑坐标可配合getVisibleLogicalRange()/setVisibleLogicalRange()实现精确到第几根 K 线的缩放定位即使数据尚未加载到对应区间也能工作。回调中收到null表示图表当前没有任何可见数据需要按空状态处理function myVisibleLogicalRangeChangeHandler(newVisibleLogicalRange) { if (newVisibleLogicalRange null) { // 处理无数据的情况 return; } // 处理新的逻辑范围 { from, to } } chart.timeScale().subscribeVisibleLogicalRangeChange(myVisibleLogicalRangeChangeHandler);底层实现ITimeScaleApi迁移目标接口定义在仓库 src/api/itime-scale-api.ts它统一封装了时间刻度的全部能力滚动scrollToPosition、scrollToRealTime、缩放定位setVisibleRange、setVisibleLogicalRange、fitContent、resetTimeScale、坐标换算timeToCoordinate、coordinateToTime、logicalToCoordinate、coordinateToLogical以及事件订阅时间范围、逻辑范围、尺寸变化。理解这一接口的分工有助于你在迁移后写出更规范的新代码——例如监听可见区间变化应统一经由chart.timeScale()而不是散落在 chart 层面。迁移二双价格刻度Two Price Scales设计动机与默认行为v3 允许图表同时存在多条价格刻度这是双价格刻度特性的基础。虽然 API 变了但默认行为没有变化如果不指定任何价格刻度选项图表右侧会显示一条价格刻度所有新添加的系列默认都挂载到它上面。这一点可以从当前仓库的默认配置源码得到印证src/api/options/chart-options-defaults.ts 中overlayPriceScales: { ...priceScaleOptionsDefaults }, leftPriceScale: { ...priceScaleOptionsDefaults, visible: false, }, rightPriceScale: { ...priceScaleOptionsDefaults, visible: true, }, defaultVisiblePriceScaleId: right,即左侧刻度默认visible: false、右侧刻度默认visible: true未显式指定priceScaleId的系列会被归入defaultVisiblePriceScaleIdright。该逻辑在 chart-model.ts 的系列添加流程中实现若系列未指定priceScaleId则使用defaultVisiblePriceScaleId()返回的默认 ID。迁移场景 1左侧价格刻度Left price scale如果你需要价格刻度绘制在左侧v2 的写法是const chart LightweightCharts.createChart(container, { priceScale: { position: left, }, });v3 需要改为先隐藏右侧刻度、显示左侧刻度然后在创建系列时显式指定priceScaleId: leftconst chart LightweightCharts.createChart(container, { rightPriceScale: { visible: false, }, leftPriceScale: { visible: true, }, });const histSeries chart.addHistogramSeries({ priceScaleId: left, });官方文档注明该场景在新版本中依然可以通过旧 API 工作但这种兼容支持会在未来版本移除建议尽早迁移。从源码看left与right是预定义的两个默认刻度 ID定义在 src/model/default-price-scale.tsDefaultPriceScaleId.Left left、DefaultPriceScaleId.Right rightisDefaultPriceScale则用于区分默认刻度与覆盖层刻度。迁移场景 2隐藏全部价格刻度No price scale如果你希望图表完全不显示任何价格刻度v2 的写法是const chart LightweightCharts.createChart(container, { priceScale: { position: none, }, });v3 中左右两条默认刻度无法被删除只能通过visible: false隐藏。因此把两侧刻度都隐藏即可const chart LightweightCharts.createChart(container, { leftPriceScale: { visible: false, }, rightPriceScale: { visible: false, }, });同样这一场景在新版本中仍可通过旧 API 工作但兼容支持未来会被移除。关于默认刻度只能隐藏、不能删除的约束website/docs/price-scale.md 有明确说明。迁移场景 3创建覆盖层系列Creating overlay覆盖层overlay用于绘制不与主价格刻度共享坐标轴的系列——典型如成交量Volume其数值与价格量级差异很大适合挂在独立、且不在界面上显示的刻度上。v2 用overlay: true表达const histogramSeries chart.addHistogramSeries({ overlay: true, });v3 中改为给系列指定一个空字符串priceScaleId同一批 overlay 系列应使用同一个 IDconst histogramSeries chart.addHistogramSeries({ // 或者使用任意其他 _相同的_ id用于所有 overlay 系列 priceScaleId: , });这一设计正是双价格刻度模型的自然延伸任何非left/right的 ID 都会在内部创建一个覆盖层刻度overlay price scale。覆盖层刻度不占用界面空间系列挂上去后不会影响可见刻度的取值范围。若多个系列使用相同 ID则共享同一条 overlay 刻度overlay 刻度只要还挂有至少一个系列就持续存在移除全部关联系列后即被清理参见 website/docs/price-scale.md。此场景同样保留旧 API 兼容但未来会移除。迁移场景 4把价格刻度从左移到右或反之这是唯一一个新版本不再支持旧 API的场景因此如果你的代码在运行时动态调整过价格刻度位置必须立即迁移否则升级后功能会失效。v2 的做法是通过chart.applyOptions({ priceScale: { position: left } })整体移动刻度const chart LightweightCharts.createChart(container); const mainSeries chart.addLineSeries(); // ... chart.applyOptions({ priceScale: { position: left, }, });v3 中需要两步完成先在图表层面切换左右刻度的显隐再在系列层面把系列改挂到目标刻度const chart LightweightCharts.createChart(container); const mainSeries chart.addLineSeries(); // ... chart.applyOptions({ leftPriceScale: { visible: true, }, rightPriceScale: { visible: false, }, }); mainSeries.applyOptions({ priceScaleId: left, });原因同样来自双价格刻度的模型left与right是两条独立存在的刻度对象迁移的本质是把系列的priceScaleId从right切换到left同时调整两条刻度的可见性而不是移动一条刻度。系列层面对应的方法在 ISeriesApi 接口 中也有体现series.priceScale()可以返回系列当前挂载刻度的 API 对象。迁移对照速查表场景v2 写法v3 写法旧 API 兼容情况订阅时间范围变化chart.subscribeVisibleTimeRangeChange(fn)chart.timeScale().subscribeVisibleTimeRangeChange(fn)需迁移方法已移走退订时间范围变化chart.unsubscribeVisibleTimeRangeChange(fn)chart.timeScale().unsubscribeVisibleTimeRangeChange(fn)需迁移方法已移走订阅逻辑范围变化无v3 新增chart.timeScale().subscribeVisibleLogicalRangeChange(fn)新增能力左侧价格刻度priceScale: { position: left }leftPriceScale.visible: trueseries { priceScaleId: left }兼容未来移除隐藏价格刻度priceScale: { position: none }左右visible: false兼容未来移除覆盖层系列series { overlay: true }series { priceScaleId: }兼容未来移除动态移动刻度位置chart.applyOptions({ priceScale: { position } })chart.applyOptions({ leftPriceScale/rightPriceScale })series.applyOptions({ priceScaleId })不再支持必须迁移延伸阅读与仓库定位本文依据的官方迁移文档位于 website/versioned_docs/version-4.2/migrations/from-v2-to-v3.md仓库同时提供下一阶段的迁移说明 from-v3-to-v4.md。新版价格刻度的完整概念与 API 用法参见 website/docs/price-scale.md其中包含覆盖层刻度的创建、修改与移除规则。时间刻度 API 的完整方法签名与注释见 src/api/itime-scale-api.ts默认配置见 src/api/options/chart-options-defaults.ts 与 src/api/options/price-scale-options-defaults.ts。默认刻度 ID 与判断逻辑见 src/model/default-price-scale.ts系列挂载刻度的内部逻辑见 src/model/chart-model.ts。升级时建议按速查表逐项核对你的代码先处理时间刻度订阅机械替换再处理价格刻度配置结合具体场景选择对应迁移写法并优先改造动态移动刻度位置这类旧 API 已失效的代码路径以确保图表在 v3 及后续版本中长期稳定运行。【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考