tanstack-charts

TanStack Charts

在涉及 TanStack Charts 的工作中使用此技能，尤其是标记组合、转换、scales 注册表、紧凑型与 D3 比例尺、React Chart、SSR、工具提示／焦点、Canvas、可选的 motion()、React Native、空间／层级／网络条目或迁移。

将此库视为 Alpha（技能刷新时为 0.18.0；自 0.16.0 起正式进入 Alpha）。Alpha 版本适用于评估和早期集成：次要版本可能会破坏 API，因此请锁定确切版本。依赖边缘 API 前，请核实当前文档和 npm latest 版本。优先查阅 GitHub 标签 v0.18.0 的文档，不要依赖过时的搜索结果、使用根级 x／y 的 Alpha 前代码片段或已归档的 react-charts。

工作流

1. 确认技术栈使用的是统一软件包中的新版 TanStack Charts：
   • 正确：使用 bun add @tanstack/charts 和框架 peer 依赖。从 @tanstack/charts/react 导入 Chart，从 @tanstack/charts/scales/linear（以及 /band、/point、/ordinal）导入比例尺。
   • 仅用于兼容：@tanstack/react-charts、@tanstack/charts-scales 和其他 @tanstack/*-charts 适配器软件包仍然存在，供现有应用使用。不要在新代码中添加它们。
   • 错误：未限定作用域的 react-charts，或 options／primaryAxis／secondaryAxes／UserSerie。
2. 从 source-map.md 刷新版本和 URL。
3. 安装、defineChart、scales 注册表、命名比例尺／多个坐标轴、坐标轴和参考线样式、图例、工具提示扩展：setup-core.md。
4. 标记、柱形圆角、decorative、各标记的 Canvas、极坐标／地理、组合图：marks-composition.md。
5. 立即执行的转换与标记布局：transforms-layouts.md。
6. 适配器、尺寸设置、焦点、十字准线、刷选／缩放／光标／选择、动画、SSR：frameworks-interaction.md。
7. Alpha 稳定性、破坏性迁移（根级比例尺迁移到 scales）、测试、大型数据、Canvas、自定义标记、AI 检查：production-patterns.md。

实现判断

• 图表是标记的组合，而不是图表类型组件。优先选择能够回答问题的最小标记集。
• 保持数据行的自然形态。不要臆造由库定义的系列封装。
• 只安装一个包：@tanstack/charts。精简版 scales：使用精确的 @tanstack/charts/scales/*（不使用 /scales 汇总入口）。应用源码使用的每个 d3-* 都要导入并声明。对于推断的域，传入工厂；对于固定的域，传入已配置的实例。切勿为图表管理的位置 scales 指定像素范围。
• 将位置 scales 放在 scales 注册表中：每个定义都必须包含 scales: { x, y }（未使用的维度设为 null），极坐标视图使用 polar({ scales: { angle, radius } })。根级的 x / y / angle / radius 已在 0.16.0 中移除。只有在确实需要第二坐标轴时，才添加命名 scales（channel、side）以及标记的 xScale / yScale。
• 坐标轴呈现设置位于 axis / axis.ticks / axis.tickLabels 下。axis: false 会隐藏辅助线并保留 scale。只有在没有标记使用该维度时，才将 scales 条目设为 null。
• 针对每个捕获的值，对完整的 defineChart(...) 进行记忆化。定义的标识就是更新边界。响应式 { chart: ({ width }) => …, svgAnimation, tooltip, … } 会保留外层选项。
• 默认 SVG 动画选项是 svgAnimation，不是 animate。motion() 会忽略 svgAnimation，读取定义级别的 motion。
• 只有一个长度通道的条形图/面积图会隐式堆叠。并排条形图使用 layout: group()；仅在必须显式指定顺序/偏移时使用 layout: stack({ order, offset })；y1/y2 或 x1/x2 则会退出堆叠。
• 原生工具提示：使用 @tanstack/charts/tooltip 中的 tooltip。使用 @tanstack/charts/tooltip/portal 中的 portal 可避免裁剪。React renderTooltipBody 需要 @tanstack/charts/react/tooltip。分组行默认按标记的视觉顺序排列。
• 通道和变换访问器使用 (datum, { index, data })，而不是 (datum, index, data)。
• 滚动变换：使用 rollingWindow，而不是 window。归约辅助函数：使用 delta，而不是 difference。
• 每个已挂载的图表都要提供 ariaLabel。使用 focus: false 省略生成的焦点几何图形；当自定义焦点标记取代焦点环时使用 focusRing: false；当应用手势拥有该表面时使用 focusDisabled。径向分组焦点：使用 @tanstack/charts/polar 中的 focusGroupAngle。
• 默认使用 SVG。对于绘制负载较重的图层，为这些标记附加 renderer: canvasChartRenderer，而不是切换整个图表。只有通过精确子路径导入 polar、geo、Canvas、export、motion、spatial、hierarchy、network、brush/zoom。
• 优先使用内置标记（boxY、waffleY、violinY、复合标记），而不是 createMark。如果只有一个图层应负责命中测试，则使用 decorative(...) 包装同级图层。

验证

优先使用仓库现有的检查。对于有实质意义的 Charts 工作，包含相关的检查子集：

• 包检查：@tanstack/charts 固定为精确的 0.18.x（或项目固定的版本）。新代码从该包导入适配器/scales，而不是从 @tanstack/react-charts / @tanstack/charts-scales 导入。定义使用 scales.x / scales.y。
• 对通道、scales、坐标轴选项、工具提示宿主品牌、motion、ChartPoint 回调进行类型检查——不得出现意外类型转换。
• 使用 createChartScene / renderChartSvg 检查域、几何图形、键、无障碍标记。
• 交互测试：焦点、键盘、工具提示、选择、brush/zoom、调整大小、空数据、销毁。
• 当主题令牌或工具提示表面 CSS 更改时，进行浅色/深色模式冒烟测试。
• 对 initialWidth、格式化器、Canvas 外壳、idPrefix 进行 SSR/水合冒烟测试。
• 添加 polar、geo、Canvas、export、motion、spatial、hierarchy、network 或额外的 D3 模块时，测量 bundle。