React Hooks 速查表:17 个内置 hook + 10 个自定义 hook 范式,带真实例子和坑

const [count, setCount] = useState(0);
// functional form is mandatory when next depends on prev
const inc = () => setCount(c => c + 1);

// lazy initializer — fn runs once, not on every render
const [grid, setGrid] = useState(() => buildExpensiveGrid(1000));

type Action = { type: 'inc' } | { type: 'reset' };
function reducer(state: number, action: Action) {
  switch (action.type) {
    case 'inc': return state + 1;
    case 'reset': return 0;
  }
}
const [count, dispatch] = useReducer(reducer, 0);

// async flow modeled as a state machine
type S = { status: 'idle' | 'loading' | 'ok' | 'err'; data?: User };
type A = { type: 'start' } | { type: 'ok'; data: User } | { type: 'err' };

useEffect(() => {
  const id = setInterval(() => setTick(t => t + 1), 1000);
  return () => clearInterval(id);   // cleanup is mandatory for timers
}, []);

// subscribe + cleanup pattern
useEffect(() => {
  const onResize = () => setWidth(window.innerWidth);
  window.addEventListener('resize', onResize);
  return () => window.removeEventListener('resize', onResize);
}, []);

// data fetching with abort to avoid setState-after-unmount warning
useEffect(() => {
  const ctrl = new AbortController();
  fetch(`/api/user/${id}`, { signal: ctrl.signal })
    .then(r => r.json()).then(setUser).catch(() => {});
  return () => ctrl.abort();
}, [id]);

useLayoutEffect(() => {
  const { height } = ref.current!.getBoundingClientRect();
  setRowHeight(height);   // setState is safe — it batches before paint
}, []);

// styled-components-style use case
useInsertionEffect(() => {
  const tag = document.createElement('style');
  tag.textContent = generatedCss;
  document.head.appendChild(tag);
  return () => tag.remove();
}, [generatedCss]);

const visible = useMemo(
  () => items.filter(i => i.name.includes(query)).sort(byDate),
  [items, query],
);

// stabilize an object so memoized child does not re-render
const style = useMemo(() => ({ color, fontSize }), [color, fontSize]);

const onSelect = useCallback(
  (id: string) => setSelected(s => ({ ...s, [id]: true })),
  [],   // setSelected from useState is already stable
);

const inputRef = useRef<HTMLInputElement>(null);
useEffect(() => { inputRef.current?.focus(); }, []);
return <input ref={inputRef} />;

// instance value pattern — no re-render on change
const lastSeenRef = useRef(0);
function onScroll() { lastSeenRef.current = window.scrollY; }

const Input = forwardRef<{ focus: () => void }, Props>((props, ref) => {
  const inner = useRef<HTMLInputElement>(null);
  useImperativeHandle(ref, () => ({
    focus: () => inner.current?.focus(),
  }), []);
  return <input ref={inner} {...props} />;
});

const ThemeCtx = createContext<'light' | 'dark'>('light');
function Toolbar() {
  const theme = useContext(ThemeCtx);
  return <div className={theme}>...</div>;
}

const [isPending, startTransition] = useTransition();
function onChange(e: ChangeEvent<HTMLInputElement>) {
  setQuery(e.target.value);                 // urgent: input updates now
  startTransition(() => setList(filter(e.target.value))); // non-urgent
}

function Search({ query }: { query: string }) {
  const deferred = useDeferredValue(query);
  const isStale = deferred !== query;
  return (
    <div style={{ opacity: isStale ? 0.5 : 1 }}>
      <HeavyList query={deferred} />
    </div>
  );
}

function useOnline() {
  return useSyncExternalStore(
    (cb) => {
      window.addEventListener('online', cb);
      window.addEventListener('offline', cb);
      return () => {
        window.removeEventListener('online', cb);
        window.removeEventListener('offline', cb);
      };
    },
    () => navigator.onLine,
    () => true,  // SSR snapshot
  );
}

function Field({ label }: { label: string }) {
  const id = useId();
  return <><label htmlFor={id}>{label}</label><input id={id} /></>;
}

const [optimisticLikes, addLike] = useOptimistic(
  likes,
  (current, _: number) => current + 1,
);
async function onLike() {
  addLike(1);                   // UI updates immediately
  await serverLike(postId);     // real call
}

async function login(prev: State, fd: FormData): Promise<State> {
  const res = await api.login(fd.get('email'), fd.get('password'));
  return res.ok ? { user: res.user } : { error: res.message };
}
const [state, action, isPending] = useActionState(login, { user: null });
return <form action={action}>...</form>;

function SubmitButton() {
  const { pending } = useFormStatus();
  return <button type="submit" disabled={pending}>
    {pending ? 'Saving…' : 'Save'}
  </button>;
}

function User({ userPromise }: { userPromise: Promise<User> }) {
  const user = use(userPromise);   // suspends until resolved
  return <div>{user.name}</div>;
}

// conditional context read — useContext cannot do this
const value = condition ? use(CtxA) : use(CtxB);

function useToggle(initial = false) {
  const [on, setOn] = useState(initial);
  const toggle = useCallback(() => setOn(o => !o), []);
  return [on, toggle, setOn] as const;
}
const [open, toggleOpen] = useToggle();
<button onClick={toggleOpen}>{open ? 'Hide' : 'Show'}</button>

function useLocalStorage<T>(key: string, initial: T) {
  const [v, setV] = useState<T>(() => {
    if (typeof window === 'undefined') return initial;
    try { const raw = localStorage.getItem(key); return raw ? JSON.parse(raw) : initial; }
    catch { return initial; }
  });
  useEffect(() => { localStorage.setItem(key, JSON.stringify(v)); }, [key, v]);
  return [v, setV] as const;
}

function useDebounce<T>(value: T, delay = 300): T {
  const [v, setV] = useState(value);
  useEffect(() => {
    const id = setTimeout(() => setV(value), delay);
    return () => clearTimeout(id);
  }, [value, delay]);
  return v;
}

function useFetch<T>(url: string) {
  const [data, setData] = useState<T | null>(null);
  const [error, setError] = useState<Error | null>(null);
  const [loading, setLoading] = useState(true);
  useEffect(() => {
    const ctrl = new AbortController();
    setLoading(true);
    fetch(url, { signal: ctrl.signal })
      .then(r => r.json()).then(d => { setData(d); setLoading(false); })
      .catch(e => { if (e.name !== 'AbortError') { setError(e); setLoading(false); } });
    return () => ctrl.abort();
  }, [url]);
  return { data, error, loading };
}

function useMediaQuery(query: string) {
  const subscribe = (cb: () => void) => {
    const mql = window.matchMedia(query);
    mql.addEventListener('change', cb);
    return () => mql.removeEventListener('change', cb);
  };
  return useSyncExternalStore(
    subscribe,
    () => window.matchMedia(query).matches,
    () => false,
  );
}
const isMobile = useMediaQuery('(max-width: 768px)');

function useEventListener<K extends keyof WindowEventMap>(
  event: K,
  handler: (e: WindowEventMap[K]) => void,
) {
  const ref = useRef(handler);
  useEffect(() => { ref.current = handler; }, [handler]);
  useEffect(() => {
    const fn = (e: WindowEventMap[K]) => ref.current(e);
    window.addEventListener(event, fn);
    return () => window.removeEventListener(event, fn);
  }, [event]);
}

function useOnClickOutside(
  ref: RefObject<HTMLElement>,
  handler: (e: MouseEvent | TouchEvent) => void,
) {
  useEffect(() => {
    const fn = (e: MouseEvent | TouchEvent) => {
      const el = ref.current;
      if (!el || el.contains(e.target as Node)) return;
      handler(e);
    };
    document.addEventListener('mousedown', fn);
    document.addEventListener('touchstart', fn);
    return () => {
      document.removeEventListener('mousedown', fn);
      document.removeEventListener('touchstart', fn);
    };
  }, [ref, handler]);
}

function usePrevious<T>(value: T): T | undefined {
  const ref = useRef<T | undefined>(undefined);
  useEffect(() => { ref.current = value; }, [value]);
  return ref.current;
}
const prevCount = usePrevious(count);
const direction = prevCount === undefined ? 'init' : count > prevCount ? 'up' : 'down';

function useWindowSize() {
  const [size, setSize] = useState(() => ({
    width: typeof window === 'undefined' ? 0 : window.innerWidth,
    height: typeof window === 'undefined' ? 0 : window.innerHeight,
  }));
  useEffect(() => {
    let raf = 0;
    const onResize = () => {
      cancelAnimationFrame(raf);
      raf = requestAnimationFrame(() => {
        setSize({ width: window.innerWidth, height: window.innerHeight });
      });
    };
    window.addEventListener('resize', onResize);
    return () => { cancelAnimationFrame(raf); window.removeEventListener('resize', onResize); };
  }, []);
  return size;
}

function useInterval(cb: () => void, delay: number | null) {
  const ref = useRef(cb);
  useEffect(() => { ref.current = cb; }, [cb]);
  useEffect(() => {
    if (delay === null) return;
    const id = setInterval(() => ref.current(), delay);
    return () => clearInterval(id);
  }, [delay]);
}
useInterval(() => setNow(Date.now()), running ? 1000 : null);

function useTimeout(cb: () => void, delay: number | null) {
  const ref = useRef(cb);
  useEffect(() => { ref.current = cb; }, [cb]);
  useEffect(() => {
    if (delay === null) return;
    const id = setTimeout(() => ref.current(), delay);
    return () => clearTimeout(id);
  }, [delay]);
}
useTimeout(() => setVisible(false), visible ? 4000 : null);

function useIsMounted() {
  const mounted = useRef(false);
  useEffect(() => {
    mounted.current = true;
    return () => { mounted.current = false; };
  }, []);
  return useCallback(() => mounted.current, []);
}
const isMounted = useIsMounted();
await save(); if (isMounted()) setDone(true);

function useUpdateEffect(effect: () => void | (() => void), deps?: any[]) {
  const isFirst = useRef(true);
  useEffect(() => {
    if (isFirst.current) { isFirst.current = false; return; }
    return effect();
  }, deps);
}
useUpdateEffect(() => { syncUrl(filter); }, [filter]);

function useSet<T>(initial?: Iterable<T>) {
  const [set, setSet] = useState(() => new Set(initial));
  const actions = useMemo(() => ({
    add: (v: T) => setSet(s => new Set(s).add(v)),
    remove: (v: T) => setSet(s => { const n = new Set(s); n.delete(v); return n; }),
    toggle: (v: T) => setSet(s => { const n = new Set(s); n.has(v) ? n.delete(v) : n.add(v); return n; }),
    reset: () => setSet(new Set()),
  }), []);
  return [set, actions] as const;
}

function useCounter(initial = 0, { min = -Infinity, max = Infinity } = {}) {
  const clamp = (n: number) => Math.min(max, Math.max(min, n));
  const [count, setCount] = useState(clamp(initial));
  const actions = useMemo(() => ({
    inc: (step = 1) => setCount(c => clamp(c + step)),
    dec: (step = 1) => setCount(c => clamp(c - step)),
    set: (n: number) => setCount(clamp(n)),
    reset: () => setCount(clamp(initial)),
  }), []);
  return [count, actions] as const;
}

function useClipboard(resetMs = 1500) {
  const [copied, setCopied] = useState(false);
  const copy = useCallback(async (text: string) => {
    try {
      await navigator.clipboard.writeText(text);
      setCopied(true);
      setTimeout(() => setCopied(false), resetMs);
    } catch { setCopied(false); }
  }, [resetMs]);
  return { copy, copied };
}

function useHover<T extends HTMLElement>() {
  const [hovered, setHovered] = useState(false);
  const ref = useRef<T | null>(null);
  useEffect(() => {
    const node = ref.current;
    if (!node) return;
    const on = () => setHovered(true);
    const off = () => setHovered(false);
    node.addEventListener('mouseenter', on);
    node.addEventListener('mouseleave', off);
    return () => {
      node.removeEventListener('mouseenter', on);
      node.removeEventListener('mouseleave', off);
    };
  }, []);
  return [ref, hovered] as const;
}

function useIntersectionObserver(options?: IntersectionObserverInit) {
  const [entry, setEntry] = useState<IntersectionObserverEntry | null>(null);
  const ref = useRef<HTMLElement | null>(null);
  useEffect(() => {
    const node = ref.current;
    if (!node) return;
    const io = new IntersectionObserver(([e]) => setEntry(e), options);
    io.observe(node);
    return () => io.disconnect();
  }, [options?.root, options?.rootMargin, options?.threshold]);
  return [ref, entry] as const;
}

function useDocumentTitle(title: string, restore = false) {
  const prev = useRef(typeof document !== 'undefined' ? document.title : '');
  useEffect(() => {
    document.title = title;
  }, [title]);
  useEffect(() => {
    const previous = prev.current;
    return () => { if (restore) document.title = previous; };
  }, [restore]);
}

function useEventCallback<A extends any[], R>(fn: (...a: A) => R) {
  const ref = useRef(fn);
  useLayoutEffect(() => { ref.current = fn; });
  return useCallback((...args: A) => ref.current(...args), []);
}
const onScroll = useEventCallback(() => log(pageName, window.scrollY));

function useThrottle<T>(value: T, interval = 200): T {
  const [throttled, setThrottled] = useState(value);
  const last = useRef(Date.now());
  useEffect(() => {
    const now = Date.now();
    const remaining = interval - (now - last.current);
    if (remaining <= 0) { last.current = now; setThrottled(value); return; }
    const id = setTimeout(() => { last.current = Date.now(); setThrottled(value); }, remaining);
    return () => clearTimeout(id);
  }, [value, interval]);
  return throttled;
}

function useScrollLock(locked: boolean) {
  useLayoutEffect(() => {
    if (!locked) return;
    const root = document.documentElement;
    const prev = root.style.overflow;
    root.style.overflow = 'hidden';
    return () => { root.style.overflow = prev; };
  }, [locked]);
}

function useControllableState<T>({ value, defaultValue, onChange }: {
  value?: T; defaultValue?: T; onChange?: (v: T) => void;
}) {
  const isControlled = value !== undefined;
  const [uncontrolled, setUncontrolled] = useState(defaultValue);
  const state = isControlled ? value : uncontrolled;
  const setState = useCallback((next: T) => {
    if (!isControlled) setUncontrolled(next);
    onChange?.(next);
  }, [isControlled, onChange]);
  return [state, setState] as const;
}

function useRenderCount() {
  const count = useRef(0);
  count.current += 1;
  return count.current;
}
const renders = useRenderCount();
console.log('Table rendered', renders, 'times');

function useStateWithHistory<T>(initial: T) {
  const [history, setHistory] = useState<T[]>([initial]);
  const [ptr, setPtr] = useState(0);
  const set = useCallback((value: T) => {
    setHistory(h => [...h.slice(0, ptr + 1), value]);
    setPtr(p => p + 1);
  }, [ptr]);
  const undo = useCallback(() => setPtr(p => Math.max(0, p - 1)), []);
  const redo = useCallback(() => setPtr(p => Math.min(history.length - 1, p + 1)), [history.length]);
  return [history[ptr], set, {
    undo, redo, canUndo: ptr > 0, canRedo: ptr < history.length - 1,
  }] as const;
}

function useKeyPress(targetKey: string, handler: (e: KeyboardEvent) => void) {
  const ref = useRef(handler);
  useEffect(() => { ref.current = handler; }, [handler]);
  useEffect(() => {
    const onKey = (e: KeyboardEvent) => {
      if (e.key === targetKey) ref.current(e);
    };
    window.addEventListener('keydown', onKey);
    return () => window.removeEventListener('keydown', onKey);
  }, [targetKey]);
}
useKeyPress('Escape', () => setOpen(false));

function useDebouncedCallback<A extends any[]>(fn: (...a: A) => void, delay = 300) {
  const fnRef = useRef(fn);
  useEffect(() => { fnRef.current = fn; }, [fn]);
  const timer = useRef<ReturnType<typeof setTimeout>>();
  useEffect(() => () => clearTimeout(timer.current), []);
  return useCallback((...args: A) => {
    clearTimeout(timer.current);
    timer.current = setTimeout(() => fnRef.current(...args), delay);
  }, [delay]);
}
const save = useDebouncedCallback((draft: Draft) => api.save(draft), 800);

function useFavicon(href: string) {
  useEffect(() => {
    let link = document.querySelector<HTMLLinkElement>('link[rel="icon"]');
    if (!link) {
      link = document.createElement('link');
      link.rel = 'icon';
      document.head.appendChild(link);
    }
    link.href = href;
  }, [href]);
}
useFavicon(unread > 0 ? '/favicon-alert.ico' : '/favicon.ico');