一份定义跑通10大框架:TanStack Charts React/Vue/Svelte/Angular统一图表指南
一份定义跑通10大框架:TanStack Charts React/Vue/Svelte/Angular统一图表指南
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> 适配器组件,负责生命周期和响应式绑定。
核心概念:定义(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/。
服务端渲染(SSR)与响应式:开箱即用
跨框架一致性不只体现在 UI 上,SSR 行为也统一了:
- React / Vue / Svelte / Angular / Octane / Lit 等适配器在服务端直接输出完整 SVG,浏览器挂载后自动接管(hydration),无需二次重绘闪烁
- 响应式由
ResizeObserver驱动,图表默认跟随容器宽度;initialWidth为服务端和首帧提供确定性尺寸 - 交互层内置 tooltip、focus 引导、brush 选区、zoom 缩放等能力,且所有适配器行为一致
下图是同一份定义在不同图表族上的渲染结果之一(高级 tooltip 带总计行),官方用 benchmarks/conformance/ 目录下的合规用例对多种参考渲染器做了逐项验证:
打包体积:只用你 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/ 中与主流图表库做了等价的线/柱/面积/散点消费对比和大数据压力测试。
想多看几张图?这里有 70 张参考渲染
仓库内置了一套 shadcn 风格的参考渲染目录,覆盖面积、折线、柱状、饼图、雷达等几乎所有图表族,可直接当"能力菜单"浏览:
- 参考渲染图目录:benchmarks/conformance/shadcn/reference/
- 示例合集索引:docs/examples/index.md
- 框架示例工程:examples/charts-react/、examples/charts-octane/、examples/charts-expo/
- 项目总览与文档导航:README.md、llms.txt
总结:统一图表的正确打开方式
| 你关心的 | TanStack Charts 的答案 |
|---|---|
| 多框架一致性 | 一份 defineChart() 定义,10 个框架适配器直接复用 |
| 数据模型 | marks 直接吃原始数组/对象,无中间层 |
| 高级能力 | 原生 D3 工厂函数按同一比例尺契约无缝传入 |
| SSR 与响应式 | 各框架统一输出/接管 SVG,ResizeObserver 自适应 |
| 体积 | 全子路径精确 import,按需摇树,可切 Canvas |
如果你受够了"每个框架一套图表库"的重复劳动,TanStack Charts 的这套「语法化定义 + 薄框架适配器」模型值得一试:安装 @tanstack/charts 一次,从 docs/quick-start.md 开始,10 分钟就能让同一张图出现在你的所有前端项目里。




