改造方案)
Lightweight Charts v3 到 v4 遷移指南破壞性變更逐項分析與實戰(zhàn)改造方案【免費下載鏈接】lightweight-chartsPerformant financial charts built with HTML5 canvas項目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts本指南以 Lightweight Charts v4 官方遷移文檔為主體系統(tǒng)梳理從 v3 升級到 v4 時的全部破壞性變更——從被移除的枚舉、失效的 series 級選項到價格刻度 API 簽名變化、時間值類型統(tǒng)一以及MouseEventParams字段重構(gòu)——并結(jié)合當(dāng)前倉庫源碼逐一解釋變更動機、給出可直接復(fù)制的改造代碼與類型守衛(wèi)用法。讀完本文你將能把基于 v3 編寫的圖表代碼穩(wěn)定、無殘留地遷移到 v4并理解每個破壞性變更背后的 API 設(shè)計演進。遷移概覽v4 都改了什么v4 是 Lightweight Charts 的一次重要 API 收斂版本其變更主要集中在以下幾個方向刪除冗余 API移除拼寫錯誤的枚舉LasPriceAnimationMode、series 級scaleMargins、layout.backgroundColor、series 級overlay與priceScale選項收緊 API 簽名chart.priceScale()必須顯式傳入價格刻度 ID統(tǒng)一時間值類型出站outbound時間值與入站inbound時間值完全一致不再丟失業(yè)務(wù)日字符串信息重構(gòu)事件參數(shù)對象MouseEventParams.seriesPrices被seriesData取代hoveredMarkerId更名為hoveredObjectId。以下各節(jié)按原文檔順序逐項展開每節(jié)均給出“變更原因 遷移前代碼 遷移后代碼 源碼佐證”的完整改造說明。已移除的枚舉從LasPriceAnimationMode到LastPriceAnimationMode變更內(nèi)容v4 刪除了拼寫錯誤的導(dǎo)出枚舉LasPriceAnimationMode請統(tǒng)一使用LastPriceAnimationMode。原因分析舊枚舉名存在拼寫錯誤少了t。在 v4 中源碼已經(jīng)只保留正確拼寫的枚舉見 series-options.ts 中LastPriceAnimationMode的定義并由 入口文件 通過export { PriceLineSource, LastPriceAnimationMode } from ./model/series-options對外導(dǎo)出。遷移方式全局替換標(biāo)識符即可// v3錯誤拼寫已刪除 import { LasPriceAnimationMode } from lightweight-charts; // v4正確拼寫 import { LastPriceAnimationMode } from lightweight-charts; series.applyOptions({ lastPriceAnimation: LastPriceAnimationMode.OnDataUpdate, });LastPriceAnimationMode是 series 選項lastPriceAnimation的取值枚舉Disabled/OnDataUpdate/Continuous其實際渲染邏輯由 series-last-price-animation-pane-view.ts 承載并分別被 line-series.ts、area-series.ts、baseline-series.ts 等 series 實現(xiàn)使用。scaleMargins從 series 選項移至價格刻度 API變更內(nèi)容series 選項中的scaleMargins已被移除。v3 中你可以這樣寫const series chart.addLineSeries({ scaleMargins: { /* options here */ }, });在 v3 中該選項會作用于該 series 所屬的價格刻度而v4 起這個選項會被靜默忽略TypeScript 用戶會直接收到編譯錯誤因為該屬性已從 series 選項類型中刪除。遷移方式把scaleMargins應(yīng)用到 series 的價格刻度上const series chart.addLineSeries(); series.priceScale().applyOptions({ scaleMargins: { /* options here */ }, });源碼佐證在 v4 中scaleMargins只存在于價格刻度層級。見 price-scale.ts 中帶 JSDoc 注釋的scaleMargins: PriceScaleMargins字段定義以及 price-scale.ts 中applyOptions對top/bottom的解析邏輯而 price-scale-options-defaults.ts 給出了默認值。scaleMargins的實際作用體現(xiàn)在 price-scale.ts它按比例在繪圖區(qū)上下預(yù)留邊距供價格線、最后價格動畫等元素使用。從源碼結(jié)構(gòu)看v4 將“外觀/幾何”配置與“數(shù)據(jù)綁定”配置解耦scaleMargins屬于價格刻度的幾何布局理應(yīng)通過價格刻度 API 管理而不是通過某一條 series 隱式設(shè)置。layout.backgroundColor已被layout.background取代變更內(nèi)容layout選項中扁平化的backgroundColor: string被移除改為結(jié)構(gòu)化的background對象。遷移前v3const chart createChart({ layout: { backgroundColor: red, }, });遷移后v4import { createChart, ColorType } from lightweight-charts; const chart createChart({ layout: { background: { type: ColorType.Solid, color: red, }, }, });原因分析v4 的布局背景支持兩種類型——ColorType.Solid純色與ColorType.VerticalGradient垂直漸變。扁平字符串只能表達純色無法表達漸變需求因此改為帶type字段的結(jié)構(gòu)化對象。源碼佐證當(dāng)前倉庫的默認布局配置正是結(jié)構(gòu)化的background對象見 layout-options-defaults.ts默認值為{ type: ColorType.Solid, color: #FFFFFF }純白底。ColorType枚舉從 layout-options.ts 定義并經(jīng) index.ts 對外導(dǎo)出。若你希望保持 v3 的純色行為直接使用ColorType.Solid即可無縫遷移。徹底移除overlay與 series 級priceScale選項變更內(nèi)容這兩項屬于 v2 時代遺留的舊配置在 v3 中已被標(biāo)記為棄用v4 正式刪除。series 的overlay屬性遷移指引見 v2 到 v3 遷移指南中“創(chuàng)建 Overlay”一節(jié)series 的priceScale屬性遷移指引見 v2 到 v3 遷移指南中“兩個價格刻度”一節(jié)。遷移方式摘要不再在addLineSeries({ overlay: true })或addLineSeries({ priceScale: right })中聲明歸屬而是通過系列 API 指定價格刻度 ID// v4 推薦在添加 series 時通過選項指定 const series chart.addLineSeries({ priceFormat: { type: price } }); // 或創(chuàng)建后設(shè)置歸屬刻度 series.applyOptions({ priceScaleId: right });需要創(chuàng)建“疊加/浮動”類型overlayseries 時為其分配一個自定義價格刻度 ID 即可例如chart.addLineSeries({ priceScaleId: })配合覆蓋刻度 ID 的方式具體語義以 v2 到 v3 遷移指南 為準(zhǔn)。chart.priceScale()必須顯式傳入價格刻度 ID變更內(nèi)容v3 中調(diào)用chart.priceScale()不帶參數(shù)時庫會根據(jù)可見性自動返回右側(cè)或左側(cè)價格刻度v4 起該方法要求顯式提供 ID。遷移前v3行為隱式const priceScale chart.priceScale();遷移后v4行為顯式const rightPriceScale chart.priceScale(right); const leftPriceScale chart.priceScale(left);源碼佐證當(dāng)前倉庫中該方法簽名已經(jīng)強制要求 ID 與可選 pane 索引見 ichart-api.ts/** * param priceScaleId - ID of the price scale. */ priceScale(priceScaleId: string, paneIndex?: number): IPriceScaleApi;若你的代碼沒有顯式設(shè)置過價格刻度 ID那么 v3 中的“當(dāng)前刻度”在 v4 中等價于chart.priceScale(right)當(dāng)它可見時。升級時請按“右側(cè)刻度、左側(cè)刻度”逐一顯式替換避免依賴隱式行為。drawTicks更名為ticksVisible變更內(nèi)容價格刻度選項drawTicks更名為ticksVisible且默認值從true變?yōu)閒alse默認不繪制刻度線。遷移后v4const chart createChart({ leftPriceScale: { ticksVisible: false, }, rightPriceScale: { ticksVisible: false, }, });源碼佐證默認值可以在 price-scale-options-defaults.ts 中確認——ticksVisible: false時間刻度一側(cè)的默認值同樣為false見 time-scale-options-defaults.ts。繪制邏輯方面價格軸只在borderVisible ticksVisible時才渲染刻度線見 price-axis-widget.ts時間軸同理見 time-axis-widget.ts價格軸視圖還會將tickVisible與ticksVisible做與運算以決定最終是否繪制見 price-axis-view.ts。升級注意由于默認值由true翻轉(zhuǎn)為false如果你依賴舊行為默認顯示刻度線遷移后需要在選項里顯式設(shè)置ticksVisible: true否則圖表刻度線將不再顯示。出站時間值類型統(tǒng)一回傳給你的一定是你給出去的變更內(nèi)容v4 之前入站時間你傳給庫的值如ISeriesApi.setData中的數(shù)據(jù)與出站時間庫回調(diào)給你的值如timeFormatter的參數(shù)類型不一致出站時間不可能是業(yè)務(wù)日字符串business day string。v4 修復(fù)了這一問題庫現(xiàn)在會原樣回傳你提供的任何時間值。受影響 API 包括IChartApi.subscribeClick經(jīng)MouseEventParams.timeIChartApi.subscribeCrosshairMove經(jīng)MouseEventParams.timeLocalizationOptions.timeFormatter經(jīng)TimeFormatterFn參數(shù)TimeScaleOptions.tickMarkFormatter經(jīng)TickMarkFormatter參數(shù)遷移驗證示例如果你用字符串2001-01-01喂給 seriesv4 中所有出站位置都能收到完全相同的字符串series.setData([ { time: 2001-01-01, value: 1 }, ]); chart.applyOptions({ localization: { timeFormatter: time time, // 對上面這根 bar回調(diào)值將是 2001-01-01 }, timeScale: { tickMarkFormatter: time time, // 對上面這根 bar回調(diào)值將是 2001-01-01 }, }); chart.subscribeCrosshairMove(param { console.log(param.time); // 懸停上面這根 bar 時輸出 2001-01-01 }); chart.subscribeClick(param { console.log(param.time); // 點擊上面這根 bar 時輸出 2001-01-01 });如何處理回調(diào)中的時間類型由于出站時間現(xiàn)在是聯(lián)合類型UTCTimestamp | BusinessDay | string遷移時通常需要手動將時間轉(zhuǎn)換為目標(biāo)格式。官方推薦配合類型守衛(wèi)使用import { createChart, isUTCTimestamp, isBusinessDay, } from lightweight-charts; const chart createChart(document.body); chart.subscribeClick(param { if (param.time undefined) { // 沒有數(shù)據(jù)點無法取到時間 return; } if (isUTCTimestamp(param.time)) { // param.time 是 UTCTimestampUNIX 秒級時間戳 } else if (isBusinessDay(param.time)) { // param.time 是 BusinessDay 對象 { year, month, day } } else { // param.time 是 ISO 格式業(yè)務(wù)日字符串例如 2010-01-01 } });源碼佐證當(dāng)前倉庫的時間聯(lián)合類型定義如下見 horz-scale-behavior-time/types.tsexport type Time UTCTimestamp | BusinessDay | string;UTCTimestamp是對number的命名類型nominal type要求傳入秒而非毫秒Date.now()返回毫秒需除以 1000見 types.tsBusinessDay為{ year, month, day }對象見 types.ts字符串為 ISO 格式業(yè)務(wù)日如2021-02-03。兩個類型守衛(wèi)isUTCTimestamp/isBusinessDay定義于 types.ts由 入口文件 對外導(dǎo)出。它們在實際解析中被廣泛使用例如時間解析器在判斷數(shù)據(jù)首位時間類型時調(diào)用isBusinessDay(data[0].time) || isString(data[0].time)在格式轉(zhuǎn)換時調(diào)用isUTCTimestamp(time)見 time-utils.ts。這印證了“入站/出站同源”的設(shè)計——底層解析與回傳使用同一套類型判斷。MouseEventParams.seriesPrices已被seriesData取代變更內(nèi)容MouseEventParams中的seriesPrices屬性被移除改用seriesData。兩者相似但seriesData返回的是完整的 series 數(shù)據(jù)項而不僅是價格值。受影響 APIIChartApi.subscribeClickIChartApi.subscribeCrosshairMove遷移前v3從param.seriesPrices.get(lineSeries)拿到的只是價格數(shù)值且無法區(qū)分不同 series 類型的完整數(shù)據(jù)。遷移后v4lineSeries.setData([{ time: 2001-01-01, value: 1 }]); barSeries.setData([{ time: 2001-01-01, open: 5, high: 10, low: 1, close: 7 }]); chart.subscribeCrosshairMove(param { console.log(param.seriesData.get(lineSeries)); // { time: 2001-01-01, value: 1 } 或 undefined console.log(param.seriesData.get(barSeries)); // { time: 2001-01-01, open: 5, high: 10, low: 1, close: 7 } 或 undefined });注意seriesData的類型是MapISeriesApi, BarData | LineData | HistogramData | CustomData見 ichart-api.ts。它把整行 plot 數(shù)據(jù)含 time 與 OHLC 等字段回傳給事件處理器因此在十字光標(biāo)或點擊回調(diào)中你可以直接讀取 open/high/low/close而不必再通過 series 查詢價格。源碼佐證seriesData的組裝邏輯位于 chart-api.ts——庫內(nèi)部遍歷param.seriesDataSeriesPlotRow集合將每個 series 的 plot 行轉(zhuǎn)換為 API 層的完整數(shù)據(jù)對象再在 chart-api.ts 處將其與hoveredObjectId: param.hoveredObject一并寫入對外暴露的MouseEventParams。hoveredMarkerId更名為hoveredObjectId變更內(nèi)容MouseEventParams.hoveredMarkerId更名為hoveredObjectId。遷移后v4chart.subscribeCrosshairMove(param { console.log(param.hoveredObjectId); }); chart.subscribeClick(param { console.log(param.hoveredObjectId); });原因分析v4 擴展了“可被懸停/命中的對象”范圍——不再局限于 series marker標(biāo)記還包括價格線price line等對象因此字段名從“marker”泛化為“object”。其類型為unknown見 ichart-api.ts在 chart-api.ts 中由內(nèi)部的param.hoveredObject直接映射而來因此你可以在回調(diào)里自行縮小類型后再使用。遷移核對清單完成 v3 → v4 遷移后建議逐項自查變更項v3 寫法v4 寫法最后價格動畫枚舉LasPriceAnimationModeLastPriceAnimationModeseries 邊距addLineSeries({ scaleMargins })series.priceScale().applyOptions({ scaleMargins })布局背景l(fā)ayout.backgroundColor: redlayout.background: { type: ColorType.Solid, color: red }疊加 series{ overlay: true }指定priceScaleId見 v2→v3 指南刻度歸屬{ priceScale: right }通過priceScaleId指定見 v2→v3 指南獲取價格刻度chart.priceScale()chart.priceScale(right)/chart.priceScale(left)刻度線顯隱drawTicks: true默認開ticksVisible: true默認關(guān)閉時間回傳值出站值丟失業(yè)務(wù)日字符串出站值與你傳入的完全一致配合isUTCTimestamp/isBusinessDay守衛(wèi)使用懸停數(shù)據(jù)param.seriesPricesparam.seriesData返回完整數(shù)據(jù)項懸停對象 IDparam.hoveredMarkerIdparam.hoveredObjectId其中與時間類型守衛(wèi)相關(guān)的導(dǎo)出isUTCTimestamp、isBusinessDay可在 入口文件 中確認價格刻度默認選項ticksVisible: false、scaleMargins默認值見 price-scale-options-defaults.ts布局背景默認值見 layout-options-defaults.ts。遷移完成后建議用 TypeScript 嚴(yán)格模式編譯一遍項目絕大多數(shù)被移除的選項如 series 級scaleMargins、drawTicks會直接在編譯期暴露出來剩下的運行時行為差異如刻度線默認關(guān)閉、出站時間類型變化再結(jié)合本文清單逐一驗證即可?！久赓M下載鏈接】lightweight-chartsPerformant financial charts built with HTML5 canvas項目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Lightweight Charts v3 到 v4 遷移指南：破壞性變更逐項分析與實戰(zhàn)改造方案
Lightweight Charts v3 到 v4 遷移指南破壞性變更逐項分析與實戰(zhàn)改造方案【免費下載鏈接】lightweight-chartsPerformant financial charts built with HTML5 canvas項目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts本指南以 Lightweight Charts v4 官方遷移文檔為主體系統(tǒng)梳理從 v3 升級到 v4 時的全部破壞性變更——從被移除的枚舉、失效的 series 級選項到價格刻度 API 簽名變化、時間值類型統(tǒng)一以及MouseEventParams字段重構(gòu)——并結(jié)合當(dāng)前倉庫源碼逐一解釋變更動機、給出可直接復(fù)制的改造代碼與類型守衛(wèi)用法。讀完本文你將能把基于 v3 編寫的圖表代碼穩(wěn)定、無殘留地遷移到 v4并理解每個破壞性變更背后的 API 設(shè)計演進。遷移概覽v4 都改了什么v4 是 Lightweight Charts 的一次重要 API 收斂版本其變更主要集中在以下幾個方向刪除冗余 API移除拼寫錯誤的枚舉LasPriceAnimationMode、series 級scaleMargins、layout.backgroundColor、series 級overlay與priceScale選項收緊 API 簽名chart.priceScale()必須顯式傳入價格刻度 ID統(tǒng)一時間值類型出站outbound時間值與入站inbound時間值完全一致不再丟失業(yè)務(wù)日字符串信息重構(gòu)事件參數(shù)對象MouseEventParams.seriesPrices被seriesData取代hoveredMarkerId更名為hoveredObjectId。以下各節(jié)按原文檔順序逐項展開每節(jié)均給出“變更原因 遷移前代碼 遷移后代碼 源碼佐證”的完整改造說明。已移除的枚舉從LasPriceAnimationMode到LastPriceAnimationMode變更內(nèi)容v4 刪除了拼寫錯誤的導(dǎo)出枚舉LasPriceAnimationMode請統(tǒng)一使用LastPriceAnimationMode。原因分析舊枚舉名存在拼寫錯誤少了t。在 v4 中源碼已經(jīng)只保留正確拼寫的枚舉見 series-options.ts 中LastPriceAnimationMode的定義并由 入口文件 通過export { PriceLineSource, LastPriceAnimationMode } from ./model/series-options對外導(dǎo)出。遷移方式全局替換標(biāo)識符即可// v3錯誤拼寫已刪除 import { LasPriceAnimationMode } from lightweight-charts; // v4正確拼寫 import { LastPriceAnimationMode } from lightweight-charts; series.applyOptions({ lastPriceAnimation: LastPriceAnimationMode.OnDataUpdate, });LastPriceAnimationMode是 series 選項lastPriceAnimation的取值枚舉Disabled/OnDataUpdate/Continuous其實際渲染邏輯由 series-last-price-animation-pane-view.ts 承載并分別被 line-series.ts、area-series.ts、baseline-series.ts 等 series 實現(xiàn)使用。scaleMargins從 series 選項移至價格刻度 API變更內(nèi)容series 選項中的scaleMargins已被移除。v3 中你可以這樣寫const series chart.addLineSeries({ scaleMargins: { /* options here */ }, });在 v3 中該選項會作用于該 series 所屬的價格刻度而v4 起這個選項會被靜默忽略TypeScript 用戶會直接收到編譯錯誤因為該屬性已從 series 選項類型中刪除。遷移方式把scaleMargins應(yīng)用到 series 的價格刻度上const series chart.addLineSeries(); series.priceScale().applyOptions({ scaleMargins: { /* options here */ }, });源碼佐證在 v4 中scaleMargins只存在于價格刻度層級。見 price-scale.ts 中帶 JSDoc 注釋的scaleMargins: PriceScaleMargins字段定義以及 price-scale.ts 中applyOptions對top/bottom的解析邏輯而 price-scale-options-defaults.ts 給出了默認值。scaleMargins的實際作用體現(xiàn)在 price-scale.ts它按比例在繪圖區(qū)上下預(yù)留邊距供價格線、最后價格動畫等元素使用。從源碼結(jié)構(gòu)看v4 將“外觀/幾何”配置與“數(shù)據(jù)綁定”配置解耦scaleMargins屬于價格刻度的幾何布局理應(yīng)通過價格刻度 API 管理而不是通過某一條 series 隱式設(shè)置。layout.backgroundColor已被layout.background取代變更內(nèi)容layout選項中扁平化的backgroundColor: string被移除改為結(jié)構(gòu)化的background對象。遷移前v3const chart createChart({ layout: { backgroundColor: red, }, });遷移后v4import { createChart, ColorType } from lightweight-charts; const chart createChart({ layout: { background: { type: ColorType.Solid, color: red, }, }, });原因分析v4 的布局背景支持兩種類型——ColorType.Solid純色與ColorType.VerticalGradient垂直漸變。扁平字符串只能表達純色無法表達漸變需求因此改為帶type字段的結(jié)構(gòu)化對象。源碼佐證當(dāng)前倉庫的默認布局配置正是結(jié)構(gòu)化的background對象見 layout-options-defaults.ts默認值為{ type: ColorType.Solid, color: #FFFFFF }純白底。ColorType枚舉從 layout-options.ts 定義并經(jīng) index.ts 對外導(dǎo)出。若你希望保持 v3 的純色行為直接使用ColorType.Solid即可無縫遷移。徹底移除overlay與 series 級priceScale選項變更內(nèi)容這兩項屬于 v2 時代遺留的舊配置在 v3 中已被標(biāo)記為棄用v4 正式刪除。series 的overlay屬性遷移指引見 v2 到 v3 遷移指南中“創(chuàng)建 Overlay”一節(jié)series 的priceScale屬性遷移指引見 v2 到 v3 遷移指南中“兩個價格刻度”一節(jié)。遷移方式摘要不再在addLineSeries({ overlay: true })或addLineSeries({ priceScale: right })中聲明歸屬而是通過系列 API 指定價格刻度 ID// v4 推薦在添加 series 時通過選項指定 const series chart.addLineSeries({ priceFormat: { type: price } }); // 或創(chuàng)建后設(shè)置歸屬刻度 series.applyOptions({ priceScaleId: right });需要創(chuàng)建“疊加/浮動”類型overlayseries 時為其分配一個自定義價格刻度 ID 即可例如chart.addLineSeries({ priceScaleId: })配合覆蓋刻度 ID 的方式具體語義以 v2 到 v3 遷移指南 為準(zhǔn)。chart.priceScale()必須顯式傳入價格刻度 ID變更內(nèi)容v3 中調(diào)用chart.priceScale()不帶參數(shù)時庫會根據(jù)可見性自動返回右側(cè)或左側(cè)價格刻度v4 起該方法要求顯式提供 ID。遷移前v3行為隱式const priceScale chart.priceScale();遷移后v4行為顯式const rightPriceScale chart.priceScale(right); const leftPriceScale chart.priceScale(left);源碼佐證當(dāng)前倉庫中該方法簽名已經(jīng)強制要求 ID 與可選 pane 索引見 ichart-api.ts/** * param priceScaleId - ID of the price scale. */ priceScale(priceScaleId: string, paneIndex?: number): IPriceScaleApi;若你的代碼沒有顯式設(shè)置過價格刻度 ID那么 v3 中的“當(dāng)前刻度”在 v4 中等價于chart.priceScale(right)當(dāng)它可見時。升級時請按“右側(cè)刻度、左側(cè)刻度”逐一顯式替換避免依賴隱式行為。drawTicks更名為ticksVisible變更內(nèi)容價格刻度選項drawTicks更名為ticksVisible且默認值從true變?yōu)閒alse默認不繪制刻度線。遷移后v4const chart createChart({ leftPriceScale: { ticksVisible: false, }, rightPriceScale: { ticksVisible: false, }, });源碼佐證默認值可以在 price-scale-options-defaults.ts 中確認——ticksVisible: false時間刻度一側(cè)的默認值同樣為false見 time-scale-options-defaults.ts。繪制邏輯方面價格軸只在borderVisible ticksVisible時才渲染刻度線見 price-axis-widget.ts時間軸同理見 time-axis-widget.ts價格軸視圖還會將tickVisible與ticksVisible做與運算以決定最終是否繪制見 price-axis-view.ts。升級注意由于默認值由true翻轉(zhuǎn)為false如果你依賴舊行為默認顯示刻度線遷移后需要在選項里顯式設(shè)置ticksVisible: true否則圖表刻度線將不再顯示。出站時間值類型統(tǒng)一回傳給你的一定是你給出去的變更內(nèi)容v4 之前入站時間你傳給庫的值如ISeriesApi.setData中的數(shù)據(jù)與出站時間庫回調(diào)給你的值如timeFormatter的參數(shù)類型不一致出站時間不可能是業(yè)務(wù)日字符串business day string。v4 修復(fù)了這一問題庫現(xiàn)在會原樣回傳你提供的任何時間值。受影響 API 包括IChartApi.subscribeClick經(jīng)MouseEventParams.timeIChartApi.subscribeCrosshairMove經(jīng)MouseEventParams.timeLocalizationOptions.timeFormatter經(jīng)TimeFormatterFn參數(shù)TimeScaleOptions.tickMarkFormatter經(jīng)TickMarkFormatter參數(shù)遷移驗證示例如果你用字符串2001-01-01喂給 seriesv4 中所有出站位置都能收到完全相同的字符串series.setData([ { time: 2001-01-01, value: 1 }, ]); chart.applyOptions({ localization: { timeFormatter: time time, // 對上面這根 bar回調(diào)值將是 2001-01-01 }, timeScale: { tickMarkFormatter: time time, // 對上面這根 bar回調(diào)值將是 2001-01-01 }, }); chart.subscribeCrosshairMove(param { console.log(param.time); // 懸停上面這根 bar 時輸出 2001-01-01 }); chart.subscribeClick(param { console.log(param.time); // 點擊上面這根 bar 時輸出 2001-01-01 });如何處理回調(diào)中的時間類型由于出站時間現(xiàn)在是聯(lián)合類型UTCTimestamp | BusinessDay | string遷移時通常需要手動將時間轉(zhuǎn)換為目標(biāo)格式。官方推薦配合類型守衛(wèi)使用import { createChart, isUTCTimestamp, isBusinessDay, } from lightweight-charts; const chart createChart(document.body); chart.subscribeClick(param { if (param.time undefined) { // 沒有數(shù)據(jù)點無法取到時間 return; } if (isUTCTimestamp(param.time)) { // param.time 是 UTCTimestampUNIX 秒級時間戳 } else if (isBusinessDay(param.time)) { // param.time 是 BusinessDay 對象 { year, month, day } } else { // param.time 是 ISO 格式業(yè)務(wù)日字符串例如 2010-01-01 } });源碼佐證當(dāng)前倉庫的時間聯(lián)合類型定義如下見 horz-scale-behavior-time/types.tsexport type Time UTCTimestamp | BusinessDay | string;UTCTimestamp是對number的命名類型nominal type要求傳入秒而非毫秒Date.now()返回毫秒需除以 1000見 types.tsBusinessDay為{ year, month, day }對象見 types.ts字符串為 ISO 格式業(yè)務(wù)日如2021-02-03。兩個類型守衛(wèi)isUTCTimestamp/isBusinessDay定義于 types.ts由 入口文件 對外導(dǎo)出。它們在實際解析中被廣泛使用例如時間解析器在判斷數(shù)據(jù)首位時間類型時調(diào)用isBusinessDay(data[0].time) || isString(data[0].time)在格式轉(zhuǎn)換時調(diào)用isUTCTimestamp(time)見 time-utils.ts。這印證了“入站/出站同源”的設(shè)計——底層解析與回傳使用同一套類型判斷。MouseEventParams.seriesPrices已被seriesData取代變更內(nèi)容MouseEventParams中的seriesPrices屬性被移除改用seriesData。兩者相似但seriesData返回的是完整的 series 數(shù)據(jù)項而不僅是價格值。受影響 APIIChartApi.subscribeClickIChartApi.subscribeCrosshairMove遷移前v3從param.seriesPrices.get(lineSeries)拿到的只是價格數(shù)值且無法區(qū)分不同 series 類型的完整數(shù)據(jù)。遷移后v4lineSeries.setData([{ time: 2001-01-01, value: 1 }]); barSeries.setData([{ time: 2001-01-01, open: 5, high: 10, low: 1, close: 7 }]); chart.subscribeCrosshairMove(param { console.log(param.seriesData.get(lineSeries)); // { time: 2001-01-01, value: 1 } 或 undefined console.log(param.seriesData.get(barSeries)); // { time: 2001-01-01, open: 5, high: 10, low: 1, close: 7 } 或 undefined });注意seriesData的類型是MapISeriesApi, BarData | LineData | HistogramData | CustomData見 ichart-api.ts。它把整行 plot 數(shù)據(jù)含 time 與 OHLC 等字段回傳給事件處理器因此在十字光標(biāo)或點擊回調(diào)中你可以直接讀取 open/high/low/close而不必再通過 series 查詢價格。源碼佐證seriesData的組裝邏輯位于 chart-api.ts——庫內(nèi)部遍歷param.seriesDataSeriesPlotRow集合將每個 series 的 plot 行轉(zhuǎn)換為 API 層的完整數(shù)據(jù)對象再在 chart-api.ts 處將其與hoveredObjectId: param.hoveredObject一并寫入對外暴露的MouseEventParams。hoveredMarkerId更名為hoveredObjectId變更內(nèi)容MouseEventParams.hoveredMarkerId更名為hoveredObjectId。遷移后v4chart.subscribeCrosshairMove(param { console.log(param.hoveredObjectId); }); chart.subscribeClick(param { console.log(param.hoveredObjectId); });原因分析v4 擴展了“可被懸停/命中的對象”范圍——不再局限于 series marker標(biāo)記還包括價格線price line等對象因此字段名從“marker”泛化為“object”。其類型為unknown見 ichart-api.ts在 chart-api.ts 中由內(nèi)部的param.hoveredObject直接映射而來因此你可以在回調(diào)里自行縮小類型后再使用。遷移核對清單完成 v3 → v4 遷移后建議逐項自查變更項v3 寫法v4 寫法最后價格動畫枚舉LasPriceAnimationModeLastPriceAnimationModeseries 邊距addLineSeries({ scaleMargins })series.priceScale().applyOptions({ scaleMargins })布局背景l(fā)ayout.backgroundColor: redlayout.background: { type: ColorType.Solid, color: red }疊加 series{ overlay: true }指定priceScaleId見 v2→v3 指南刻度歸屬{ priceScale: right }通過priceScaleId指定見 v2→v3 指南獲取價格刻度chart.priceScale()chart.priceScale(right)/chart.priceScale(left)刻度線顯隱drawTicks: true默認開ticksVisible: true默認關(guān)閉時間回傳值出站值丟失業(yè)務(wù)日字符串出站值與你傳入的完全一致配合isUTCTimestamp/isBusinessDay守衛(wèi)使用懸停數(shù)據(jù)param.seriesPricesparam.seriesData返回完整數(shù)據(jù)項懸停對象 IDparam.hoveredMarkerIdparam.hoveredObjectId其中與時間類型守衛(wèi)相關(guān)的導(dǎo)出isUTCTimestamp、isBusinessDay可在 入口文件 中確認價格刻度默認選項ticksVisible: false、scaleMargins默認值見 price-scale-options-defaults.ts布局背景默認值見 layout-options-defaults.ts。遷移完成后建議用 TypeScript 嚴(yán)格模式編譯一遍項目絕大多數(shù)被移除的選項如 series 級scaleMargins、drawTicks會直接在編譯期暴露出來剩下的運行時行為差異如刻度線默認關(guān)閉、出站時間類型變化再結(jié)合本文清單逐一驗證即可?！久赓M下載鏈接】lightweight-chartsPerformant financial charts built with HTML5 canvas項目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考