一份定义跑通10大框架:TanStack Charts React/Vue/Svelte/Angular统一图表指南

原创2026-10-25 10:18:531,767 阅读

一份定义跑通10大框架:TanStack Charts React/Vue/Svelte/Angular统一图表指南

TanStack Charts 多序列折线图渲染效果

TanStack Charts 是一款用 TypeScript 编写的可视化图表库:你只需写一份图表定义,就能在 React、Vue、Svelte、Angular 等 10 种前端框架中渲染出同一张响应式、可访问、支持服务端渲染的图表。它基于细粒度的 D3 原语构建,让"统一图表"从口号变成了日常开发体验。

为什么需要"一份定义,多框架运行"的图表库?

很多团队同时维护多个前端项目:管理后台是 Vue,官网是 React,营销页用 Svelte,移动端用 React Native。传统做法是每个框架各配一套图表库(Recharts、ECharts、Chart.js……),结果是:

  • 数据模型不统一:同一份数据要写 3 遍不同的配置
  • 交互行为不一致:tooltip、缩放、选区在不同库里手感完全不同
  • 学习成本高:团队要同时熟悉多套 API

TanStack Charts 的解法很直接:把图表定义(definition)与框架彻底解耦。定义部分(数据、marks、scales、tooltip)是纯 TypeScript、与任何 UI 框架无关;框架侧只提供一个薄薄的 <Chart> 适配器组件,负责生命周期和响应式绑定。

TanStack Charts 堆叠柱状图与图例渲染效果

核心概念:定义(Definition)就是全部

整个库的核心心智只有一个函数:defineChart()。你描述"用什么 mark 画什么数据、轴怎么配",库负责响应式布局、坐标边距、主题、交互、动画和无障碍,最后把结果交给宿主框架渲染。

最小示例(官方快速上手见 docs/quick-start.md):

const revenueChart = defineChart({
  marks: [
    barY(revenue, { x: 'month', y: 'value' }),
  ],
  scales: {
    x: { scale: () => scaleBand().padding(0.2) },
    y: { scale: scaleLinear, nice: true, grid: true, axis: { label: 'Revenue' } },
  },
  tooltip,
})

注意两点:

  • 数据保持原样:marks 直接消费数组、对象、元组,不做中间 dataframe
  • 按需升级 D3:常用比例尺(linear、band、point、ordinal)用库内置的紧凑实现即可;需要时间轴、对数轴等高级能力时,直接传入原生 d3-scale 工厂函数

这套"从常用到自定义"的分层设计在 docs/concepts/grammar-of-graphics.md 中有完整讲解。

10 大框架适配器一览

同一份 revenueChart 定义,只替换适配器 import 即可切换宿主,官方兼容矩阵见 docs/installation.md:

框架 适配器入口 安装
React 18/19 @tanstack/charts/react pnpm add @tanstack/charts react react-dom
Vue ≥3.5 @tanstack/charts/vue pnpm add @tanstack/charts vue
Svelte 5 @tanstack/charts/svelte pnpm add @tanstack/charts svelte
Angular ≥19 @tanstack/charts/angular pnpm add @tanstack/charts @angular/core @angular/platform-browser
Solid ≥1.8 @tanstack/charts/solid pnpm add @tanstack/charts solid-js
Preact ≥10 @tanstack/charts/preact pnpm add @tanstack/charts preact
Lit ≥3.1.3 @tanstack/charts/lit pnpm add @tanstack/charts lit
Alpine ≥3.15 @tanstack/charts/alpine pnpm add @tanstack/charts alpinejs
Octane @tanstack/charts/octane pnpm add @tanstack/charts octane
原生 DOM mountChart()(包根入口) pnpm add @tanstack/charts

另有实验性的 React Native 适配器(@tanstack/charts/react-native),通过 react-native-svg 渲染,Expo 57 可直接安装使用。

各框架用法差异极小,举两个代表性写法:

React(适配器文档:docs/framework/react/adapter.md)

<Chart definition={revenueChart} height={320} ariaLabel="Monthly revenue" />

Vue(适配器文档:docs/framework/vue/adapter.md)

<script setup lang="ts">
import { Chart } from '@tanstack/charts/vue'
const definition = computed(() => defineChart({ ...revenueChart }))
</script>
<template>
  <Chart :definition="definition" aria-label="Revenue by month" />
</template>

Svelte 用 $derived、Angular 用单一 options 输入、Alpine 用 x-chart 指令——每个适配器都遵循"定义不变、只换绑定方式"的原则。各框架的完整适配文档在 docs/framework/ 下按框架分子目录组织,源码则分别在 packages/react-charts/、packages/vue-charts/、packages/angular-charts/ 等独立工作区包中,核心运行时统一放在 packages/charts-core/。

TanStack Charts 环形图(Donut)渲染效果

服务端渲染(SSR)与响应式:开箱即用

跨框架一致性不只体现在 UI 上,SSR 行为也统一了:

  • React / Vue / Svelte / Angular / Octane / Lit 等适配器在服务端直接输出完整 SVG,浏览器挂载后自动接管(hydration),无需二次重绘闪烁
  • 响应式由 ResizeObserver 驱动,图表默认跟随容器宽度;initialWidth 为服务端和首帧提供确定性尺寸
  • 交互层内置 tooltip、focus 引导、brush 选区、zoom 缩放等能力,且所有适配器行为一致

下图是同一份定义在不同图表族上的渲染结果之一(高级 tooltip 带总计行),官方用 benchmarks/conformance/ 目录下的合规用例对多种参考渲染器做了逐项验证:

TanStack Charts 带自定义格式与总计的 Tooltip 效果

打包体积:只用你 import 的东西

很多图表库"轻量"只是宣传语,TanStack Charts 的粒度是真实的:marks、transforms、布局、渲染器、交互各自有独立的子路径,打包器可以精确摇树。

import { scaleLinear } from '@tanstack/charts/scales/linear'
import { Chart } from '@tanstack/charts/react'
import { Chart as CanvasChart } from '@tanstack/charts/react/canvas'
  • 内置紧凑比例尺不带 D3 运行时依赖
  • 需要 D3 算法的能力(contour、force、sankey、hierarchy 等)走精确子路径,且只依赖对应的那个 d3-* 小模块,不会引入整个 d3 伞包
  • SVG 元素成为瓶颈时,可一行换成 Canvas 渲染器(/canvas 子路径),定义和宿主回调完全不动

官方在 benchmarks/bundle-size/ 中锁定了普通消费包的体积基线,并在 benchmarks/comparison/ 中与主流图表库做了等价的线/柱/面积/散点消费对比和大数据压力测试。

TanStack Charts 面积图默认渲染效果

想多看几张图?这里有 70 张参考渲染

仓库内置了一套 shadcn 风格的参考渲染目录,覆盖面积、折线、柱状、饼图、雷达等几乎所有图表族,可直接当"能力菜单"浏览:

总结:统一图表的正确打开方式

你关心的 TanStack Charts 的答案
多框架一致性 一份 defineChart() 定义,10 个框架适配器直接复用
数据模型 marks 直接吃原始数组/对象,无中间层
高级能力 原生 D3 工厂函数按同一比例尺契约无缝传入
SSR 与响应式 各框架统一输出/接管 SVG,ResizeObserver 自适应
体积 全子路径精确 import,按需摇树,可切 Canvas

如果你受够了"每个框架一套图表库"的重复劳动,TanStack Charts 的这套「语法化定义 + 薄框架适配器」模型值得一试:安装 @tanstack/charts 一次,从 docs/quick-start.md 开始,10 分钟就能让同一张图出现在你的所有前端项目里。

登录后查看全文
charts