React Hooks 深度解析

// 用一个极简实现理解"顺序依赖"的本质
let hookStates = [];
let hookIndex = 0;

function useStateMock(initial) {
  const currentIndex = hookIndex;
  hookStates[currentIndex] = hookStates[currentIndex] ?? initial;
  const setState = (value) => {
    hookStates[currentIndex] = value;
    render(); // 触发重新渲染
  };
  hookIndex++;
  return [hookStates[currentIndex], setState];
}

function render() {
  hookIndex = 0; // 每次渲染前重置索引，保证按相同顺序取值
  // ...调用组件函数
}
// 正因如此：Hook 必须无条件、按固定顺序调用，否则索引对不上

// useState 基础用法：函数式更新与惰性初始化
function Counter() {
  const [count, setCount] = useState(0);

  // 函数式更新：基于前值计算，避免闭包旧值问题
  const incrementThrice = () => {
    setCount(prev => prev + 1);
    setCount(prev => prev + 1);
    setCount(prev => prev + 1); // 连续 +3，若写 setCount(count+1) 只会 +1
  };

  // 惰性初始化：函数只在首次渲染执行一次
  const [data, setData] = useState(() => {
    const saved = localStorage.getItem('data');
    return saved ? JSON.parse(saved) : [];
  });

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={incrementThrice}>+3</button>
    </div>
  );
}

// useEffect 数据获取与竞态处理（cancelled 标志防止旧请求覆盖新结果）
function UserProfile({ userId }) {
  const [user, setUser] = useState(null);

  useEffect(() => {
    let cancelled = false;

    async function fetchUser() {
      const response = await fetch(`/api/users/${userId}`);
      const data = await response.json();
      if (!cancelled) setUser(data); // 组件已卸载或 userId 已变则不再 setState
    }

    fetchUser();
    return () => { cancelled = true; }; // 清理：标记本次请求作废
  }, [userId]);

  if (!user) return <div>Loading...</div>;
  return <div>{user.name}</div>;
}

// useRef 的两种典型用途
function RefExamples() {
  const inputRef = useRef(null);   // 用途一：访问 DOM
  const renderCount = useRef(0);   // 用途二：存可变值而不触发渲染

  renderCount.current++; // 记录渲染次数，改它不会引发新渲染

  const focusInput = () => inputRef.current?.focus();

  return (
    <div>
      <input ref={inputRef} type="text" />
      <button onClick={focusInput}>Focus Input</button>
      <p>已渲染 {renderCount.current} 次</p>
    </div>
  );
}

// useMemo 和 useCallback 优化：配合 React.memo 才有意义
const ChildList = React.memo(function ChildList({ items, onItemClick }) {
  return (
    <ul>
      {items.map(item => (
        <li key={item.id} onClick={() => onItemClick(item.id)}>{item.name}</li>
      ))}
    </ul>
  );
});

function ExpensiveComponent({ items, onItemClick }) {
  // 缓存昂贵的排序结果，仅在 items 变化时重算
  const sortedItems = useMemo(() => {
    console.log('Sorting items...');
    return [...items].sort((a, b) => a.name.localeCompare(b.name));
  }, [items]);

  // 缓存函数引用，避免每次渲染都给 memo 子组件传新函数导致其重渲染
  const handleClick = useCallback((id) => {
    onItemClick?.(id);
  }, [onItemClick]);

  return <ChildList items={sortedItems} onItemClick={handleClick} />;
}

// useReducer：把复杂更新逻辑集中到 reducer，组件只负责 dispatch
const initialState = { count: 0, step: 1 };

function reducer(state, action) {
  switch (action.type) {
    case 'increment': return { ...state, count: state.count + state.step };
    case 'decrement': return { ...state, count: state.count - state.step };
    case 'setStep':   return { ...state, step: action.payload };
    case 'reset':     return initialState;
    default:          throw new Error('Unknown action: ' + action.type);
  }
}

function Counter() {
  const [state, dispatch] = useReducer(reducer, initialState);
  return (
    <div>
      <p>Count: {state.count}</p>
      <button onClick={() => dispatch({ type: 'increment' })}>+{state.step}</button>
      <button onClick={() => dispatch({ type: 'decrement' })}>-{state.step}</button>
      <input type="number" value={state.step}
        onChange={e => dispatch({ type: 'setStep', payload: Number(e.target.value) })} />
      <button onClick={() => dispatch({ type: 'reset' })}>Reset</button>
    </div>
  );
}

// useLocalStorage：状态与 localStorage 双向同步
function useLocalStorage(key, initialValue) {
  const [storedValue, setStoredValue] = useState(() => {
    try {
      const item = localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch (error) {
      console.error(error);
      return initialValue;
    }
  });

  const setValue = useCallback((value) => {
    try {
      const valueToStore = value instanceof Function ? value(storedValue) : value;
      setStoredValue(valueToStore);
      localStorage.setItem(key, JSON.stringify(valueToStore));
    } catch (error) {
      console.error(error);
    }
  }, [key, storedValue]);

  return [storedValue, setValue];
}

function ThemeToggle() {
  const [theme, setTheme] = useLocalStorage('theme', 'light');
  return (
    <button onClick={() => setTheme(prev => prev === 'light' ? 'dark' : 'light')}>
      Current theme: {theme}
    </button>
  );
}

// useDebounce：延迟返回值，常用于搜索输入
function useDebounce(value, delay = 300) {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(timer); // 每次 value 变化重置计时
  }, [value, delay]);
  return debounced;
}

function SearchBox() {
  const [keyword, setKeyword] = useState('');
  const debouncedKeyword = useDebounce(keyword, 400);

  useEffect(() => {
    if (debouncedKeyword) fetch(`/api/search?q=${debouncedKeyword}`);
  }, [debouncedKeyword]); // 用户停止输入 400ms 后才真正请求

  return <input value={keyword} onChange={e => setKeyword(e.target.value)} />;
}

// useFetch：通用数据请求 Hook，封装 loading/error/竞态
function useFetch(url) {
  const [state, setState] = useState({ data: null, loading: true, error: null });

  useEffect(() => {
    let cancelled = false;
    setState({ data: null, loading: true, error: null });
    const controller = new AbortController();

    fetch(url, { signal: controller.signal })
      .then(res => {
        if (!res.ok) throw new Error('HTTP ' + res.status);
        return res.json();
      })
      .then(data => { if (!cancelled) setState({ data, loading: false, error: null }); })
      .catch(error => {
        if (!cancelled && error.name !== 'AbortError')
          setState({ data: null, loading: false, error });
      });

    return () => { cancelled = true; controller.abort(); };
  }, [url]);

  return state;
}

function useWindowSize() {
  const [size, setSize] = useState({ width: window.innerWidth, height: window.innerHeight });
  useEffect(() => {
    const handler = () => setSize({ width: window.innerWidth, height: window.innerHeight });
    window.addEventListener('resize', handler);
    return () => window.removeEventListener('resize', handler); // 卸载清理，防泄漏
  }, []);
  return size;
}

function Responsive() {
  const { width } = useWindowSize();
  return <div>{width < 768 ? '移动端布局' : '桌面布局'}</div>;
}

function Timer() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    const id = setInterval(() => {
      // 这里的 count 永远是首次渲染时的 0
      console.log('当前 count =', count);
    }, 1000);
    return () => clearInterval(id);
  }, []); // 空依赖：effect 只在挂载时执行一次

  return <button onClick={() => setCount(count + 1)}>{count}</button>;
}

// 方案一（推荐）：用函数式更新，彻底不依赖外部 count
function Timer() {
  const [count, setCount] = useState(0);
  useEffect(() => {
    const id = setInterval(() => {
      setCount(prev => prev + 1); // prev 始终是最新值，无需 count 进依赖
    }, 1000);
    return () => clearInterval(id);
  }, []); // 合法：内部不再引用 count
  return <div>{count}</div>;
}

// 方案二：把 count 加入依赖，每次变化重建定时器（会有重建开销）
useEffect(() => {
  const id = setInterval(() => console.log(count), 1000);
  return () => clearInterval(id);
}, [count]); // count 变则清理旧定时器、建新的

// 方案三：用 ref 保存最新值，effect 仍只建一次（适合高频场景）
function Timer() {
  const [count, setCount] = useState(0);
  const countRef = useRef(count);
  countRef.current = count; // 每次渲染同步最新值到 ref

  useEffect(() => {
    const id = setInterval(() => console.log(countRef.current), 1000);
    return () => clearInterval(id);
  }, []);
  return <div>{count}</div>;
}

// 反例：options 每次渲染都是新对象，effect 每次都执行
function Bad({ id }: { id: number }) {
  const options = { id, verbose: true }; // 每次渲染新引用
  useEffect(() => {
    doSomething(options);
  }, [options]); // 等于没有优化，每帧都跑
  return null;
}

// 正解：把真正的原始值放进依赖，或用 useMemo 稳定对象
function Good({ id }: { id: number }) {
  const options = useMemo(() => ({ id, verbose: true }), [id]);
  useEffect(() => {
    doSomething(options);
  }, [options]); // 仅 id 变时执行
  return null;
}

// 场景：根据元素实际宽度动态定位 tooltip，若用 useEffect 会先闪一下再归位
function Tooltip({ targetRect }: { targetRect: DOMRect }) {
  const ref = useRef<HTMLDivElement>(null);
  const [pos, setPos] = useState({ top: 0, left: 0 });

  // 用 useLayoutEffect：测量后同步 setState，在绘制前完成，用户看不到中间态
  useLayoutEffect(() => {
    const rect = ref.current!.getBoundingClientRect();
    setPos({
      top: targetRect.top - rect.height - 8,
      left: targetRect.left,
    });
  }, [targetRect]);

  return <div ref={ref} style={{ position: 'fixed', ...pos }}>提示内容</div>;
}

// 一个带完整 TS 类型的表单 reducer
interface FormState {
  values: { name: string; email: string };
  errors: Record<string, string>;
  submitting: boolean;
}

type FormAction =
  | { type: 'change'; field: 'name' | 'email'; value: string }
  | { type: 'submit_start' }
  | { type: 'submit_success' }
  | { type: 'submit_error'; errors: Record<string, string> }
  | { type: 'reset' };

const initialForm: FormState = {
  values: { name: '', email: '' },
  errors: {},
  submitting: false,
};

function formReducer(state: FormState, action: FormAction): FormState {
  switch (action.type) {
    case 'change':
      return {
        ...state,
        values: { ...state.values, [action.field]: action.value },
        errors: { ...state.errors, [action.field]: '' }, // 输入即清错
      };
    case 'submit_start':
      return { ...state, submitting: true, errors: {} };
    case 'submit_success':
      return { ...state, submitting: false };
    case 'submit_error':
      return { ...state, submitting: false, errors: action.errors };
    case 'reset':
      return initialForm;
    default: {
      // TS 穷尽性检查：新增 action 忘处理时编译期报错
      const _exhaustive: never = action;
      return state;
    }
  }
}

function SignupForm() {
  const [state, dispatch] = useReducer(formReducer, initialForm);

  const onSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    dispatch({ type: 'submit_start' });
    try {
      await api.signup(state.values);
      dispatch({ type: 'submit_success' });
    } catch (err) {
      dispatch({ type: 'submit_error', errors: { email: '邮箱已被注册' } });
    }
  };

  return (
    <form onSubmit={onSubmit}>
      <input
        value={state.values.name}
        onChange={e => dispatch({ type: 'change', field: 'name', value: e.target.value })}
      />
      <input
        value={state.values.email}
        onChange={e => dispatch({ type: 'change', field: 'email', value: e.target.value })}
      />
      {state.errors.email && <span>{state.errors.email}</span>}
      <button disabled={state.submitting}>提交</button>
    </form>
  );
}

// 用法一：usePrevious —— 记住上一次的值
function usePrevious<T>(value: T): T | undefined {
  const ref = useRef<T>();
  useEffect(() => {
    ref.current = value; // 渲染提交后才更新，所以渲染期间读到的是"上一次"
  }, [value]);
  return ref.current;
}

function PriceDisplay({ price }: { price: number }) {
  const prev = usePrevious(price);
  const trend = prev === undefined ? '' : price > prev ? '↑' : price < prev ? '↓' : '→';
  return <div>{price} {trend}</div>;
}

// 用法二：保存最新回调，避免 effect 频繁重建（Dan Abramov 的 useEventCallback 模式）
function useEventCallback<A extends unknown[], R>(fn: (...args: A) => R) {
  const ref = useRef(fn);
  useLayoutEffect(() => {
    ref.current = fn; // 每次渲染同步最新的 fn
  });
  return useCallback((...args: A) => ref.current(...args), []); // 返回引用永久稳定
}

// 用法三：标记"是否首次渲染"，跳过挂载时的 effect
function useUpdateEffect(effect: React.EffectCallback, deps?: React.DependencyList) {
  const isFirst = useRef(true);
  useEffect(() => {
    if (isFirst.current) {
      isFirst.current = false;
      return; // 首次挂载跳过
    }
    return effect();
  }, deps);
}

// 封装一个只暴露 focus / clear 两个命令的输入框
interface FancyInputHandle {
  focus: () => void;
  clear: () => void;
}

const FancyInput = forwardRef<FancyInputHandle, { placeholder?: string }>(
  function FancyInput(props, ref) {
    const inputRef = useRef<HTMLInputElement>(null);

    useImperativeHandle(ref, () => ({
      focus: () => inputRef.current?.focus(),
      clear: () => {
        if (inputRef.current) inputRef.current.value = '';
      },
    }), []); // 依赖数组决定 handle 何时重建，一般为空

    return <input ref={inputRef} placeholder={props.placeholder} />;
  }
);

function Parent() {
  const inputRef = useRef<FancyInputHandle>(null);
  return (
    <>
      <FancyInput ref={inputRef} placeholder="搜索" />
      <button onClick={() => inputRef.current?.focus()}>聚焦</button>
      <button onClick={() => inputRef.current?.clear()}>清空</button>
    </>
  );
}

// 误用一：给一个加法加 useMemo，纯属负优化
const sum = useMemo(() => a + b, [a, b]); // ❌ 比较开销 > 计算开销

// 误用二：useCallback 但子组件没被 memo 包裹，缓存白搭
const onClick = useCallback(() => doSomething(), []); // 若 <Child onClick> 未 memo，无意义

// 误用三：依赖写错导致缓存永不更新，读到旧值
const filtered = useMemo(() => list.filter(x => x.type === type), []); // ❌ 漏了 [list, type]

// 正确：三者协同才有意义
const Child = React.memo(function Child({ onAction }: { onAction: () => void }) {
  return <button onClick={onAction}>触发</button>;
});
function Parent({ list }: { list: Item[] }) {
  const heavy = useMemo(() => expensiveTransform(list), [list]); // 昂贵计算才缓存
  const onAction = useCallback(() => console.log(heavy.length), [heavy]); // 稳定引用
  return <Child onAction={onAction} />;
}

// useTransition：把状态更新标记为"非紧急"，避免大列表更新时输入卡顿
function SearchableList({ all }: { all: string[] }) {
  const [query, setQuery] = useState('');
  const [list, setList] = useState(all);
  const [isPending, startTransition] = useTransition();

  const onChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setQuery(e.target.value); // 紧急更新：输入框立刻响应
    startTransition(() => {
      // 非紧急更新：可被打断，不阻塞输入
      setList(all.filter(s => s.includes(e.target.value)));
    });
  };

  return (
    <>
      <input value={query} onChange={onChange} />
      {isPending && <span>过滤中…</span>}
      <ul>{list.map(s => <li key={s}>{s}</li>)}</ul>
    </>
  );
}

// useDeferredValue：给某个值一个"延迟版本"，效果类似防抖但由 React 调度
function Results({ query }: { query: string }) {
  const deferredQuery = useDeferredValue(query); // 高优先级更新时用旧值渲染
  const list = useMemo(() => search(deferredQuery), [deferredQuery]);
  const stale = query !== deferredQuery;
  return <div style={{ opacity: stale ? 0.5 : 1 }}>{list.length} 条结果</div>;
}

// useId：生成跨服务端/客户端一致的稳定 id，解决 SSR 水合不匹配
function Field({ label }: { label: string }) {
  const id = useId();
  return (
    <>
      <label htmlFor={id}>{label}</label>
      <input id={id} />
    </>
  );
}

// useSyncExternalStore：订阅外部数据源（Redux、浏览器 API），并发安全
function useOnlineStatus() {
  return useSyncExternalStore(
    (callback) => {
      window.addEventListener('online', callback);
      window.addEventListener('offline', callback);
      return () => {
        window.removeEventListener('online', callback);
        window.removeEventListener('offline', callback);
      };
    },
    () => navigator.onLine,   // 客户端快照
    () => true                // 服务端快照（SSR）
  );
}

// React 19：useOptimistic —— 乐观更新，请求返回前先展示预期结果
function MessageBox({ messages, send }: { messages: string[]; send: (m: string) => Promise<void> }) {
  const [optimistic, addOptimistic] = useOptimistic(
    messages,
    (state, newMsg: string) => [...state, newMsg + '（发送中…）']
  );

  const onSend = async (text: string) => {
    addOptimistic(text);      // 立刻显示
    await send(text);         // 真实请求，完成后 messages 更新覆盖乐观值
  };

  return <ul>{optimistic.map((m, i) => <li key={i}>{m}</li>)}</ul>;
}

// React 19：use() —— 可在渲染中读取 Promise 或 Context，且可条件调用
function Comments({ commentsPromise }: { commentsPromise: Promise<string[]> }) {
  const comments = use(commentsPromise); // 配合 <Suspense> 自动挂起
  return <ul>{comments.map((c, i) => <li key={i}>{c}</li>)}</ul>;
}
// 注意：use 是唯一可以在条件语句里调用的 "use 开头" API，它不是传统 Hook

// usePrevious 已在上文给出；这里补充 useToggle
function useToggle(initial = false): [boolean, () => void, (v: boolean) => void] {
  const [on, setOn] = useState(initial);
  const toggle = useCallback(() => setOn(v => !v), []);
  return [on, toggle, setOn];
}

// useEventListener：声明式绑定事件，自动清理，支持最新回调
function useEventListener<K extends keyof WindowEventMap>(
  eventName: K,
  handler: (event: WindowEventMap[K]) => void,
  element: Window | HTMLElement = window
) {
  const savedHandler = useRef(handler);
  useEffect(() => { savedHandler.current = handler; }, [handler]);

  useEffect(() => {
    const listener = (e: Event) => savedHandler.current(e as WindowEventMap[K]);
    element.addEventListener(eventName, listener);
    return () => element.removeEventListener(eventName, listener);
  }, [eventName, element]);
}

// useIntersectionObserver：元素进入视口时触发（懒加载、无限滚动）
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 observer = new IntersectionObserver(([e]) => setEntry(e), options);
    observer.observe(node);
    return () => observer.disconnect();
  }, [options]);

  return { ref, isIntersecting: entry?.isIntersecting ?? false, entry };
}

function LazyImage({ src }: { src: string }) {
  const { ref, isIntersecting } = useIntersectionObserver({ rootMargin: '200px' });
  return (
    <div ref={ref as React.RefObject<HTMLDivElement>}>
      {isIntersecting ? <img src={src} alt="" /> : <div style={{ height: 200 }} />}
    </div>
  );
}

// useMediaQuery：响应式断点判断，优于监听 resize（更省）
function useMediaQuery(query: string): boolean {
  const [matches, setMatches] = useState(() =>
    typeof window !== 'undefined' ? window.matchMedia(query).matches : false
  );
  useEffect(() => {
    const mql = window.matchMedia(query);
    const onChange = () => setMatches(mql.matches);
    mql.addEventListener('change', onChange);
    return () => mql.removeEventListener('change', onChange);
  }, [query]);
  return matches;
}

// useAsync：管理任意异步操作的状态机（idle / pending / success / error）
type AsyncState<T> =
  | { status: 'idle' }
  | { status: 'pending' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error };

function useAsync<T>(asyncFn: () => Promise<T>, immediate = true) {
  const [state, setState] = useState<AsyncState<T>>({ status: 'idle' });

  const run = useCallback(async () => {
    setState({ status: 'pending' });
    try {
      const data = await asyncFn();
      setState({ status: 'success', data });
    } catch (error) {
      setState({ status: 'error', error: error as Error });
    }
  }, [asyncFn]);

  useEffect(() => {
    if (immediate) run();
  }, [run, immediate]);

  return { ...state, run };
}

// .eslintrc 配置片段
{
  "plugins": ["react-hooks"],
  "rules": {
    "react-hooks/rules-of-hooks": "error",
    "react-hooks/exhaustive-deps": "warn"
  }
}

// ❌ 条件调用，破坏顺序
function Bad({ show }: { show: boolean }) {
  if (show) {
    const [x] = useState(0); // 报错：顺序不稳定
  }
}

// ✅ 无条件调用，把条件放进 Hook 内部或 JSX
function Good({ show }: { show: boolean }) {
  const [x, setX] = useState(0); // 永远调用
  return show ? <div>{x}</div> : null;
}

// 极简还原 React 内部的 Hook 链表结构
const fiber = {
  memoizedState: null, // 指向第一个 Hook 节点
};

function mountWorkInProgressHook() {
  const hook = { memoizedState: null, queue: null, next: null };
  if (fiber.memoizedState === null) {
    fiber.memoizedState = hook;          // 链表头
  } else {
    let last = fiber.memoizedState;
    while (last.next) last = last.next;  // 找到尾部
    last.next = hook;                    // 追加
  }
  return hook;
}
// 更新时则是沿着 next 指针"按序取节点"，这正是顺序不能变的根本原因