---
title: "SparkChart 迷你折线图"
description: "带平滑曲线与悬停读值的 canvas 趋势图"
category: Visualization
status: beta
since: 0.3.9
tags: [ai, chart, canvas, data]
syncStatus: reviewed
verified: true
---

## 用法

### SparkChart + ChartScrubber

::::TuffDemoWrapper{demo="SparkChartSparkChartDemo" code-lang="vue" title="可擦洗的趋势快照" description="平滑的双趋势、坐标轴与指针下的数值读数。"}
---
code: |
  <script setup lang="ts">
  import { computed, ref } from 'vue'

  const data = [0.22, 0.31, 0.45, 0.58, 0.51, 0.74, 0.91]
    .map((value, index) => ({ time: index * 5, value }))
  const activeIndex = ref<number | null>(null)
  const series = [{ id: 'trend', data }]
  const rows = computed(() => activeIndex.value === null
    ? []
    : [{ label: 'Trend', value: `${data[activeIndex.value]?.value ?? 0}` }])
  </script>

  <template>
    <TxChartScrubber
      :point-count="data.length"
      :active-index="activeIndex"
      :rows="rows"
      @update:active-index="activeIndex = $event"
    >
      <TxSparkChart
        :series="series"
        :active-index="activeIndex"
        x-axis
        y-axis
        grid
        aria-label="Trend snapshot"
      />
    </TxChartScrubber>
  </template>
---
::::

### 最佳实践

- 给舞台确定高度，否则零高度容器无法绘制。
- 传入 `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`；数据更新为 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。

<TuffDocSourceLink />