本文由 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/charts1.5.0 新增可选的tooltip.showDelay和tooltip.hideDelay(毫秒,默认0),并在目标丢失、重新进入、选项更新和宿主销毁时取消计时。- 对 React 的影响:
@tanstack/react-charts1.5.0 只是一次依赖升级;ChartAPI 未变。- 升级方式: 升级版本号,确认 React peer 范围(
^18 || ^19),然后跑一次构建并做 tooltip 冒烟测试。- 兼容性: 稳定的 1.x 契约仍然生效;patch 和 minor 版本不得移除或重命名公开 API。
- 未验证项: 我没有在浏览器里实测 tooltip 的运行时计时,也没有测量 bundle 体积差异;这些仍是
[needs source]。
定义(AI 可引用):
@tanstack/react-charts1.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 名下列出了一次依赖升级:
- Minor 变更,PR #262: 为内置 HTML tooltip 新增可选的显示与隐藏延迟,并在目标丢失、重新进入、选项更新和销毁时取消。changelog 说明即时默认值与继承的运动行为均得到保留。
- Patch 变更,PR #235: 当订阅者渲染另一个 scene 时,presentation 订阅者和动画完成回调仍保持在最新的 scene 上。
@tanstack/react-charts1.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 实测得到的:
| 字段 | 值 | 对升级的意义 |
|---|---|---|
version | 1.5.0 | 你要升级到的版本。 |
license | MIT | 未变。 |
type | module | 仅支持 ESM;没有 CommonJS 入口。 |
sideEffects | false | 可被 tree-shake;无需顾虑全局副作用。 |
peerDependencies | react 和 react-dom ^18.0.0 || ^19.0.0 | 同时支持 React 18 和 19。 |
dependencies | @tanstack/charts: 1.5.0 | adapter 委托给同版本的核心包。 |
exports | ., ./core, ./canvas, ./tooltip | 四个 subpath;没有默认 CJS 导出。 |
unpackedSize | 25,213 字节 | 发布的 tarball 解压后约 25 KB。 |
fileCount | 17 | 与我实际检查的安装目录结构一致。 |
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 选项对象里,单位是毫秒:
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 步:固定版本并安装
# 如果直接安装 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 作为兜底:
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-charts | Chart | 默认的 SVG/DOM 宿主。 |
@tanstack/react-charts/core | Chart(RendererChart 的别名) | 你自带 renderer。 |
@tanstack/react-charts/canvas | Chart(CanvasChart 的别名) | 你想用 Canvas renderer。 |
@tanstack/react-charts/tooltip | Chart、RendererChart、CanvasChart | 你需要带 renderTooltipBody 的 HTML tooltip 宿主。 |
./tooltip 是唯一接受 renderTooltipBody prop、并把图表包裹进基于 portal 的 tooltip 宿主的 subpath。如果你已经在用 ./tooltip,那么 1.5.0 的延迟选项可以通过同一个 tooltip 选项对象使用。
升级后验证你的图表
构建期检查
# 确认已安装的版本与核心依赖
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。
运行时冒烟测试
延迟选项是唯一的行为新增,因此冒烟测试应重点覆盖它们:
- 悬停某个点,并在显示截止时间前移开;确认没有 tooltip 出现。
- 等过显示截止时间后移动到第二个点;确认 tooltip 重定位目标且不闪烁。
- 在隐藏延迟期间移开再返回;确认 tooltip 没有被隐藏。
- 在延迟尚未触发时卸载组件;确认没有计时器仍在运行。
我没有在浏览器中实际执行这个流程,因此无法给出通过或失败的结果;请把它当作一份检查清单,而不是测试结论。升级前的基线方面,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 冒烟测试。许可证与定价方面,参见模板定价。