组件/SparkChart 迷你折线图

SparkChart 迷你折线图

带平滑曲线与悬停读值的 canvas 趋势图

Verified自 0.3.9

用法

SparkChart + ChartScrubber

可擦洗的趋势快照

平滑的双趋势、坐标轴与指针下的数值读数。

Loading demo...

最佳实践

  • 给舞台确定高度,否则零高度容器无法绘制。
  • 传入 aria-label 与 SparkSeries.label,悬停数值就不会只存在于视觉提示框里。
  • 默认 monotone 配合均匀且足够密集的采样点。稀疏数据仍然稀疏,平滑不应凭空发明数据。
  • 同时使用两个组件时,把同一个 activeIndex 绑定到 TxChartScrubber 与 TxSparkChart。
  • 两者都按绘图区(而非整个舞台)换算指针位置,十字线才会落在它所报告的采样点上。图表把自己留出的横向边距以 --tx-bui-plot-left / --tx-bui-plot-right 写在根节点上,擦洗层从被包裹的元素读取,无需手工同步。
  • 提示框居中跟随指针,只有将要越出舞台时才被拉回。提示框宽度需小于舞台,否则它就没有可移动的空间。

API 参考

SparkChart Props

属性名类型默认值说明
seriesSparkSeries[]—序列数组,{ id, data, color?, label? }。
theme'light' | 'dark' | 'auto''auto'auto 跟随 data-theme 或 .dark。
gridbooleanfalse是否画水平发丝网格线。
gridLinesnumber4网格线条数。
lineWidthnumber2.25线宽(CSS 像素)。
curveLineCurve'monotone'linear、monotone、natural 或 step。
xAxisbooleanfalse是否画紧凑的 x 轴基线与标签。
yAxisbooleanfalse是否画紧凑的 y 轴基线与标签。
xTicksnumber3x 轴标签条数。
yTicksnumber4y 轴标签条数。
xTickFormat(value: number) => string—覆盖 x 轴标签格式化。
yTickFormat(value: number) => string—覆盖 y 轴标签格式化。
paddingPartial<SparkChartPadding>{ top: 24, right: 0, bottom: 22, left: 0 }内边距;坐标轴会额外保留最小边缘。
domain[number, number]—固定纵轴范围,省略则按数据自适应。
activeIndexnumber | null—受控的高亮采样点。
interactivebooleantrue是否启用指针与键盘悬停状态。
baselinebooleantrue在每条序列自己的起始值上画一条虚线基准。没有基准,眼睛只能看出线在抖,看不出最终比起点高还是低。按序列各画一条而不是共用一条零线——同一张 spark 图上的两条序列很少同刻度。
endpointbooleantrue在每条序列的最后一个样本上画实心圆点。线的末端是当前值,也就是读者真正要看的那个数,只描边的话它和任何中间点一样重。
animationbooleantrueECharts 对齐的 1000ms 进入与 500ms 更新动效。
ariaLabelstring—canvas 的可访问名。

SparkPoint 是 { time: number, value: number };time 用来定位采样点,不要求是真实时间戳。给 SparkSeries.label 后,悬停宣读会使用它。

SparkChart Events

事件名回调参数说明
update:activeIndex(index: number | null)受控悬停写回。
hover(index: number)到达新的活动采样点。
leave—指针离开或 Escape 清除了活动采样点。

ChartScrubber Props

属性名类型默认值说明
pointCountnumber—指针映射到的采样点总数。
activeIndexnumber | null—受控下标。不传则由组件自持。
rowsChartTooltipRow[]—提示框行,{ label, value, color? }。
timeLabelstring—提示框顶部的时间行。
tooltipbooleantrue关掉后只保留游标线。
anchorMarginnumber8提示框与舞台边缘保留的间距(px)。
disabledbooleanfalse关掉指针响应。

ChartScrubber Events

事件名回调参数说明
scrub(index: number)指针落到新的采样点。
leave—指针离开、抬起或被取消。
update:activeIndex(index: number | null)受控写回。

暴露方法

名称说明
redraw()按当前测得的容器尺寸与数据重绘画布。

插槽

插槽说明
defaultTxChartScrubber 包裹的图表(通常是 TxSparkChart);擦洗层按它的绘图区换算指针位置。

尺寸与主题

图表填满容器,尺寸从容器量出来而不是靠宽高 prop 指定。外层必须有确定高度。ResizeObserver 会在尺寸变化后重绘;位图按 devicePixelRatio(上限 2)放大,绘制计算仍使用 CSS 像素。

theme 默认 'auto',跟随 <html> 与 <body> 上的 data-theme 或 .dark。canvas 不能继承 CSS 变量,因此主题切换会用当前 token 色重绘。

曲线、坐标轴与悬停

默认 curve="monotone" 使用与完整 @talex-touch/tuffex/charts 折线系列相同的 d3 曲线工厂:它消除折角而不会越过局部极值。只有编码确实需要时才选择 linear、natural 或 step。

xAxis 与 yAxis 在 canvas 内画紧凑的基线和刻度,并自动预留边距。原始时间或数值不适合阅读时,传入 xTickFormat 与 yTickFormat。

interactive 让独立图表拥有指针/键盘十字线:方向键、Home、End 与 Escape 移动或清除活动采样点。受控 activeIndex 让外层 TxChartScrubber 持有提示框,而 canvas 仍绘制高亮点。图表与擦洗层都会通过 polite live region 宣读当前值。

概述

  • 所有序列共用一套纵轴范围;横轴按 time 折算,时间全部相同则按下标均分。单点居中并由圆头线帽画成点。
  • 存在受控下标时,活动十字线与点使用该下标。外层擦洗层可以持有 DOM 提示框而不丢失 canvas 反馈。
  • 数据为空、容器尺寸为 0 或宿主没有 2D 上下文时什么都不画,也不会抛错。
  • 进入动效为 1000ms cubicInOut;数据更新为 500ms cubicInOut;超过 2000 点或 prefers-reduced-motion: reduce 时两者都跳过。

技术实现

  • 组件源码:packages/tuffex/packages/components/src/spark-chart/src/TxSparkChart.vue、TxChartScrubber.vue;投影与绘制见 geometry.ts、draw.ts,类型见 types.ts。
  • 以 canvas 绘制,ResizeObserver 在尺寸变化后重绘;悬停提示框由 TxChartScrubber 以 DOM 呈现,canvas 仍画出高亮点。
  • 移植自 Beautiful UI(https://www.beautifului.dev),© 2026 Shane Levine,MIT。
查看源码
packages/tuffex/packages/components/src/spark-chart/index.ts