React 和 Next.js 数据可视化
概述
当可视化位于 React 或 Next.js 产品表面时，使用此技能。重点不仅仅是图表渲染。重点是组件所有权、水合安全性、客户端和服务器边界、打包策略，以及 React 与任何实际绘制标记的可视化层之间的干净集成。
默认假设：React 应负责结构、布局和应用状态，而可视化层负责比例尺、几何图形和范围有限的命令式渲染。
如果主要请求涉及截图测试、视觉回归、模拟图表数据或端到端覆盖策略，请首先路由到 ../testing-data-visualizations/SKILL.md，然后仅针对 React 或 Next 特定的实现细节再回到此技能。
选择此技能的场景
- 用户正在 React 组件内构建图表
- 应用程序使用 Next.js、App Router 或服务器和客户端组件边界
- 图表在 React 表面内使用 D3、Canvas、SVG、Vega-Lite、Plot、WebGL、deck.gl、PixiJS、Sigma.js 或 Three.js
- 表面使用 Mermaid、React Flow、Cytoscape.js、Sprotty、JointJS、GoJS、ELK、Dagre、Graphviz/WASM、D2 或其他类 UML 图表渲染器
- 水合作用、SSR、动态加载或仅浏览器 API 影响实现
- 打包大小、路由级别加载和产品集成很重要
- 页面是一个编辑型视觉故事，结合了 React 布局、滚动状态、视差效果、粘性图形、生成的资产、SVG/Canvas/D3/WebGL/Three.js 层、粒子、流式动画和可访问性回退
工作模式
- 确定哪些部分在服务器端是安全的，哪些必须在浏览器中运行。
- 保持数据加载、转换、图表配置和渲染层关注点分离。
- 估计一个页面上可以同时可见多少个图表实例，以及是否可以在它们之间共享昂贵的工作。
- 让 React 负责布局、控件、路由状态、持久化功能以及活动状态摘要。
- 让 D3、Canvas、Vega-Lite 嵌入、Plot、WebGL 库或 Three.js 负责标记级渲染。
- 在连接控件之前，明确地对 URL 支持的视图状态进行建模：过滤器、范围、指标、比较、选中的实体、活动标签页、地图边界、缩放、相机目标以及下钻路径。
- 仅将 localStorage 用于非常小的个人偏好；对于较大的已保存视图、草稿、缓存切片、自定义注释或共享/跨设备工作区，使用 IndexedDB 或远程存储。传入的 URL 状态应覆盖持久化的默认值。
- 对于仅浏览器的可视化代码，有目的地使用动态加载或仅客户端边界。
- 如果图表拥有滚轮、捏合或拖拽交互，请明确浏览器合约。当必须取消默认滚动时，使用非被动原生监听器或库钩子，并且不要假定框架级别的
onWheel就足够了。 - 对于编辑或信息图表面，将洞察标题、工件模式、副标题、注释计划、来源说明、大屏幕布局、移动端竖屏布局、可选的移动端横屏布局和图表渲染层作为明确的组件职责。对于触摸、键盘、可视视口、连接不稳定和设备能力决策，请使用
../../references/foundations/mobile-first-responsive-visualization.md。 - 对于滚动叙事或视差效果，使用
../scrollytelling-and-parallax-data-visualization/SKILL.md作为故事合约。将场景建模为类型化状态，而不是临时的滚动数学计算。每个场景应定义可见层、注释文本、媒体资产、相机或变换状态、触发/进度范围、静态关键帧和减少运动回退。 - 对于高级编辑、报告、演示文稿、生成图像、动画或现有页面集成工作，在实现前使用
../../references/foundations/meaning-preserving-visual-design-workflow.md和../../references/foundations/mobile-first-responsive-visualization.md。应用共享工作流程来处理概念图像、大屏幕/移动端变体、审批或迭代，以及 React 必须实现的绑定语义设计合约。 - 对于生成的图像或插图，将资产放在确定性的公共路径或可导入模块中，并将标签/数据叠加层保留在 React 拥有、可编辑的层中。
- 对于 WebGL，将渲染器生命周期、大小调整、上下文丢失、清理和动画循环保持在一个狭窄的仅客户端组件边界内。React 应传递数据版本和 props，而不是在整个树中直接操作 GPU 对象。
- 对于交互式 UML、ERD、依赖关系、状态机、流程或架构图，首先使用
../uml-and-software-architecture-visualization/SKILL.md；React 应负责应用状态、面板、控件、路由和持久化，而图表层负责布局/渲染细节。 - 对于运营工作空间，在组件分解之前使用
../../references/foundations/operational-visualization-workspaces.md。React 应负责外壳状态、命令栏、抽屉、导轨、活动摘要、URL 状态和检查器同步，而可视化层负责几何图形、布局和拾取。
Next.js 指南
- 当图表不需要浏览器 API 时，优先使用 Server Components 进行数据获取、框架内容和布局。
- 对于交互式图表、测量容器、指针事件或仅浏览器库，使用 Client Components。
- 当图表库运行时在初始路径上不需要或应避免 SSR 时，使用动态导入。
- 当相同的可视化必须出现在报告或文档中时，保持图表资产和导出路径的确定性。
- 尽可能使用路由参数或搜索参数作为可共享视图状态的规范输入。在初始化仅客户端图表状态之前解析并规范化它们，以便链接的视图不会因无关的默认值而闪烁。
- 对于高频瞬态更改，使用替换式导航；对于已确认的选择、应用的过滤器、下钻步骤和已保存视图的转换，使用推送式导航。
- 对于出版风格的页面，将桌面和移动端布局设计为兄弟状态，而不是一个被挤压的 SVG。
- 在移动端上，将主要可视化放在首位或立即可见。将辅助过滤器、检查器和设置放在可折叠的面板、抽屉、底部弹出框或内联控件中，这些控件可保留活动状态摘要，并在应用、取消、重置或关闭后将焦点/滚动返回到图表。
- 对于密集工作区，首选桌面大纲/控制导轨、中央视口和检查器导轨；在移动端上使用命令栏配合大纲、过滤器和详细信息面板，而不是将桌面导轨堆叠在可视化上方。
- 对于键盘密集型控件，使用
window.visualViewport或等效的调整大小处理，以便搜索、过滤和注释流程不会隐藏唯一的关键操作或永久遮挡可视化。 - 尽可能使用指针事件进行自定义触摸/笔/鼠标交互，并明确指定
touch-action、放大的点击区域、拖拽替代方案、重置控件，并且不存在仅悬停即可的证据。 - 少而精地、可访问地使用 IntersectionObserver、Scrollama、Motion 的
useScroll、GSAP ScrollTrigger、CSS 滚动时间线或显式步骤控件。默认视图仍应传达主要信息。 - 对于固定的故事章节，优先使用原生滚动和
position: sticky。避免滚动劫持，并保持滚轮、触摸、滚动条和键盘行为的可预测性。 - 使用
prefers-reduced-motion将动画故事切换到最终状态、关键帧或分步布局。 - 延迟加载重型 WebGL、3D、视频或图像生成衍生的资产，同时避免布局偏移。预留长宽比和标签通道。
- 当 WebGL 动画循环处于屏幕外、被路由隐藏、标签页切换或减少运动激活状态时，暂停动画。
输出期望
- 指明 React 和可视化层之间的所有权边界。
- 对于解释性工作，指明洞察标题、工件模式、注释层、直接标签策略和移动端阅读路径。
- 对于移动端工作，指明移动端竖屏布局、是否支持横屏、控件如何避免遮挡图表、屏幕键盘的行为方式，以及触摸/捏合交互如何映射到选择、缩放、平移和重置。
- 对于运营工作空间，指明外壳组件、默认选中状态、同步的大纲/搜索/过滤器/检查器行为、空表面清除选择规则、移动端命令面板和 URL 支持的工作空间状态。
- 对于艺术指导工作，指明生成或插图的资产、滚动/动画状态、减少运动行为和静态帧回退。
- 对于概念设计表面，使用共享设计工作流程处理概念图像、审批状态、已批准的参考、绑定的语义设计合约、锁定和灵活元素、React 拥有的数据层、渲染器拥有的层、移动端/横屏延续以及已批准的偏差。
- 对于滚动叙事或视差效果，指明滚动控制器、场景合约、触发/进度范围、粘性布局、移动端回退和静态关键帧。
- 对于 WebGL 或粒子效果，指明渲染器、数据到缓冲区边界、动画时钟、清理/销毁路径、减少运动行为和静态回退。
- 明确标出任何仅客户端或对水合敏感的代码。
- 明确标出任何必须抑制原生浏览器滚动或滚动链的交互。
- 指明哪些状态由 URL 支持、本地持久化、IndexedDB 支持、远程保存或有意为临时状态。
- 指明复制链接、已保存视图、重置、刷新、后退/前进以及无效 URL 状态的行为。
- 指明哪些控件或详细信息区域默认折叠或可关闭，以及活动状态如何保持可见。
- 指明移动端上的实时数据连接行为：陈旧状态、重新连接、离线/部分数据、低带宽模式、以及在相关时的告警/通知策略。
- 说明图表是否适合 SSR、仅客户端渲染或动态加载。
- 对于新工作，包含一个技术设计部分，涵盖同时实例数量、每个实例与页面级别的性能，以及所选集成模式的维护影响。
- 在设计过程中，始终保持对打包大小、导出需求和可访问性的可见性。
参考
- 共享理论：
../../references/foundations/editorial-infographic-system.md../../references/foundations/art-directed-interactive-visual-stories.md../../references/foundations/meaning-preserving-visual-design-workflow.md../../references/foundations/task-abstraction-and-chart-selection.md../../references/foundations/perception-color-and-encoding.md../../references/foundations/shareable-state-and-persistence.md../../references/foundations/mobile-first-responsive-visualization.md../../references/foundations/operational-visualization-workspaces.md../../references/foundations/implementation-design-and-tradeoffs.md
- 技能参考：
./references/react-component-patterns.md./references/d3-canvas-and-grammar-in-react.md./references/nextjs-client-server-boundaries.md./references/lazy-loading-ssr-and-bundle-strategy.md../uml-and-software-architecture-visualization/SKILL.md../scrollytelling-and-parallax-data-visualization/SKILL.md../testing-data-visualizations/SKILL.md
代表性提示
- “我应该如何将此图表集成到 React 应用中？”
- “这里适用于 D3、Canvas 或 Vega-Lite 的正确 React 模式是什么？”
- “让这个可视化在 Next.js App Router 中干净地工作。”
- “构建一个带有粘性图形和减少运动回退功能的 React 滚动叙事故事。”
- “这个图表应该是 Client Component 还是使用动态导入？”
- “帮助我避免此可视化中的水合和 SSR 问题。”
- “构建一个交互式 React UML、ERD、流程图、状态机、依赖关系或架构图。”