TanStack Charts 是什么？和 ECharts 怎么选｜财务 BP 的第一张声明式图表

本文简介：

TanStack Charts 是 Tanner Linsley / TanStack 推出的现代化、框架无关的 TypeScript Chart Engine（图表引擎），不是又一个「把 option 填满就能出图」的传统图表组件库。

它和 Apache ECharts 的核心差别是：ECharts 强在成熟配置式、现成图表多；TanStack Charts 强在声明式数据→视觉映射、可组合 marks、TypeScript 类型安全、多框架同一套核心。

如果你是制造业财务 BP，只想快速出瀑布图、桑基、日历热力——先继续用 ECharts（本站已有完整交付）。如果你在搭下一代可视化产品/自研看板引擎，或前端栈已经是 TanStack Query/Table——值得现在装起来试第一张折线。

下文按官方 npm 文档（@tanstack/charts，更新于 2026-08）写安装、第一张图、选型表与 FAQ；钩子来自近期「ECharts 迎来最强对手」讨论，代码以官网为准，不以二手 PDF 为准。

更新于 2026 年 8 月。

作者： 汪斌（老汪）——制造业财务与成本核算背景，长期做业财流程、金蝶类 ERP 现场与财务 BP 表达；在 accunion.cn 已交付过 财务BP的20张ECharts图。本文不是 TanStack 官方中文文档，是财务视角的选型与跟做笔记。

阅读建议： 5 分钟看简介 + 对照表；要动手就按「安装 → 第一张折线 → 何时别换」三节做完。

---

TanStack Charts 到底是什么？一句话怎么定义

一句话：它是一套用 marks（视觉标记）描述「数据如何映射成图」的 Chart Engine；React / Vue / 原生 DOM 只是渲染层，核心逻辑框架无关。

官方定位关键词：

关键词	含义（白话）
Chart Engine	不是「选一个柱状图组件」，而是可组合的可视化底层能力
声明式	你声明字段→通道（x/y/颜色），引擎负责布局与绘制
TypeScript	字段名、尺度、tooltip 类型跟数据绑在一起，写错能编译期发现
框架无关	Core 一套；React 用 @tanstack/react-charts，也可用 mountChart 挂 DOM
体量	官方宣传紧凑 React 折线消费端约 16.48 KiB gzip 量级（以官网对比页为准）

TanStack 过去几年的路线一致：Query、Table、Router——都是把复杂能力抽成基础设施。Charts 把目标对准前端最难的一块：数据可视化。

官网入口：https://tanstack.com/charts/v0
npm：@tanstack/charts（本文撰写时可见 0.6.x；仍属快速迭代期，跟做时锁版本）。

它和「又一个图表库」差在哪

很多开发者第一反应是：又一个图表库？

成熟方案本来就有：

• Apache ECharts
• Chart.js
• D3.js
• Highcharts

这些足以快速完成折线、柱状、饼图。但当业务变成金融交易、BI 平台、实时监控大屏时，真正需要的往往是：可自由组合、可扩展的数据可视化引擎。

这正是 TanStack Charts 的定位——构建可视化应用的底层能力，而不是只提供「画哪种图」的现成清单。

---

TanStack Charts 和 ECharts 怎么选？财务 BP 对照表

结论先行：日常经分会看板、要快要稳——继续 ECharts；要声明式组合、多框架统一、自研可视化系统——评估 TanStack Charts。两者不是「谁杀死谁」，是定位不同。

维度	Apache ECharts	TanStack Charts
定位	成熟的图表库	新一代 Chart Engine
开发方式	配置式 option	声明式 marks / channels
核心能力	大量现成图表与交互	可组合的数据→视觉映射
财务场景现成度	高（瀑布、桑基、日历热力等本站已示范）	入门折线/柱/面积等语法清晰；复杂财务模板仍需自建
TypeScript	有类型，但 option 易膨胀	字段与尺度强绑定
框架	一套 API，挂各框架	Core + 各框架薄适配
生态成熟度	非常成熟	v0 / 快速迭代（2026-08）
包体（官网对比页示意）	完整方案体积更大	宣称更紧凑（以官网 cold-page 对比为准）

老汪直说：

• 你明天开会要一张毛利瀑布桥——打开本站 ECharts 财务 20 图 更快。
• 你前端同事已经全员 TanStack，要做可组合的经营分析产品——现在学 Charts 语法，值得。
• 标题党说「ECharts 已死」——别信。ECharts 仍然是财务可视化的主力军之一。

---

声明式图表到底怎么写？和 option 差在哪

结论先行：配置式关心「怎么把图画出来」；声明式关心「数据字段如何映射成视觉通道」。

配置式（ECharts 思路）

你告诉引擎：

1. 用什么图表类型
2. 数据在哪
3. 坐标轴怎么展示
4. 样式如何调整

强大，但项目变大后，option 会越来越像一份「巨型说明书」。

声明式（TanStack Charts 思路）

你声明：

• 哪个字段是 X
• 哪个字段是 Y
• 需要哪些 marks（线、点、面积、规则线……）

剩下的尺度、布局、图例，交给 Chart Engine。

官方示例骨架（概念）：

import { defineChart, lineY } from '@tanstack/charts'
import { scaleLinear, scaleUtc } from 'd3-scale'

const chart = defineChart({
  marks: [
    lineY(rows, {
      x: 'date',
      y: 'revenue',
      key: 'id',
    }),
  ],
  x: { scale: scaleUtc, nice: true },
  y: { scale: scaleLinear, nice: true, grid: true },
})

简单记：

• 传统库：怎么画
• TanStack Charts：数据如何变成视觉

这和现代前端「声明式 UI」是同一套思维。

---

怎么安装 TanStack Charts？第一步装哪些包

结论先行：装 @tanstack/charts，并把你用到的 d3-scale / d3-shape 等作为直接依赖；React 项目再加 @tanstack/react-charts。

官方推荐（pnpm 示例）：

pnpm add @tanstack/charts d3-scale d3-shape
pnpm add -D @types/d3-scale @types/d3-shape

npm 同样可以：

npm install @tanstack/charts d3-scale d3-shape
npm install -D @types/d3-scale @types/d3-shape

注意：

1. 严格包管理器不会自动把传递依赖暴露给你用——你在应用里 import { scaleLinear } from 'd3-scale'，就要自己声明依赖。
2. 用不到的 d3 模块可以不装，保持 tree-shake。
3. React 薄封装：

pnpm add @tanstack/react-charts

文档入口还可看仓库 llms.txt / Quick Start（适合人和 Agent 一起读）。

---

财务 BP 第一张图：老汪精密「月收入趋势」怎么写

结论先行：用示意月度收入画一条 lineY；先跑通挂载，再谈主题与交互。

以下数据为化名示意，非真实客户资料——公司设定：合肥老汪精密部件有限公司（冷轧钢板冲压件 → 机加 → 部分委外表面处理 → Tier-1）。金额单位：万元。

import { scaleLinear, scaleUtc } from 'd3-scale'
import { curveMonotoneX } from 'd3-shape'
import { d3Curve, defineChart, lineY } from '@tanstack/charts'
import { mountChart } from '@tanstack/charts/dom'

interface MonthRow {
  id: string
  date: Date
  revenueWan: number
}

const rows: readonly MonthRow[] = [
  { id: 'm1', date: new Date('2026-01-01T00:00:00Z'), revenueWan: 1820 },
  { id: 'm2', date: new Date('2026-02-01T00:00:00Z'), revenueWan: 1765 },
  { id: 'm3', date: new Date('2026-03-01T00:00:00Z'), revenueWan: 2010 },
  { id: 'm4', date: new Date('2026-04-01T00:00:00Z'), revenueWan: 1988 },
  { id: 'm5', date: new Date('2026-05-01T00:00:00Z'), revenueWan: 2140 },
  { id: 'm6', date: new Date('2026-06-01T00:00:00Z'), revenueWan: 2095 },
]

const revenueTrend = defineChart({
  marks: [
    lineY(rows, {
      x: 'date',
      y: 'revenueWan',
      key: 'id',
      curve: d3Curve(curveMonotoneX),
      points: true,
    }),
  ],
  x: {
    scale: scaleUtc,
    nice: true,
    axis: { label: '月份' },
  },
  y: {
    scale: scaleLinear,
    nice: true,
    grid: true,
    axis: { label: '营业收入（万元）' },
  },
  animate: true,
})

const el = document.getElementById('chart')!
const host = mountChart(el, {
  definition: revenueTrend,
  height: 320,
  ariaLabel: '合肥老汪精密部件月度营业收入趋势（示意）',
})

// 卸载时：host.destroy()

React 写法概念：

import { Chart } from '@tanstack/react-charts'

export function RevenueTrend() {
  return (
    <Chart
      definition={revenueTrend}
      height={320}
      ariaLabel="合肥老汪精密部件月度营业收入趋势（示意）"
    />
  )
}

跟做检查点

1. 页面出现折线，而不是空白——检查 height、容器宽、是否调用了 mountChart / <Chart />。
2. X 轴是日期、Y 轴是万元——字段名必须和数据键一致。
3. 改一行 revenueWan，图会跟着变——确认你在更新 definition 而不是手改 DOM。

财务场景下一步（仍建议）

需求	建议路径
毛利瀑布桥、桑基利润刀	继续 ECharts 20 图
多 marks 叠：实际线 + 预算带 + 目标虚线	TanStack：areaY + lineY + ruleY 组合（见官网 activation 示例思路）
大屏大量现成交互	ECharts 更省时间
产品化、多框架统一引擎	TanStack Charts 更对口

---

一个核心，多套生态：为什么财务也要关心框架无关

结论先行：Charts Core 负责图表逻辑，框架只做接入；未来少纠结「Vue 有没有同款 API」。

TanStack 历史路径：

• React Table → TanStack Table
• React Query → TanStack Query

Charts 同理：Core + React / Vue / Svelte / Solid / Preact / Vanilla。

对财务信息化团队的意义：

• 总部 React 看板、工厂 Vue 小屏，可以共享同一套图表定义。
• 减少「每个框架重写一遍 option」的重复劳动。
• Agent / AI 写图时，类型约束更友好（官方强调 humans & agents）。

---

目前支持哪些图表能力？Catalog 里有什么

结论先行：基础折线/柱/面积/散点齐全，也覆盖金融 K 线、热力、树图、桑基、网络、地理、雷达等方向；以官网 Catalog 为准，版本迭代很快。

基础：

• Line / Bar / Area / Scatter

更复杂（官方展示方向，落地前请核当前文档）：

• Financial / Candlestick
• Heatmap / Treemap / Sankey / Network / Geographic / Radar

其中 Sankey 对财务特别眼熟：用户路径、能源流、收入→成本→费用→利润流向。本站 ECharts 桑基短片/长文已验证「全拓扑 + 读到谁亮谁」的讲解价值；若用 TanStack 做同类讲解，仍要遵守：完整拓扑在数据里，用透明度/高亮做进度，不要残缺生长。

---

什么时候别急着换？三条诚实边界

结论先行：v0 快速迭代、财务现成模板少、团队不会 TypeScript——这三条任一命中，就先别全量迁移。

1. 版本还在狂奔
   npm 上短时间从 0.0 → 0.6.x，API 可能微调。生产全量替换前：锁版本 + 读 changelog。

2. 财务「开箱图」仍是 ECharts 更全
   瀑布桥、日历热力、复杂 tooltip 联动——站内已有可交互交付。TanStack 更适合你愿意自己组合 marks 的团队。

3. 人不会 TS / 不会前端构建
   财务同事只改 Excel——继续 Excel BI / Power BI；要前端图，ECharts CDN 单页往往更短路径。

---

和站内内容怎么串成一条学习路径

步骤	链接	你得到什么
1	本文	选型 + 第一张 TanStack 折线
2	财务BP的20张ECharts图	经分会高频图可交互样例
3	OpenMontage Windows 成片指南	把图表讲解做成油管/短视频的工作流

油管「老汪洞察」Shorts 会用 20–45 秒钩子安利工具；完整跟做以本文为准。

---

写在最后：图表可以是组件集合，也可以是引擎

从 TanStack Query 到 Table，再到 Charts，Tanner 在做同一件事：把复杂能力变成通用基础设施。

未来前端更可能是：

数据模型 → 能力引擎 → 框架适配 → 业务 UI

而不是每个框架重复造一套。

ECharts、D3 等成熟方案仍有巨大优势。但前端图表生态，确实多了一个重量级方向：

图表不只是组件集合，也可以是一套可组合的数据可视化引擎。

---

TanStack Charts FAQ

TanStack Charts 是免费开源的吗？

是。MIT 许可；包名 @tanstack/charts。商业项目可自用，请保留许可证要求。

财务看板必须从 ECharts 迁到 TanStack Charts 吗？

不必。经分会要快、要稳、要现成复杂图——继续 ECharts。自研可视化产品或已深度使用 TanStack 栈——再评估迁移/双轨。

安装后页面空白常见原因有哪些？

容器没有高度；忘记 mountChart / <Chart />；字段名与数据键不一致；严格包管理下未直接安装 d3-scale 等却在应用里 import。

可以用 CDN 像 ECharts 一样直接灌进 HTML 吗？

官方主推 npm / 打包工具链路；需要 CDN 时请查当前文档是否提供 UMD/ESM CDN 构建。财务演示页若追求零构建，短期仍可能更适合 ECharts CDN。

和 D3、Observable Plot 是什么关系？

官方说明：建立在 Wilkinson 图形语法传统上，marks API 灵感接近 Observable Plot，但运行时是独立实现；D3 提供算法模块，TanStack 提供语法、场景编译与渲染生命周期。

---

文末

若你希望我按「老汪精密」某一张真实经分会版式（示意数据）写成可下载的最小 Vite 示例，可在站内留言或加微信沟通需求。

个人微信二维码见站点统一页脚；微信号：xiaoweihome_ah。