react-table-search-pagination

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Table Search Pagination

描述

Description

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

This is a comprehensive development guide specifically for table, search, and pagination features in React/Next.js projects. It covers all core technical implementations and best practices, from basic race condition handling to complex state management selection.

適用場景

Applicable Scenarios

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

React/Next.js applications needing to implement search and pagination features
List display and CRUD operations for large datasets
Need for high-performance infinite scrolling or virtualized lists
Facing complex data management issues such as race conditions and state synchronization
Projects needing to select an appropriate state management solution

📚 指南結構

📚 Guide Structure

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

This guide has been split into multiple dedicated files for easy reference and maintenance:

🔗 核心技術指南

🔗 Core Technical Guides

文件	描述	主要內容
race-condition.md	競態條件處理	AbortController、Boolean Flag、TanStack Query
search-system.md	搜尋系統實作	自動完成、輸入法優化、防護機制
pagination-system.md	分頁系統實作	快取策略、異常處理、效能優化
infinite-scroll.md	動態加載與無限捲動	Intersection Observer、位置保存
intersection-observer.md	Intersection Observer API	懶加載、動畫觸發、廣告追蹤
crud-sync.md	列表資料 CRUD 同步	同步策略、狀態管理整合
state-management.md	狀態管理選擇指南	決策樹、工具對比、最佳實踐
refresh-token-race-condition.md	Refresh Token 與競態條件	無感刷新、Axios攔截器、TanStack Query/SWR整合

File	Description	Main Content
race-condition.md	Race Condition Handling	AbortController, Boolean Flag, TanStack Query
search-system.md	Search System Implementation	Autocomplete, IME Optimization, Protection Mechanisms
pagination-system.md	Pagination System Implementation	Caching Strategies, Exception Handling, Performance Optimization
infinite-scroll.md	Dynamic Loading & Infinite Scrolling	Intersection Observer, Position Saving
intersection-observer.md	Intersection Observer API	Lazy Loading, Animation Triggering, Ad Tracking
crud-sync.md	List Data CRUD Synchronization	Synchronization Strategies, State Management Integration
state-management.md	State Management Selection Guide	Decision Tree, Tool Comparison, Best Practices
refresh-token-race-condition.md	Refresh Token & Race Conditions	Seamless Refresh, Axios Interceptors, TanStack Query/SWR Integration

🚀 快速導航

🚀 Quick Navigation

快速開始

Quick Start

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

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

If you're working on a new project, we recommend the following reading order:

state-management.md - Understand the state management decision framework
race-condition.md - Master asynchronous request handling
search-system.md - Implement search functionality
Choose based on your needs:
- Pagination System → pagination-system.md
- Infinite Scrolling → infinite-scroll.md
- CRUD Operations → crud-sync.md

專案檢查清單

Project Checklist

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

For the complete development checklist, refer to the "Development Checklist" section at the end of each dedicated file.

🛠️ 技術棧推薦

🛠️ Tech Stack Recommendations

狀態管理組合

State Management Combinations

專案規模	推薦組合	理由
小型（< 10 頁）	URL + useState + Context	輕量、快速開發、零依賴
中型（10-30 頁）	TanStack Query + URL + Zustand/Jotai	平衡功能與複雜度
大型（> 30 頁）	TanStack Query + URL + Redux Toolkit	完整生態、團隊規範
高性能要求	TanStack Query + Zustand	極簡 API、最高效能
複雜狀態依賴	TanStack Query + Jotai	原子化細粒度控制、自動優化

Project Scale	Recommended Combination	Reason
Small (<10 pages)	URL + useState + Context	Lightweight, fast development, zero dependencies
Medium (10-30 pages)	TanStack Query + URL + Zustand/Jotai	Balances functionality and complexity
Large (>30 pages)	TanStack Query + URL + Redux Toolkit	Complete ecosystem, team standards
High Performance Needs	TanStack Query + Zustand	Minimal API, maximum performance
Complex State Dependencies	TanStack Query + Jotai	Atomic fine-grained control, automatic optimization

核心工具庫

Core Libraries

類型	工具	推薦理由
資料獲取	TanStack Query	自動快取、重試、樂觀更新
客戶端狀態	Zustand/Jotai	極簡 API、高效能/原子化
路由管理	React Router v6 / Next.js App Router	標準方案、型別安全
表單管理	React Hook Form	效能優異、驗證整合
UI 增強	@tanstack/react-virtual	虛擬滾動、長列表優化

Category	Tool	Recommendation Reason
Data Fetching	TanStack Query	Automatic caching, retries, optimistic updates
Client State	Zustand/Jotai	Minimal API, high performance/atomicity
Routing	React Router v6 / Next.js App Router	Standard solution, type-safe
Form Management	React Hook Form	Excellent performance, validation integration
UI Enhancement	@tanstack/react-virtual	Virtual scrolling, long list optimization

🎯 最佳實踐核心原則

🎯 Best Practice Core Principles

1. 效能優先

1. Performance First

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

Use
```
Intersection Observer
```
instead of
```
scroll
```
events
Implement
```
AbortController
```
to avoid invalid requests
Use
```
debounce
```
to reduce API call frequency

2. 資料一致性

2. Data Consistency

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

Properly handle race conditions
Correctly manage cache invalidation
Ensure UI synchronization after CRUD operations

3. 使用者體驗

3. User Experience

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

Provide appropriate loading states
Save scroll positions
Implement optimistic updates
Clear error handling and feedback

4. 可維護性

4. Maintainability

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

Use URL as the Source of Truth
Encapsulate reusable custom Hooks
Follow clear naming conventions
Provide complete error boundary handling

📖 詳細指南

📖 Detailed Guides

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

Race Condition Handling (race-condition.md)

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

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

Learn how to handle race conditions in asynchronous requests, including:

AbortController usage
Boolean Flag pattern
Automatic handling with TanStack Query/SWR

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

Search System Implementation (search-system.md)

建立高效能搜尋系統：

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

Build a high-performance search system:

Autocomplete functionality
IME optimization (for CJK languages)
Debounce and protection mechanisms
URL state synchronization

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

Pagination System Implementation (pagination-system.md)

實作專業級分頁系統：

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

Implement a professional-grade pagination system:

Caching strategies and invalidation
Exception handling and edge cases
Virtual scrolling optimization
State management integration

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

Dynamic Loading & Infinite Scrolling (infinite-scroll.md)

流暢的無限捲動體驗：

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

Create a smooth infinite scrolling experience:

Intersection Observer implementation
Scroll position saving
Data deduplication and concurrency protection

Intersection Observer API (intersection-observer.md)

掌握高效能監測技術：

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

Master high-performance monitoring technology:

Image lazy loading
Animation triggering
Ad exposure tracking
React Hook encapsulation

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

List CRUD Synchronization (crud-sync.md)

確保資料操作的一致性：

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

Ensure consistency in data operations:

Synchronization strategy selection
Optimistic update implementation
State management library integration
Development protection mechanisms

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

State Management Selection (state-management.md)

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

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

Choose the most suitable state management solution:

State classification framework
Decision tree guidance
Tool comparison analysis
Migration path recommendations

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

Refresh Token & Race Condition Handling (refresh-token-race-condition.md)

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

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

Best practices for handling complex authentication scenarios:

Seamless refresh mechanism for Refresh Token
Axios interceptors and request queues
TanStack Query/SWR integration solutions
Automatic race condition handling
Practical scenario analysis and solutions

🛠️ 開發工具推薦

🛠️ Recommended Development Tools

DevTools 必備

Essential DevTools

工具	用途	安裝方式
React DevTools	組件檢查	瀏覽器擴充
TanStack Query DevTools	查詢調試	`npm install @tanstack/react-query-devtools`
Redux DevTools	狀態調試	瀏覽器擴充 + `@reduxjs/toolkit`
Zustand DevTools	狀態調試	使用 `devtools` 中間件
Jotai DevTools	狀態調試	使用 `jotai-devtools` 擴充

Tool	Purpose	Installation Method
React DevTools	Component Inspection	Browser extension
TanStack Query DevTools	Query debugging	`npm install @tanstack/react-query-devtools`
Redux DevTools	State debugging	Browser extension + `@reduxjs/toolkit`
Zustand DevTools	State debugging	Use `devtools` middleware
Jotai DevTools	State debugging	Use `jotai-devtools` extension

效能監控

Performance Monitoring

工具	監控目標
React Profiler	組件渲染效能
Lighthouse	整體網頁效能
Web Vitals	核心網頁指標

Tool	Monitoring Target
React Profiler	Component rendering performance
Lighthouse	Overall web performance
Web Vitals	Core web vitals

📋 版本資訊

📋 Version Information

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

Version: 2.0 (Refactored Version)
Last Updated: 2025-01-28
Applicable Scope: React 18+, Next.js 13+ (App Router)

📝 更新日誌

📝 Update Log

v2.2 (2025-01-29)

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

🎯 Added dedicated guide for Refresh Token & Race Condition Handling
🔄 Fully organized Axios interceptor implementation solutions
⚡ Added TanStack Query/SWR integration strategies
🛡️ Added practical scenario analysis and solutions
📋 Updated technical guide list with authentication-related content

v2.1 (2025-01-28)

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

✨ Added Jotai state management support and detailed comparison
📚 Updated state management combination recommendation table
🛠️ Added Jotai sample code and best practices
🔧 Added Jotai DevTools tool description

v2.0 (2025-01-28)

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

🔄 Split single file into multiple dedicated guides
✨ Added dedicated Intersection Observer file
📚 Optimized state management decision framework
🛠️ Updated all sample code
📋 Added detailed checklists

v1.0 (原始版本)

v1.0 (Original Version)

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

🎉 Established complete React/Next.js development guide
📄 Covered core features such as race conditions, search, pagination, CRUD, etc.

🤝 貢獻指南

🤝 Contribution Guide

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

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

To update or add content, please:

Identify the dedicated file to modify
Maintain consistency in code samples
Update the corresponding checklist
Ensure version information is synchronized

🔗 相關連結

🔗 Related Links

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

✍️ Writing Style Guide (Traditional Chinese)

本專案的寫作風格指南請參考

README.md

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

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

For the writing style guide of this project, please refer to the "Writing Style Guide (Traditional Chinese)" section in

README.md

, which includes unified terminology, UI copy rules, punctuation and Chinese-English mixing strategies, and document change processes.

This guide is continuously updated. Feedback and suggestions are welcome.