---
title: 前端-07-React
aliases:
  - React
  - React 19
  - JSX
  - Hooks
tags:
  - 前端/React
  - 类型/教程
created: 2026-10-11
updated: 2026-10-11
level: 进阶
prerequisites:
  - "[[前端-01-HTML基础]]"
  - "[[JavaScript-02-函数与作用域]]"
  - "[[JavaScript-07-ES6新特性]]"
  - "[[前端-05-TypeScript]]"
sources:
  - https://zh-hans.react.dev/learn
  - https://zh-hans.react.dev/learn/describing-the-ui
  - https://zh-hans.react.dev/learn/managing-state
  - https://zh-hans.react.dev/learn/escape-hatches
  - https://zh-hans.react.dev/reference/react/hooks
  - https://zh-hans.react.dev/reference/rules
  - https://zh-hans.react.dev/blog/2024/12/05/react-19
  - https://vite.dev/guide/
---

# 前端-07-React

> [!abstract] 这篇笔记讲什么
> React 是一个用于构建用户界面的 **JavaScript 库（Library）**，官方对它的定位只有一句话：**"用于构建 Web 和原生交互界面的库"**。当前最新主版本为 **React 19.3.0**（本库核实时间 2026-10-11，见 [[版本与官方资源速查]]）。
> 本篇以 **React 19 + TypeScript + 函数组件 + Hooks** 为主线，不涉及类组件（`class extends React.Component` 的写法已不再是官方推荐的教学路径，旧代码里仍会遇到）。
> 读完你应该能：用 Vite 建起 React + TS 项目、说清 JSX 编译成什么、写出不出无限循环的 `useEffect`、判断什么时候真的需要状态管理库、解释"为什么直接改 state 不触发更新"，并完成一个与 [[前端-06-Vue]] 版本对照的 TodoList。

---

## 一、是什么：React 的定位与核心思想

### 1.1 一句话定义

**React 是一个声明式的、基于组件的 JavaScript 库**：你把界面描述成组件的组合，把变化描述成状态的更新，React 负责在状态变化时算出最小必要的 DOM 操作。

注意用词是"**库**"而不是"框架"：React 官方只提供"组件 + 状态 + 渲染"这三件事，路由（React Router）、状态管理（Redux / Zustand）、数据请求（TanStack Query）、表单、样式方案全部由社区生态补齐。这与 [[前端-06-Vue]] 的"渐进式框架 + 官方全家桶"路线形成鲜明对比。

### 1.2 四个核心思想

| 思想 | 含义 | 具体体现 |
|---|---|---|
| **UI = f(state)** | 界面是状态的函数：给定同一份状态，渲染结果必然相同 | 组件就是接收 props 返回 JSX 的纯函数 |
| **组件化**（Component） | 一个组件 = 一段可复用的 UI + 它自己的逻辑与状态 | 函数组件是唯一的推荐写法 |
| **单向数据流**（One-way Data Flow） | 数据只能从父流向子，子不能改父的数据 | props 只读；要改就调用父传下来的回调 |
| **不可变更新**（Immutable Update） | 更新状态时创建新对象/新数组，而不是改原对象 | `setItems([...items, x])` 而不是 `items.push(x)` |

### 1.3 声明式 vs 命令式：React 让你少写什么

同一个需求：点按钮给列表加一项，并显示总数。

**命令式（原生 DOM）**：

```js
let count = 0
const list = document.querySelector('#list')
const total = document.querySelector('#total')

document.querySelector('#add').addEventListener('click', () => {
  count++
  // 你必须手写：创建节点、填内容、插入、再同步派生数据
  const li = document.createElement('li')
  li.textContent = `条目 ${count}`
  list.appendChild(li)
  total.textContent = String(count)
})
```

**声明式（React 19）**：

```tsx
export default function App() {
  const [items, setItems] = useState<string[]>([])

  return (
    <>
      <ul>
        {items.map((item) => (
          <li key={item}>{item}</li>
        ))}
      </ul>
      <span>{items.length}</span>
      <button onClick={() => setItems([...items, `条目 ${items.length + 1}`])}>添加</button>
    </>
  )
}
```

**你只负责"状态变成什么样"，DOM 怎么变由 React 决定。** 要加筛选、加删除，都只改数据。

| 对比维度 | 命令式（原生 DOM / jQuery） | 声明式（React） |
|---|---|---|
| 你写的是 | 操作步骤 | 状态与视图的对应关系 |
| 状态存放 | 常散落在闭包与 DOM 中 | 集中在 `useState` / `useReducer` |
| 派生数据 | 手动同步（容易忘） | 渲染时算出来（`items.length`） |
| 性能优化方式 | 精确手动控制 | 先正确，再用 `memo` / `useMemo` 定位瓶颈 |
| 心智负担 | 随交互数量增长 | 随状态数量增长 |

形式化地说，React 保证的是：

$$
\text{DOM} = f(\text{state}) \qquad \text{且} \quad \text{state}_t \Rightarrow \text{DOM}_t \ \text{（同一状态必得同一界面）}
$$

这也是"组件必须是纯函数"这条规则的根本原因：只要渲染有副作用或依赖外部可变数据，$f$ 就不再是函数，界面就无法预测。

---

## 二、为什么这样设计

### 2.1 为什么要"重新执行整个组件函数"

React 的更新模型很"笨"也很可靠：状态变化 → **重新调用组件函数** → 得到新的 JSX 树（虚拟 DOM）→ 与上一次的树对比（Reconciliation）→ 只把差异写进真实 DOM。

好处是心智模型极简：你不需要知道"哪个 DOM 节点对应哪个数据"，只需要保证"函数在给定 props/state 下返回正确的界面"。代价是每次更新都会重新执行组件函数（因此有 `memo`、`useMemo` 这类优化 API），以及必须遵守不可变更新（否则新旧树看起来一样，diff 就发现不了变化）。

### 2.2 为什么 props 是只读的

如果子组件能改父组件的数据，任何一次界面异常都要回溯整棵组件树去找"谁改的"。React 用"props 只读 + 回调上报"把数据流约束成单向的：**数据向下流，事件向上走**。这样任何一份数据的"修改入口"都是唯一的，调试范围立刻收敛。

### 2.3 为什么 Hooks 必须写在顶层

React 内部用**调用顺序**来把 Hook 与组件实例对应起来：第 1 个 `useState` 是 A，第 2 个是 B。如果 Hook 写在 `if` 或循环里，某次渲染少调用了"第 2 个"，那么后面的 Hook 就会错误地拿到"第 2 个"的状态槽，状态全部错位。所以规则不是"风格建议"，而是运行时机制决定的硬约束。

### 2.4 为什么现在少用 `create-react-app`

| 对比项 | Vite（当前推荐） | `create-react-app`（CRA） |
|---|---|---|
| 开发服务器 | 原生 ESM 按需编译，启动快、HMR 快 | Webpack 全量打包，项目变大后启动明显变慢 |
| 维护状态 | 活跃 | 已停止维护（React 官方文档与 CRA 仓库均已不再推荐） |
| 配置自由度 | `vite.config.ts` 一处搞定 | 想改配置需要 `eject`，不可逆 |
| SSR / 框架方向 | 可用 Vite 生态，或直接用 Next.js 等框架 | 无官方路径 |
| 该选谁 | 单页应用、组件库、想理解构建流程 | 仅存在于历史项目中 |

> [!tip] 官方文档的三个起步选项
> React 官方文档的"开始使用"章节给出的路径是：① **框架**（如 Next.js / Remix，适合需要路由、数据获取、SSR 的完整应用）；② **从零构建**（用 Vite 等打包工具，适合纯客户端 SPA 与学习）；③ **CDN 引入**（适合在已有页面里试用一个小部件）。具体推荐列表**以官方最新文档为准**。

---

## 三、核心内容

### 3.1 创建项目

```bash
# 需要 Node.js 18+ / 20+（具体下限以官方最新文档为准）
npm create vite@latest my-react-app -- --template react-ts
cd my-react-app
npm install
npm run dev     # http://localhost:5173
npm run build   # 产物在 dist/
npm run preview # 本地预览生产构建
```

生成的关键文件：

```jsonc
// package.json（关键部分）
{
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build", // 先类型检查，再打包
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^19.3.0",
    "react-dom": "^19.3.0"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^5.0.0",
    "typescript": "~5.9.0",
    "vite": "^8.0.0"
  }
}
```

```tsx
// src/main.tsx：入口
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import App from './App.tsx'
import './index.css'

// React 18 起的客户端 API：createRoot 取代了 ReactDOM.render
createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
)
```

> [!warning] StrictMode 会让开发环境的副作用执行两次
> `<StrictMode>` 在**开发环境**会故意把组件函数与 `useEffect` 的挂载/卸载多跑一遍，用来暴露"没写清理函数"和"渲染时有副作用"的问题。这不是 bug：**如果它让你的代码出错，说明代码本身有问题**。生产构建不会重复执行。

### 3.2 JSX

#### 3.2.1 JSX 本质是语法糖

JSX 不是 HTML 也不是字符串，而是**函数调用的语法糖**。现代构建工具（Vite 的 React 插件、Babel、TypeScript）默认使用 **Automatic Runtime** 转换：

```tsx
// 你写的
const el = <h1 className="title">Hello {name}</h1>

// 编译后（自动运行时，自动注入 jsx 导入）+ 格式化后等价于：
import { jsx as _jsx } from 'react/jsx-runtime'

const el = _jsx('h1', {
  className: 'title',
  children: ['Hello ', name],
})
```

一次 `<App />` 组件调用的编译结果同样是普通函数调用：

```tsx
// 你写的
return <App count={1} />

// 编译后
return _jsx(App, { count: 1 })
```

因此 JSX 里可以放**任何 JavaScript 表达式**：`{2 + 2}`、`{items.map(...)}`、`{cond ? <A /> : <B />}`，因为它们最终都只是函数参数。

```tsx
// 需要多行/多元素时用 Fragment 包裹，它不产生额外 DOM 节点
const list = (
  <>
    <li>第一项</li>
    <li>第二项</li>
  </>
)
// 等价于 <React.Fragment>...</React.Fragment>
```

#### 3.2.2 与 HTML 的差异清单

| 项目 | HTML | JSX | 原因 |
|---|---|---|---|
| class 属性 | `class="box"` | `className="box"` | `class` 是 JS 保留字 |
| label 关联 | `for="id"` | `htmlFor="id"` | 同上 |
| 自闭合 | `<img>` / `<br>` | `<img />` / `<br />` **必须闭合** | JSX 是表达式，必须结构完整 |
| 插入表达式 | 无 | `{expr}`，属性值也用 `{}` | 属性值是 JS 值：`value={n}` |
| 字符串属性 | `title=hello` | `title="hello"` | 不加引号会被当成变量 |
| 条件渲染 | 无 | `{cond && <A />}` 或三元 | 表达式只能是表达式 |
| 列表渲染 | 手写重复节点 | `{items.map(i => <li key={i.id} />)}` | `key` 帮助 React 识别身份 |
| style | `style="color:red"` | `style={{ color: 'red' }}` | 值是对象，属性名用 camelCase |
| 事件名 | `onclick`（小写） | `onClick`（小驼峰） | 属性名映射到 React 的合成事件系统 |
| 注释 | `<!-- -->` | `{/* */}` | 在大括号里写 JS 注释 |
| 布尔属性 | `disabled` | `disabled={true}` 或省略 | 值是 JS 布尔值 |
| 自定义属性 | 任意 | `data-*` / `aria-*` 原样透传 | 其它未识别属性在 React 19 会原样透传给 DOM（**以官方最新文档为准**） |

几个容易写错的例子：

```tsx
// ❌ 两个相邻元素没有父节点
return <li>a</li><li>b</li>

// ✅ Fragment
return (
  <>
    <li>a</li>
    <li>b</li>
  </>
)

// ❌ 0 会被渲染出来
{items.length && <List />}

// ✅ 显式判断
{items.length > 0 && <List />}

// ✅ 三元：二选一
{isLoading ? <Spinner /> : <List items={items} />}
```

#### 3.2.3 `key` 的作用，以及为什么不能用数组索引

`key` 是 React 在协调（Reconciliation）时判断"新旧列表里哪个元素是同一个"的**身份标识**。有了稳定的 key，React 才能复用对应的 DOM 节点与组件状态、正确搬运节点，而不是逐个重建。

```tsx
// ❌ 索引作 key：删除 / 排序后身份错位
{items.map((item, index) => (
  <Row key={index} item={item} />
))}

// ✅ 业务 id 作 key
{items.map((item) => (
  <Row key={item.id} item={item} />
))}
```

为什么索引会出问题：假设列表是 `[A, B, C]`，key 为 `0,1,2`；删除 A 后新列表是 `[B, C]`，key 变成 `0,1`。React 认为"key=0 这一项还在，只是内容从 A 变成了 B"，于是**复用原有 DOM 与组件状态**（比如输入框里用户已输入的内容、展开状态、动画状态），把它们错配到别的数据上。

| key 选择 | 结果 | 什么时候能用 |
|---|---|---|
| 稳定的业务 id | 身份正确，状态与数据一一对应 | 默认选择 |
| 数组索引 | 中间增删/排序时状态错位 | 仅"只追加、不删除、不排序、项内无状态" |
| `Math.random()` / 时间戳 | **每次渲染都重建整棵子树**，性能与状态全毁 | 永远不要 |
| 复合键 `${id}-${type}` | 同一数据在不同列表位置需要独立状态时有用 | 明确知道自己在做什么时 |

> [!tip] 一个实用技巧
> key 变化会让组件**重新挂载**、状态重置。可以利用这一点：想让"切换到另一个用户时表单清空"，给表单加 `key={userId}` 比写一堆 `useEffect` 重置状态更简洁可靠。

### 3.3 组件与 Props

#### 3.3.1 函数组件与 props

```tsx
// React 19 + TS 的推荐写法：直接用函数类型标注 props
type AvatarProps = {
  src: string
  alt?: string
  size?: 'sm' | 'md' | 'lg'
}

const SIZE_MAP = { sm: 24, md: 40, lg: 64 } as const

export function Avatar({ src, alt = '头像', size = 'md' }: AvatarProps) {
  // props 只读：下面这行会报错（TS 层面就无法通过）
  // alt = '其它'

  const px = SIZE_MAP[size]
  return <img src={src} alt={alt} width={px} height={px} style={{ borderRadius: '50%' }} />
}
```

```tsx
// React 18 及以前的常见写法（仍可用，但类型更啰嗦）
import type { FC } from 'react'
const Avatar: FC<AvatarProps> = ({ src }) => <img src={src} />
```

| 写法 | 评价 |
|---|---|
| `function Comp(props: Props)` | **推荐**，类型推导自然，便于泛型组件 |
| `const Comp = (props: Props) => ...` | 同样可以，但函数声明在堆栈里更好认 |
| `React.FC<Props>` | 旧风格；早期版本的隐式 `children` 会造成误导，现已收敛，但没必要用 |

#### 3.3.2 `children` 与组合优于继承

```tsx
import type { ReactNode } from 'react'

type CardProps = {
  title: string
  children: ReactNode          // children 只是普通的 prop
  footer?: ReactNode
}

export function Card({ title, children, footer }: CardProps) {
  return (
    <section className="card">
      <h3>{title}</h3>
      <div className="card-body">{children}</div>
      {footer && <footer>{footer}</footer>}
    </section>
  )
}

// 使用：内容由调用方决定，Card 不关心里面是什么
;<Card title="用户信息" footer={<button>编辑</Button>}>
  <p>张三，20 岁</p>
</Card>
```

> [!important] 组合优于继承
> React 没有"组件继承"这套机制，也**不需要**。要复用 UI，就用 `children`（内容交给调用方）、具名 prop 传 ReactNode（多个插槽位）、或抽取自定义 Hook 复用逻辑。**用一个布尔 prop 控制一堆 if，通常是拆分或插槽的信号**。

**拆分原则**：① UI 在两处以上出现；② 组件自己有状态且与父级无关；③ 组件文件超过约 200 行、或需要频繁上下滚动才能读完；④ 某部分有独立的性能优化需求（要包 `memo`）。

### 3.4 State 与 Hooks

#### 3.4.1 `useState` 的异步与批量更新

```tsx
import { useState } from 'react'

export function Counter() {
  const [count, setCount] = useState(0)
  const [flag, setFlag] = useState(false)

  function handleClick() {
    // ❌ 三次都基于"本次渲染时的 count"计算，结果只加 1
    setCount(count + 1)
    setCount(count + 1)
    setCount(count + 1)

    // ✅ 函数式更新：每次拿到"最新的待提交值"
    setCount((prev) => prev + 1)
    setCount((prev) => prev + 1)
    setCount((prev) => prev + 1)

    // 同一事件处理器里的多个 setState 会被"批量更新（Batching）"，
    // 只触发一次重新渲染（React 18 起自动批量，包括异步回调里）
    setFlag((f) => !f)

    console.log(count) // 仍然是本次渲染的值，state 更新是"异步"的
  }

  return <button onClick={handleClick}>点了 {count} 次</button>
}
```

| 现象 | 原因 | 正确写法 |
|---|---|---|
| `setCount(count + 1)` 连续三次只加 1 | `count` 是本次渲染的快照，三次读到同一个值 | `setCount(p => p + 1)` |
| 调用 `setState` 后立刻 `console.log` 还是旧值 | 更新被排队，本次执行上下文里的变量不会变 | 在事件处理里自己算一份，或用 `useEffect` 观察 |
| 连续两次 `setState` 只重渲染一次 | 自动批量更新（Batching） | 无需处理，这是优化 |
| `setState` 相同值时组件仍重渲染一次 | React 用 `Object.is` 比较；相同则跳过渲染，但可能已进入调度 | 不需要手动 `if` 拦截，除非值计算代价很高 |

**什么时候必须用函数式更新**：① 新值依赖旧值；② 在 `setTimeout`、`Promise.then`、事件订阅回调里更新（那里的闭包可能已经过期）；③ 同一个值被连续更新多次。

#### 3.4.2 `useEffect` 的依赖数组三种情况

```tsx
import { useEffect, useState } from 'react'

export function Timer({ userId }: { userId: number }) {
  const [seconds, setSeconds] = useState(0)

  // ① 没有依赖数组：每次渲染后都执行 → 绝大多数情况下是错的
  useEffect(() => {
    console.log('每次渲染后执行')
  })

  // ② 空数组：只在挂载后执行一次（开发环境 StrictMode 会跑两遍用于暴露问题）
  useEffect(() => {
    console.log('只在挂载后执行一次')
  }, [])

  // ③ 有依赖：挂载后 + 依赖变化后执行
  useEffect(() => {
    setSeconds(0) // 切换用户时重置计时
    const id = window.setInterval(() => setSeconds((s) => s + 1), 1000)

    // 清理函数：在"下次 effect 执行前"和"组件卸载时"调用
    return () => window.clearInterval(id)
  }, [userId]) // 依赖必须写全：effect 里用到的所有响应式值都要列上

  return <p>用户 {userId} 已停留 {seconds} 秒</p>
}
```

| 依赖数组 | 执行时机 | 典型用途 | 风险 |
|---|---|---|---|
| 省略 | 每次渲染后 | 极少（如需要与 DOM 同步的测量） | 极易造成无限循环 |
| `[]` | 挂载后一次 | 订阅、初始化第三方库、只执行一次的请求 | 用到 props/state 时会捕获过期值（stale closure） |
| `[a, b]` | 挂载后 + `a`/`b` 变化后 | 按参数重新取数、重新订阅 | 漏写依赖 → 读取到旧值 |
| `return () => {}` | 清理函数 | 取消定时器、取消订阅、abort 请求 | 不写清理 → 内存泄漏、重复订阅 |

**副作用的四种正确去向**（先问"这真的需要 effect 吗"）：

| 需求 | 不要用 effect | 应该怎么做 |
|---|---|---|
| 由 props/state 派生的值 | 用 effect 同步到另一个 state | 直接在渲染时算（或 `useMemo`） |
| 用户操作触发的请求 | —— | 在事件处理函数里发 |
| 父组件传 prop 变化时重置子组件状态 | 用 effect 里 `setX` | 用 `key` 让组件重新挂载 |
| 真正的外部同步（订阅、定时器、DOM 测量、非 React 组件） | —— | **这才是 effect 的用途** |

#### 3.4.3 无限循环的成因与排查

```tsx
// ❌ 成因一：effect 里 set 的 state 又是该 effect 的依赖
const [count, setCount] = useState(0)
useEffect(() => {
  setCount(count + 1) // 改了 count → 依赖 count 变化 → 再次执行 → 死循环
}, [count])

// ❌ 成因二：依赖是每次渲染都新建的对象/数组/函数
const [user, setUser] = useState({ id: 1 })
useEffect(() => {
  fetchData() // 每次都执行
}, [{ id: user.id }]) // 字面量每次都是新引用，永远不相等
useEffect(() => {}, [() => {}]) // 内联函数同理

// ❌ 成因三：渲染期间直接调用 setState（没有条件保护）
function Bad() {
  const [n, setN] = useState(0)
  setN(n + 1) // 渲染 → setState → 重新渲染 → …… 报 "Too many re-renders"
  return null
}
```

```tsx
// ✅ 修法一：用函数式更新 + 空依赖（effect 不依赖 count）
useEffect(() => {
  const id = window.setInterval(() => setCount((c) => c + 1), 1000)
  return () => window.clearInterval(id)
}, [])

// ✅ 修法二：把对象/函数依赖用 useMemo / useCallback 稳定下来，
//           或改成依赖它的原始值
useEffect(() => {
  void fetchData(user.id)
}, [user.id]) // 依赖原始值，而不是每次新建的对象

// ✅ 修法三：只在渲染期间计算派生值，不要 setState
const doubled = n * 2
```

> [!warning] 排查无限循环的四步
> ① 打开控制台看是否有 `Maximum update depth exceeded` 或 `Too many re-renders`；
> ② 用 `console.trace()` 放进可疑的 effect，看是谁在反复触发；
> ③ 逐条检查依赖：**effect 里 set 的 state 是否出现在依赖里**（最经典）；
> ④ 检查依赖是否是对象/数组/函数字面量——如果是，改成原始值依赖或用 `useCallback` 包一层。

#### 3.4.4 `useRef` 的两种用途

```tsx
import { useRef, useState } from 'react'

export function SearchBox() {
  // 用途一：引用 DOM 节点（React 19 起 ref 是普通 prop，函数组件无需 forwardRef）
  const inputRef = useRef<HTMLInputElement>(null)

  // 用途二：保存"不需要触发渲染"的可变值
  const timerRef = useRef<number | undefined>(undefined)
  const renderCountRef = useRef(0)
  renderCountRef.current += 1 // 改 ref 不会重新渲染

  function focusInput() {
    inputRef.current?.focus()
  }

  function onInput() {
    window.clearTimeout(timerRef.current)
    timerRef.current = window.setTimeout(() => console.log('防抖请求'), 300)
  }

  return (
    <div>
      <input ref={inputRef} onInput={onInput} />
      <button onClick={focusInput}>聚焦</button>
      <p>渲染次数（不触发更新）：{renderCountRef.current}</p>
    </div>
  )
}
```

| 对比项 | `useState` | `useRef` |
|---|---|---|
| 值变化是否触发渲染 | 是 | **否** |
| 是否在渲染间保持 | 是 | 是 |
| 是否应参与渲染输出 | 是（界面依赖它） | 否（否则界面会与数据不同步） |
| 典型用途 | 界面要显示的数据 | DOM 引用、定时器 id、上一次的值、渲染计数 |

#### 3.4.5 `useMemo` 与 `useCallback`

```tsx
import { useCallback, useMemo, useState } from 'react'

export function ProductList({ products }: { products: Product[] }) {
  const [keyword, setKeyword] = useState('')
  const [sortAsc, setSortAsc] = useState(true)

  // useMemo：缓存"计算结果"，依赖不变就复用
  const visible = useMemo(() => {
    return products
      .filter((p) => p.name.includes(keyword))
      .sort((a, b) => (sortAsc ? a.price - b.price : b.price - a.price))
  }, [products, keyword, sortAsc])

  // useCallback：缓存"函数引用"，依赖不变就复用同一个函数对象
  // 主要用于：传给 memo 包裹的子组件，或作为其它 Hook 的依赖
  const handleAdd = useCallback((id: number) => {
    console.log('加入购物车', id)
  }, []) // 只用了 setState 与常量，依赖可以为空

  return (
    <>
      <input value={keyword} onChange={(e) => setKeyword(e.target.value)} />
      <button onClick={() => setSortAsc((v) => !v)}>切换排序</button>
      {visible.map((p) => (
        <Row key={p.id} product={p} onAdd={handleAdd} />
      ))}
    </>
  )
}
```

| Hook | 缓存什么 | 有效的前提 | 无效（纯亏）的情况 |
|---|---|---|---|
| `useMemo` | 计算结果 | 计算代价高（大数据集遍历、复杂推导），或结果要作为其它 Hook 的依赖 | 简单运算（`a + b`）——缓存本身的开销可能更大 |
| `useCallback` | 函数引用 | 函数要传给 `memo` 子组件，或作为 effect 依赖 | 函数只在本组件内用，不传给子组件 |

> [!warning] 过度优化的代价
> ① `useMemo` / `useCallback` 自身有开销：每次渲染都要比较依赖数组；
> ② 依赖写错会引入"值不更新"的诡异 bug，比性能问题更难查；
> ③ React 官方明确保留"未来可能丢弃缓存"的权利——**语义正确性不能依赖缓存一定命中**（`useMemo` 是性能优化，不是语义保证）；
> ④ 真正有效的手段往往是"把状态往下挪（让 state 离使用它的组件更近）"、"用 `children` 把不变化的子树传进去"，而不是到处包 `memo`。

#### 3.4.6 `useContext`

```tsx
import { createContext, useContext, useMemo, useState, type ReactNode } from 'react'

type Theme = 'light' | 'dark'
type ThemeContextValue = { theme: Theme; toggle: () => void }

// 默认值只在"没有 Provider"时生效；实际项目里常设为 null 并做断言
const ThemeContext = createContext<ThemeContextValue | null>(null)

export function ThemeProvider({ children }: { children: ReactNode }) {
  const [theme, setTheme] = useState<Theme>('light')

  // value 每次渲染都会新建对象 → 所有消费者都会重渲染
  // 用 useMemo 稳定引用，是 Context 最常见的性能修复
  const value = useMemo<ThemeContextValue>(
    () => ({ theme, toggle: () => setTheme((t) => (t === 'light' ? 'dark' : 'light')) }),
    [theme],
  )

  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
}

// 自定义 Hook 封装 useContext：集中处理"未包裹 Provider"的错误
export function useTheme() {
  const ctx = useContext(ThemeContext)
  if (!ctx) throw new Error('useTheme 必须在 <ThemeProvider> 内使用')
  return ctx
}
```

```tsx
// React 19 起可以直接渲染 <Context> 作为 Provider（以官方最新文档为准）
<ThemeContext value={value}>{children}</ThemeContext>
```

| Context 适合 | Context 不适合 |
|---|---|
| 低频变化、全局读取的配置：主题、语言、当前用户 | 高频变化的数据（每次变化会让所有消费者重渲染） |
| 避免多层 props 透传（prop drilling） | 当作"全局 store"存放大量互不相关的状态 |
| 与 `useReducer` 组合做轻量状态管理 | 需要中间件、时间旅行调试、跨 store 依赖时（改选 Zustand/Redux） |

#### 3.4.7 自定义 Hook

规则只有两条：**名字必须以 `use` 开头**（否则 React 不会按 Hook 规则检查它），**内部调用的 Hook 必须在顶层**。它只是"把逻辑抽出来的函数"，不共享状态——两个组件调用同一个自定义 Hook，各自拿到独立的状态。

```tsx
// src/hooks/useDebounce.ts
import { useEffect, useState } from 'react'

/**
 * 返回防抖后的值：只有 value 停止变化 delay 毫秒后才更新。
 * 用途：搜索框输入时避免每次按键都发请求。
 */
export function useDebounce<T>(value: T, delay = 300): T {
  const [debounced, setDebounced] = useState(value)

  useEffect(() => {
    const id = window.setTimeout(() => setDebounced(value), delay)
    // 清理：value 再次变化时取消上一次的定时器，这就是"防抖"的实现
    return () => window.clearTimeout(id)
  }, [value, delay])

  return debounced
}
```

```tsx
// src/hooks/useFetch.ts：带取消与错误处理的数据请求 Hook
import { useEffect, useState } from 'react'

interface State<T> {
  data: T | null
  loading: boolean
  error: string | null
}

export function useFetch<T>(url: string): State<T> & { refetch: () => void } {
  const [state, setState] = useState<State<T>>({ data: null, loading: true, error: null })
  // 用一个自增值作为"重新请求"的触发器
  const [nonce, setNonce] = useState(0)

  useEffect(() => {
    // 关键：用 AbortController 在依赖变化/卸载时取消在途请求
    const controller = new AbortController()
    let alive = true // 双保险：即便 abort 未生效也不再 setState

    setState({ data: null, loading: true, error: null })

    fetch(url, { signal: controller.signal })
      .then((res) => {
        if (!res.ok) throw new Error(`HTTP ${res.status}`)
        return res.json() as Promise<T>
      })
      .then((data) => {
        if (alive) setState({ data, loading: false, error: null })
      })
      .catch((err: unknown) => {
        // abort 引发的中断不是错误，必须忽略，否则切页面会误报
        if (err instanceof DOMException && err.name === 'AbortError') return
        if (alive) setState({ data: null, loading: false, error: (err as Error).message })
      })

    return () => {
      alive = false
      controller.abort()
    }
  }, [url, nonce])

  return { ...state, refetch: () => setNonce((n) => n + 1) }
}
```

```tsx
// 使用两个自定义 Hook 做"输入 → 防抖 → 请求"
import { useState } from 'react'
import { useDebounce } from '@/hooks/useDebounce'
import { useFetch } from '@/hooks/useFetch'

interface Article { id: number; title: string }

export function ArticleSearch() {
  const [keyword, setKeyword] = useState('')
  const debounced = useDebounce(keyword, 400)
  const { data, loading, error } = useFetch<Article[]>(`/api/articles?q=${encodeURIComponent(debounced)}`)

  return (
    <div>
      <input value={keyword} onChange={(e) => setKeyword(e.target.value)} placeholder="搜索文章" />
      {loading && <p>加载中…</p>}
      {error && <p>出错了：{error}</p>}
      <ul>
        {data?.map((a) => (
          <li key={a.id}>{a.title}</li>
        ))}
      </ul>
    </div>
  )
}
```

### 3.5 Hooks 规则

| 规则 | 内容 | 违反了会怎样 |
|---|---|---|
| 只在**顶层**调用 | 不能放在 `if`、`for`、`while`、`try/catch`、嵌套函数里 | 运行时 Hook 顺序错位，状态串位甚至崩溃 |
| 只在 **React 函数**里调用 | 函数组件或自定义 Hook 内 | ESLint 报错；React 无法关联到实例 |
| 依赖数组要写全 | effect 里用到的所有响应式值 | 读取过期值（stale closure） |
| 自定义 Hook 用 `use` 前缀 | 便于 lint 与团队识别 | lint 插件无法校验其中的 Hook 调用 |

```tsx
// ❌ 条件里调用 Hook：两次渲染的 Hook 数量不同
function Bad({ show }) {
  if (show) {
    const [n, setN] = useState(0) // 违规
  }
  const [m, setM] = useState(0)
}

// ✅ 提前返回放在 Hook 之前？也不行——必须所有 Hook 都无条件调用
function Good({ show }) {
  const [n, setN] = useState(0) // 先无条件调用
  const [m, setM] = useState(0)
  if (!show) return null // 再决定渲染什么
  return <p>{n + m}</p>
}
```

```jsonc
// .eslintrc / eslint.config.js 里启用官方插件，让违规在编辑期就暴露
{
  "extends": ["plugin:react-hooks/recommended"],
  "plugins": ["react-hooks"]
}
// 两个核心规则：react-hooks/rules-of-hooks（error）、react-hooks/exhaustive-deps（warn）
```

> [!tip] `exhaustive-deps` 的警告不要随手关
> 它提示"依赖写漏了"。正确做法是按提示补全，或用函数式更新/把值挪进 effect 内部来**消除对它的依赖**。用 `// eslint-disable-next-line` 压掉警告，等于把过期闭包的 bug 留到线上。

### 3.6 受控组件与非受控组件

| 对比项 | 受控组件（Controlled） | 非受控组件（Uncontrolled） |
|---|---|---|
| 值的来源 | React state（唯一数据源） | DOM 自己管，通过 `ref` 读取 |
| 取值方式 | `value` + `onChange` | `useRef<HTMLInputElement>(null)` 后读 `ref.current.value` |
| 能否实时校验/联动 | 能（每次输入都可响应） | 只能在提交或失焦时 |
| 代码量 | 多一些 | 少 |
| 适合 | 需要实时校验、联动、格式化、受控的 UI 组件库 | 简单表单、文件输入 `<input type="file" />`、集成非 React 库 |

```tsx
import { useRef, useState } from 'react'

export function UserForm() {
  // 受控：每次输入都更新 state
  const [email, setEmail] = useState('')
  const emailValid = /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)

  // 非受控：只在提交时读取
  const nicknameRef = useRef<HTMLInputElement>(null)
  const fileRef = useRef<HTMLInputElement>(null)

  function onSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault()
    console.log({
      email,                                   // 从 state 读
      nickname: nicknameRef.current?.value,    // 从 DOM 读
      file: fileRef.current?.files?.[0]?.name, // 文件输入必须非受控
    })
  }

  return (
    <form onSubmit={onSubmit}>
      <input value={email} onChange={(e) => setEmail(e.target.value)} placeholder="邮箱" />
      {!emailValid && email && <span style={{ color: 'red' }}>邮箱格式不正确</span>}

      <input ref={nicknameRef} defaultValue="匿名" placeholder="昵称" />

      {/* 文件输入无法受控：value 只能由用户设置 */}
      <input ref={fileRef} type="file" />

      <button type="submit" disabled={!emailValid}>提交</button>
    </form>
  )
}
```

> [!warning] `value` 没有配 `onChange` 会变成只读
> 只写 `value={x}` 而不写 `onChange`，React 会警告并把输入框变成只读。想要"初始值 + 用户自己改"用 `defaultValue`（非受控）。

### 3.7 状态管理

#### 3.7.1 原生方案：Context + useReducer

```tsx
// src/store/todo-context.tsx
import { createContext, useContext, useMemo, useReducer, type ReactNode, type Dispatch } from 'react'

export interface Todo { id: number; title: string; done: boolean }

type Action =
  | { type: 'add'; title: string }
  | { type: 'toggle'; id: number }
  | { type: 'remove'; id: number }
  | { type: 'clearDone' }

function reducer(state: Todo[], action: Action): Todo[] {
  switch (action.type) {
    case 'add':
      return [{ id: Date.now(), title: action.title, done: false }, ...state]
    case 'toggle':
      return state.map((t) => (t.id === action.id ? { ...t, done: !t.done } : t))
    case 'remove':
      return state.filter((t) => t.id !== action.id)
    case 'clearDone':
      return state.filter((t) => !t.done)
    default: {
      // 穷尽性检查：所有 action 都被处理时 action 的类型收窄为 never，
      // 将来新增 action 却忘了写 case，这一行会直接编译报错
      const _exhaustive: never = action
      return state
    }
  }
}

const TodoStateContext = createContext<Todo[] | null>(null)
const TodoDispatchContext = createContext<Dispatch<Action> | null>(null)

export function TodoProvider({ children }: { children: ReactNode }) {
  const [todos, dispatch] = useReducer(reducer, [] as Todo[])

  // 状态与 dispatch 分成两个 Context：
  // dispatch 的引用永远稳定，所以"只派发不读状态"的组件不会因状态变化而重渲染
  return (
    <TodoStateContext.Provider value={todos}>
      <TodoDispatchContext.Provider value={dispatch}>{children}</TodoDispatchContext.Provider>
    </TodoStateContext.Provider>
  )
}

export function useTodos() {
  const ctx = useContext(TodoStateContext)
  if (!ctx) throw new Error('useTodos 必须在 <TodoProvider> 内使用')
  return ctx
}

export function useTodoDispatch() {
  const ctx = useContext(TodoDispatchContext)
  if (!ctx) throw new Error('useTodoDispatch 必须在 <TodoProvider> 内使用')
  return ctx
}
```

**为什么用 `useReducer` 而不是多个 `useState`**：① 状态转移逻辑集中在一处，可测试（reducer 是纯函数，离开 React 也能单测）；② `dispatch` 引用稳定，适合作为 Context 值或传给 `memo` 子组件，省掉一堆 `useCallback`；③ 复杂状态（多个字段需要一起变）不会出现"中间态不一致"。

#### 3.7.2 选型：Context+useReducer / Zustand / Redux Toolkit

| 对比项 | Context + useReducer | Zustand | Redux Toolkit |
|---|---|---|---|
| 依赖 | 无（React 内置） | `zustand`（约 1KB 级） | `@reduxjs/toolkit` + `react-redux` |
| 学习成本 | 低（但容易写出重渲染陷阱） | 低（一个 `create` 搞定） | 中高（slice、store、Provider、中间件） |
| 更新粒度 | 粗：Context 值一变，**所有消费者**重渲染 | 细：用选择器订阅所需字段 | 细：`useSelector` + 浅比较 |
| 组件外访问 | 不行（需要额外传递） | 可以：`useStore.getState()` | 可以：`store.getState()` |
| 异步 | 自己写（函数里 dispatch） | 直接在 action 里 `async/await` | `createAsyncThunk` / RTK Query |
| 调试能力 | 基本没有 | Redux DevTools 插件（可选接入） | 强（时间旅行、action 日志、DevTools） |
| 适合规模 | 中小型、低频更新的全局状态（主题、语言、登录用户） | 中小到大型，追求开发体验 | 大型团队、需要严格规范与可追溯性 |

> [!important] 什么时候才真的需要状态管理库
> 按顺序判断：
> ① **只在父子之间** → props + 回调，不要库；
> ② **只是避免透传（prop drilling）** → Context 就够；
> ③ **服务端数据**（列表、详情、分页） → 用请求缓存库（如 TanStack Query / SWR），它解决的是缓存与失效，不是"全局状态"；
> ④ **真正需要库的信号**：多个不相关路由/功能都要读写同一份**客户端**状态；需要在组件外（如 axios 拦截器）读取或修改；状态变化需要被 DevTools 追踪或持久化。
> 一上来就全局 store 的代价是：组件与 store 强耦合、复用变难、测试要造 store、性能优化变成"选择器地狱"。

```ts
// Zustand 最小示例：组件外也能用，粒度天然更细
import { create } from 'zustand'
import { persist } from 'zustand/middleware'

interface CartState {
  items: { id: number; qty: number }[]
  add: (id: number) => void
  total: () => number
}

export const useCartStore = create<CartState>()(
  persist(
    (set, get) => ({
      items: [],
      add: (id) =>
        set((state) => {
          const found = state.items.find((i) => i.id === id)
          return found
            ? { items: state.items.map((i) => (i.id === id ? { ...i, qty: i.qty + 1 } : i)) }
            : { items: [...state.items, { id, qty: 1 }] } // 不可变更新
        }),
      total: () => get().items.reduce((sum, i) => sum + i.qty, 0),
    }),
    { name: 'cart' }, // 自动持久化到 localStorage
  ),
)

// 组件里：只订阅需要的字段，其它字段变化不会引起重渲染
// const qty = useCartStore((s) => s.items.length)
```

```ts
// Redux Toolkit 最小示例：slice + store + Provider
import { configureStore, createSlice, type PayloadAction } from '@reduxjs/toolkit'
import { Provider, useSelector, useDispatch } from 'react-redux'

const counterSlice = createSlice({
  name: 'counter',
  initialState: { value: 0 },
  reducers: {
    increment: (state, action: PayloadAction<number>) => {
      // RTK 内置 Immer：这里"看起来在改原对象"，实际生成不可变的新状态
      state.value += action.payload
    },
  },
})

export const { increment } = counterSlice.actions
export const store = configureStore({ reducer: { counter: counterSlice.reducer } })

// 组件用法：<Provider store={store}><App /></Provider>
// const value = useSelector((s: RootState) => s.counter.value)
// const dispatch = useDispatch()
// dispatch(increment(1))
```

### 3.8 列表渲染与性能

#### 3.8.1 `React.memo` 与浅比较

```tsx
import { memo, useCallback, useState } from 'react'

interface RowProps {
  id: number
  title: string
  done: boolean
  onToggle: (id: number) => void
}

// 自定义比较函数：返回 true 表示"跳过重渲染"
// 只在确实需要忽略某个 prop 时才自定义，否则用默认浅比较
function areEqual(prev: RowProps, next: RowProps) {
  return prev.id === next.id && prev.title === next.title && prev.done === next.done
  // 注意这里刻意忽略了 onToggle：只要父组件保证它稳定，忽略它就是安全的
}

export const Row = memo(function Row({ id, title, done, onToggle }: RowProps) {
  console.log('Row 渲染', id)
  return (
    <li>
      <input type="checkbox" checked={done} onChange={() => onToggle(id)} />
      <span style={{ textDecoration: done ? 'line-through' : 'none' }}>{title}</span>
    </li>
  )
}, areEqual)

export function Parent() {
  const [items, setItems] = useState([{ id: 1, title: 'A', done: false }])
  const [text, setText] = useState('') // 与列表无关的 state

  // 如果这里写成内联箭头函数 (id) => {...}，每次渲染都是新引用，memo 会失效
  const handleToggle = useCallback((id: number) => {
    setItems((prev) => prev.map((i) => (i.id === id ? { ...i, done: !i.done } : i)))
  }, [])

  return (
    <>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <ul>
        {items.map((i) => (
          <Row key={i.id} {...i} onToggle={handleToggle} />
        ))}
      </ul>
    </>
  )
}
```

`memo` 的默认行为是**浅比较（shallow compare）**：逐个比较 props 的引用（`Object.is`）。所以：

| prop 类型 | 浅比较结果 | 结论 |
|---|---|---|
| 原始值（`string` / `number` / `boolean`） | 值相同即相等 | 天然友好 |
| 对象/数组字面量 | 每次渲染都是新引用 | **memo 失效**，需要 `useMemo` 稳定引用或改传原始值 |
| 内联箭头函数 | 每次渲染都是新函数 | **memo 失效**，需要 `useCallback` |
| `children` 里的 JSX | 每次渲染都新建元素对象 | 会破坏 memo，除非把 children 从父组件"提前"创建 |

> [!tip] 比 `memo` 更有效的两招
> ① **把状态往下挪**：如果只有搜索框需要 `text`，就把 `text` 放进搜索框组件内部，这样父组件根本不会因输入而重渲染整张列表；
> ② **用 `children` 传稳定的子树**：把不变的 `<Heavy />` 作为 `children` 传进会频繁重渲染的父组件，React 会复用同一个元素对象，从而跳过它的重渲染。

#### 3.8.2 虚拟列表思路

```tsx
import { useMemo, useRef, useState } from 'react'

interface VirtualListProps<T> {
  items: T[]
  itemHeight: number
  height: number
  renderItem: (item: T, index: number) => React.ReactNode
  buffer?: number
}

export function VirtualList<T>({ items, itemHeight, height, renderItem, buffer = 3 }: VirtualListProps<T>) {
  const [scrollTop, setScrollTop] = useState(0)
  const containerRef = useRef<HTMLDivElement>(null)

  // 只渲染视口内的项：start/end 随 scrollTop 变化
  const { start, end, offsetY } = useMemo(() => {
    const first = Math.max(0, Math.floor(scrollTop / itemHeight) - buffer)
    const visibleCount = Math.ceil(height / itemHeight)
    const last = Math.min(items.length, first + visibleCount + buffer * 2)
    return { start: first, end: last, offsetY: first * itemHeight }
  }, [scrollTop, itemHeight, height, buffer, items.length])

  const visible = items.slice(start, end)

  return (
    <div
      ref={containerRef}
      style={{ height, overflowY: 'auto' }}
      onScroll={(e) => setScrollTop(e.currentTarget.scrollTop)} // 也可以用 requestAnimationFrame 节流
    >
      {/* 总高度占位，撑出真实滚动条长度 */}
      <div style={{ height: items.length * itemHeight, position: 'relative' }}>
        {/* 用 transform 平移可见区域，避免触发额外布局 */}
        <div style={{ transform: `translateY(${offsetY}px)` }}>
          {visible.map((item, i) => (
            <div key={start + i} style={{ height: itemHeight }}>
              {renderItem(item, start + i)}
            </div>
          ))}
        </div>
      </div>
    </div>
  )
}

// 使用：渲染 10000 条数据，DOM 里始终只有几十个节点
export function Demo() {
  const data = Array.from({ length: 10000 }, (_, i) => ({ id: i, name: `第 ${i} 行` }))
  return (
    <VirtualList
      items={data}
      itemHeight={36}
      height={400}
      renderItem={(item) => <div>{item.name}</div>}
    />
  )
}
```

$$
\text{渲染节点数} = \left\lceil \frac{H_{\text{视口}}}{H_{\text{行}}} \right\rceil + 2 \times \text{buffer} \quad \text{（与 } n \text{ 无关）}
$$

> [!note] 生产环境建议
> 虚拟列表要处理行高不固定、横向滚动、`scrollToIndex`、无障碍等大量细节，实际项目更推荐成熟的方案（如 TanStack Virtual），**以上思路用于理解原理**。

### 3.9 渲染机制

#### 3.9.1 虚拟 DOM 与协调（Reconciliation）

React 的渲染分两个阶段：

| 阶段 | 做什么 | 是否可中断 |
|---|---|---|
| **Render（渲染/协调）** | 调用组件函数得到新的元素树，与上一次的树对比，算出需要变更的部分 | 并发特性下可中断、可放弃（因此这个阶段必须是纯函数、不能有副作用） |
| **Commit（提交）** | 把算好的变更一次性写入真实 DOM，然后执行 `useEffect` | 不可中断，DOM 已变更 |

**虚拟 DOM（Virtual DOM）**只是"描述界面的普通 JS 对象"：

```tsx
// <div className="box">hi</div> 的元素对象大致长这样
{
  type: 'div',
  props: { className: 'box', children: 'hi' },
}
```

它带来了三件事：① 让"计算差异"可以在 JS 里完成，再把最小变更批量写入 DOM；② 让 React 不依赖浏览器，从而能做服务端渲染与原生渲染（React Native）；③ 让开发者以声明式方式写 UI。

#### 3.9.2 Diff 策略（启发式 $O(n)$）

完整的两棵树最小编辑距离是 $O(n^3)$，对界面不可接受。React 用三条启发式规则把复杂度降到 $O(n)$：

| 规则 | 做法 |
|---|---|
| 不同类型的元素 → 直接重建 | `<div>` 变成 `<span>`，整棵子树卸载重建（状态丢失） |
| 同类型元素 → 保留 DOM，只更新变化的属性 | `<div className="a">` → `<div className="b">` 只改 class |
| 列表用 `key` 匹配身份 | 有 key 就能识别"这一项被移动了"而不是"内容变了" |

$$
T_{\text{完整树编辑距离}} = O(n^3) \quad\longrightarrow\quad T_{\text{启发式 diff}} = O(n)
$$

> [!important] 两条实战推论
> ① **改变元素类型或 key，会丢掉子树内部状态**（输入框内容、展开状态、滚动位置）——这也是"用 key 重置表单"技巧的原理；
> ② 因为"同类型元素保留 DOM"，条件渲染时若两个分支的最外层元素类型相同，React 会以为还是同一个元素而**复用状态**，这时给它们加不同的 key 更安全。

#### 3.9.3 为什么直接改 state 不触发更新

```tsx
const [items, setItems] = useState([{ id: 1, done: false }])

// ❌ 直接改：引用没变，React 新旧树看起来完全一样，diff 找不到差异 → 不重渲染
function toggleWrong(id: number) {
  const found = items.find((i) => i.id === id)
  if (found) found.done = !found.done
  setItems(items) // 传的是同一个数组引用，Object.is 判定"没变"，直接 bail out
}

// ✅ 不可变更新：创建新数组 + 新对象
function toggleRight(id: number) {
  setItems((prev) => prev.map((i) => (i.id === id ? { ...i, done: !i.done } : i)))
}
```

两个层面的原因：① 浅比较：`useState` 用 `Object.is` 判断新值是否与旧值相同，同一个引用会被认为"没变化"而跳过渲染；② 即使强行渲染，旧树与新树里的对象是同一个（已被就地修改），diff 也发现不了差异。

**不可变更新的常用写法**：

```ts
// 数组：增 / 删 / 改
const added = [...list, newItem]
const removed = list.filter((i) => i.id !== id)
const updated = list.map((i) => (i.id === id ? { ...i, done: true } : i))
const inserted = [...list.slice(0, idx), newItem, ...list.slice(idx)]

// 对象：改一个字段 / 嵌套字段
const nextUser = { ...user, name: '新名字' }
const nextState = { ...state, profile: { ...state.profile, age: 21 } }

// 用 Immer 写"看起来可变"的代码，得到不可变的结果
import { produce } from 'immer'
const next = produce(state, (draft) => {
  draft.profile.age = 21
  draft.items.push({ id: 9, done: false })
})
```

> [!warning] 不可变更新最容易踩的三个坑
> ① `arr.push(x); setArr(arr)`——引用没变，不更新；要 `setArr([...arr, x])`；
> ② `arr.sort()` / `arr.reverse()` **会就地修改原数组**（即使写了 `setArr(sorted)` 也可能因为引用相同而跳过），要 `[...arr].sort(...)`；
> ③ 只改了深层对象：`setState({ ...state, a: 1 })` 忘了 `profile` 也要展开，导致丢字段。Reducer 里用展开运算符要逐层处理，或改用 Immer。

### 3.10 React 19 新特性简介

> [!note] 版本说明
> 以下特性来自 React 19（当前最新主版本 19.3.0），**细节与新增 API 以官方最新文档为准**。React 19 是一次以"表单与异步"为重心的更新。

| 特性 | 是什么 | 解决了什么 |
|---|---|---|
| **Actions** | 在 `startTransition` 里执行异步函数的约定；表单可以直接传 `action` 函数 | 表单提交不再需要手写"pending + error + 手动禁用按钮"的三件套 |
| `useActionState` | `const [state, formAction, isPending] = useActionState(fn, init)` | 把"提交 → 返回状态 → 显示错误 → 禁用按钮"收敛成一个 Hook |
| `useFormStatus` | 在子组件里读取父级 `<form>` 的提交状态 | 提交按钮组件不用层层传 `isSubmitting` |
| **`use`** | 在渲染中读取 Promise 或 Context：`const data = use(promise)` | 组件内直接消费 Promise（需配合 Suspense 与缓存） |
| `useOptimistic` | 乐观更新：先展示预期结果，请求失败自动回滚 | 点赞、发送消息等即时反馈场景 |
| **`ref` 作为 prop** | 函数组件可直接接收 `ref`，`forwardRef` 不再必要（仍向后兼容） | 少一层包装，ref 就是普通 prop |
| ref 清理函数 | `ref` 回调可以返回清理函数 | 引用解除时自动收尾，替代以前的 `null` 判断 |
| 文档元数据 | `<title>` / `<meta>` / `<link>` 写在组件里会自动提升到 `<head>` | 不再需要 react-helmet 这类库处理基础场景 |
| Context 作为 Provider | 可直接 `<MyContext value={...}>` 渲染 | 少写 `.Provider` |
| 更好的错误提示 | 服务端渲染 hydration 错误会给出差异 diff | 排查更快 |

```tsx
// React 19：表单 Action + 内置 pending 状态（不再手写 loading 三件套）
import { useActionState, useOptimistic, useRef } from 'react'

interface Todo { id: number; title: string; done: boolean }

// Action：签名固定为 (上一次的结果, 表单数据)。表单序列化后的数据都在 formData 里
async function createTodo(_prev: string | null, formData: FormData): Promise<string | null> {
  const title = String(formData.get('title') ?? '').trim()
  if (!title) return '标题不能为空'
  const res = await fetch('/api/todos', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title }),
  })
  return res.ok ? null : '保存失败，请重试' // 返回 null 表示没有错误
}

export function AddTodo() {
  // error：最近一次 Action 的返回值；formAction：可直接交给 <form action={...}>
  // isPending：由 React 维护，无需自己 setState
  const [error, formAction, isPending] = useActionState(createTodo, null)
  const inputRef = useRef<HTMLInputElement>(null)

  // 乐观更新：先按"预期结果"渲染，请求失败后 React 会自动回滚到真实状态
  const [optimisticTodos, addOptimisticTodo] = useOptimistic<Todo[], string>(
    [],
    (todos, title) => [...todos, { id: -Date.now(), title, done: false }],
  )

  return (
    <form
      action={async (formData: FormData) => {
        addOptimisticTodo(String(formData.get('title') ?? '')) // 立刻显示"已添加"
        await formAction(formData) // 真正的提交；成功后列表会在父组件重新取数
        if (inputRef.current) inputRef.current.value = ''
      }}
    >
      {/* React 19 中 Action 提交完成后会自动重置非受控表单，这里只是演示 ref 用法 */}
      <input name="title" ref={inputRef} placeholder="输入待办标题" />
      <button type="submit" disabled={isPending}>
        {isPending ? '保存中…' : '添加'}
      </button>
      {error && <p style={{ color: 'red' }}>{error}</p>}

      {/* 乐观列表：id 为负数的项是"尚未确认"的临时项 */}
      <ul>
        {optimisticTodos.map((t) => (
          <li key={t.id}>{t.title}</li>
        ))}
      </ul>
    </form>
  )
}
```

```tsx
// ref 作为 prop（React 19）：不需要 forwardRef 了
// ComponentPropsWithRef<'input'> 里已经包含 ref 的类型，因此可以直接解构出来
function MyInput({ ref, ...props }: React.ComponentPropsWithRef<'input'>) {
  return <input ref={ref} {...props} />
}

// 使用
const ref = useRef<HTMLInputElement>(null)
;<MyInput ref={ref} placeholder="直接传 ref" />
```

### 3.11 完整示例：TodoList（并与 Vue 版对照）

下面的组件用到了本篇的 `useState`、`useMemo`、`useRef`、`useEffect`、`useReducer`、`memo`、自定义 Hook 与不可变更新，可直接放进 Vite 生成的 React + TS 项目运行。

```tsx
// src/App.tsx
import { memo, useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react'

// ---------------- 类型 ----------------
export interface Todo {
  id: number
  title: string
  done: boolean
}
type Filter = 'all' | 'active' | 'done'

type Action =
  | { type: 'add'; title: string }
  | { type: 'toggle'; id: number }
  | { type: 'remove'; id: number }
  | { type: 'edit'; id: number; title: string }
  | { type: 'toggleAll'; done: boolean }
  | { type: 'clearDone' }

const STORAGE_KEY = 'react-todolist'

// ---------------- 纯函数 reducer：可单独单测 ----------------
function todoReducer(state: Todo[], action: Action): Todo[] {
  switch (action.type) {
    case 'add':
      // 新数组（不可变更新），新项放最前
      return [{ id: Date.now(), title: action.title, done: false }, ...state]
    case 'toggle':
      return state.map((t) => (t.id === action.id ? { ...t, done: !t.done } : t))
    case 'remove':
      return state.filter((t) => t.id !== action.id)
    case 'edit':
      return state.map((t) => (t.id === action.id ? { ...t, title: action.title } : t))
    case 'toggleAll':
      // 一次性把每一项都设成同一个 done 值；不必读当前 todos
      return state.map((t) => (t.done === action.done ? t : { ...t, done: action.done }))
    case 'clearDone':
      return state.filter((t) => !t.done)
    default:
      return state
  }
}

// ---------------- 自定义 Hook：把"读一次 + 变化就写"收敛起来 ----------------
function usePersistentTodos(): [Todo[], React.Dispatch<Action>] {
  const [todos, dispatch] = useReducer(todoReducer, undefined, () => {
    try {
      const raw = localStorage.getItem(STORAGE_KEY)
      if (!raw) return [] as Todo[]
      const parsed: unknown = JSON.parse(raw)
      // 数据来自外部，必须校验形状，避免脏数据让页面崩掉
      if (!Array.isArray(parsed)) return []
      return parsed.filter(
        (t): t is Todo =>
          typeof t === 'object' && t !== null && typeof (t as Todo).id === 'number' && typeof (t as Todo).title === 'string',
      )
    } catch {
      return []
    }
  })

  // 首次渲染不写回，避免把"初始化前的空数组"覆盖掉存储里已有的数据
  const mounted = useRef(false)
  useEffect(() => {
    if (!mounted.current) {
      mounted.current = true
      return
    }
    localStorage.setItem(STORAGE_KEY, JSON.stringify(todos))
  }, [todos])

  return [todos, dispatch]
}

// ---------------- 子组件：React.memo + 自定义比较 ----------------
interface TodoItemProps {
  todo: Todo
  onToggle: (id: number) => void
  onRemove: (id: number) => void
  onEdit: (id: number, title: string) => void
}

const TodoItem = memo(
  function TodoItem({ todo, onToggle, onRemove, onEdit }: TodoItemProps) {
    const [editing, setEditing] = useState(false)
    const [draft, setDraft] = useState(todo.title)
    const inputRef = useRef<HTMLInputElement>(null)

    // 进入编辑态后自动聚焦（DOM 副作用，必须放 effect 里）
    useEffect(() => {
      if (editing) inputRef.current?.focus()
    }, [editing])

    function commit() {
      const title = draft.trim()
      if (title) onEdit(todo.id, title) // 空标题不提交，保持原值
      setEditing(false)
    }

    return (
      <li className={todo.done ? 'done' : ''}>
        <input type="checkbox" checked={todo.done} onChange={() => onToggle(todo.id)} />

        {editing ? (
          <input
            ref={inputRef}
            value={draft}
            onChange={(e) => setDraft(e.target.value)}
            onKeyDown={(e) => {
              if (e.key === 'Enter') commit()
              if (e.key === 'Escape') {
                setDraft(todo.title) // 取消：恢复原值
                setEditing(false)
              }
            }}
            onBlur={commit}
          />
        ) : (
          <span onDoubleClick={() => setEditing(true)}>{todo.title}</span>
        )}

        <button onClick={() => (editing ? commit() : setEditing(true))}>{editing ? '保存' : '编辑'}</button>
        <button className="del" onClick={() => onRemove(todo.id)}>
          删除
        </button>
      </li>
    )
  },
  // 只有这三项变化才重渲染；回调的引用稳定性由父组件的 useCallback/useReducer 保证
  (prev, next) =>
    prev.todo.id === next.todo.id && prev.todo.title === next.todo.title && prev.todo.done === next.todo.done,
)

// ---------------- 根组件 ----------------
export default function App() {
  const [todos, dispatch] = usePersistentTodos()
  const [draft, setDraft] = useState('')
  const [filter, setFilter] = useState<Filter>('all')

  // 派生数据一律在渲染时算，不要用 useEffect + useState 同步一份副本
  const remaining = useMemo(() => todos.filter((t) => !t.done).length, [todos])
  const visibleTodos = useMemo(() => {
    switch (filter) {
      case 'active':
        return todos.filter((t) => !t.done)
      case 'done':
        return todos.filter((t) => t.done)
      default:
        return todos
    }
  }, [todos, filter])

  const allDone = todos.length > 0 && todos.every((t) => t.done)

  // 回调用 useCallback 稳定引用，否则 TodoItem 的 memo 完全失效
  const handleToggle = useCallback((id: number) => dispatch({ type: 'toggle', id }), [])
  const handleRemove = useCallback((id: number) => dispatch({ type: 'remove', id }), [])
  const handleEdit = useCallback((id: number, title: string) => dispatch({ type: 'edit', id, title }), [])
  // 注意依赖里只放 allDone（原始值），dispatch 的引用永远稳定，不需要列入
  const toggleAll = useCallback(() => dispatch({ type: 'toggleAll', done: !allDone }), [allDone])

  function addTodo(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault()
    const title = draft.trim()
    if (!title) return
    dispatch({ type: 'add', title })
    setDraft('')
  }

  return (
    <div className="todo">
      <h2>待办清单（剩余 {remaining} 项）</h2>

      <form className="add" onSubmit={addTodo}>
        <input value={draft} onChange={(e) => setDraft(e.target.value)} placeholder="输入后回车添加" />
        <button type="submit" disabled={!draft.trim()}>
          添加
        </button>
      </form>

      <label className="all">
        <input type="checkbox" checked={allDone} onChange={toggleAll} />
        全部标记为{allDone ? '未完成' : '已完成'}
      </label>

      <ul className="list">
        {visibleTodos.map((todo) => (
          // key 用业务 id，不用索引
          <TodoItem key={todo.id} todo={todo} onToggle={handleToggle} onRemove={handleRemove} onEdit={handleEdit} />
        ))}
      </ul>

      {visibleTodos.length === 0 && <p className="empty">这里还没有内容</p>}

      <div className="footer">
        {(['all', 'active', 'done'] as const).map((f) => (
          <button key={f} className={filter === f ? 'active' : ''} onClick={() => setFilter(f)}>
            {f === 'all' ? '全部' : f === 'active' ? '未完成' : '已完成'}
          </button>
        ))}
        <button onClick={() => dispatch({ type: 'clearDone' })}>清除已完成</button>
      </div>
    </div>
  )
}
```

```css
/* src/index.css：与 Vue 版共用同一套样式 */
.todo { max-width: 520px; margin: 24px auto; font-family: system-ui, sans-serif; }
.add { display: flex; gap: 8px; margin-bottom: 8px; }
.add input { flex: 1; padding: 6px 8px; }
.list { list-style: none; padding: 0; }
.list li { display: flex; align-items: center; gap: 8px; padding: 6px 0; border-bottom: 1px solid #eee; }
.list li.done span { text-decoration: line-through; color: #999; }
.list li span { flex: 1; cursor: pointer; }
.del { color: #d33; }
.empty { color: #999; text-align: center; }
.footer { display: flex; gap: 8px; margin-top: 12px; }
.footer button.active { font-weight: 700; border-color: #42b883; color: #42b883; }
```

#### 与 Vue 版 TodoList 的写法差异

同一份需求，两份代码的差别集中在"状态怎么变、界面怎么跟着变"：

| 维度 | Vue 3（`前端-06-Vue.md` 的 TodoList） | React 19（本篇的 TodoList） |
|---|---|---|
| 状态声明 | `const todos = ref<Todo[]>([])` | `const [todos, dispatch] = useReducer(...)` |
| 读取/写入 | `todos.value.push(x)` 直接改 | `dispatch({ type: 'add', title })` 派发动作 |
| 派生数据 | `computed(() => todos.value.filter(...))` | `useMemo(() => todos.filter(...), [todos])` |
| 列表渲染 | `<li v-for="todo in visibleTodos" :key="todo.id">` | `{visibleTodos.map((todo) => <TodoItem key={todo.id} ... />)}` |
| 条件渲染 | `<p v-if="cond">` / `v-show` | `{cond && <p>}` / 三元 |
| 双向绑定 | `<input v-model.trim="draft">` | `<input value={draft} onChange={e => setDraft(e.target.value)}>` |
| 子组件入参 | `defineProps<Props>()` | 函数参数 `{ todo, onToggle }` |
| 子组件通知父级 | `emit('toggle', id)` | 调用父组件传下来的回调 `onToggle(id)`（也可理解为"把事件当 prop 传"） |
| 持久化 | `watch(todos, ..., { deep: true })` 自动追踪深层变化 | `useEffect(..., [todos])`；**必须每次返回新数组**才能触发 |
| 子组件性能 | 响应式依赖追踪，父组件更新通常不重渲染子组件 | 默认重渲染，需要 `memo` + 稳定的回调引用 |
| 副作用清理 | `onUnmounted(() => ...)` | `useEffect(() => { ...; return () => ... }, [deps])` |
| 本地状态 | `ref` 写在顶层的任意位置 | Hook 必须无条件写在组件函数顶层 |

> [!important] 一句话差异
> **Vue 是"改数据，框架找出谁受影响"；React 是"派发新状态，组件函数重新执行，diff 出变化"。**
> 因此 Vue 的代码更像在操作对象，React 的代码更像在写纯函数与不可变数据流。两者都需要你理解"状态放哪、谁是唯一数据源"。

---

## 四、常见坑

> [!warning] 十二个高频错误
> 1. **直接改 state**：`items.push(x)`、`obj.a = 1` 后 `setState(同一个引用)`，界面不更新；必须不可变更新。
> 2. **`setState` 后立刻读值**：本次执行里 state 变量不会变，这是异步更新 + 快照。
> 3. **依赖旧值却不用函数式更新**：`setCount(count + 1)` 连写三次只加一；用 `setCount(p => p + 1)`。
> 4. **`useEffect` 依赖数组写漏**：闭包读到过期 props/state；按 `exhaustive-deps` 提示补全。
> 5. **effect 里 setState 且该 state 在依赖里**：无限循环，控制台报 `Maximum update depth exceeded`。
> 6. **依赖写成对象/数组/函数字面量**：每次渲染都是新引用，effect 每轮都跑。
> 7. **忘记清理副作用**：定时器、订阅、请求未取消 → 内存泄漏与"更新已卸载组件"的警告。
> 8. **Hook 写在条件/循环里**：Hook 顺序错位，状态串位。
> 9. **`key` 用数组索引**：列表增删后组件状态错配；永远用业务 id。
> 10. **`memo` 配内联函数 prop**：浅比较永远失败，`memo` 形同虚设；回调要 `useCallback`。
> 11. **用 effect 同步派生数据**：`useEffect(() => setTotal(items.length), [items])` → 多一次渲染还可能死循环；直接算或用 `useMemo`。
> 12. **`0 && <X />` 渲染出 `0`**：用 `items.length > 0 && <X />`。

> [!tip] 调试建议
> ① 安装 **React Developer Tools**，用 Components 面板看 props/state，用 Profiler 面板录制交互找出"为什么重渲染"；
> ② 排查重渲染时打开 Profiler 的 "Highlight updates"，谁闪谁重渲染；
> ③ **StrictMode 下 effect 跑两次是故意的**，别为了"躲开两次执行"而删掉清理函数；那正是它在帮你找 bug。

---

## 五、练习题

1. **基础题**：写一个 `Tabs` 组件：接收 `items: { key: string; label: string; content: ReactNode }[]`，内部用 `useState` 管理当前选中的 key，点击标签切换内容；要求 `content` 只在被选中时才渲染（不要用 CSS 隐藏）。
2. **Hooks 辨析题**：下面这段代码有什么问题？会导致什么现象？给出两种修法并说明各自代价。
   ```tsx
   function Profile({ userId }: { userId: number }) {
     const [user, setUser] = useState<User | null>(null)
     useEffect(() => {
       fetch(`/api/users/${userId}`).then((r) => r.json()).then(setUser)
     }, [])
     return <div>{user?.name}</div>
   }
   ```
3. **无限循环题**：找出下面代码的循环链，并改写为正确版本（要求：只有 `filter` 变化时才重新计算，且不产生额外渲染）。
   ```tsx
   const [list, setList] = useState<Item[]>([])
   const [filter, setFilter] = useState('')
   const [filtered, setFiltered] = useState<Item[]>([])
   useEffect(() => {
     setFiltered(list.filter((i) => i.name.includes(filter)))
   }, [list, filter, filtered])
   ```
4. **性能优化题**：给定一个"1000 行 × 每行一个输入框"的列表，父组件还有一个搜索框。请写出优化方案：说明为什么输入时整个列表会重渲染，并用"把状态往下挪"与 `memo` + `useCallback` 两种方式分别实现，比较两者代码复杂度与效果。
5. **综合题**：把 3.11 的 TodoList 改造成 `Context + useReducer` 版本（拆分 state 与 dispatch 两个 Context），再加一个"撤销删除"（3 秒内可撤销、组件卸载时清理定时器）。回答：为什么把 state 与 dispatch 拆成两个 Context 能减少重渲染？

---

## 六、常见问题（FAQ）

**Q1：React 和 Vue 我该先学哪个？**
A：看目标岗位与生态需求，但**不要同时学**。想更快做出东西、喜欢模板与官方全家桶，先学 Vue（见 [[前端-06-Vue]]）；想接触更纯粹的"JS 表达 UI"、目标公司技术栈是 React/Next.js，先学 React。两者的核心概念（组件化、单向数据流、状态提升、列表 key）是通的，学会一个再学另一个主要是语法迁移成本。

**Q2：为什么我的组件渲染了两次？**
A：三种常见原因：① 开发环境的 `<StrictMode>` 故意双跑组件函数与 effect（生产不会）；② 父组件重渲染导致的正常子渲染（用 Profiler 确认是否可优化）；③ `setState` 里传入的值与旧值不同但触发了额外一轮（例如在 effect 里同步派生数据）。**先确认是哪种，再决定要不要优化**：StrictMode 的双跑不需要处理。

**Q3：`useMemo` / `useCallback` 到底要不要加？**
A：默认**不加**，先写正确、清晰的代码。只在以下情况加：① 计算确实昂贵（大数据排序/过滤，可在 Profiler 里看到明显耗时）；② 值/函数要作为 effect 依赖，而引用不稳定会导致 effect 反复执行；③ 要传给 `memo` 包裹的子组件。React 官方明确说明：`useMemo` 是性能优化手段，**不能当作语义保证**（缓存可能被丢弃），所以不要把"必须只执行一次"的逻辑放进去。

**Q4：什么时候该引入状态管理库？**
A：按 3.7.2 的判定顺序走：父子用 props、避免透传用 Context、服务端数据用 TanStack Query/SWR，只有"多个不相关模块读写同一份客户端状态、且需要组件外访问或 DevTools 追踪"时才引入 Zustand / Redux Toolkit。经验标准：如果引入后你要为"选择器粒度""Provider 层级""异步 thunk"写大量模板代码，而业务本身没有复杂到那个程度，说明引入早了。

**Q5：`useEffect` 到底什么时候该用？**
A：只有一个判断标准：**需要与 React 之外的系统同步**。比如订阅浏览器事件/WebSocket、操作 DOM（聚焦、测量、初始化第三方图表）、定时器、发送分析埋点。反之，"根据 props 算一个值""props 变化时重置子组件状态""用户点击后请求数据"都不该用 effect（分别用直接计算、`key`、事件处理器）。官方文档把这一节命名为"脱围机制（Escape Hatches）"，就是提醒你 effect 是例外而非常规。

---

## 相关笔记

- [[前端-06-Vue]]：同一问题的另一套答案，文末有同款 TodoList 的写法对照表，建议两篇对着读
- [[前端-05-TypeScript]]：props 类型、泛型组件、`React.ComponentPropsWithRef` 等类型工具的基础
- [[前端-08-构建工具-Vite与Webpack]]：`npm create vite@latest` 背后的开发服务器、HMR 与打包流程
- [[JavaScript-07-ES6新特性]]：展开运算符、解构、可选链是不可变更新写法的基础
- [[前端-04-浏览器与HTTP]]：虚拟 DOM、重排重绘与渲染性能的浏览器侧原理

## 参考来源

以下链接核实于 2026-10-11，均为官方文档（`zh-hans.react.dev` 是 React 官方中文文档，内容与英文版同步）：

- React 官方中文文档 · 学习总入口：<https://zh-hans.react.dev/learn>
- React 官方中文文档 · 描述 UI（组件、JSX、props、条件与列表渲染、纯函数）：<https://zh-hans.react.dev/learn/describing-the-ui>
- React 官方中文文档 · 管理状态（state、状态结构、`useReducer`、Context）：<https://zh-hans.react.dev/learn/managing-state>
- React 官方中文文档 · 脱围机制（`useRef`、`useEffect`、自定义 Hook）：<https://zh-hans.react.dev/learn/escape-hatches>
- React 官方中文文档 · 内置 Hooks API 参考（`useMemo` / `useCallback` / `useOptimistic` 等）：<https://zh-hans.react.dev/reference/react/hooks>
- React 官方中文文档 · Hooks 规则：<https://zh-hans.react.dev/reference/rules>
- React 官方博客 · React 19 发布说明（Actions、`use`、`ref` as prop）：<https://zh-hans.react.dev/blog/2024/12/05/react-19>
- Vite 官方文档（`create-vite` 脚手架与 React 模板）：<https://vite.dev/guide/>

> [!note] 版本说明
> 本篇对应 **React 19.3.0**（本库核实时间 2026-10-11）。
> 其中 `ref` 作为 prop、Context 作为 Provider、`useActionState` / `useOptimistic` / `use` 等 API 的**稳定状态与新增细节，以官方最新文档为准**；React 19 的完整变更清单见官方发布说明（链接见上）。
> 类组件、`forwardRef`、`ReactDOM.render` 等旧写法仍向后兼容，但新代码不再使用，本库不作为教学主线。
