visx

visx

当工作涉及 Airbnb visx（@visx/*）时使用此技能，包括低级 React 可视化图元、@visx/xychart、交互包、专用布局或 v3→v4 迁移。

将 4.0.0 视为已发布的稳定版本线（支持 React 18/19）。优先使用包根目录导入、与已安装版本标签对应的图库沙盒，以及 GitHub/visx.airbnb.tech，不要采用过时的深层导入代码片段。4.1 的软件包（@visx/theme、@visx/a11y、@visx/chart、@visx/kernel、registry）在 npm 上发布前均应标记为不可安装。

工作流

1. 更改代码前，先确认本地环境：
   • 所有 @visx/* 版本均对齐到同一主版本（优先使用 ^4.0.0）；不要混用 v3 和 v4。
   • React peers 为 ^18 || ^19（使用 TypeScript 时，@types/react / @types/react-dom 也应匹配）。
   • 确认任务属于 XYChart、图元组合还是专用布局（geo/hierarchy/network/stats/…）。
   • 仅当从 @visx/xychart 或 @visx/react-spring 导入 Animated* 时，才需要动画 peer @react-spring/web。
2. 根据 source-map.md 刷新软件包证据和文档 URL。
3. 有关安装策略、思维模型、比例尺、形状、曲线、字形、标记、文本、defs（裁剪/图案/渐变）和 @visx/vendor，请参阅 setup-core.md。
4. 有关坐标轴、网格、图例、注释、阈值带以及主题/a11y（4.0 XYChart + 4.1 预览版），请参阅 guides-decoration.md。
5. 有关 ParentSize、边界、localPoint、拖拽、画笔、缩放以及工具提示/Portal，请参阅 interaction-layout.md。
6. 有关 stats、热力图、hierarchy、network、sankey、chord、geo、voronoi/delaunay、wordcloud 和 kernel 说明，请参阅 specialized-viz.md。
7. 有关 XYChart 系列/提供程序/主题、react-spring、模拟数据和 @visx/visx 总包，请参阅 xychart-high-level.md。
8. 有关 v3→v4 迁移、决策指南、生产环境/SSR/a11y/性能以及 AI 编写代码时的陷阱，请参阅 production-migration.md。

实现判断

• visx 不是一个开箱即用的图表库。组合 SVG：尺寸 → 比例尺 → 图元/辅助线 → 交互。优先选择能满足需求的最小 @visx/* 集合。
• D3 负责计算；React 管理 DOM。 比例尺和形状工厂会生成数字/路径 d 字符串；组件负责渲染 SVG。不要在 visx 图元树中混用 d3 selections/enter/exit。
• 连续 y 范围要反转（[innerHeight, 0]）。SVG 的 y 轴向下增长。
• 使用命名的包根导入（import { Bar } from '@visx/shape'）。v4 的 exports 下，切勿深度导入 @visx/*/lib/...。
• 优先使用 @visx/vendor/d3-*（或自行声明 d3-*），避免意外导入传递依赖中的 D3。不要在无明确意图的情况下同时使用 vendor 版本和裸 d3-shape/d3-scale。
• 对于标准笛卡尔坐标系折线图/面积图/柱状图/图元/堆叠/分组图表，以及共享的工具提示/主题/注释，使用 XYChart。传入 xScale/yScale 的应是 ScaleConfig 对象（{ type: 'band' }），而不是实时 d3 比例尺实例。
• 对于极坐标、地理、层次结构、网络、统计、自定义 SVG 结构或最小化捆绑包，使用基础组件。
• 对于新的 Voronoi/命中目标工作，优先使用 @visx/delaunay，而不是旧版 @visx/voronoi。
• @visx/network 不会运行力导向布局——请提供 x/y（例如通过外部 d3-force）。
• @visx/kernel 不是 KDE。密度图 → 使用 @visx/stats 的分箱/ViolinPlot，或外部 KDE + @visx/shape。
• 使用 ParentSize / useParentSize 包装响应式图表；渲染前检查 width < 10。在测试/SSR 中提供固定尺寸。
• 根据宽度/高度/数据记忆化比例尺配置和开销较大的布局。跨渲染周期使用可变 d3 比例尺时要谨慎。
• 渐变、图案、标记、clipPaths 和 Threshold 剪切都要使用唯一的 SVG id——尤其是在同一页面上有多个图表时。
• 添加图表语义时，将装饰性元素（Grid*、Axis*、背景）设为 aria-hidden；在 4.0.0 中使用 XYChart accessibilityLabel / 系列焦点处理器。

验证

优先使用仓库现有的检查。对于有实质影响的 visx 变更，加入相关的检查子集：

• 包/版本检查，证明 @visx/*@^4 与 React 18/19 对等依赖保持一致（使用 Animated* 时还要检查 @react-spring/web）。
• 对访问器、ScaleInput、系列 Datum/dataKey、轴/网格属性和工具提示状态进行类型检查——不使用深度导入的类型。
• 使用固定 width/height 进行确定性的 SVG 断言（涉及 ParentSize/工具提示 portal 时模拟 ResizeObserver）。
• 当相关 API 发生变更时，测试工具提示的显示/隐藏、brush 域筛选、zoom 重置和键盘焦点。
• 对主题 token、堆叠/分组柱状图和注释位置进行视觉冒烟测试。
• 添加总括包 @visx/visx、动画、地理 TopoJSON 或大型层次结构/网络示例时，审查捆绑包/导入情况。
• 迁移扫描：检查深度导入、React 16/17 对等依赖、withBoundingRects 缺少 nodeRef，以及 useParentSize 后使用 parentRef.current。