React 和 Next.js 資料視覺化
概述
當視覺化存在於 React 或 Next.js 產品表面內時，請使用此技能。重點不只是圖表渲染，而是元件所有權、水合安全性、客戶端與伺服器邊界、打包策略，以及 React 與實際繪製標記的視覺化層之間的乾淨整合。
預設假設：React 應擁有結構、佈局和應用程式狀態，而視覺化層則擁有縮放、幾何和狹義範圍的命令式渲染。
如果主要請求是關於螢幕截圖測試、視覺回歸、模擬圖表資料或 E2E 覆蓋率策略，請先導向 ../testing-data-visualizations/SKILL.md，然後僅在需要 React 或 Next.js 特定的實作細節時，再回配到此技能。
選擇此技能的時機
- 使用者在 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 狀態應覆蓋持久化的預設值。 - 對僅限瀏覽器的視覺化程式碼，有意識地使用動態載入或僅限客戶端的邊界。
- 如果圖表擁有滾輪、捏合或拖曳互動，請明確說明瀏覽器合約。當必須取消預設滾動時，請使用非被動的 native 監聽器或庫鉤子，並且不要假設框架層級的
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 時，優先使用伺服器元件進行資料擷取、內容框架和佈局。
- 對互動式圖表、測量容器、指標事件或僅限瀏覽器的庫，使用客戶端元件。
- 當圖表執行時期在初始路徑上不需要，或應避免 SSR 時，使用動態匯入。
- 當相同視覺化必須出現在報告或文件中時，保持圖表資產和匯出路徑的確定性。
- 盡可能使用路由參數或搜尋參數作為可分享檢視狀態的規範輸入。在初始化僅限客戶端的圖表狀態之前，解析並規範化它們，以便連結的檢視不會因不相關的預設值而閃爍。
- 對高頻率的短暫變更使用 replace-style 導航，對已確認的選取、已套用的篩選器、向下鑽取步驟和已儲存檢視的轉換使用 push-style 導航。
- 對於出版風格的頁面，將桌面和行動裝置的組成設計為兄弟狀態，而不是單一壓縮的 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 滾動敘述故事。”
- “這個圖表應該是客戶端元件還是使用動態匯入？”
- “幫我避免這個視覺化時的水合和 SSR 問題。”
- “建立一個互動式 React UML、ERD、流程、狀態機、相依性或架構圖。”