d3

D3

当工作涉及 D3.js（d3 或模块化的 d3-*）时，请使用此技能，包括数据准备、比例尺、图形、选择集/数据绑定、坐标轴、过渡、刷选/拖拽/缩放、力导向、层次结构、地理、delaunay 或框架互操作。

将 [email protected] 视为当前的总包版本线（入门指南、API 索引）。优先参考官方 d3js.org 模块页面和 npm 解析出的主版本，而不是依赖记忆。D3 是由约 30 个模块组成的工具箱，而不是图表库——请自行组合编码方式（或在不需要定制 D3 时选择更高层级的图表技术栈）。

工作流

1. 更改代码前，先确认本地情况：
   • 总包 d3 版本与模块化 d3-* 安装；通过 @types/d3 / @types/d3-*（DefinitelyTyped）支持 TypeScript 的情况。
   • 任务需要DOM 模块（selection、transition、通过 call 使用 axis、brush、drag、zoom），还是纯数学模块（array、scale、shape、interpolate、format 等）。
   • 渲染目标：SVG、Canvas（generator.context），或声明式 JSX 的 path/cx/cy 属性。
2. 从 source-map.md 更新软件包证据和文档 URL。
3. 有关安装策略、数据准备、比例尺、颜色方案、颜色和插值，请参阅 setup-data-scales.md。
4. 有关 line/area/arc/pie/stack/symbol/link、路径、多边形、坐标轴、等值线/密度和四叉树，请参阅 shapes-geometry.md。
5. 有关层次结构、力导向、弦图、地理和 delaunay/voronoi，请参阅 layouts-geo.md。
6. 有关选择集/数据绑定、brush、drag、zoom 和 dispatch（包括 React/Svelte DOM 冲突规则），请参阅 selection-interaction.md。
7. 有关过渡/ease/timer、框架指南、生产/SSR/Canvas、v6→v7 注意事项和 AI 陷阱，请参阅 animation-frameworks.md。

实现判断

• 优先选择能满足需求的最小模块集。原型开发：bun add d3。生产环境中的 React 图表通常只需 d3-scale + d3-shape + d3-array（使用 DOM API 时再加上 selection/axis）。
• 反转连续 y 比例尺的范围（[innerHeight, marginTop]）。SVG 的 y 轴向下增长。
• 在 JSX 中使用纯数学逻辑没有问题（scale、array、shape 路径字符串、format）。在 React 中，DOM 修改器需要配合 refs + effects：selection、selection.call(axis)、transition、brush、drag、zoom（官方 React 指南）。
• 优先使用现代的 selection.data(data, key).join(...)，而不是冗长的 enter/update/exit，除非需要自定义退出动画。
• 向监听器传递原生事件（D3 6+）；没有 d3.event。
• 优先使用 d3-delaunay（Delaunay.from），而不是已弃用的 d3-voronoi。
• 对值进行编码的层次布局，在使用 treemap/pack/partition 之前需要调用 .sum()（通常也需要 .sort()）。
• 力模拟会在每个 tick 上修改 node.x/node.y——请从 "tick"（或 React state）触发渲染，并在卸载时调用 stop()。
• 条带柱状图使用 .bandwidth()；分类折线图/散点图通常使用 scalePoint。使用 curveMonotoneX 前先对数据排序。
• 不要使用 d3.nest（已移除）；请使用 group / rollup / groups / rollups。
• 多个图表共用一个文档时，剪裁路径/渐变/标记要使用唯一的 SVG id。

验证

优先使用代码库现有的检查。对有实际意义的 D3 更改，请包含相关子集：

• 检查软件包/版本是否为 d3@7 或主版本一致的模块；使用 TypeScript 时检查 @types/d3。
• 对访问器、比例尺域和数据绑定键类型进行类型检查。
• 使用固定宽度/高度进行确定性的 SVG/Canvas 断言（过渡使用模拟计时器；测试中停止力模拟）。
• 更改 brush 域筛选、zoom 变换和 drag 等 API 时，进行交互测试。
• 添加 geo、force、hierarchy、contour 或完整总包时，审查打包内容。
• 从较早版本的 D3 升级时，扫描迁移问题：d3.event、d3.nest、d3.voronoi 和 React 16 时代的模式。