React Table Search Pagination

描述

這是一個專門處理 React/Next.js 專案中表格、搜尋、分頁功能的完整開發指南。涵蓋了從基礎的競態條件處理到複雜的狀態管理選擇等所有核心技術實作與最佳實踐。

適用場景

• 需要實作搜尋與分頁功能的 React/Next.js 應用
• 處理大量資料的列表展示和 CRUD 操作
• 需要高效能的無限捲動或虛擬化列表
• 面臨競態條件、狀態同步等複雜資料管理問題
• 需要選擇合適的狀態管理方案的專案

📚 指南結構

本指南已拆分為多個專門文件，便於查閱和維護：

🔗 核心技術指南

🚀 快速導航

快速開始

如果你是新專案，建議閱讀順序：

1. state-management.md – 了解狀態管理決策框架
2. race-condition.md – 掌握非同步請求處理
3. search-system.md – 實作搜尋功能
4. 根據需求選擇：
   • 分頁系統 → pagination-system.md
   • 無限捲動 → infinite-scroll.md
   • CRUD 操作 → crud-sync.md

專案檢查清單

完整開發檢查清單請參考各專門文件末尾的「開發檢查清單」章節。

🛠️ 技術棧推薦

狀態管理組合

核心工具庫

🎯 最佳實踐核心原則

1. 效能優先

• 使用 Intersection Observer 替代 scroll 事件
• 實作 AbortController 避免無效請求
• 使用 debounce 減少 API 呼叫頻率

2. 資料一致性

• 妥善處理競態條件
• 正確管理快取失效
• CRUD 操作後確保 UI 同步

3. 使用者體驗

• 提供適當的 Loading 狀態
• 保存捲動位置
• 實作樂觀更新
• 清晰的錯誤處理與反饋

4. 可維護性

• 將 URL 作為 Source of Truth
• 封裝可重用的自定義 Hook
• 遵循清晰的命名規範
• 提供完整的錯誤邊界處理

📖 詳細指南

競態條件處理 (race-condition.md)

學習如何處理非同步請求的競態條件，包括：

• AbortController 使用方法
• Boolean Flag 模式
• TanStack Query/SWR 自動處理

搜尋系統實作 (search-system.md)

建立高效能搜尋系統：

• 自動完成功能
• 輸入法優化（中日韓文）
• 防抖與防護機制
• URL 狀態同步

分頁系統實作 (pagination-system.md)

實作專業級分頁系統：

• 快取策略與失效
• 異常處理與邊界情況
• 虛擬滾動優化
• 狀態管理整合

動態加載與無限捲動 (infinite-scroll.md)

流暢的無限捲動體驗：

• Intersection Observer 實作
• 捲動位置保存
• 資料去重與併發防護

Intersection Observer API (intersection-observer.md)

掌握高效能監測技術：

• 圖片懶加載
• 動畫觸發
• 廣告曝光追蹤
• React Hook 封裝

列表 CRUD 同步 (crud-sync.md)

確保資料操作的一致性：

• 同步策略選擇
• 樂觀更新實作
• 狀態管理庫整合
• 開發防護機制

狀態管理選擇 (state-management.md)

選擇最適合的狀態管理方案：

• 狀態分類框架
• 決策樹指導
• 工具對比分析
• 遷移路徑建議

Refresh Token 與競態條件處理 (refresh-token-race-condition.md)

處理複雜驗證場景的最佳實踐：

• Refresh Token 無感刷新機制
• Axios 攔截器與請求佇列
• TanStack Query/SWR 整合方案
• 競態條件自動處理
• 實務情境分析與解決方案

🛠️ 開發工具推薦

DevTools 必備

效能監控

📋 版本資訊

版本：2.0 (重構版本)
最後更新：2025-01-28
適用範圍：React 18+, Next.js 13+ (App Router)

📝 更新日誌

v2.2 (2025-01-29)

• 🎯 新增 Refresh Token 與競態條件處理專門指南
• 🔄 完整整理 Axios 攔截器實作方案
• ⚡ 補充 TanStack Query/SWR 整合策略
• 🛡️ 增加實務情境分析與解決方案
• 📋 更新技術指南清單，新增驗證相關內容

v2.1 (2025-01-28)

• ✨ 新增 Jotai 狀態管理支援與詳細對比
• 📚 更新狀態管理組合推薦表格
• 🛠️ 增加 Jotai 範例程式碼與最佳實踐
• 🔧 補充 Jotai DevTools 工具說明

v2.0 (2025-01-28)

• 🔄 重新拆分單一文件為多個專門指南
• ✨ 新增 Intersection Observer 專門文件
• 📚 優化狀態管理決策框架
• 🛠️ 更新所有範例程式碼
• 📋 增加詳細的檢查清單

v1.0 (原始版本)

• 🎉 建立完整的 React/Next.js 開發指南
• 📄 涵蓋競態條件、搜尋、分頁、CRUD 等核心功能

🤝 貢獻指南

若要更新或新增內容，請：

1. 確定修改的專門文件
2. 保持程式碼範例的一致性
3. 更新對應的檢查清單
4. 確保版本資訊同步更新

🔗 相關連結

• React 官方文檔
• Next.js 官方文檔
• TanStack Query 文檔
• Zustand 文檔
• Jotai 文檔
• Intersection Observer API

✍️ 寫作風格指南（繁體中文）

本專案的寫作風格指南請參考 README.md 的「寫作風格指南（繁體中文）」章節，該章節包含用詞統一、UI 文案規則、標點與中英混寫策略，以及文件變更流程等內容。

本指南持續更新中，歡迎提供回饋與建議。