react-state-management

快速参考

库	最适用于	安装
Context	小型应用、主题	内置
Zustand	简单的全局状态	npm i zustand
Jotai	原子化／细粒度状态	npm i jotai
TanStack Query	服务端状态／缓存	npm i @tanstack/react-query
SWR	数据获取	npm i swr

场景	推荐方案
简单的本地状态	useState
复杂的本地状态	useReducer
共享状态（小型应用）	Context + useReducer
共享状态（大型应用）	Zustand 或 Jotai
服务端状态	TanStack Query 或 SWR

何时使用此技能

用于状态管理决策：

• 在不同状态管理方案之间进行选择
• 设置 Zustand、Jotai 或 Context 存储
• 配置 TanStack Query 以管理服务端状态
• 实现乐观更新
• 规范化复杂状态结构
• 避免不必要的重新渲染

React Hooks 基础知识：请参阅 react-hooks-complete

---

React 状态管理

内置状态管理

使用 useState 管理组件状态

'use client';

import { useState } from 'react';

function ShoppingCart() {
  const [items, setItems] = useState<CartItem[]>([]);
  const [isOpen, setIsOpen] = useState(false);

  const addItem = (product: Product) => {
    setItems((prev) => {
      const existing = prev.find((item) => item.id === product.id);
      if (existing) {
        return prev.map((item) =>
          item.id === product.id
            ? { ...item, quantity: item.quantity + 1 }
            : item
        );
      }
      return [...prev, { ...product, quantity: 1 }];
    });
  };

  const total = items.reduce(
    (sum, item) => sum + item.price * item.quantity,
    0
  );

  return (
    <div>
      <button onClick={() => setIsOpen(!isOpen)}>
        Cart ({items.length}) - ${total.toFixed(2)}
      </button>
      {isOpen && <CartDropdown items={items} />}
    </div>
  );
}

使用 useReducer 管理复杂状态

'use client';

import { useReducer, Dispatch, createContext, useContext } from 'react';

// Types
interface CartState {
  items: CartItem[];
  isLoading: boolean;
  error: string | null;
}

type CartAction =
  | { type: 'ADD_ITEM'; payload: Product }
  | { type: 'REMOVE_ITEM'; payload: string }
  | { type: 'UPDATE_QUANTITY'; payload: { id: string; quantity: number } }
  | { type: 'CLEAR_CART' }
  | { type: 'SET_LOADING'; payload: boolean }
  | { type: 'SET_ERROR'; payload: string };

// Reducer
function cartReducer(state: CartState, action: CartAction): CartState {
  switch (action.type) {
    case 'ADD_ITEM': {
      const existing = state.items.find(
        (item) => item.id === action.payload.id
      );
      if (existing) {
        return {
          ...state,
          items: state.items.map((item) =>
            item.id === action.payload.id
              ? { ...item, quantity: item.quantity + 1 }
              : item
          ),
        };
      }
      return {
        ...state,
        items: [...state.items, { ...action.payload, quantity: 1 }],
      };
    }
    case 'REMOVE_ITEM':
      return {
        ...state,
        items: state.items.filter((item) => item.id !== action.payload),
      };
    case 'UPDATE_QUANTITY':
      return {
        ...state,
        items: state.items.map((item) =>
          item.id === action.payload.id
            ? { ...item, quantity: action.payload.quantity }
            : item
        ),
      };
    case 'CLEAR_CART':
      return { ...state, items: [] };
    case 'SET_LOADING':
      return { ...state, isLoading: action.payload };
    case 'SET_ERROR':
      return { ...state, error: action.payload };
    default:
      return state;
  }
}

// Context
const CartContext = createContext<{
  state: CartState;
  dispatch: Dispatch<CartAction>;
} | null>(null);

// Provider
export function CartProvider({ children }: { children: React.ReactNode }) {
  const [state, dispatch] = useReducer(cartReducer, {
    items: [],
    isLoading: false,
    error: null,
  });

  return (
    <CartContext.Provider value={{ state, dispatch }}>
      {children}
    </CartContext.Provider>
  );
}

// Hook
export function useCart() {
  const context = useContext(CartContext);
  if (!context) {
    throw new Error('useCart must be used within CartProvider');
  }
  return context;
}

Context API

创建和使用 Context

import { createContext, useContext, useState, ReactNode } from 'react';

// Theme context
interface Theme {
  colors: { primary: string; secondary: string; background: string };
  spacing: { sm: number; md: number; lg: number };
}

interface ThemeContextType {
  theme: Theme;
  setTheme: (theme: Theme) => void;
  toggleDarkMode: () => void;
  isDark: boolean;
}

const ThemeContext = createContext<ThemeContextType | null>(null);

const lightTheme: Theme = {
  colors: { primary: '#3b82f6', secondary: '#8b5cf6', background: '#ffffff' },
  spacing: { sm: 8, md: 16, lg: 24 },
};

const darkTheme: Theme = {
  colors: { primary: '#60a5fa', secondary: '#a78bfa', background: '#1f2937' },
  spacing: { sm: 8, md: 16, lg: 24 },
};

export function ThemeProvider({ children }: { children: ReactNode }) {
  const [isDark, setIsDark] = useState(false);
  const [theme, setTheme] = useState<Theme>(lightTheme);

  const toggleDarkMode = () => {
    setIsDark((prev) => !prev);
    setTheme(isDark ? lightTheme : darkTheme);
  };

  return (
    <ThemeContext.Provider value={{ theme, setTheme, toggleDarkMode, isDark }}>
      {children}
    </ThemeContext.Provider>
  );
}

export function useTheme() {
  const context = useContext(ThemeContext);
  if (!context) {
    throw new Error('useTheme must be used within ThemeProvider');
  }
  return context;
}

优化 Context 性能

import { createContext, useContext, useMemo, useCallback, useState } from 'react';

// Split context to prevent unnecessary re-renders
const UserContext = createContext<User | null>(null);
const UserActionsContext = createContext<{
  login: (email: string, password: string) => Promise<void>;
  logout: () => void;
  updateProfile: (data: Partial<User>) => Promise<void>;
} | null>(null);

export function UserProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState<User | null>(null);

  const login = useCallback(async (email: string, password: string) => {
    const response = await fetch('/api/login', {
      method: 'POST',
      body: JSON.stringify({ email, password }),
    });
    const userData = await response.json();
    setUser(userData);
  }, []);

  const logout = useCallback(() => {
    setUser(null);
  }, []);

  const updateProfile = useCallback(async (data: Partial<User>) => {
    const response = await fetch('/api/profile', {
      method: 'PATCH',
      body: JSON.stringify(data),
    });
    const updated = await response.json();
    setUser(updated);
  }, []);

  // Memoize actions object
  const actions = useMemo(
    () => ({ login, logout, updateProfile }),
    [login, logout, updateProfile]
  );

  return (
    <UserContext.Provider value={user}>
      <UserActionsContext.Provider value={actions}>
        {children}
      </UserActionsContext.Provider>
    </UserContext.Provider>
  );
}

// Separate hooks for data and actions
export function useUser() {
  return useContext(UserContext);
}

export function useUserActions() {
  const context = useContext(UserActionsContext);
  if (!context) {
    throw new Error('useUserActions must be used within UserProvider');
  }
  return context;
}

Zustand

Zustand 存储基础用法

import { create } from 'zustand';
import { persist, devtools } from 'zustand/middleware';

interface CartStore {
  items: CartItem[];
  addItem: (product: Product) => void;
  removeItem: (id: string) => void;
  updateQuantity: (id: string, quantity: number) => void;
  clearCart: () => void;
  total: () => number;
}

export const useCartStore = create<CartStore>()(
  devtools(
    persist(
      (set, get) => ({
        items: [],

        addItem: (product) =>
          set((state) => {
            const existing = state.items.find((item) => item.id === product.id);
            if (existing) {
              return {
                items: state.items.map((item) =>
                  item.id === product.id
                    ? { ...item, quantity: item.quantity + 1 }
                    : item
                ),
              };
            }
            return { items: [...state.items, { ...product, quantity: 1 }] };
          }),

        removeItem: (id) =>
          set((state) => ({
            items: state.items.filter((item) => item.id !== id),
          })),

        updateQuantity: (id, quantity) =>
          set((state) => ({
            items: state.items.map((item) =>
              item.id === id ? { ...item, quantity } : item
            ),
          })),

        clearCart: () => set({ items: [] }),

        total: () =>
          get().items.reduce(
            (sum, item) => sum + item.price * item.quantity,
            0
          ),
      }),
      { name: 'cart-storage' }
    )
  )
);

// Usage in component
function CartButton() {
  const items = useCartStore((state) => state.items);
  const total = useCartStore((state) => state.total());

  return (
    <button>
      Cart ({items.length}) - ${total.toFixed(2)}
    </button>
  );
}

在 Zustand 中使用 Immer

import { create } from 'zustand';
import { immer } from 'zustand/middleware/immer';

interface TodoStore {
  todos: Todo[];
  addTodo: (text: string) => void;
  toggleTodo: (id: string) => void;
  deleteTodo: (id: string) => void;
}

export const useTodoStore = create<TodoStore>()(
  immer((set) => ({
    todos: [],

    addTodo: (text) =>
      set((state) => {
        state.todos.push({
          id: crypto.randomUUID(),
          text,
          completed: false,
        });
      }),

    toggleTodo: (id) =>
      set((state) => {
        const todo = state.todos.find((t) => t.id === id);
        if (todo) {
          todo.completed = !todo.completed;
        }
      }),

    deleteTodo: (id) =>
      set((state) => {
        const index = state.todos.findIndex((t) => t.id === id);
        if (index !== -1) {
          state.todos.splice(index, 1);
        }
      }),
  }))
);

Jotai 和 TanStack Query

Jotai 基于 atom 的状态管理和 TanStack Query 服务端状态管理的详细模式——包括 atoms、派生 atoms、异步 atoms、query 客户端、mutation、失效处理、乐观更新和缓存调优——位于 references/jotai-and-tanstack-query.md。选择 atom 组合方式或生产级服务端状态缓存时，请加载该参考文档。

SWR

SWR 基本用法

import useSWR, { SWRConfig } from 'swr';

const fetcher = (url: string) => fetch(url).then((res) => res.json());

function App() {
  return (
    <SWRConfig
      value={{
        fetcher,
        refreshInterval: 0,
        revalidateOnFocus: true,
        dedupingInterval: 2000,
      }}
    >
      <Dashboard />
    </SWRConfig>
  );
}

function Dashboard() {
  const { data, error, isLoading, mutate } = useSWR('/api/dashboard');

  if (error) return <div>Failed to load</div>;
  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <h1>Dashboard</h1>
      <p>Total Users: {data.totalUsers}</p>
      <button onClick={() => mutate()}>Refresh</button>
    </div>
  );
}

SWR Mutation

import useSWRMutation from 'swr/mutation';

async function createUser(url: string, { arg }: { arg: CreateUserInput }) {
  const res = await fetch(url, {
    method: 'POST',
    body: JSON.stringify(arg),
  });
  return res.json();
}

function CreateUserForm() {
  const { trigger, isMutating } = useSWRMutation('/api/users', createUser);

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    await trigger({
      name: formData.get('name') as string,
      email: formData.get('email') as string,
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" required />
      <input name="email" type="email" required />
      <button disabled={isMutating}>
        {isMutating ? 'Creating...' : 'Create'}
      </button>
    </form>
  );
}

最佳实践

1. 选择合适的工具

场景	推荐方案
简单的本地状态	useState
复杂的本地状态	useReducer
共享状态（小型应用）	Context + useReducer
共享状态（大型应用）	Zustand 或 Jotai
服务端状态	TanStack Query 或 SWR

2. 避免逐层传递 props

// Instead of passing props through many levels
<Parent user={user}>
  <Child user={user}>
    <GrandChild user={user} />
  </Child>
</Parent>

// Use context or state management
<UserProvider>
  <Parent>
    <Child>
      <GrandChild /> {/* Access user via useUser() */}
    </Child>
  </Parent>
</UserProvider>

3. 规范化复杂状态

// Instead of nested objects
const badState = {
  posts: [
    { id: 1, title: 'Post 1', author: { id: 1, name: 'Alice' } },
    { id: 2, title: 'Post 2', author: { id: 1, name: 'Alice' } },
  ],
};

// Use normalized structure
const goodState = {
  posts: {
    byId: { 1: { id: 1, title: 'Post 1', authorId: 1 } },
    allIds: [1, 2],
  },
  authors: {
    byId: { 1: { id: 1, name: 'Alice' } },
    allIds: [1],
  },
};

其他参考资料

如需了解详细模式和高级用例，请参阅：

• references/zustand-patterns.md - 高级 Zustand 模式，包括切片、中间件和测试