前端图表库金融科技数据可视化【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址https://gitcode.com/gh_mirrors/li/lightweight-charts点击查看免费下载时间刻度Time Scale又称时间轴是 lightweight-charts 图表底部的水平坐标轴负责展示数据点的时间、控制当前可视范围并在时间点/逻辑索引与像素坐标之间互相转换。本文以官方文档 time-scale.md 为骨架结合当前仓库源码itime-scale-api.ts、time-scale-api.ts、time-scale.ts与单元测试time-scale.spec.ts系统讲解逻辑区间的含义、可视范围的读写、事件订阅以及全部时间刻度 API 的用法读完即可在项目中精确控制图表横向缩放与滚动。什么是时间刻度时间刻度是绘制在图表底部的一条水平刻度线用于显示每一根 K 线bar或数据点的时间。它的职责可以归纳为三方面控制当前可视范围你可以读取或修改图表当前看到的时间区间坐标换算把一个时间点或逻辑索引logical index转换为像素 x 坐标反之亦然——也就是接管了图表 x 轴相关的全部换算逻辑事件通知提供一组可订阅的事件在可视范围、逻辑范围或刻度尺寸发生变化时收到通知。要操作时间刻度有两条路径改选项通过ITimeScaleApi.applyOptions修改时间刻度选项调方法通过ITimeScaleApi接口上的方法直接控制。// 通过 IChartApi 获取时间刻度 API 实例 const timeScale chart.timeScale(); timeScale.resetTimeScale();ITimeScaleApi实例通过IChartApi.timeScale方法获取。所有可用的时间刻度选项都声明在TimeScaleOptions源码中对应HorzScaleOptions接口中。两种等效的选项设置方式设置时间刻度选项有两种方式效果完全一致图表初始化时在调用createChart时把选项作为timeScale子对象传入运行期动态调整调用chart.timeScale().applyOptions({ ... })或调用chart.applyOptions({ timeScale: { ... } })。// 方式一初始化时配置 const chart LightweightCharts.createChart(container, { timeScale: { barSpacing: 8, rightOffset: 5, timeVisible: true, }, }); // 方式二运行期动态调整两种写法等价 chart.timeScale().applyOptions({ barSpacing: 10 }); chart.applyOptions({ timeScale: { barSpacing: 10 } });从源码看TimeScaleApi.applyOptions直接透传给内部模型time-scale-api.ts 中的applyOptions调用了this._timeScale.applyOptions(options)而模型层 time-scale.ts 会分别处理barSpacing与rightOffset的更新因此两条路径殊途同归。逻辑区间Logical Range理解时间刻度的核心概念逻辑区间是时间刻度最重要也最容易混淆的概念。在源码中LogicalRange被定义为一个仅含两个属性from和to的对象它们的值都是逻辑索引// src/model/time-data.ts export type Logical Nominalnumber, Logical; export type LogicalRange IRangeLogical; // { from: Logical; to: Logical }逻辑索引的规则如下原点时间刻度逻辑区间的起点是所有 series 中的第一个数据项。该点之前的索引为负数从该点开始索引为正数。连续而非离散索引可以带小数部分例如4.2因为时间刻度是连续的而非一格一格离散的。整数部分整数部分表示完全可见的 bar 的索引。例如最后一个可见逻辑索引to字段为5.2意味着最后一根完全可见的 bar 索引为 5同时第 6 根 bar 有 20% 部分可见。半值含义1.5、3.5、10.5这类 .5 索引恰好落在某根 bar 的正中间。上图中红色竖线是 bar 之间的分界线因此该图当前的可视逻辑区间大约是从-4.73到5.05。这段文字与源码中LogicalRange类型定义time-data.ts的注释完全一致两者互相印证。需要特别注意的是逻辑索引与时间点不是一回事。逻辑索引描述的是数据位置不依赖具体的时间戳因此它可以轻松表达数据范围之外的区域例如负数部分、右侧留白部分这正是后面用setVisibleLogicalRange实现图表边距等高级需求的基础。可视范围Visible Range数据范围与逻辑范围可视范围指当前画布上实际显示出来的图表区域它可以用两种尺度衡量数据范围Data Range包含从第一根可见 bar 到最后一根可见 bar 的时间戳。如果可视区域存在空白空荡的部分这部分不计入数据范围。逻辑范围Logical Range上一节介绍的、基于逻辑索引的连续数值线。操作可视范围的四个核心方法全部定义在 itime-scale-api.ts方法作用getVisibleRange()返回当前可见的时间范围{ from, to }值为时间戳无数据时返回nullsetVisibleRange(range)按时间戳设置可见范围getVisibleLogicalRange()返回当前可见的逻辑范围{ from, to }值为逻辑索引无数据时返回nullsetVisibleLogicalRange(range)按逻辑索引设置可见范围数据范围的限制不能外推时间setVisibleRange有一个重要限制它不能外推时间只会使用当前已经存在的数据。例如图表上没有2018-01-01之前的数据如果你把可见范围设为从2016-01-01开始它会被自动调整回2018-01-01to方向同理。这一行为在源码的 JSDoc 中有明确说明itime-scale-api.ts并在setVisibleRange的实现中体现时间戳会先经过logicalRangeForTimeRange转换为逻辑区间再交由模型设置超出数据范围的部分自然会被裁剪。// 按时间戳设置可见范围秒级时间戳 chart.timeScale().setVisibleRange({ from: new Date(Date.UTC(2018, 0, 1)).getTime() / 1000, to: new Date(Date.UTC(2018, 1, 1)).getTime() / 1000, });如果需要更灵活地调整可视范围应该改用逻辑范围setVisibleLogicalRange允许你把可视范围设置到现有数据边界之外这在设置图表边距chart margin或对齐 series 时非常有用。// 按逻辑索引设置可见范围 chart.timeScale().setVisibleLogicalRange({ from: 0, to: 10 });图表边距Chart Margin控制图表与边框的间距边距指的是图表边框与 series 之间的空白空间它主要由两个时间刻度选项决定选项含义默认值barSpacing相邻 bar 之间的像素间距6rightOffset从图表右边缘到最新一根 bar 的距离以 bar 数为单位0这两个默认值来自 time-scale-options-defaults.ts 中的timeScaleOptionsDefaults常量是整个时间刻度选项体系的基准。实际计算坐标时模型层会按宽度 - (deltaFromRight 0.5) * barSpacing - 1的公式time-scale.ts把逻辑索引换算成像素坐标可见barSpacing直接决定了每个数据点被分配到的横向宽度。数据点少时的左侧大边距问题如果一个 series 只有少量数据点图表左侧可能会出现很大的边距。此时可以调用fitContent()方法让图表自动调整视角、把全部数据适配进可视区域chart.timeScale().fitContent();如果调用fitContent没有效果可能是库的数据宽度分配机制所致库会为每个数据点分配特定宽度以保持不同图表类型如折线、K 线之间的一致性。例如折线 series 的绘图点位于分配空间的正中心而 K 线 series 则用大部分宽度绘制实体每个数据点分配到的空间与图表宽度成正比。因此数据点较少的 series 在两侧都可能有少量边距。让 series 精确贴合边缘逻辑范围微调如果需要让 series 精确贴合图表左右边缘可以先用getVisibleLogicalRange()读取当前逻辑范围再用setVisibleLogicalRange在两侧各收缩半个 bar 宽度const vr chart.timeScale().getVisibleLogicalRange(); chart.timeScale().setVisibleLogicalRange({ from: vr.from 0.5, to: vr.to - 0.5 });这段代码之所以可行正是因为逻辑索引是连续值0.5表示向中间收缩半个 bar-0.5同理。这是setVisibleLogicalRange相比setVisibleRange更灵活的典型场景。事件订阅感知时间刻度的变化时间刻度提供了三个可订阅事件处理器类型定义见 itime-scale-api.ts均在TimeScaleApi构造函数中与内部模型的Delegate建立连接time-scale-api.ts事件处理器参数触发时机subscribeVisibleTimeRangeChange(handler){ from, to }时间为Time类型或null可见时间范围变化subscribeVisibleLogicalRangeChange(handler){ from, to }值为数字或null可见逻辑范围变化subscribeSizeChange(handler)(width, height)时间刻度尺寸变化function myVisibleLogicalRangeChangeHandler(newVisibleLogicalRange) { if (newVisibleLogicalRange null) { // 图表没有可见数据处理 null 情况 return; } console.log(visible logical range:, newVisibleLogicalRange); } chart.timeScale().subscribeVisibleLogicalRangeChange(myVisibleLogicalRangeChangeHandler); // 不再需要时取消订阅 chart.timeScale().unsubscribeVisibleLogicalRangeChange(myVisibleLogicalRangeChangeHandler);每个订阅事件都配有对应的unsubscribe*方法用于取消订阅。注意当图表没有任何数据时处理器收到的参数是null因此处理器内部应先做空值判断源码示例中的myVisibleTimeRangeChangeHandler也演示了这一点。坐标换算与其余 API 一览除了范围控制与事件ITimeScaleApi还提供了完整的换算与导航方法坐标换算方法作用logicalToCoordinate(logical)逻辑索引 → 本地 x 坐标无数据返回nullcoordinateToLogical(x)像素 x 坐标 → 逻辑索引无数据返回nulltimeToCoordinate(time)时间 → x 坐标刻度上找不到该时间返回nullcoordinateToTime(x)x 坐标 → 该位置 bar 的时间找不到返回nulltimeToIndex(time, findNearest)时间 → 索引findNearest为true时允许取最接近的索引其中timeToIndex的findNearest行为有单元测试覆盖time-scale.spec.ts 中验证了时间大于最后一个时间戳且findNearest为true时返回最后一个索引时间介于两个值之间且findNearest为true时返回下一个索引等边界情况说明该方法对未命中时间的处理是可预测的。滚动与复位方法作用scrollPosition()返回从时间刻度右边缘到最新 bar 的距离以 bar 数计scrollToPosition(position, animated)滚动图表到指定位置animated为true时平滑滚动scrollToRealTime()恢复到默认滚动位置始终带动画resetTimeScale()恢复时间刻度的默认缩放级别与滚动位置fitContent()自动计算可视范围以容纳所有 series 的全部数据chart.timeScale().scrollToRealTime(); // 回到最新数据 chart.timeScale().resetTimeScale(); // 恢复默认缩放与位置 chart.timeScale().fitContent(); // 适配全部数据尺寸查询width()与height()分别返回时间刻度的宽高对应TimeAxisWidget的实际尺寸见 time-scale-api.ts可用于自定义插件或布局计算。常用选项速查表除了barSpacing与rightOffsetHorzScaleOptions还包含一批高频使用的选项默认值全部来自 time-scale-options-defaults.ts选项默认值说明minBarSpacing0.5bar 之间的最小像素间距缩放下限maxBarSpacing0bar 之间的最大像素间距为0时不生效fixLeftEdgefalse禁止向左滚动越过第一根 barfixRightEdgefalse禁止向右滚动越过最新一根 barlockVisibleTimeRangeOnResizefalse图表尺寸变化时锁定可见时间范围rightBarStaysOnScrollfalse滚动时防止悬停的 bar 移动borderVisibletrue是否显示时间刻度边框borderColor#2B2B43时间刻度边框颜色visibletrue是否显示时间刻度timeVisiblefalse刻度与十字光标标签是否显示时间而不只是日期secondsVisibletrue日内数据是否显示秒hh:mm:ss格式shiftVisibleRangeOnNewBartrue新增数据时是否右移可视范围仅当最后一根 bar 可见时生效allowShiftVisibleRangeOnWhitespaceReplacementfalse新 bar 替换空白时间点时是否允许右移可视范围ticksVisiblefalse是否在时间刻度标签上绘制小竖线uniformDistributionfalse均匀分布模式相同权重的刻度标记要么全部绘制、要么全部不绘制minimumHeight0时间刻度最小高度内容需要更多空间时会自动突破allowBoldLabelstrue是否允许主要刻度标签使用粗体ignoreWhitespaceIndicesfalse绘制网格线、刻度与十字光标吸附时是否忽略仅含空白的刻度点以实际应用为例一个常见的固定右侧留白 显示时间 锁定边缘配置如下chart.timeScale().applyOptions({ rightOffset: 3, // 右侧保留 3 根 bar 的留白 barSpacing: 8, // 放大 bar 间距 timeVisible: true, // 显示时间 secondsVisible: false, // 不显示秒 fixLeftEdge: true, // 禁止向左滚出数据起点 fixRightEdge: true, // 禁止向右滚出最新数据 borderColor: #333333, });小结时间刻度是 lightweight-charts 横向交互的核心入口理解逻辑索引是连续的、带小数的数据位置这一概念是正确使用setVisibleLogicalRange、fitContent与边距微调的前提getVisibleRange/setVisibleRange适合按真实时间操作但受限于不能外推时间更灵活的场景应交给逻辑范围处理事件订阅则可让你实时响应可视区域变化。配合本文列出的源码文件itime-scale-api.ts、time-scale-api.ts、time-scale.ts、time-scale-options-defaults.ts与单元测试time-scale.spec.ts继续深入阅读即可在真实项目中精准驾驭图表的横向缩放、滚动与定位。赞分享前端图表库金融科技数据可视化【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址https://gitcode.com/gh_mirrors/li/lightweight-charts点击查看免费下载相关推荐Lightweight Charts 时间轴Time Scale完全指南可见范围、逻辑范围与 API 实战Lightweight Charts 时间轴Time Scale完全指南可见范围、逻辑范围与 API 实战 导读 时间轴Time Scale是 Li前端图表库金融科技数据可视化小红书无水印下载器XHS-Downloader3分钟快速上手终极指南小红书无水印下载器XHS Downloader3分钟快速上手终极指南 小红书无水印下载器XHS Downloader是一款专为小红书用户设计的开源工具能够高前端图表库金融科技数据可视化lightweight-charts 时间轴Time Scale完全指南可见范围、逻辑索引与图表边距控制lightweight charts 时间轴Time Scale完全指南可见范围、逻辑索引与图表边距控制 导读 时间轴Time scale又称时间横轴前端图表库金融科技数据可视化上一篇Zotero Style插件版本升级导致功能失效问题分析下一篇VueDataUI项目中如何实现图表注释标签的显示创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考