Lightweight Charts 系列类型（Series Types）完整指南：内置图表类型、配置项与自定义系列扩展

Lightweight Charts 系列类型Series Types完整指南内置图表类型、配置项与自定义系列扩展【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts本文是 Lightweight Charts 系列类型Series Types的实战技术指南系统梳理库内置的六种标准系列——Area面积图、BarOHLC 柱状图、Baseline基线图、CandlestickK 线图、Histogram直方图、Line折线图——以及基于插件机制的自定义系列Custom Series。读完本文你将掌握每种系列的创建方法、数据格式、专属样式选项及其默认值学会在创建时或运行时applyOptions灵活定制系列外观并能通过addCustomSeries扩展出全新的图表类型。系列定制Series Customisation在 Lightweight Charts 中所有系列series都支持自定义但可用的选项取决于具体系列类型每种类型都拥有自己专属的一组配置项通常由「该类型的样式选项」与「所有系列共享的通用选项SeriesOptionsCommon」混合而成。通用选项定义了title、visible、lastValueVisible、priceLineVisible、priceLineSource、priceLineWidth、priceLineColor、priceLineStyle、priceFormat、baseLineVisible、baseLineColor、baseLineWidth、baseLineStyle、hitTestTolerance、autoscaleInfoProvider等行为其默认值集中在 src/api/options/series-options-defaults.ts 中例如// src/api/options/series-options-defaults.ts export const seriesOptionsDefaults: SeriesOptionsCommon { title: , visible: true, hitTestTolerance: 3, lastValueVisible: true, priceLineVisible: true, priceLineSource: PriceLineSource.LastBar, priceLineWidth: 1, priceLineColor: , priceLineStyle: LineStyle.Dashed, baseLineVisible: true, baseLineWidth: 1, baseLineColor: #B2B5BE, baseLineStyle: LineStyle.Solid, priceFormat: { type: price, precision: 2, minMove: 0.01 }, };值得关注的是priceFormat它支持price最常见的价格格式可自定义精度与舍入、volume使用1.2K、12.67M之类的缩写、percent末尾带%三种内置格式也支持type: custom配合formatter函数完全接管价格格式化定义见 src/model/series-options.ts。修改系列选项有两条途径创建系列时直接指定默认选项——每一个创建系列的方法都带一个可选的options参数// 在创建时修改面积图的顶部与底部颜色 const series chart.addAreaSeries({ topColor: red, bottomColor: green, });通过ISeriesApi.applyOptions方法在运行时动态应用其他选项// 在运行时更新 K 线图选项 candlestickSeries.applyOptions({ upColor: red, downColor: blue, });这种方式适合根据用户交互、主题切换或实时数据状态动态调整系列外观无需重建系列实例。底层来看所有系列的选项类型由SeriesOptionsT T SeriesOptionsCommon、SeriesPartialOptionsT DeepPartialT SeriesOptionsCommon推导并通过 SeriesOptionsMap 把每种系列类型映射到各自的选项结构。Area面积图创建方法IChartApi.addAreaSeries对应 src/api/ichart-api.ts数据格式SingleValueData或WhitespaceData样式选项SeriesOptionsCommon与AreaStyleOptions的混合面积图本质上是「连接所有数据点的折线」与 时间坐标轴 之间填充的一块彩色区域const chartOptions { layout: { textColor: CHART_TEXT_COLOR, background: { type: solid, color: CHART_BACKGROUND_COLOR } } }; const chart createChart(document.getElementById(container), chartOptions); const areaSeries chart.addAreaSeries({ lineColor: LINE_LINE_COLOR, topColor: AREA_TOP_COLOR, bottomColor: AREA_BOTTOM_COLOR }); const data [{ value: 0, time: 1642425322 }, { value: 8, time: 1642511722 }, { value: 10, time: 1642598122 }, { value: 20, time: 1642684522 }, { value: 3, time: 1642770922 }, { value: 43, time: 1642857322 }, { value: 41, time: 1642943722 }, { value: 43, time: 1643030122 }, { value: 56, time: 1643116522 }, { value: 46, time: 1643202922 }]; areaSeries.setData(data); chart.timeScale().fitContent();面积图的默认样式定义在 src/model/series/area-series.tstopColor默认rgba( 46, 220, 135, 0.4)、bottomColor默认rgba( 40, 221, 100, 0)渐变到透明、lineColor默认#33D778、lineWidth默认3、lineStyle默认实线、lineType默认LineType.Simple并支持crosshairMarkerVisible、crosshairMarkerRadius默认4、lastPriceAnimation默认Disabled可选Continuous或OnDataUpdate、pointMarkersVisible默认false等选项。此外AreaStyleOptions还提供两个进阶选项relativeGradient默认false为true时渐变相对于基准值与当前可见范围为false时渐变相对于图表顶部和底部invertFilledArea默认false为true时反转填充区域即填充折线上方的区域。BarOHLC 柱状图创建方法IChartApi.addBarSeries数据格式BarData或WhitespaceData样式选项SeriesOptionsCommon与BarStyleOptions的混合柱状图以条形形式展示价格变动。垂直条的长度由最高价与最低价决定开盘点Open与收盘点Close分别用条形左侧与右侧的短横线tick mark表示const chartOptions { layout: { textColor: CHART_TEXT_COLOR, background: { type: solid, color: CHART_BACKGROUND_COLOR } } }; const chart createChart(document.getElementById(container), chartOptions); const barSeries chart.addBarSeries({ upColor: BAR_UP_COLOR, downColor: BAR_DOWN_COLOR }); const data [{ open: 10, high: 10.63, low: 9.49, close: 9.55, time: 1642427876 }, { open: 9.55, high: 10.30, low: 9.42, close: 9.94, time: 1642514276 }, { open: 9.94, high: 10.17, low: 9.92, close: 9.78, time: 1642600676 }, { open: 9.78, high: 10.59, low: 9.18, close: 9.51, time: 1642687076 }, { open: 9.51, high: 10.46, low: 9.10, close: 10.17, time: 1642773476 }, { open: 10.17, high: 10.96, low: 10.16, close: 10.47, time: 1642859876 }, { open: 10.47, high: 11.39, low: 10.40, close: 10.81, time: 1642946276 }, { open: 10.81, high: 11.60, low: 10.30, close: 10.75, time: 1643032676 }, { open: 10.75, high: 11.60, low: 10.49, close: 10.93, time: 1643119076 }, { open: 10.93, high: 11.53, low: 10.76, close: 10.96, time: 1643205476 }]; barSeries.setData(data); chart.timeScale().fitContent();BarData继承自OhlcDatasrc/model/data-consumer.ts包含time、open、high、low、close五个字段并可附加可选的color字段对单根柱单独着色。BarStyleOptionssrc/model/series-options.ts只有四个专属选项默认值见 src/model/series/bar-series.tsupColor上涨柱颜色默认#26a69adownColor下跌柱颜色默认#ef5350openVisible是否显示开盘点横线默认truethinBars是否以细线stick形式绘制默认true。Baseline基线图创建方法IChartApi.addBaselineSeries数据格式SingleValueData或WhitespaceData样式选项SeriesOptionsCommon与BaselineStyleOptions的混合基线图本质上是「连接所有数据点的折线」与基准值线base value 之间填充的两块彩色区域——上方一块、下方一块非常适合展示相对某个阈值如零轴、成本线的偏离const chartOptions { layout: { textColor: CHART_TEXT_COLOR, background: { type: solid, color: CHART_BACKGROUND_COLOR } } }; const chart createChart(document.getElementById(container), chartOptions); const baselineSeries chart.addBaselineSeries({ baseValue: { type: price, price: 25 }, topLineColor: BASELINE_TOP_LINE_COLOR, topFillColor1: BASELINE_TOP_FILL_COLOR1, topFillColor2: BASELINE_TOP_FILL_COLOR2, bottomLineColor: BASELINE_BOTTOM_LINE_COLOR, bottomFillColor1: BASELINE_BOTTOM_FILL_COLOR1, bottomFillColor2: BASELINE_BOTTOM_FILL_COLOR2 }); const data [{ value: 1, time: 1642425322 }, { value: 8, time: 1642511722 }, { value: 10, time: 1642598122 }, { value: 20, time: 1642684522 }, { value: 3, time: 1642770922 }, { value: 43, time: 1642857322 }, { value: 41, time: 1642943722 }, { value: 43, time: 1643030122 }, { value: 56, time: 1643116522 }, { value: 46, time: 1643202922 }]; baselineSeries.setData(data); chart.timeScale().fitContent();BaselineStyleOptions的默认值定义在 src/model/series/baseline-series.tsbaseValue默认{ type: price, price: 0 }目前仅支持price类型见BaseValueType上方区域使用topFillColor1默认rgba(38, 166, 154, 0.28)、topFillColor2默认rgba(38, 166, 154, 0.05)、topLineColor默认rgba(38, 166, 154, 1)三色控制形成从实色到透明的渐变下方区域则对应bottomFillColor1默认rgba(239, 83, 80, 0.05)、bottomFillColor2默认rgba(239, 83, 80, 0.28)、bottomLineColor默认rgba(239, 83, 80, 1)上下两区默认即呈现「绿上红下」的语义化配色。与面积图类似它也支持relativeGradient、lineWidth默认3、lineStyle、lineType、crosshairMarker*与lastPriceAnimation等选项。CandlestickK 线图创建方法IChartApi.addCandlestickSeries数据格式CandlestickData或WhitespaceData样式选项SeriesOptionsCommon与CandlestickStyleOptions的混合K 线图以蜡烛形态展示价格变动开盘价与收盘价构成蜡烛的实体body影线wick表示该时间区间内的最高价与最低价const chartOptions { layout: { textColor: CHART_TEXT_COLOR, background: { type: solid, color: CHART_BACKGROUND_COLOR } } }; const chart createChart(document.getElementById(container), chartOptions); const candlestickSeries chart.addCandlestickSeries({ upColor: BAR_UP_COLOR, downColor: BAR_DOWN_COLOR, borderVisible: false, wickUpColor: BAR_UP_COLOR, wickDownColor: BAR_DOWN_COLOR }); const data [{ open: 10, high: 10.63, low: 9.49, close: 9.55, time: 1642427876 }, { open: 9.55, high: 10.30, low: 9.42, close: 9.94, time: 1642514276 }, { open: 9.94, high: 10.17, low: 9.92, close: 9.78, time: 1642600676 }, { open: 9.78, high: 10.59, low: 9.18, close: 9.51, time: 1642687076 }, { open: 9.51, high: 10.46, low: 9.10, close: 10.17, time: 1642773476 }, { open: 10.17, high: 10.96, low: 10.16, close: 10.47, time: 1642859876 }, { open: 10.47, high: 11.39, low: 10.40, close: 10.81, time: 1642946276 }, { open: 10.81, high: 11.60, low: 10.30, close: 10.75, time: 1643032676 }, { open: 10.75, high: 11.60, low: 10.49, close: 10.93, time: 1643119076 }, { open: 10.93, high: 11.53, low: 10.76, close: 10.96, time: 1643205476 }]; candlestickSeries.setData(data); chart.timeScale().fitContent();CandlestickData同样继承自OhlcData并额外支持按数据点覆盖颜色的color、borderColor、wickColor字段src/model/data-consumer.ts。CandlestickStyleOptions是内置系列中颜色体系最丰富的一类默认值见 src/model/series/candlestick-series.ts选项默认值说明upColor#26a69a上涨蜡烛实体颜色downColor#ef5350下跌蜡烛实体颜色wickVisibletrue是否显示最高/最低价影线borderVisibletrue是否显示蜡烛边框borderColor#378658统一边框颜色borderUpColor#26a69a上涨蜡烛边框颜色borderDownColor#ef5350下跌蜡烛边框颜色wickColor#737375统一影线颜色wickUpColor#26a69a上涨蜡烛影线颜色wickDownColor#ef5350下跌蜡烛影线颜色源码中的fillUpDownCandlesticksColors工具函数src/model/series-options.ts还实现了一个便捷行为当你只设置了borderColor时它会自动把该颜色同时赋给borderUpColor与borderDownColor只设置wickColor时同理自动同步到wickUpColor与wickDownColor减少重复配置。Histogram直方图创建方法IChartApi.addHistogramSeries数据格式HistogramData或WhitespaceData样式选项SeriesOptionsCommon与HistogramStyleOptions的混合直方图系列用于图形化展示数值分布它在时间轴上按区间生成柱状列columns每根柱的高度对应落入该区间的数值大小const chartOptions { layout: { textColor: CHART_TEXT_COLOR, background: { type: solid, color: CHART_BACKGROUND_COLOR } } }; const chart createChart(document.getElementById(container), chartOptions); const histogramSeries chart.addHistogramSeries({ color: HISTOGRAM_COLOR }); const data [{ value: 1, time: 1642425322 }, { value: 8, time: 1642511722 }, { value: 10, time: 1642598122 }, { value: 20, time: 1642684522 }, { value: 3, time: 1642770922, color: red }, { value: 43, time: 1642857322 }, { value: 41, time: 1642943722, color: red }, { value: 43, time: 1643030122 }, { value: 56, time: 1643116522 }, { value: 46, time: 1643202922, color: red }]; histogramSeries.setData(data); chart.timeScale().fitContent();HistogramStyleOptions仅有两个专属选项src/model/series/histogram-series.tscolor柱列颜色默认#26a69a与base柱列的初始基准值默认0。从上面的例子可以看出HistogramData支持在单个数据点上通过可选的color字段覆盖全局颜色——这是成交量柱按涨跌分色、或突出显示特定柱列的常用手法。Line折线图创建方法IChartApi.addLineSeries数据格式LineData或WhitespaceData样式选项SeriesOptionsCommon与LineStyleOptions的混合折线图以一系列被直线段连接起来的数据点展示信息是最基础也最常用的趋势展示形式const chartOptions { layout: { textColor: CHART_TEXT_COLOR, background: { type: solid, color: CHART_BACKGROUND_COLOR } } }; const chart createChart(document.getElementById(container), chartOptions); const lineSeries chart.addLineSeries({ color: LINE_LINE_COLOR }); const data [{ value: 0, time: 1642425322 }, { value: 8, time: 1642511722 }, { value: 10, time: 1642598122 }, { value: 20, time: 1642684522 }, { value: 3, time: 1642770922 }, { value: 43, time: 1642857322 }, { value: 41, time: 1642943722 }, { value: 43, time: 1643030122 }, { value: 56, time: 1643116522 }, { value: 46, time: 1643202922 }]; lineSeries.setData(data); chart.timeScale().fitContent();LineStyleOptions的核心默认值定义在 src/model/series/line-series.ts面积图、基线图共用了其中的大部分线型选项color折线颜色默认#2196f3lineStyle线条样式默认LineStyle.Solid还支持虚线、点线等枚举lineWidth像素线宽默认3lineType线段类型默认LineType.Simple另有阶梯线等类型lineVisible是否显示系列折线默认truepointMarkersVisible/pointMarkersRadius是否在每个数据点上显示圆形标记及其半径默认不显示crosshairMarkerVisible/crosshairMarkerRadius默认4/crosshairMarkerBorderColor/crosshairMarkerBackgroundColor/crosshairMarkerBorderWidth默认2十字光标吸附标记的显示控制其中颜色留空时会自动回退到十字光标下方系列自身的颜色lastPriceAnimation最新价格动画模式默认LastPriceAnimationMode.Disabled可切换为Continuous始终启用或OnDataUpdate仅在收到新数据后播放。此外LineData与HistogramData一样允许通过每个数据点的可选color字段实现逐点着色src/model/data-consumer.ts。自定义系列Custom Series / Plugins除六种内置系列外Lightweight Charts 允许开发者添加自己的系列类型也就是系列插件series plugins。这一机制让开发者能够为库扩展全新的图表类型、指标或其他自定义可视化形态。自定义系列类型的定义方式是创建一个实现了ICustomSeriesPaneView接口的类该类负责实现 Lightweight Charts 在绘制该系列时会调用的渲染代码。定义完成后通过IChartApi.addCustomSeries()方法即可把它添加到任意图表实例上使用方式与内置系列完全一致// 实现 ICustomSeriesPaneView 接口的自定义系列类 class MyCustomSeries { /* 渲染逻辑实现 */ } // 将自定义系列实例添加到图表 const customSeries chart.addCustomSeries(new MyCustomSeries(), { /* 可选的系列选项 */ }); // 与其他系列一样使用 setData 提供数据 customSeries.setData([ { time: 1642425322, value: 1 }, { time: 1642511722, value: 8 }, ]);从源码看自定义系列的机制是成体系的ICustomSeriesPaneViewsrc/model/icustom-series.ts定义了渲染视图契约addCustomSeries的签名接受TData extends CustomDataHorzScaleItem与TOptions extends CustomSeriesOptions两个泛型src/api/ichart-api.ts自定义数据要求包含合法的time字段即扩展WhitespaceData结构见 src/model/data-consumer.ts并可携带任意自定义字段供渲染层使用CustomPlotRow.data见 src/model/series-data.ts。在选项层面CustomStyleOptions目前提供color一项用于价格线与价格刻度标签的着色src/model/series-options.ts。关于插件开发的完整指引请参阅 插件介绍Plugins 一文本仓库的 src/plugins 目录与 plugin-examples/src/plugins 目录下还有大量可直接参考的自定义系列与绘制原语示例。系列数据格式与选型速查综合以上各节可把内置系列的核心要素汇总如下系列类型创建方法IChartApi数据格式专属样式选项接口典型用途AreaaddAreaSeriesSingleValueData/WhitespaceDataAreaStyleOptions趋势 面积填充、净值曲线BaraddBarSeriesBarData/WhitespaceDataBarStyleOptionsOHLC 行情、数据密度高的行情条BaselineaddBaselineSeriesSingleValueData/WhitespaceDataBaselineStyleOptions围绕基准值的偏离展示CandlestickaddCandlestickSeriesCandlestickData/WhitespaceDataCandlestickStyleOptions金融 K 线行情HistogramaddHistogramSeriesHistogramData/WhitespaceDataHistogramStyleOptions成交量、分布统计LineaddLineSeriesLineData/WhitespaceDataLineStyleOptions通用趋势线、指数曲线CustomaddCustomSeries任意扩展WhitespaceData的数据结构CustomStyleOptions 自定义选项库未覆盖的新图表类型需要特别说明两点其一WhitespaceData仅含time字段src/model/data-consumer.ts可插入任意系列用于在时间轴上保留空位例如非交易日而不产生绘制内容其二每个系列最终都会把输入数据规整为对应的 PlotRow 结构src/model/series-data.ts例如CandlestickPlotRow携带color、borderColor、wickColorBaselinePlotRow携带六组填充/线条颜色这些逐点覆盖色与系列级选项共同决定了最终的渲染效果。选型时遵循「有明确 OHLC 需求选 Bar/Candlestick只需单值趋势选 Line/Area需要阈值对比选 Baseline需要分布展示选 Histogram库内没有的形态走自定义系列」即可快速落地。【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考