SparkChart 迷你折线图
带平滑曲线与悬停读值的 canvas 趋势图
用法
SparkChart + ChartScrubber
可擦洗的趋势快照
平滑的双趋势、坐标轴与指针下的数值读数。
Loading demo...
最佳实践
- 给舞台确定高度,否则零高度容器无法绘制。
- 传入
aria-label与SparkSeries.label,悬停数值就不会只存在于视觉提示框里。 - 默认 monotone 配合均匀且足够密集的采样点。稀疏数据仍然稀疏,平滑不应凭空发明数据。
- 同时使用两个组件时,把同一个
activeIndex绑定到TxChartScrubber与TxSparkChart。 - 两者都按绘图区(而非整个舞台)换算指针位置,十字线才会落在它所报告的采样点上。图表把自己留出的横向边距以
--tx-bui-plot-left/--tx-bui-plot-right写在根节点上,擦洗层从被包裹的元素读取,无需手工同步。 - 提示框居中跟随指针,只有将要越出舞台时才被拉回。提示框宽度需小于舞台,否则它就没有可移动的空间。
API 参考
SparkChart Props
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
series | SparkSeries[] | — | 序列数组,{ id, data, color?, label? }。 |
theme | 'light' | 'dark' | 'auto' | 'auto' | auto 跟随 data-theme 或 .dark。 |
grid | boolean | false | 是否画水平发丝网格线。 |
gridLines | number | 4 | 网格线条数。 |
lineWidth | number | 2.25 | 线宽(CSS 像素)。 |
curve | LineCurve | 'monotone' | linear、monotone、natural 或 step。 |
xAxis | boolean | false | 是否画紧凑的 x 轴基线与标签。 |
yAxis | boolean | false | 是否画紧凑的 y 轴基线与标签。 |
xTicks | number | 3 | x 轴标签条数。 |
yTicks | number | 4 | y 轴标签条数。 |
xTickFormat | (value: number) => string | — | 覆盖 x 轴标签格式化。 |
yTickFormat | (value: number) => string | — | 覆盖 y 轴标签格式化。 |
padding | Partial<SparkChartPadding> | { top: 24, right: 0, bottom: 22, left: 0 } | 内边距;坐标轴会额外保留最小边缘。 |
domain | [number, number] | — | 固定纵轴范围,省略则按数据自适应。 |
activeIndex | number | null | — | 受控的高亮采样点。 |
interactive | boolean | true | 是否启用指针与键盘悬停状态。 |
baseline | boolean | true | 在每条序列自己的起始值上画一条虚线基准。没有基准,眼睛只能看出线在抖,看不出最终比起点高还是低。按序列各画一条而不是共用一条零线——同一张 spark 图上的两条序列很少同刻度。 |
endpoint | boolean | true | 在每条序列的最后一个样本上画实心圆点。线的末端是当前值,也就是读者真正要看的那个数,只描边的话它和任何中间点一样重。 |
animation | boolean | true | ECharts 对齐的 1000ms 进入与 500ms 更新动效。 |
ariaLabel | string | — | canvas 的可访问名。 |
SparkPoint 是 { time: number, value: number };time 用来定位采样点,不要求是真实时间戳。给 SparkSeries.label 后,悬停宣读会使用它。
SparkChart Events
| 事件名 | 回调参数 | 说明 |
|---|---|---|
update:activeIndex | (index: number | null) | 受控悬停写回。 |
hover | (index: number) | 到达新的活动采样点。 |
leave | — | 指针离开或 Escape 清除了活动采样点。 |
ChartScrubber Props
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
pointCount | number | — | 指针映射到的采样点总数。 |
activeIndex | number | null | — | 受控下标。不传则由组件自持。 |
rows | ChartTooltipRow[] | — | 提示框行,{ label, value, color? }。 |
timeLabel | string | — | 提示框顶部的时间行。 |
tooltip | boolean | true | 关掉后只保留游标线。 |
anchorMargin | number | 8 | 提示框与舞台边缘保留的间距(px)。 |
disabled | boolean | false | 关掉指针响应。 |
ChartScrubber Events
| 事件名 | 回调参数 | 说明 |
|---|---|---|
scrub | (index: number) | 指针落到新的采样点。 |
leave | — | 指针离开、抬起或被取消。 |
update:activeIndex | (index: number | null) | 受控写回。 |
暴露方法
| 名称 | 说明 |
|---|---|
redraw() | 按当前测得的容器尺寸与数据重绘画布。 |
插槽
| 插槽 | 说明 |
|---|---|
default | TxChartScrubber 包裹的图表(通常是 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;数据更新为 500mscubicInOut;超过 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