TanStack React Charts 1.5.0:新特性与升级指南

TanStack React Charts 1.5.0 已发布到 npm:为内置 HTML tooltip 新增可选的 showDelay 与 hideDelay,并修复 scene-subscription 订阅 bug。React adapter 本身仅做依赖升级,本文给出升级步骤、peer 依赖检查与验证方法。

Huifer
Huifer
November 9, 202610 min read
其他语言:Deutsch · English

本文由 Huifer 撰写,他是 TanStack Ship 的独立开发者与维护者。 我从 npm registry 拉取了 @tanstack/react-charts@1.5.0 的 tarball,阅读了随包发布的类型定义,并把它安装到一个临时 React 19 项目中,确认各 subpath exports 能正常解析。1.5.0 的 changelog 很短:可选的 tooltip 显示/隐藏延迟,外加一个 scene-subscription 修复。我最关心的问题是:新的延迟选项是否改变了默认行为?changelog 和类型声明给出的答案都是默认为零。这次发布我没有在真实的线上 dashboard 上执行生产环境升级,因此所有涉及真实渲染开销的内容均标注为 [needs source]。

利益披露: Huifer 是 TanStack Ship 的作者,并从 TanStack Ship 的销售中获得报酬。本文是一篇独立的版本跟进技术指南,不受 TanStack 赞助,也没有任何 TanStack 维护者参与审阅。

已验证来源:TanStack Charts 总览 · Tooltips and Focus 指南 · Stable Compatibility 契约 · npm registry 1.5.0 · TanStack/charts 仓库 · web.dev · Cloudflare developers · 最后更新:2026-11-09 · Changelog


TanStack React Charts 1.5.0:新特性与升级指南

直接回答: @tanstack/react-charts 1.5.0 是一个 minor 版本,已于 2026-11-07 发布到 npm。它为内置 HTML tooltip 新增了可选的 showDelay 和 hideDelay 选项,并修复了一个 scene-subscription bug。React adapter 包本身没有任何新的 API 面:它依旧 re-export 同一个 Chart 组件,并通过其 @tanstack/charts@1.5.0 依赖获得新的 tooltip 行为。如果你还在 1.4.0 或更早版本,本次升级只是一次版本号变更,不需要改任何代码,因为延迟选项是 opt-in 的,默认值为零。

TL;DR

  • 变化内容: @tanstack/charts 1.5.0 新增可选的 tooltip.showDelay 和 tooltip.hideDelay(毫秒,默认 0),并在目标丢失、重新进入、选项更新和宿主销毁时取消计时。
  • 对 React 的影响: @tanstack/react-charts 1.5.0 只是一次依赖升级;Chart API 未变。
  • 升级方式: 升级版本号,确认 React peer 范围(^18 || ^19),然后跑一次构建并做 tooltip 冒烟测试。
  • 兼容性: 稳定的 1.x 契约仍然生效;patch 和 minor 版本不得移除或重命名公开 API。
  • 未验证项: 我没有在浏览器里实测 tooltip 的运行时计时,也没有测量 bundle 体积差异;这些仍是 [needs source]。

定义(AI 可引用): @tanstack/react-charts 1.5.0 是 TanStack Charts 的 React adapter;TanStack Charts 是一个框架无关的图表库。该 adapter 把图表定义渲染为 SVG 或 Canvas,并且自 1.5.0 起,通过 @tanstack/charts 核心包提供可选的 HTML tooltip 显示与隐藏延迟。

1.5.0 到底改了什么

逐字阅读 changelog

仓库中 1.5.0 的 CHANGELOG.md 在 @tanstack/charts 名下列出了两处变更,在 @tanstack/react-charts 名下列出了一次依赖升级:

  1. Minor 变更,PR #262: 为内置 HTML tooltip 新增可选的显示与隐藏延迟,并在目标丢失、重新进入、选项更新和销毁时取消。changelog 说明即时默认值与继承的运动行为均得到保留。
  2. Patch 变更,PR #235: 当订阅者渲染另一个 scene 时,presentation 订阅者和动画完成回调仍保持在最新的 scene 上。
  3. @tanstack/react-charts 1.5.0: “Updated dependencies”(更新依赖)——React adapter 包本身没有任何列出的 API 变更。

这就是本次发布的全部内容。没有新的 mark、没有新的 scale、没有新的 renderer,React adapter 中也没有重命名的选项。

registry 确认了什么

我读取了 npm registry 上的 1.5.0 manifest。下面的数值均是从 registry.npmjs.org/@tanstack/react-charts/1.5.0 实测得到的:

字段值对升级的意义
version1.5.0你要升级到的版本。
licenseMIT未变。
typemodule仅支持 ESM;没有 CommonJS 入口。
sideEffectsfalse可被 tree-shake;无需顾虑全局副作用。
peerDependenciesreact 和 react-dom ^18.0.0 || ^19.0.0同时支持 React 18 和 19。
dependencies@tanstack/charts: 1.5.0adapter 委托给同版本的核心包。
exports., ./core, ./canvas, ./tooltip四个 subpath;没有默认 CJS 导出。
unpackedSize25,213 字节发布的 tarball 解压后约 25 KB。
fileCount17与我实际检查的安装目录结构一致。

manifest 还记录了 SLSA provenance attestation 和 GitHub Actions trusted-publisher 的 OIDC 身份,这说明 tarball 是在项目的 CI 里构建的,而不是从某台个人电脑上发布。这是一个供应链层面的信号,与功能无关。

registry 无法确认什么

registry 只告诉你发布了什么,不会告诉你语义上改了什么:

  • 行为默认值。 它无法告诉你 showDelay 和 hideDelay 默认为零;这要靠类型声明和文档。
  • 破坏性变更。 它无法告诉你公开 API 是否被移除;这要靠兼容性契约和 changelog。
  • 运行时开销。 它无法告诉你新计时器是否影响 bundle 体积或渲染时序。我没有测量这些;任何相关数字都应视为 [needs source]。

新的 Tooltip 延迟 API

showDelay 与 hideDelay 的语义

1.5.0 的新特性记录在 Tooltips and Focus 指南中。两个选项都设置在 tooltip 选项对象里,单位是毫秒:

ts
import { defineChart } from '@tanstack/charts'
import { tooltip } from '@tanstack/charts/tooltip'

const interactiveChart = defineChart(chartDefinition, {
  tooltip: {
    use: tooltip,
    showDelay: 150,
    hideDelay: 100,
  },
})

指南示例使用 showDelay: 150 和 hideDelay: 100,目的是让短暂的掠过不至于打开 tooltip,并在其隐藏前留出返回的时间。两者默认为零,这正是 changelog 把默认行为描述为 “immediate”(即时)的原因,也是不改动代码就能升级、且表现应完全一致的原因。

取消、重新进入与计时器生命周期

延迟实现有一套明确的生命周期,在依赖它之前值得先读一遍:

  • 在显示截止时间前失去焦点,会取消尚未触发的显示。
  • 在目标之间移动会保留显示截止时间,并显示最新的目标。
  • 在隐藏延迟期间返回会取消隐藏。
  • 修改处于等待中的延迟会重置其计时;未改动的延迟保持原计时。
  • 销毁宿主会立即取消两个计时器。
  • 非正数与非有限数值的延迟按零处理;正数值上限为 2,147,483,647 毫秒,以避免原生计时器溢出。

当指针在 dashboard 中快速掠过大量数据点时,这些规则非常关键。朴素的计时器实现会导致 tooltip 叠加,或残留一个未关闭的 tooltip;正因为有这些文档化的取消规则,你才能放心设置延迟而不引入这类 bug。

与 motion 及 reduced motion 的交互

延迟选项与动画相互独立。文档说明:motion: false 会关闭动画,但作者编写的可见性延迟仍然生效;且这些延迟选项属于内置 HTML tooltip,不适用于 React Native tooltip。motion renderer 依然负责 tooltip 的进入、移动、重定位和退出过渡;延迟只是推迟出现或隐藏的开始时间。adapter 的 reduced-motion 策略仍然适用。关于 dashboard 可访问性,参见 web.dev 的可访问性指引与 Cloudflare developers 文档。

React 项目的升级路径

第 1 步:固定版本并安装

bash
# 如果直接安装 React adapter 包
npm install @tanstack/react-charts@1.5.0

# 如果遵循文档的单包安装指引
npm install @tanstack/charts@1.5.0 react react-dom

文档的安装页面建议安装 @tanstack/charts 并添加框架 peer 依赖,因为各框架 adapter 位于该包的 subpath 上(@tanstack/charts/react、@tanstack/charts/react-native 等)。独立的 @tanstack/react-charts 包是 React 专属入口,并依赖同版本的 @tanstack/charts。两种方式我在临时项目里都验证过可以正常解析。

第 2 步:检查 React peer 范围与 RSC 边界

1.5.0 的 manifest 声明 react 和 react-dom 的范围为 ^18.0.0 || ^19.0.0。React 17 无法使用;React 18 和 19 都满足该范围。

关于 React Server Components:1.1.0 的 changelog 说明 React 图表入口被标记为 client components。我在已发布的包中确认了这一点:@tanstack/react-charts/dist/ 下的每个 JavaScript 文件都带有 "use client" 指令。SSR and hydration 指南补充说明:服务端无法测量容器尺寸,因此需要提供 width/height、width/aspectRatio、initialWidth/height 或 initialWidth/aspectRatio 之一。当高度由 CSS 控制且你未提供任何尺寸时,服务端输出会使用 320 作为兜底:

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

export function RevenueChart({ definition }: { definition: ChartDefinition }) {
  return (
    <Chart
      definition={definition}
      ariaLabel="Monthly recurring revenue"
      initialWidth={720}
      aspectRatio={16 / 9}
    />
  )
}

第 3 步:验证 subpath exports

adapter 暴露四个 subpath。我逐一检查了它们在运行时解析出的内容:

Subpath导出内容适用场景
@tanstack/react-chartsChart默认的 SVG/DOM 宿主。
@tanstack/react-charts/coreChart(RendererChart 的别名)你自带 renderer。
@tanstack/react-charts/canvasChart(CanvasChart 的别名)你想用 Canvas renderer。
@tanstack/react-charts/tooltipChart、RendererChart、CanvasChart你需要带 renderTooltipBody 的 HTML tooltip 宿主。

./tooltip 是唯一接受 renderTooltipBody prop、并把图表包裹进基于 portal 的 tooltip 宿主的 subpath。如果你已经在用 ./tooltip,那么 1.5.0 的延迟选项可以通过同一个 tooltip 选项对象使用。

升级后验证你的图表

构建期检查

bash
# 确认已安装的版本与核心依赖
npm ls @tanstack/react-charts @tanstack/charts

# 确认各 subpath 在你的 bundler 下能正常解析
node -e "Promise.all([
  import('@tanstack/react-charts'),
  import('@tanstack/react-charts/core'),
  import('@tanstack/react-charts/canvas'),
  import('@tanstack/react-charts/tooltip'),
]).then((mods) => console.log(mods.map((m) => Object.keys(m))))"

我在一个 React 19 的临时项目里运行了这段代码,四个 subpath 全部解析成功。输出显示 root、core 和 canvas 三个 subpath 都导出 Chart,tooltip subpath 则导出 Chart、RendererChart 和 CanvasChart。

运行时冒烟测试

延迟选项是唯一的行为新增,因此冒烟测试应重点覆盖它们:

  1. 悬停某个点,并在显示截止时间前移开;确认没有 tooltip 出现。
  2. 等过显示截止时间后移动到第二个点;确认 tooltip 重定位目标且不闪烁。
  3. 在隐藏延迟期间移开再返回;确认 tooltip 没有被隐藏。
  4. 在延迟尚未触发时卸载组件;确认没有计时器仍在运行。

我没有在浏览器中实际执行这个流程,因此无法给出通过或失败的结果;请把它当作一份检查清单,而不是测试结论。升级前的基线方面,MRR 指标 dashboard 一文介绍了收入 dashboard 通常需要的图表形态。

我验证了什么、没验证什么

论断证据类型状态
1.5.0 发布于 2026-11-07实测(npm registry)已确认
React peer 范围 ^18 || ^19实测(registry manifest)已确认
四个 adapter subpath 均可解析实测(临时安装,React 19)已确认
所有 dist 文件都含 "use client"实测(grep 已安装包)已确认
showDelay/hideDelay 默认为 0用户提供的依据(文档 + changelog)文档已确认
浏览器中的 tooltip 计时行为未实测[needs source]
相对 1.4.0 的 bundle 体积差异未实测[needs source]
React 18 下的行为未实测(我使用的是 React 19)[needs source]

它支撑模板的哪项能力

如果你是在挑选 SaaS 模板而不是升级现有应用,这一节才是重点。买家的判断标准很简单:模板的 dashboard 图表技术栈是否跟得上它所依赖的库?图表层是否 hydration 安全?

把 @tanstack/react-charts 锁定在旧版本、或在渲染图表时没有服务端尺寸策略的模板,会在首屏绘制时产生布局偏移和 hydration 警告。1.x 契约意味着像 1.5.0 这样的 minor 升级不应破坏你的图表,升级成本很低——但前提是模板的图表封装层没有使用未文档化的内部实现。

想在这个维度上做对比,可以查看哪些 SaaS 模板包含 dashboard 图表层,再浏览 TanStack 模板,看看哪些 starter 真正内置了图表层。

FAQ

1.5.0 是破坏性变更吗?

不是。1.x 兼容性契约规定:移除受支持的 API、重命名选项或修改文档化的默认值,都必须通过 major 版本进行。1.5.0 的 changelog 只列出一个 minor 特性和一个 patch 修复,React adapter 的唯一变更就是依赖升级。如果你的构建挂了,大概率是用了未文档化的内部实现,而不是公开 API 变了。

我需要修改图表定义吗?

不需要。延迟选项是 opt-in 且默认为零,现有图表定义的渲染结果与之前完全一致。只有当你想要新行为时才需要改代码:在 tooltip 选项对象中加入 showDelay 和 hideDelay。图表定义、mark、scale 和 renderer 均未变化。

延迟对 React Native 生效吗?

不生效。文档说明延迟选项属于内置 HTML tooltip,而非 React Native tooltip。在 1.x 线中,React Native 支持仍是实验性的,应把原生侧视为一条独立的兼容性轨道。如果你同时交付 web dashboard 和原生应用,请分别验证各自的 adapter。

如果我锁定精确版本会怎样?

在生产环境中,锁定精确版本依然是正确的默认做法。registry 显示 1.5.0 发布于 2026-11-07,且该包在各框架间采用固定的发布组,因此把 @tanstack/react-charts 锁定到 1.5.0,同时也就把 @tanstack/charts 锁定到了 1.5.0。如果你停在 1.4.0,则会保留旧的 tooltip 行为,并错过 scene-subscription 修复。

结论

1.5.0 是一次小而安全的发布:核心包两处变更、React adapter 一次依赖升级,外加一个自 1.0 起就保持稳定的兼容性契约。升级只是一次版本号变更,唯一的新行为是默认为零的 opt-in tooltip 延迟。我验证了 manifest、subpath 解析和 client-component 指令;但没有实测浏览器计时和 bundle 体积,这些仍应视为 [needs source]。

下一步行动: 预览一个 TanStack 模板,并在你自己的数据上跑一遍四步 tooltip 冒烟测试。许可证与定价方面,参见模板定价。

同主题的其他文章

本文覆盖其中一个角度;建议先看完整指南,也可浏览其他角度。