企业官网建设流程全解析

Lightweight Charts 双区间直方图系列插件：lwc-plugin-dual-range-histogram-series 功能解析与实战指南

【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts

导读

本文围绕@tradingview/lwc-plugin-dual-range-histogram-series（Lightweight Charts™ 官方插件系列中的双区间直方图自定义系列）1.0.0 版本的能力展开。它基于 HTML5 Canvas 在零轴线上下绘制固定像素高度的内外嵌套柱状图，常用于买卖量（含主动单占比）、买卖盘口深度、资金净流入等成对数据的叠加展示。读完本文，你将掌握该插件的安装方式、数据结构、全部配置参数，以及scaleMode双模式、keepPixelSeriesInView视口预留、命中测试与合并（conflation）等底层机制。

一、插件定位与核心能力（1.0.0 里程碑）

根据本插件的 CHANGELOG，1.0.0（2026-09-16）是该包从 Lightweight Charts™ 仓库plugin-examples示例集合独立发布的第一个正式版本。本次发布引入的完整能力如下：

• DualRangeHistogramSeries自定义系列：在零轴线上绘制固定像素高度的上下嵌套柱状图；
• createDualRangeHistogramSeries：官方推荐的添加方式，绘图值构建时读取当前 options，使scaleMode与baseValue无需重新setData即可生效；
• 样式选项colors与borderRadius，分别按列（upOuter、upInner、downOuter、downInner）键控，另有maxHeight、borderColor、borderWidth；
• scaleMode：'price'模式把数值当作相对baseValue的价格参与自动缩放，替代固定像素高度；
• keepPixelSeriesInView(chart, series, maxHeight?)：为pixels模式的系列在价格刻度上预留空间，并在图表缩放时持续维护；
• normalize（'visible'、'all'或数字）：决定pixels模式下柱高以什么为基准缩放，外加上下两半之间的gap、widthPercent与baseValue；
• 数据点级柱色覆盖：通过数据项上的colors字段实现；
• highlightHovered：悬停时淡化除悬停点外的所有数据点，由hitTest通过十字光标上报bar-<index>支撑；
• conflationReducer：合并（conflation）时保留较新值而非禁用合并。hitTest、conflationReducer、conflationFactor仅在 Lightweight Charts™ 5.1 及以上版本生效。

二、安装与快速上手

2.1 安装前提

该插件以lightweight-charts^5.0.0为 peer 依赖（见 package.json），并提供dist/dual-range-histogram-series.js（ESM 主入口）与dist/dual-range-histogram-series.standalone.js（standalone 构建）两种产物，类型声明位于dist/dual-range-histogram-series.d.ts。

npm 安装：

npm install @tradingview/lwc-plugin-dual-range-histogram-series

2.2 最小可运行示例

import { createChart } from 'lightweight-charts'; import { createDualRangeHistogramSeries } from '@tradingview/lwc-plugin-dual-range-histogram-series'; const chart = createChart(document.getElementById('container')); const histogram = createDualRangeHistogramSeries(chart, { priceLineVisible: false, lastValueVisible: false, }); histogram.setData([ { time: '2024-04-22', values: [120, 45, -80, -30] }, { time: '2024-04-23', values: [90, 60, -110, -20] }, { time: '2024-04-24', values: [140, 35, -60, -40] }, ]);

每个数据点形如{ time, values: number[], colors? }：values中的正数向上绘制、负数向下绘制，数组顺序固定为[upOuter, upInner, downOuter, downInner]；values为空或缺失的点被当作空白（whitespace）处理，该判定逻辑实现在 dual-range-histogram-series.ts 的isWhitespace中。

2.3 CDN 使用

插件以 ES Module 发布，可用 import map 将库与插件映射到 CDN 构建：

<script type="importmap"> { "imports": { "lightweight-charts": "https://unpkg.com/lightweight-charts@^5/dist/lightweight-charts.standalone.production.mjs", "@tradingview/lwc-plugin-dual-range-histogram-series": "https://unpkg.com/@tradingview/lwc-plugin-dual-range-histogram-series/dist/dual-range-histogram-series.standalone.js" } } </script>

之后即可像在打包器环境下一样按名称导入插件。

三、数据模型：values与按列覆盖

3.1 数据结构定义

数据接口DualRangeHistogramData<HorzScaleItem>定义在 data.ts，继承自库的CustomData，包含：

• values: number[]：每根柱的取值序列；
• colors?: (string | undefined)[]：本数据点按列的颜色覆盖，undefined项回落到系列级颜色。

DualRangeHistogramColumns<T>（见 options.ts）把四个键与values中的位置一一对应：[upOuter, upInner, downOuter, downInner]，columnOrder常量即此顺序。

3.2 位置优先于符号

柱形与colors、borderRadius的匹配按values中的位置而非正负号进行：一个落在upOuter槽位的负值仍向下绘制，却使用upOuter的颜色。同一数据点的柱共享宽度与位置，按数组顺序依次绘制，后面的（内层）值覆盖前面的（外层）值，因此要让内柱小于外柱才能呈现嵌套效果。

3.3 超过四个值与多值复用

数据点允许携带超过四个值，四列会循环复用样式，values[4]会再次使用upOuter的样式。此外，非有限数（NaN/Infinity）会被跳过；当不存在可用于缩放的值（例如全零数据集）时，pixels模式下不会绘制任何内容（见 renderer.ts）。

四、完整配置项详解

除库标准系列选项（priceLineVisible、lastValueVisible、priceFormat、autoscaleInfoProvider等）外，插件新增选项及默认值如下表（默认值定义于 options.ts）：

4.1 运行时修改样式

可通过series.applyOptions({ ... })随时调整，示例：

histogram.applyOptions({ colors: { upOuter: '#BBDEFB', upInner: '#1565C0', downOuter: '#FFE0B2', downInner: '#EF6C00', }, borderRadius: { upOuter: 8, upInner: 4, downOuter: 8, downInner: 4 }, borderColor: '#131722', borderWidth: 1, });

五、双缩放模式：pixels与price

scaleMode是插件最核心的选项，语义定义见 options.ts。

5.1pixels模式（默认）：紧凑叠加层

柱高是固定像素数：最大取值填满maxHeight的一半，其余柱按比例缩放。该模式只上报baseValue对应的基线，柱形不参与价格刻度自动缩放，因此不会干扰同一刻度上其他系列（如主 K 线）的缩放——代价是当基线贴近面板顶部或底部时柱形会被裁剪，需要用keepPixelSeriesInView预留空间。柱高换算逻辑位于 renderer.ts：height = (|value| / scale) * (maxHeight / 2)。

5.2price模式：参与自动缩放

数值被当作相对baseValue的价格，与其他系列一样由价格刻度自动缩放；此时maxHeight与normalize均被忽略，也无需预留边距。priceValueBuilder（dual-range-histogram-series.ts）在该模式下计算[base + min, base + max, base]三元组作为绘图值，使刻度能覆盖全部柱形。

5.3normalize：像素模式下的缩放基准

• 'visible'（默认）：以可视范围内绝对值最大的值为基准，平移/缩放时柱高随之重新缩放；
• 'all'：以全量数据集中绝对值最大的值为基准，平移时各柱相对高度保持不变。实现中会缓存扫描结果直到库传入新的 bars 数组（renderer.ts）；
• 数字：以该值作为半高基准，缩放恒定不变。

5.4 关键同步细节：为什么推荐createDualRangeHistogramSeries

绘图值在setData时构建，因此scaleMode与baseValue在那时被读取。若直接chart.addCustomSeries(new DualRangeHistogramSeries(), options)，在 LWC 5.0 上无法在数据摄取前把缩放选项传入；而createDualRangeHistogramSeries(chart, options?, paneIndex?)内部通过createOptionsAwareSeries（来自@tradingview/lwc-toolkit）把['scaleMode', 'baseValue']声明为“敏感”选项，在applyOptions修改它们时自动重建绘图值，保证自动缩放、最新价标签与十字光标数值保持一致，且流式更新仍保持增量（见 dual-range-histogram-series.ts）。

在官方示例 example.ts 中，切换 scaleMode 的典型流程是：先stopKeepingInView()，再applyOptions({ scaleMode })，随后setData(data)让新模式到达价格刻度，最后按需重新调用keepPixelSeriesInView。

六、keepPixelSeriesInView：像素模式下的视口保障

pixels模式下系列不向价格刻度上报取值，自动缩放对柱形一无所知，基线贴近面板上下边缘时柱形会被裁剪。keepPixelSeriesInView(chart, series, maxHeight?)（实现见 keep-in-view.ts）通过计算margin = clamp(seriesHeight / 2 / paneHeight, 0, 0.3)并写入价格刻度的scaleMargins，始终为直方图上下各预留一半高度，且面板调整尺寸或系列移动到其他面板时持续生效。

关键实现细节：

• 它向系列附加一个“尺寸型 primitive”（sizing primitive），通过updateAllViews响应面板级尺寸变化——这类变化是外层图表的ResizeObserver无法捕获的；
• 为避免重入布局，更新被推迟到queueMicrotask中执行；
• 返回值是 detach 函数：在移除图表前调用stop()，多次调用是安全的；
• 第三个参数可传入自定义高度，默认回落到系列自身的maxHeight选项并在每次 resize 时重新读取。

用法：

import { keepPixelSeriesInView } from '@tradingview/lwc-plugin-dual-range-histogram-series'; const stop = keepPixelSeriesInView(chart, histogram); // … 在移除图表之前： stop();

七、交互与高性能渲染机制

7.1 命中测试与highlightHovered

hitTest（renderer.ts）记录上一次绘制在媒体坐标系中的命中区域，命中时返回{ distance: 0, objectId: 'bar-<index>', type: 'range', hitTestData: index }，objectId 会经十字光标上报。highlightHovered: true时，绘制循环把非悬停点的globalAlpha降至0.35，实现“高亮悬停、淡化其余”的效果（renderer.ts）。命中结果类型CustomSeriesHitTestResult在 compat.ts 中自行声明，因为库从 5.1 起才导出该类型；更早的宿主根本不会调用hitTest，此时highlightHovered无效果。

7.2 合并（conflation）与有效柱间距

conflationReducer（dual-range-histogram-series.ts）在数据点合并时返回两个点中较新的一个，与内置直方图行为一致，从而保留合并能力而不必禁用。合并后的柱宽按conflationFactor修正：effectiveBarSpacing（compat.ts）返回barSpacing * factor，因为合并后单个数据点占据的空间比原始barSpacing更宽。这些仅由 5.1+ 调用，5.0 宿主自动跳过。

7.3 渲染管线

渲染基于@tradingview/lwc-toolkit的位图坐标渲染框架：mapVisibleBars只处理可见柱，calculateColumnPositionsInPlace按与内置直方图一致的像素网格布局柱宽（跨空白间隙不延续对齐），圆角矩形由drawRoundRectWithBorder绘制，圆角仅应用于柱形外端（上柱为顶部两角、下柱为底部两角），半径经clampCornerRadius限制在柱宽与柱高范围内（renderer.ts）。

八、典型场景与进阶注意事项

8.1 典型应用

• 买卖量 + 主动单占比：外层柱为总量，内层柱为主动/被动单分量；
• 买卖盘口深度：双向报价柱状对比；
• 资金净流入/流出：以零线为界，上下对称显示，内层高亮某一成分。

正负成对数据均适用。官方示例（example.ts）展示了它与BaselineSeries（baseValue: { type: 'price', price: 0 }）共享价格刻度的组合用法——直方图落在主系列的零线上，互不干扰缩放；sample-data.ts中的generateDualRangeHistogramData演示了如何生成[正外, 正内, 负外, 负内]形式的测试数据。

8.2 版本兼容性速查

8.3 实用提示

• 内层值应小于外层值，才能呈现“嵌套”视觉效果（后绘制者覆盖先绘制者）；
• 柱宽遵循内置直方图相同的像素网格，跨空白（whitespace）间隙时对齐不会延续；
• 非有限数值会被跳过；无缩放基准（如全零数据）时pixels模式不绘制；
• 若以createDualRangeHistogramSeries创建系列后需要直接构造DualRangeHistogramSeries，可为构造函数传入自定义 options getter（readOptions），适用于自行管理选项同步的集成场景。

结语

从 CHANGELOG 的 1.0.0 条目出发可以看到，lwc-plugin-dual-range-histogram-series在轻量级的 API 表面下，把“固定像素高度”“不干扰主系列缩放”“随 resize 保持视口”“命中高亮”与“合并兼容”这些棘手问题都封装在了源码层（options.ts、renderer.ts、keep-in-view.ts）中。将其作为买入卖出量、盘口深度或资金流向的紧凑叠加层接入图表，同时配合官方示例（src/example/）进行交互式调试，即可快速落地一套专业的金融图表展示方案。

【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts