---
title: "Charts 图表"
description: "图表家族：原生 SVG 与按需加载的 ECharts"
category: Charts
status: beta
since: 0.6.0
tags: [chart, svg, d3, overview]
syncStatus: reviewed
verified: true
---

## 安装

图表家族与主包同源，走独立子路径 `@talex-touch/tuffex/charts`，API 面对标 Cloudflare kumo 的 Charts 族，但原生图表的渲染层是 Vue 直出的 SVG，不依赖 echarts，也不依赖任何整图表框架，数学只用可摇树的 d3 微模块（`d3-scale` / `d3-shape` / `d3-sankey` / `d3-geo`）。本族没覆盖的图表类型、以及想直接用 ECharts 配置面时，用 [ECharts 图表家族](/docs/dev/components/echart-charts)：它读同一套颜色 token，以可选 `echarts` peer 的形式提供。

```bash
pnpm add @talex-touch/tuffex
```

```ts
import { TxTimeseriesChart } from '@talex-touch/tuffex/charts'
import '@talex-touch/tuffex/charts/style.css'
```

## 用法

图表沿用 ECharts 的默认时序：首绘入场 1000ms `cubicInOut`，数据更新几何形变 500ms `cubicInOut`；单个序列超过 2000 个点时跳过动画、直接渲染终态。折线/面积的首绘是例外——按 ECharts 折线序列的默认值走 `linear`，从左到右裁剪揭示。悬停高亮不照搬 ECharts 的 300ms `cubicOut`：其余序列变淡、换色这类变化在指针到达的那一帧完成，这是 TuffEx 的悬停规则；只有几何上的强调（扇区外移、地图气泡放大）仍按 300ms `cubicOut` 过渡。
### 最佳实践

- 常见指标场景优先使用专用图表封装（`TxTimeseriesChart`、`TxBubbleMap`、`TxChoroplethMap`、`TxSankeyChart`、`TxSparkChart` 或 `TxEChart`），避免过早从零手拼基础序列原语。
- 样式取色统一通过 `--tx-chart-*` CSS 变量跟随宿主自适应主题，切忌硬编码固定十六进制颜色或手动维护暗色判断分支。
- 单张图表序列数量建议控制在 3–7 条以内以保持良好可读性，并始终为每条序列提供明确图例或完整 Tooltip 说明。

## API 参考

### ChartLegendItem Props

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `variant` | `'small' \| 'large'` | `'small'` | 单行，或可并排进仪表指标带的堆叠大数值。 |
| `name` | `string` | — | 序列名。`loading` 时可省略。 |
| `color` | `string` | — | 色点颜色，接受任意 CSS 颜色（含 `var()`）。 |
| `value` | `string` | — | 已格式化的数值文本。 |
| `unit` | `string` | — | 数值后的单位（仅 `large`）。 |
| `inactive` | `boolean` | `false` | 半透明表示被反选。 |
| `loading` | `boolean` | `false` | 渲染骨架占位（`aria-hidden`，不可聚焦）。 |

## 可用图表

| 组件 | 板块 | 说明 |
|------|------|------|
| `TxTimeseriesChart` | [Timeseries](/docs/dev/components/timeseries-chart) | 时序折线/堆叠柱，标记、阈值、缩放与刷选、tooltip 全家桶。 |
| `TxLearningCurve` | [LearningCurve](/docs/dev/components/learning-curve) | 训练曲线：多种子均值与区间、EMA 平滑、缩放与实时增长。 |
| `TxBubbleMap` / `TxChoroplethMap` | [Maps](/docs/dev/components/maps) | GeoJSON 地图：气泡与分级填色。 |
| `TxSankeyChart` | [Sankey](/docs/dev/components/sankey-chart) | 桑基流向图。 |
| `TxChart` + 系列原语 | [Custom Chart](/docs/dev/components/custom-chart) | 组合式逃生舱：折线/面积/柱/散点/环形自由拼装。 |
| `TxMonoChart` | [MonoChart](/docs/dev/components/mono-chart) | 30 种单色图表变体与活动日历。 |
| `TxDitherChart` | [DitherChart](/docs/dev/components/dither-chart) | 抖动质感的展示型图表，文档归在动效套件。 |
| `TxEChart` + 九个预设 | [ECharts](/docs/dev/components/echart-charts) | 其余图表类型；挂载时按需加载可选 peer `echarts`。 |
| `ChartPalette` / CSS 变量 | [Colors](/docs/dev/components/chart-colors) | 分类、语义、顺序、地图色板，明暗自动。 |

## 图例

`TxChartLegendItem` 提供两种图例项版式：`small` 单行（多序列图例），`large` 堆叠大数值——多个 `large` 并排即组成仪表卡的指标带。`loading` 渲染骨架占位；挂了 `click` 监听时它会渲染成原生 `button`，回车/空格开箱可用。

### 图例项

:::TuffDemoWrapper{demo="ChartsLegendItemsDemo" code-lang="vue" title="small 单行 / 加载态" description="点击第一项切换第二项的 inactive 态。"}
---
code: |
  <script setup lang="ts">
  import { ChartPalette, TxChartLegendItem } from '@talex-touch/tuffex/charts'
  import { ref } from 'vue'

  const inactive = ref(false)
  </script>

  <template>
    <TxChartLegendItem name="Requests" :color="ChartPalette.categoricalVar(0)" value="1,234" @click="inactive = !inactive" />
    <TxChartLegendItem name="Errors" :color="ChartPalette.categoricalVar(2)" value="87" :inactive="inactive" />
    <TxChartLegendItem loading />
  </template>
---
:::

### 仪表指标带

四个 `large` 图例项并排就是仪表卡的指标带：上方是色点加名称，下方是数值与单位，列与列之间用发丝线分隔，整条指标带铺满卡片宽度。它下面可以接任意图表——这里是四序列 `TxTimeseriesChart`，悬停即可读出同一时间戳上的四个百分位。

:::TuffDemoWrapper{demo="ChartsLegendDashboardDemo" code-lang="vue" title="仪表卡中的 large 指标行" description="把鼠标移到图表上：tooltip 会列出该时间戳下全部百分位。"}
---
code: |
  <script setup lang="ts">
  import { ChartPalette, TxChartLegendItem, TxTimeseriesChart } from '@talex-touch/tuffex/charts'

  const percentiles = [
    { name: 'P99', reading: '124', slot: 0 },
    { name: 'P95', reading: '76', slot: 1 },
    { name: 'P75', reading: '32', slot: 2 },
    { name: 'P50', reading: '10', slot: 3 },
  ]
  </script>

  <template>
    <div class="metrics">
      <div v-for="item in percentiles" :key="item.name" class="metrics__column">
        <TxChartLegendItem
          variant="large"
          :name="item.name"
          :color="ChartPalette.categoricalVar(item.slot)"
          :value="item.reading"
          unit="ms"
        />
      </div>
    </div>
    <TxTimeseriesChart
      :data="data"
      :height="300"
      x-axis-name="Time (UTC)"
      :x-axis-tick-format="formatTime"
      :timestamp-format="formatStamp"
      :tooltip-value-format="formatValue"
      tooltip-footer="Percentiles use a five-minute rolling window."
    />
  </template>
---
:::

## 与 kumo 的差异

- 没有 `echarts` 实例 prop——渲染层自研，调用方不需要也不能传 echarts。
- 没有 `isDarkMode` prop——取色全部走 `--tx-chart-*` CSS 变量，跟随宿主 `.dark` / `[data-theme='dark']` 自动切换。
- 所有 HTML 字符串 formatter 一律改为插槽（VNode），不存在 XSS 转义面。

## 概述

- 这些默认值抄自 kumo 锁定的 `echarts ^6.0.0`（`src/model/globalDefault.ts`，折线序列与 tooltip 另有各自的默认值）。
- 本包没有 ECharts 运行时，于是把它们固化成导出常量：`ENTER_DURATION`（1000）、`UPDATE_DURATION`（500）、`STATE_DURATION`（300）、`ANIMATION_THRESHOLD`（2000）。
- 宿主声明 `prefers-reduced-motion: reduce` 时所有动画直接落到终帧，CSS 过渡也整体包在 `@media (prefers-reduced-motion: no-preference)` 内。
- 各图表自己的入场与交互形态写在对应的图表页（Timeseries、Maps、Sankey、Custom Chart），这里不重复。
