React / 知识点
React Hooks 速查手册
手册条目
确认 Hook 只能在函数组件或自定义 Hook 顶层调用,避免调用顺序不稳定。
遵守 Hooks 调用规则
Hook 调用顺序依赖 React 在每次渲染中的固定位置。本文用于定位 Hooks 规则错误,确保 Hook 只在允许的位置调用,避免状态错位、运行时警告或构建检查失败。
使用位置
React Hook 只能在两类位置调用:
- 函数组件的顶层。
- 自定义 Hook 函数的顶层。
不要在普通函数、条件分支、循环、事件处理函数或 try/catch 内直接调用 Hook。
正确写法
import { useState, useEffect } from 'react';
function UserPanel({ id }) {
const [name, setName] = useState('');
// Hook 保持在组件顶层,React 可以稳定记录调用顺序
useEffect(() => {
setName(`user-${id}`);
}, [id]);
return <div>{name}</div>;
}预期结果
页面显示:user-123
读取方式:组件每次渲染时,useState 和 useEffect 按固定顺序执行高频错误
条件调用会导致不同渲染阶段 Hook 数量变化:
function Panel({ enabled }) {
if (enabled) {
const [value] = useState(0);
}
return <div />;
}可能出现:
Error: Rendered fewer hooks than expected修复方式是保持 Hook 始终执行,把条件放到 Hook 内部:
useEffect(() => {
if (!enabled) return;
loadData();
}, [enabled]);排障清单
- 搜索
useState、useEffect等调用位置,确认没有嵌套在if/for/function中。 - 检查自定义 Hook 是否以
use开头并且只在组件或其他 Hook 中调用。 - 开启 ESLint Hooks 规则提前发现问题。
{
"rules": {
"react-hooks/rules-of-hooks": "error"
}
}风险提示:如果通过动态调用、条件封装等方式绕过规则,可能导致状态与组件逻辑错位。安全替代方案是拆分组件或拆分自定义 Hook,让每次渲染保持相同调用顺序。
根据状态、副作用、引用、上下文和性能需求快速确定应使用的 Hook。
选择合适的 Hook
根据数据是否需要持久化、副作用是否需要同步、引用是否需要稳定以及组件间是否共享,选择正确 Hook,避免滥用状态或引入不必要渲染。
Hook 选择路径

常用判断:
| 需求 | 推荐 Hook | 典型场景 |
|---|---|---|
| 页面交互状态 | useState |
表单、开关、计数 |
| 请求、订阅、DOM 同步 | useEffect |
API 调用、事件监听 |
| 不触发渲染的变量 | useRef |
定时器、DOM 引用 |
| 昂贵计算缓存 | useMemo |
大量数据转换 |
| 函数引用稳定 | useCallback |
优化子组件渲染 |
| 跨组件共享数据 | useContext |
主题、登录信息 |
主示例
import { useMemo, useRef, useState } from 'react';
function SearchList({ items }) {
const [keyword, setKeyword] = useState('');
const inputRef = useRef(null);
// 仅在 items 或 keyword 变化时重新计算
const result = useMemo(
() => items.filter(item => item.includes(keyword)),
[items, keyword]
);
return (
<div>
<input ref={inputRef} value={keyword} onChange={e => setKeyword(e.target.value)} />
<p>{result.length}</p>
</div>
);
}预期结果
输入关键字后列表数量更新
读取方式:useState 驱动渲染,useRef 保存输入框引用,useMemo 缓存过滤计算常见误用
不要为了“减少渲染”默认使用 useMemo 和 useCallback。如果计算简单或组件没有引用比较需求,额外缓存会增加复杂度。不要使用 useEffect 派生普通数据:
// 不推荐:额外产生一次状态更新
useEffect(() => {
setFullName(`${first} ${last}`);
}, [first, last]);直接计算通常更简单:
const fullName = `${first} ${last}`;排障清单
- 状态变化但页面不更新:检查是否错误使用
useRef保存需要展示的数据。 - Effect 无限执行:检查依赖数组中的对象或函数是否每次重新创建。
- 子组件频繁渲染:先确认是否存在真实性能问题,再考虑
useMemo或useCallback。
选择原则:先保证数据流清晰,再针对实际瓶颈优化,不要用缓存 Hook 替代组件设计。
使用 useState 保存会影响界面渲染的组件内部数据。
声明组件状态
使用 useState 保存会影响组件渲染的数据。调用状态更新函数后,React 会安排组件重新渲染,并使用新的状态值生成界面。
基本语法
useState 返回一个状态值和对应的更新函数。初始值只在组件首次渲染时读取。
import { useState } from 'react';
export default function Counter() {
const [count, setCount] = useState(0);
return (
<button onClick={() => setCount(count + 1)}>
点击次数:{count}
</button>
);
}预期结果
页面显示:点击次数:0
点击按钮后:点击次数:1读取方法:观察按钮文本变化,说明状态更新触发了重新渲染。
高频用法
保存基本值
适合保存数字、字符串、布尔值等简单状态。
const [visible, setVisible] = useState(true);
const [name, setName] = useState('React');保存对象或数组
更新对象、数组时需要创建新引用,不要直接修改原值。
const [user, setUser] = useState({ name: 'Tom' });
setUser({
...user,
name: 'Jerry'
});风险与边界
- 不要把不会影响渲染的临时变量放入状态,普通变量即可。
- 不要直接修改状态对象,例如
user.name = 'x',React 可能无法正确检测变化。 - 状态更新是批处理行为,多次调用不一定立即改变当前函数中的旧变量。
排障清单
- 页面没有变化:检查是否调用了对应的
setState函数。 - 状态更新后仍显示旧值:确认是否直接修改了对象或数组。
- 初始化逻辑重复执行:检查是否把副作用代码放入了
useState初始值。
使用函数式更新安全地基于前一次状态计算下一次状态。
根据旧状态更新
当下一次状态依赖当前状态时,使用函数式更新避免读取到过期值。React 会把最新状态作为参数传入更新函数。
基本语法
普通更新直接使用当前变量,连续更新时可能基于同一个旧值计算。函数式更新接收最新状态:
import { useState } from 'react';
export default function Counter() {
const [count, setCount] = useState(0);
function increase() {
// 基于 React 提供的最新状态计算下一值
setCount(current => current + 1);
}
return <button onClick={increase}>{count}</button>;
}预期结果
初始显示:0
点击一次:1
再次点击:2读取方法:每次点击按钮,显示数字递增,说明更新使用了最新状态。
高频用法
连续累加
多次更新同一个状态时优先使用函数式更新。
setCount(current => current + 1);
setCount(current => current + 1);结果:React 会按顺序基于最新值计算两次更新。
更新数组或对象
需要结合展开语法保留不可变更新。
setItems(current => [
...current,
newItem
]);风险与边界
- 仅依赖外部固定值时,不需要强行使用函数式更新。
- 函数参数代表 React 当前状态,不要与外层同名变量混用。
- 直接读取旧闭包变量处理异步回调,容易产生旧值问题。
排障清单
- 定时器、事件回调中状态停在旧值:检查是否捕获了旧闭包。
- 连续
setState后结果少加:改用函数式更新。 - 异步请求返回覆盖新状态:确认更新逻辑是否基于最新状态合并。
通过初始化函数避免在每次组件渲染时重复执行昂贵计算。
延迟初始化状态
当初始状态需要解析大数据、读取缓存或执行复杂计算时,把初始化逻辑作为函数传给 useState。React 只在组件初始化时使用其返回值,避免普通重新渲染重复计算。
基本语法
const [state, setState] = useState(() => {
return createInitialState();
});不要写成 useState(createInitialState()),后者会在每次组件函数执行时先调用计算函数,即使 React 不再使用该结果。
高频用法
下面的组件通过初始化函数生成一次统计结果。点击按钮只更新计数,不会再次执行昂贵计算。
import { useState } from "react";
function buildInitialReport() {
console.log("执行初始化计算");
const numbers = Array.from({ length: 1000 }, (_, index) => index + 1);
return {
total: numbers.reduce((sum, value) => sum + value, 0),
refreshCount: 0
};
}
export default function ReportPanel() {
const [report, setReport] = useState(() => buildInitialReport());
function refresh() {
setReport(previous => ({
...previous,
refreshCount: previous.refreshCount + 1
}));
}
return (
<section>
<p>总和:{report.total}</p>
<p>刷新次数:{report.refreshCount}</p>
<button onClick={refresh}>刷新</button>
</section>
);
}预期结果
控制台首次挂载时输出:
执行初始化计算
页面首次显示:
总和:500500
刷新次数:0
点击“刷新”后:
刷新次数:1读取方法:连续点击按钮时,页面计数递增;生产模式下控制台不会因普通重新渲染重复打印初始化日志。
风险与边界
初始化函数必须保持纯函数特征,不要在其中修改全局变量、发送请求或写入存储。开发环境启用 React 严格模式时,React 可能调用初始化函数两次以检查纯度;这不会发生在生产渲染中,但有副作用的代码会因此重复执行。
延迟初始化只影响首次状态创建。组件接收的新属性不会自动重新执行初始化函数;需要根据属性同步状态时,应重新评估是否真的需要本地状态,或使用事件处理、派生值与 useMemo。
排障清单
- 每次渲染都在计算:确认传入的是
() => calculate(),而不是calculate()。 - 开发环境日志出现两次:检查是否启用了严格模式,并确保初始化函数无副作用。
- 属性变化后状态未重建:这是
useState的预期行为,不要把初始化函数当作监听器。 - 计算依然卡顿:初始化只减少重复执行,首次计算本身仍会阻塞渲染,应考虑拆分数据、移到服务端或放入 Web Worker。
以不可变方式更新对象字段,避免覆盖未修改的数据。
更新对象状态
对象状态只需要修改部分字段时,应创建新对象并保留未修改字段。推荐使用函数式更新,确保计算基于最新状态,避免连续更新或异步回调读取旧值。
基本语法
setProfile(previous => ({
...previous,
city: "Shanghai"
}));展开顺序很重要:先复制旧对象,再写入目标字段。若把 ...previous 放在最后,新值会被旧字段覆盖。
高频用法
下面的表单分别更新姓名和城市。每次更新都会生成新对象,同时保留另一个字段。
import { useState } from "react";
export default function ProfileEditor() {
const [profile, setProfile] = useState({
name: "Alice",
city: "Beijing"
});
function changeName(event) {
const nextName = event.target.value;
setProfile(previous => ({
...previous,
name: nextName
}));
}
function moveToShanghai() {
setProfile(previous => ({
...previous,
city: "Shanghai"
}));
}
return (
<section>
<input value={profile.name} onChange={changeName} />
<button onClick={moveToShanghai}>迁移到上海</button>
<p>{profile.name} / {profile.city}</p>
</section>
);
}预期结果
首次显示:
Alice / Beijing
输入框改为 Bob 后:
Bob / Beijing
点击“迁移到上海”后:
Bob / Shanghai读取方法:修改任一字段后,另一个字段仍保留原值,说明更新没有覆盖整个对象。
嵌套对象
展开运算符只复制一层。更新嵌套字段时,需要逐层创建新对象。
setUser(previous => ({
...previous,
address: {
...previous.address,
city: "Shanghai"
}
}));预期结果
user.address.city 更新为 Shanghai;
user 的其他字段以及 address 的其他字段保持不变。风险与边界
不要直接执行 profile.city = "Shanghai" 后再把同一对象传回 setProfile。原地修改会破坏状态快照,React 可能因对象引用未变化而跳过渲染,也会让旧渲染意外读取到新数据。
当新状态完全替换旧对象时,不需要展开旧值,例如加载另一位用户的完整资料。只有在“保留旧字段并局部修改”时才使用展开语法。
排障清单
- 更新一个字段后其他字段消失:检查是否遗漏了
...previous。 - 新字段没有生效:检查展开旧对象是否写在新字段之后。
- 连续更新结果丢失:改用
setState(previous => ...),不要依赖当前闭包中的旧状态。 - 嵌套字段更新后界面不刷新:确认每一层被修改的对象都创建了新引用。
- 状态结构层级过深:优先扁平化数据,或在复杂更新场景使用
useReducer。
使用映射、过滤和展开操作安全地新增、修改或删除数组元素。
更新数组状态
数组状态需要新增、修改或删除元素时,创建新数组并交给状态更新函数,不要直接修改原数组。涉及连续更新时使用函数式更新,避免读取旧快照。
基本写法
- 新增:使用展开运算符生成新数组。
- 修改:使用
map替换命中的元素。 - 删除:使用
filter排除目标元素。 - 重排:先复制数组,再对副本执行
sort、reverse或splice。
import { useState } from "react";
export default function TodoList() {
const [todos, setTodos] = useState([
{ id: 1, text: "检查日志", done: false },
{ id: 2, text: "修复告警", done: false }
]);
function addTodo() {
setTodos(current => [
...current,
{ id: Date.now(), text: "验证发布", done: false }
]);
}
function toggleTodo(id) {
setTodos(current =>
current.map(todo =>
todo.id === id ? { ...todo, done: !todo.done } : todo
)
);
}
function removeTodo(id) {
setTodos(current => current.filter(todo => todo.id !== id));
}
return (
<section>
<button onClick={addTodo}>新增</button>
<ul>
{todos.map(todo => (
<li key={todo.id}>
<button onClick={() => toggleTodo(todo.id)}>
{todo.done ? "已完成" : "待处理"}
</button>
{todo.text}
<button onClick={() => removeTodo(todo.id)}>删除</button>
</li>
))}
</ul>
</section>
);
}预期结果
初始显示“检查日志”和“修复告警”。
点击“新增”后追加“验证发布”。
点击状态按钮只切换对应项,点击“删除”只移除对应项。读取结果时重点确认:未操作的元素仍被保留,命中元素生成了新对象,列表项使用稳定且唯一的 key。
高频用法
更新嵌套字段时,要同时复制数组和目标对象:
setUsers(current =>
current.map(user =>
user.id === targetId
? { ...user, profile: { ...user.profile, city: "Shanghai" } }
: user
)
);预期结果
仅 targetId 对应用户的 profile.city 变为 Shanghai,其他用户保持不变。排序时不要直接调用 items.sort(),因为它会修改原数组。安全写法是:
setItems(current => [...current].sort((a, b) => a.score - b.score));预期结果
列表按 score 从小到大重新渲染,原状态数组未被原地修改。风险与边界
直接执行 todos.push()、todos[index].done = true 或 todos.sort() 会修改现有引用。触发后可能出现组件不重新渲染、旧状态被污染或并发更新互相覆盖;安全替代方案是使用展开、map、filter,并优先传入 current => newValue。
使用数组索引作为 key 时,插入、删除或排序可能让组件状态错位。列表可能重用错误的输入框或子组件;应使用后端 ID、UUID 等稳定标识。
将可由现有属性或状态计算出的值保留为派生数据而非独立状态。
避免冗余状态
当一个值能够由当前 props 或已有状态直接计算得到时,不要再为它创建独立状态。渲染时计算派生值,可以避免多个状态不同步。
判断方法
准备调用 useState 前先判断:该值是否能仅根据本次渲染中的其他数据确定。答案为是时,通常应使用普通变量、数组方法或 useMemo,而不是额外的状态和同步副作用。
import { useState } from "react";
export default function ProductSearch() {
const [products] = useState([
{ id: 1, name: "Keyboard", price: 300 },
{ id: 2, name: "Mouse", price: 120 },
{ id: 3, name: "Monitor", price: 1600 }
]);
const [keyword, setKeyword] = useState("");
// filteredProducts 完全由 products 和 keyword 决定,无需单独存入状态。
const filteredProducts = products.filter(product =>
product.name.toLowerCase().includes(keyword.toLowerCase())
);
const totalPrice = filteredProducts.reduce(
(sum, product) => sum + product.price,
0
);
return (
<section>
<input
value={keyword}
onChange={event => setKeyword(event.target.value)}
placeholder="搜索商品"
/>
<p>匹配数量:{filteredProducts.length}</p>
<p>合计价格:{totalPrice}</p>
<ul>
{filteredProducts.map(product => (
<li key={product.id}>{product.name}</li>
))}
</ul>
</section>
);
}预期结果
输入 mouse 后只显示 Mouse。
匹配数量显示 1,合计价格显示 120。
清空输入后重新显示全部商品。这里真正需要保存的只有用户输入 keyword 和原始数据 products;过滤结果、数量与总价均随渲染自动更新。
需要缓存时
派生计算开销明显,或结果引用需要稳定地传给经过记忆化处理的子组件时,可以使用 useMemo。它是性能优化,不是保证业务正确性的状态容器。
import { useMemo, useState } from "react";
export default function Report({ records }) {
const [status, setStatus] = useState("open");
const visibleRecords = useMemo(
() => records.filter(record => record.status === status),
[records, status]
);
return (
<section>
<button onClick={() => setStatus("open")}>处理中</button>
<button onClick={() => setStatus("closed")}>已关闭</button>
<p>当前记录数:{visibleRecords.length}</p>
</section>
);
}预期结果
点击“处理中”显示 status 为 open 的记录数。
点击“已关闭”显示 status 为 closed 的记录数。
records 或 status 未变化时可复用上次计算结果。风险与边界
把 fullName、过滤列表或总价同时保存为状态后,任何依赖项更新都必须同步更新它们。遗漏一次同步就会展示旧数据;安全替代方案是在渲染期间直接计算。
不要为了同步派生值编写 useEffect(() => setDerived(...))。这种写法会先用旧值渲染一次,再触发额外渲染,还可能因依赖遗漏产生错误;只有需要连接浏览器 API、网络、订阅等外部系统时才使用 Effect。
用户正在编辑但尚未提交的草稿、服务端返回且允许本地覆盖的值,以及无法从现有数据还原的交互状态,不属于冗余状态,可以独立保存。
使用 useReducer 集中处理多字段、关联更新或事件驱动的状态变化。
使用 useReducer 管理复杂状态
当多个字段需要一起更新、状态变化由明确事件驱动,或多个处理函数反复复制更新逻辑时,用 useReducer 将变化规则集中到一个纯函数中。组件只负责派发事件,Reducer 负责计算下一状态。
基本语法
useReducer 接收 Reducer 和初始状态,返回当前状态与 dispatch:
const [state, dispatch] = useReducer(reducer, initialState)
Reducer 的签名为 (state, action) => nextState。action.type 表示发生了什么,其他字段携带计算下一状态所需的数据。
主示例
下面的表单同时管理名称、数量、提交状态和错误信息。提交事件会关联更新多个字段,比连续调用多个 setState 更容易保持一致。
import { useReducer } from "react";
const initialState = {
name: "Keyboard",
quantity: 1,
saving: false,
error: ""
};
function reducer(state, action) {
switch (action.type) {
case "fieldChanged":
return {
...state,
[action.field]: action.value,
error: ""
};
case "saveStarted":
if (!state.name.trim() || state.quantity < 1) {
return { ...state, error: "名称不能为空,数量必须大于 0" };
}
return { ...state, saving: true, error: "" };
case "saveFinished":
return { ...state, saving: false };
case "reset":
return initialState;
default:
throw new Error(`未知 action:${action.type}`);
}
}
export default function ProductEditor() {
const [state, dispatch] = useReducer(reducer, initialState);
function save() {
dispatch({ type: "saveStarted" });
if (!state.name.trim() || state.quantity < 1) return;
// 示例用同步派发模拟请求完成;真实项目应在请求成功后派发。
dispatch({ type: "saveFinished" });
}
return (
<section>
<input
aria-label="商品名称"
value={state.name}
onChange={(event) =>
dispatch({
type: "fieldChanged",
field: "name",
value: event.target.value
})
}
/>
<input
aria-label="数量"
type="number"
value={state.quantity}
onChange={(event) =>
dispatch({
type: "fieldChanged",
field: "quantity",
value: Number(event.target.value)
})
}
/>
<button onClick={save} disabled={state.saving}>保存</button>
<button onClick={() => dispatch({ type: "reset" })}>重置</button>
{state.error && <p role="alert">{state.error}</p>}
<pre>{JSON.stringify(state, null, 2)}</pre>
</section>
);
}预期结果
初始页面显示名称 Keyboard、数量 1,状态中的 saving 为 false。
将数量改为 0 后点击“保存”,页面显示:名称不能为空,数量必须大于 0。
点击“重置”后,所有字段恢复为 initialState。读取时重点观察 <pre>:每次 dispatch 后都应得到一个新的完整状态对象,而不是只包含被修改字段的残缺对象。
高频用法
- 表单包含多个字段,并且提交、清空、校验失败会同时改变多个字段。
- 请求状态存在
idle、loading、success、error等明确事件。 - 列表支持新增、修改、删除、排序,更新规则需要集中测试。
- 状态变化依赖前一状态,且多个组件事件需要复用同一套规则。
风险与边界
Reducer 必须保持纯净。若在 Reducer 内发请求、写存储或修改外部变量,开发模式下的重复调用可能造成重复请求或不可预测结果;应把副作用放入事件处理函数或 useEffect,Reducer 只返回下一状态。
不要直接修改 state 后再返回原对象。这样可能导致 React 判断引用未变化而跳过渲染;应使用展开运算符、map、filter 等方式创建新对象或新数组。
不要为每个简单布尔值都引入 Reducer。若状态彼此独立、只有一两个直接更新,多个 useState 通常更清楚。
排障清单
- 派发后界面不更新:检查是否直接修改并返回了原状态对象。
- 某些字段突然丢失:检查分支返回值是否遗漏
...state。 - 报出未知 action:核对派发端与 Reducer 中的
type拼写。 - 连续派发结果不符合预期:确保每个分支只基于收到的
state计算,不读取闭包中的旧状态。
速查原则:事件命名描述“发生了什么”,Reducer 分支描述“状态如何变化”,副作用留在 Reducer 外部。
通过 useReducer 的初始化函数构造复杂或计算成本较高的初始状态。
初始化 Reducer 状态
当初始状态需要解析输入、构建索引、读取本地缓存或执行较重计算时,将初始化逻辑传给 useReducer 的第三个参数。React 会用初始化函数的返回值作为首次状态,避免组件每次渲染都重新计算。
基本语法
初始化函数形式如下:const [state, dispatch] = useReducer(reducer, initialArg, init)
首次初始化时,React 执行 init(initialArg)。这里的 initialArg 是初始化所需的原始输入,不一定是最终状态对象。
主示例
下面从原始任务数组生成完整状态,并复用同一个初始化函数实现重置。
import { useReducer } from "react";
const defaultTasks = [
{ id: 1, title: "检查告警", done: false },
{ id: 2, title: "更新记录", done: true }
];
function createInitialState(tasks) {
return {
tasks: tasks.map((task) => ({ ...task })),
completedCount: tasks.filter((task) => task.done).length,
selectedId: null
};
}
function reducer(state, action) {
switch (action.type) {
case "taskToggled": {
const tasks = state.tasks.map((task) =>
task.id === action.id ? { ...task, done: !task.done } : task
);
return {
...state,
tasks,
completedCount: tasks.filter((task) => task.done).length
};
}
case "taskSelected":
return { ...state, selectedId: action.id };
case "reset":
// Reducer 不会自动重新执行初始化函数,重置时需要显式调用。
return createInitialState(action.tasks);
default:
throw new Error(`未知 action:${action.type}`);
}
}
export default function TaskPanel() {
const [state, dispatch] = useReducer(
reducer,
defaultTasks,
createInitialState
);
return (
<section>
<p>已完成:{state.completedCount}</p>
{state.tasks.map((task) => (
<label key={task.id}>
<input
type="checkbox"
checked={task.done}
onChange={() => dispatch({ type: "taskToggled", id: task.id })}
/>
{task.title}
</label>
))}
<button
onClick={() => dispatch({ type: "reset", tasks: defaultTasks })}
>
恢复默认任务
</button>
</section>
);
}预期结果
首次渲染显示:已完成:1。
勾选“检查告警”后显示:已完成:2。
点击“恢复默认任务”后再次显示:已完成:1。初始化函数同时生成 tasks、completedCount 和 selectedId,因此这几个字段在首次加载和重置后始终保持一致。
适用场景
- 初始状态需要遍历大数组、建立映射表或计算派生统计值。
- 原始输入与组件实际使用的状态结构不同。
- 首次状态需要从可序列化配置转换成便于更新的结构。
- 初始化规则需要在“恢复默认值”操作中复用。
边界与注意事项
不要写成 useReducer(reducer, createInitialState(defaultTasks)) 来处理昂贵计算。该表达式会在组件每次渲染时求值,即使 React 只在首次渲染采用它;应传入第三个参数,让 React 负责调用初始化函数。
初始化函数必须是纯函数。若其中写入本地存储、发送请求或修改输入数组,开发环境的严格模式检查可能暴露重复副作用;应先在组件外读取数据,再把读取结果作为 initialArg 传入。
初始化函数只用于建立首次状态。组件属性变化后,React 不会自动重新初始化 Reducer;需要明确派发同步 action,或者在确实要创建全新组件实例时调整组件的 key。
排障清单
- 初始化函数每次渲染都执行:检查是否提前调用了
init(initialArg),而不是把init作为第三个参数传入。 - 修改输入数组后状态异常:初始化时复制对象和数组,不要保留可被外部修改的共享引用。
- 属性变化但状态没刷新:这是
useReducer的预期行为,应显式派发同步或重置 action。 - 开发环境看到初始化日志两次:严格模式可能重复调用纯函数用于检查,不应依赖调用次数产生副作用。
速查写法:第二个参数提供原始数据,第三个参数负责转换,Reducer 的重置分支可显式复用同一个初始化函数。
使用 useEffect 将组件与网络、浏览器 API 或第三方组件保持同步。
执行外部系统同步
当组件需要与浏览器事件、网络连接或第三方实例保持一致时使用 useEffect。核心规则是:Effect 负责“开始同步”,清理函数负责“停止同步”。
基本语法
片段示例,需在 React 组件中使用:
useEffect(() => {
// 建立订阅、发送请求或创建第三方实例
return () => {
// 取消订阅、终止请求或销毁实例
};
}, [依赖项]);依赖项变化时,React 会先执行上一次清理,再执行新的 Effect;组件卸载时只执行清理。
主示例:同步浏览器网络状态
import { useEffect, useState } from 'react';
export default function NetworkStatus() {
const [online, setOnline] = useState(() =>
typeof navigator === 'undefined' ? true : navigator.onLine
);
useEffect(() => {
function syncStatus() {
setOnline(navigator.onLine);
}
// 订阅外部事件后,必须在清理函数中成对移除
window.addEventListener('online', syncStatus);
window.addEventListener('offline', syncStatus);
syncStatus();
return () => {
window.removeEventListener('online', syncStatus);
window.removeEventListener('offline', syncStatus);
};
}, []);
return <p>网络状态:{online ? '在线' : '离线'}</p>;
}预期结果
联网时:网络状态:在线
断网后:网络状态:离线打开浏览器开发者工具切换离线模式,文本应立即变化;恢复网络后应重新显示“在线”。
高频用法
- 事件订阅:
addEventListener、WebSocket、消息总线必须返回对应的取消订阅逻辑。 - 网络请求:在 Effect 内创建
AbortController,清理时调用abort(),避免旧请求晚到后覆盖新数据。 - 第三方组件:创建地图、播放器或图表实例后,清理时调用其
destroy、dispose或等价 API。 - 外部状态写入:同步
document.title、本地存储或浏览器 API 时,只列出实际读取的响应式值。
风险与边界
没有清理的订阅会在组件反复挂载或依赖变化后累积,导致重复回调、内存泄漏或多次请求。安全做法是确保“建立”和“销毁”成对出现。
不要用 Effect 计算可直接由 props 或 state 推导出的渲染数据,也不要把按钮点击后的单次业务操作迁入 Effect;前者应在渲染阶段计算,后者应放在事件处理函数中。
开发环境启用 Strict Mode 时,React 会额外执行一次“建立 → 清理 → 建立”以暴露不完整清理。若出现重复连接,优先修复清理逻辑,不要通过全局标记跳过第二次执行。
排障清单
- Effect 不执行:确认组件已在客户端挂载,且没有在服务端渲染阶段期待它运行。
- Effect 无限执行:检查依赖中是否有每次渲染都新建的对象或函数。
- 收到重复事件:确认监听器引用一致,并在清理函数中正确移除。
- 数据被旧请求覆盖:为每轮请求创建独立的取消控制器,并在清理时终止。
- 第三方实例残留:确认库提供的销毁方法已调用,且容器节点没有重复初始化。
速查:能在渲染期间完成的不要放进 Effect;必须连接外部系统时,始终同时设计清理路径。
准确列出副作用读取的响应式值,避免陈旧数据和无效重复执行。
设置 Effect 依赖
依赖数组必须列出 Effect 中读取的所有响应式值,包括 props、state,以及组件函数体内声明的变量和函数。准确依赖可避免陈旧闭包,也能阻止无关的重复同步。
三种执行方式
片段示例,需在 React 组件中使用:
useEffect(() => {
// 每次提交后执行
});
useEffect(() => {
// 挂载后执行;仅适用于没有读取响应式值的 Effect
}, []);
useEffect(() => {
// 挂载后执行;a 或 b 变化时重新执行
}, [a, b]);React 使用 Object.is 比较新旧依赖。对象、数组和函数即使内容相同,只要引用改变,也会触发 Effect。
主示例:只在房间变化时同步
import { useEffect, useState } from 'react';
export default function App() {
const [roomId, setRoomId] = useState('general');
useEffect(() => {
const previousTitle = document.title;
// Effect 读取了 roomId,因此依赖数组必须包含它
document.title = `房间:${roomId}`;
localStorage.setItem('active-room', roomId);
return () => {
document.title = previousTitle;
};
}, [roomId]);
return (
<main>
<p>当前房间:{roomId}</p>
<button
onClick={() =>
setRoomId(current =>
current === 'general' ? 'support' : 'general'
)
}
>
切换房间
</button>
</main>
);
}预期结果
初始页面:当前房间:general,浏览器标题为“房间:general”
点击按钮:当前房间:support,浏览器标题和 localStorage 同步更新setRoomId 是 React 提供的稳定 setter,不需要加入依赖;document 和 localStorage 是外部全局对象,也不是响应式值。
减少无效依赖
Effect 只使用某个对象的字段时,优先依赖该原始值,而不是依赖每次渲染都新建的整个对象。以下为片段示例,依赖外部提供的 connect 函数:
const options = { roomId };
useEffect(() => {
connect(options);
}, [options]);上面的 options 每次渲染都会创建新引用,可能导致重复连接。更稳妥的写法是在 Effect 内创建对象:
useEffect(() => {
const options = { roomId };
const connection = connect(options);
return () => connection.disconnect();
}, [roomId]);生效结果:只有 roomId 改变时才重新连接。若 connect 来自 props 或组件内定义的函数,它本身仍是响应式值,需要加入依赖,或把相关逻辑移入 Effect。
常见修正
- 依赖缺失:不要关闭 Hooks ESLint 规则;应补齐依赖或调整代码结构。
- 函数导致重复执行:优先把仅供 Effect 使用的函数定义移入 Effect;确需跨位置复用时再使用
useCallback。 - 对象导致重复执行:在 Effect 内构造对象,或依赖对象中的稳定原始字段。
- 读取旧 state:需要基于旧值更新时使用函数式更新,如
setCount(value => value + 1),减少对旧闭包的依赖。 - 请求参数变化:把所有参与 URL、请求体或订阅键生成的响应式值加入依赖,并在清理中取消上一轮工作。
风险与边界
故意漏写依赖会让 Effect 持续读取旧 props 或旧 state,表现为请求参数不更新、订阅未切换或定时器使用旧值。安全替代方案是重构 Effect,使其依赖集合真实、最小且可由 lint 自动验证。
不要为了减少执行次数盲目使用 useMemo 或 useCallback。只有当引用稳定本身是正确性要求,或能消除已确认的重复同步时再使用。
速查:依赖数组不是手动选择的性能开关,而是 Effect 所读取响应式值的完整声明。
在 Effect 清理函数中释放订阅、定时器、连接和事件监听器。
清理副作用资源
当 Effect 创建了订阅、定时器、网络连接或事件监听器时,在 Effect 中返回清理函数。React 会在组件卸载前,以及依赖变化导致 Effect 重新执行前调用它,避免重复注册和资源泄漏。
基本语法
useEffect(() => {
const resource = createResource();
return () => {
resource.dispose();
};
}, [dependency]);清理函数必须由 Effect 直接返回,不要写成异步函数。它应撤销本次 Effect 执行所创建的资源。
高频用法
下面的组件同时演示事件监听器和定时器的释放,可直接放入 React 项目运行。
import { useEffect, useState } from "react";
export default function WindowStatus() {
const [width, setWidth] = useState(window.innerWidth);
const [seconds, setSeconds] = useState(0);
useEffect(() => {
const handleResize = () => setWidth(window.innerWidth);
const timerId = window.setInterval(() => {
setSeconds((value) => value + 1);
}, 1000);
window.addEventListener("resize", handleResize);
return () => {
// 必须使用同一个函数引用,才能移除监听器。
window.removeEventListener("resize", handleResize);
window.clearInterval(timerId);
console.log("resources cleaned");
};
}, []);
return <p>宽度:{width},运行:{seconds} 秒</p>;
}预期结果
页面每秒更新运行时间,调整窗口宽度时同步更新宽度。
组件卸载后控制台输出:resources cleaned实际宽度和运行秒数取决于浏览器窗口与停留时间。
常见资源应成对处理:addEventListener 对应 removeEventListener,setInterval 对应 clearInterval,订阅函数对应取消订阅函数,连接对象对应 close 或 disconnect。
风险与边界
清理函数中不要更新已卸载组件的状态。清理的职责是撤销外部资源,而不是启动新的业务流程。
当依赖变化时,React 会先使用旧依赖执行清理,再使用新依赖建立资源。如果清理遗漏,可能出现多个定时器、重复消息、重复监听或连接数持续增长。安全做法是让每次 Effect 都完整返回对应的撤销操作。
不要把事件处理函数直接写成两次不同的匿名函数,否则无法移除监听器。例如注册和移除必须复用同一个 handleResize 引用。
排障清单
- 回调执行多次:检查是否重复注册,以及清理函数是否真的被返回。
- 监听器无法移除:确认注册和移除使用相同函数引用及相同事件名。
- 定时器卸载后仍运行:确认保存了定时器 ID,并调用对应的清除函数。
- WebSocket 或订阅持续增加:确认依赖变化时旧连接会关闭。
- 开发环境出现“建立、清理、再建立”:React Strict Mode 会额外执行一次检查周期,代码应能安全重复建立和释放。
速查原则:Effect 创建什么资源,清理函数就撤销什么资源。
处理只需在组件进入页面后建立并在卸载时撤销的外部连接。
组件挂载时执行
当组件进入页面后需要建立一次外部连接,并在离开页面时撤销连接,可使用依赖数组为空的 useEffect。典型场景包括连接聊天服务、注册全局监听器、启动第三方组件或读取一次浏览器环境信息。
基本语法
useEffect(() => {
const connection = connect();
return () => {
connection.disconnect();
};
}, []);空依赖数组表示该 Effect 不依赖组件中的可变值。生产环境通常在挂载后建立资源,在卸载时清理;开发环境启用 Strict Mode 时,React 可能额外执行一次建立与清理,用于检查副作用是否可安全撤销。
主示例
下面使用浏览器原生 BroadcastChannel 建立跨标签页通信。打开两个同源页面即可互发消息,组件卸载时会关闭通道。
import { useEffect, useState } from "react";
export default function ChannelStatus() {
const [lastMessage, setLastMessage] = useState("暂无消息");
useEffect(() => {
const channel = new BroadcastChannel("app-status");
channel.onmessage = (event) => {
setLastMessage(String(event.data));
};
channel.postMessage("component mounted");
console.log("channel connected");
return () => {
channel.close();
console.log("channel disconnected");
};
}, []);
return <p>最后消息:{lastMessage}</p>;
}预期结果
组件挂载时控制台输出:channel connected
另一个同源页面收到消息时,页面显示对应消息内容。
组件卸载时控制台输出:channel disconnectedBroadcastChannel 不会把消息发送回创建消息的同一个对象,因此单独打开一个页面时,页面仍可能显示“暂无消息”。
使用边界
[] 不是“强制只运行一次”的命令,而是声明 Effect 内不读取会变化的响应式值。如果 Effect 使用了 roomId、url、属性或状态,却仍保留空数组,连接将一直使用首次渲染时的旧值。
需要随参数重连时,应把参数加入依赖数组:
useEffect(() => {
const connection = createConnection(serverUrl, roomId);
connection.connect();
return () => connection.disconnect();
}, [serverUrl, roomId]);预期结果
serverUrl 或 roomId 变化时:先断开旧连接,再建立新连接。
组件卸载时:断开当前连接。不要为了绕过依赖检查而随意填写 []。触发条件是 Effect 读取了可能变化的值;可能后果是使用旧配置、连接错误房间或无法响应属性变化;安全替代方案是补全依赖,或把确实固定的配置移到组件外部。
排障清单
- 开发环境连接两次:检查是否启用了 Strict Mode,并确认清理函数能完整断开第一次连接。
- 参数变化后仍连接旧目标:把 Effect 中读取的属性和状态加入依赖数组。
- 卸载后仍收到消息:确认连接、订阅或监听器在返回函数中关闭。
- Effect 每次渲染都执行:确认第二个参数确实是
[],而不是省略依赖数组。 - 连接对象需要被按钮使用:将对象保存到
useRef,不要仅依赖 Effect 内的局部变量。
速查原则:固定外部资源使用空依赖数组;资源依赖参数时,依赖数组必须包含这些参数。
在指定属性或状态变化后重新执行同步逻辑并清理旧资源。
响应依赖变化
当组件需要随属性或状态变化去订阅事件、启动定时器、连接外部资源时,用 useEffect 建立同步逻辑,并在依赖变化或组件卸载前清理旧资源。
基本语法
useEffect(() => {
// 建立订阅、连接或定时任务
return () => {
// 清理上一次建立的资源
};
}, [dependency]);依赖数组省略时每次渲染后执行;[] 只在挂载后建立、卸载前清理;[a, b] 会在 a 或 b 按 Object.is 比较发生变化后重新执行。
高频用法
下面的组件监听指定快捷键。hotkey 改变时,React 会先移除旧监听器,再注册使用新快捷键的监听器。
import { useEffect, useState } from 'react';
export default function KeyCounter({ hotkey = 'k' }) {
const [count, setCount] = useState(0);
useEffect(() => {
function handleKeyDown(event) {
if (event.key.toLowerCase() === hotkey.toLowerCase()) {
setCount((value) => value + 1);
}
}
window.addEventListener('keydown', handleKeyDown);
// 必须移除同一个函数引用,否则旧监听器会残留。
return () => {
window.removeEventListener('keydown', handleKeyDown);
};
}, [hotkey]);
return <p>快捷键 {hotkey}:{count} 次</p>;
}预期结果
hotkey="k" 时按 k 三次:
快捷键 k:3 次
把 hotkey 改为 "x" 后,按 k 不再增加,按 x 会继续计数。风险与边界
Effect 回调不能返回 Promise,只能返回清理函数或不返回值。不要写成 useEffect(async () => {}),应在 Effect 内定义并调用异步函数。
依赖中遗漏组件内读取的属性、状态或函数,会让 Effect 持有旧值;把每次渲染都会新建的对象或函数直接放入依赖,又可能导致频繁重跑。优先把对象创建移入 Effect,或用 useMemo、useCallback稳定引用。
开发环境启用 Strict Mode 时,React 会额外执行一次“建立→清理→建立”以暴露清理缺陷。若出现重复监听或重复定时器,通常说明清理函数不完整,不应通过删除依赖来规避。
排障清单
- Effect 不重跑:确认依赖值确实变化,且没有直接修改原对象或数组。
- Effect 无限重跑:检查依赖中是否有每次渲染新建的对象、数组或函数。
- 资源重复:确认清理函数使用与建立阶段相同的句柄或函数引用。
- 页面值可直接由现有 props/state 计算时,不要用 Effect 再同步一份状态。
速查:依赖决定何时重建同步关系,清理函数负责撤销上一次建立的关系。
组织异步请求、加载状态、错误处理和过期响应取消逻辑。
在 Effect 中请求数据
当数据必须由组件属性或状态决定,并且暂时没有框架数据加载器或请求库可用时,可在 useEffect 中组织加载、成功、失败和取消逻辑,避免旧请求覆盖新结果。
基本结构
Effect 本身保持同步,在内部启动异步函数;每次依赖变化时创建新的 AbortController,清理阶段取消旧请求,并用忽略标记阻止无法取消的过期结果写入状态。
高频用法
下面的组件根据 userId 请求用户信息。它覆盖加载状态、HTTP 错误、网络错误以及快速切换参数时的过期响应处理。
import { useEffect, useState } from 'react';
export default function UserCard({ userId = 1 }) {
const [status, setStatus] = useState('idle');
const [user, setUser] = useState(null);
const [error, setError] = useState('');
useEffect(() => {
const controller = new AbortController();
let ignore = false;
async function loadUser() {
setStatus('loading');
setError('');
try {
const response = await fetch(
`https://jsonplaceholder.typicode.com/users/${encodeURIComponent(userId)}`,
{ signal: controller.signal }
);
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
const data = await response.json();
// 即使底层请求无法及时取消,旧响应也不能覆盖新状态。
if (!ignore) {
setUser(data);
setStatus('success');
}
} catch (cause) {
if (cause instanceof DOMException && cause.name === 'AbortError') {
return;
}
if (!ignore) {
setUser(null);
setError(cause instanceof Error ? cause.message : String(cause));
setStatus('error');
}
}
}
loadUser();
return () => {
ignore = true;
controller.abort();
};
}, [userId]);
if (status === 'loading') return <p>加载中…</p>;
if (status === 'error') return <p>请求失败:{error}</p>;
if (!user) return null;
return (
<p>
{user.name}({user.username})
</p>
);
}预期结果
userId=1 且接口可访问时:
加载中…
Leanne Graham(Bret)
快速把 userId 从 1 改为 2 时,只保留第二次请求的结果:
Ervin Howell(Antonette)实际网络耗时不同;请求被取消时不会进入错误界面。
风险与边界
不要只写 fetch(...).then(setUser)。当 userId 快速变化时,较慢的旧请求可能最后返回并覆盖新数据;组件卸载后继续更新状态,也会造成无效工作。安全替代是同时使用 AbortController 和过期结果守卫。
fetch 只会在网络失败或被取消时拒绝 Promise,404、500 仍会正常返回响应,因此必须检查 response.ok。取消异常应单独忽略,不能显示为业务错误。
开发环境 Strict Mode 可能看到两次请求,其中第一次会在清理阶段被取消。若业务需要缓存、去重、预取、服务端渲染或跨组件共享数据,优先使用框架的数据加载能力或专门的请求缓存库,而不是继续扩展手写 Effect。
排障清单
- 一直显示加载中:确认成功和失败分支都会更新
status。 - 旧数据闪回:确认依赖变化时执行
abort(),并在写状态前检查ignore。 404被当成功:确认在解析响应前检查response.ok。- Effect 重复请求:检查依赖是否包含每次渲染新建的对象或函数。
- 请求参数为空:在发起请求前增加条件分支,并清空或保留旧数据的策略。
速查:每次依赖变化只信任当前请求;旧请求要取消,不能取消的旧结果要忽略。
定位不稳定依赖和重复状态更新导致的副作用循环。
避免 Effect 无限循环
当页面出现“Maximum update depth exceeded”、请求连续发送或组件持续重渲染时,先检查 Effect 是否更新了自己的依赖,以及依赖中是否存在每次渲染都会重新创建的对象、数组或函数。
常见触发条件
无限循环通常来自两类链路:Effect 调用 setState,该状态变化后再次命中依赖;或依赖写入了 {}、[]、内联函数等不稳定引用,React 每次渲染都把它们视为新值。
不要通过删除依赖数组或禁用 ESLint 规则掩盖问题。这样可能暂时停止循环,却会引入旧值、漏同步或难以复现的数据错误。
稳定依赖并限制更新
下面的示例把对象依赖放进 useMemo,并在写入状态前比较新旧值。复制到 React 项目中的 App.jsx 可直接运行。
import { useEffect, useMemo, useState } from 'react';
export default function App() {
const [query, setQuery] = useState('react');
const [resultCount, setResultCount] = useState(0);
// 避免每次渲染都创建新对象,导致 Effect 重复执行。
const options = useMemo(() => ({ limit: 10 }), []);
useEffect(() => {
const nextCount = query.trim() ? options.limit : 0;
// 新旧值相同时返回原状态,阻断无意义的再次渲染。
setResultCount((current) =>
current === nextCount ? current : nextCount
);
}, [query, options]);
return (
<main>
<input
value={query}
onChange={(event) => setQuery(event.target.value)}
/>
<p>结果数:{resultCount}</p>
</main>
);
}预期结果
初始显示:结果数:10
清空输入框后显示:结果数:0
输入任意非空文本后恢复:结果数:10
控制台不会出现 Maximum update depth exceeded高频修复方式
依赖是对象或数组时,优先把创建逻辑移入 Effect,或用 useMemo 稳定引用。依赖是函数时,优先直接在 Effect 内定义;只有函数还被其他位置复用或传给子组件时才考虑 useCallback。
Effect 只需要基于旧状态计算新状态时,使用函数式更新,例如 setCount((value) => value + 1),并避免把 count 同时加入依赖。若更新后的状态本质上可由现有 props 或 state 计算,应删除该状态和 Effect,改为渲染期间直接计算。
排障清单
- 查看报错组件,定位最近一次执行
setState的 Effect。 - 暂时记录依赖值,确认哪一项在每次渲染后引用都变化。
- 检查 Effect 更新的状态是否也出现在依赖数组中。
- 确认更新前是否缺少“新旧值不同才写入”的条件。
- 保留
eslint-plugin-react-hooks的exhaustive-deps检查,再从代码结构上修复依赖。
速查原则:Effect 应同步外部系统;若它只是在组件内部搬运或派生状态,通常应先考虑移除。
将纯计算、事件响应和状态派生逻辑移出 Effect,减少额外渲染。
移除不必要的 Effect
当 Effect 只是根据 props 或 state 计算另一个值、响应点击事件,或把一个状态复制到另一个状态时,应把逻辑移到渲染过程或事件处理函数中。这样可避免额外一次渲染、状态不同步和依赖维护成本。
直接派生数据
纯计算不需要 Effect。只要输入相同就能得到相同结果的值,应在组件渲染时计算;计算确实昂贵时再用 useMemo 缓存,而不是先写入额外状态。
下面示例直接派生过滤结果,并把提交动作放进事件处理函数。复制到 React 项目中的 App.jsx 可直接运行。
import { useState } from 'react';
const PRODUCTS = ['React Book', 'Vue Guide', 'Node Handbook'];
export default function App() {
const [query, setQuery] = useState('');
const [submittedQuery, setSubmittedQuery] = useState('');
// 这是纯计算,输入变化时在渲染阶段重新得到结果即可。
const visibleProducts = PRODUCTS.filter((product) =>
product.toLowerCase().includes(query.trim().toLowerCase())
);
function handleSubmit(event) {
event.preventDefault();
// 用户动作应在事件处理函数中响应,不需要等待 Effect。
setSubmittedQuery(query.trim());
}
return (
<main>
<form onSubmit={handleSubmit}>
<input
value={query}
onChange={(event) => setQuery(event.target.value)}
placeholder="搜索商品"
/>
<button type="submit">提交</button>
</form>
<p>匹配数量:{visibleProducts.length}</p>
<p>最近提交:{submittedQuery || '无'}</p>
<ul>
{visibleProducts.map((product) => (
<li key={product}>{product}</li>
))}
</ul>
</main>
);
}预期结果
初始显示 3 个商品,最近提交为“无”
输入 react 后只显示 React Book,匹配数量为 1
点击“提交”后,最近提交显示 react
整个过程不需要 useEffect,也不会产生额外的同步渲染常见迁移位置
由现有数据得到的全名、过滤列表、总价或布尔标记,直接在组件函数中计算。由点击、提交、拖拽等用户动作触发的请求或状态修改,放进对应事件处理函数。
需要在某个标识变化时重置整棵子树状态,可给子组件设置不同的 key。多个状态必须同步变化时,优先在同一个事件中一起更新,或合并为一个更清晰的状态结构。
何时仍然需要 Effect
Effect 适合与 React 外部系统同步,例如订阅 WebSocket、控制第三方组件、调用浏览器 API、启动定时器或根据当前参数发起网络请求。此时应同时实现清理逻辑,并确保依赖准确。
不要为了“只运行一次”而机械使用空依赖数组。若逻辑属于初始化常量,可放到组件外;若属于用户动作,放到事件中;若属于数据派生,直接计算。
排障清单
- Effect 内只有
setState,且新值完全由现有 props/state 得出:删除 Effect,直接派生。 - Effect 监听某个事件标记再执行动作:把动作移到真正的事件处理函数。
- 两份状态长期保存同一信息:保留单一数据源,删除镜像状态。
- 删除 Effect 后出现性能问题:先测量,再只对昂贵纯计算使用
useMemo。
速查原则:没有外部系统需要同步,就先假设不需要 Effect。
使用 useRef 获取元素节点并执行聚焦、滚动或尺寸读取操作。
使用 useRef 读取 DOM 节点
需要让输入框聚焦、滚动到指定元素或读取元素尺寸时,将 ref 绑定到原生 DOM 元素,并在事件处理函数或 Effect 中访问 ref.current。
基本语法
使用元素类型作为 useRef 泛型,初始值设为 null。React 完成 DOM 提交后会把节点写入 current,元素卸载后重新设为 null。
const inputRef = useRef<HTMLInputElement>(null);
<input ref={inputRef} />
function focusInput() {
inputRef.current?.focus();
}预期结果
调用 focusInput() 后,输入框获得焦点并显示输入光标。高频用法
下面的组件同时演示聚焦、滚动和尺寸读取,可直接放入 React TypeScript 项目运行。
import { useRef, useState } from "react";
export default function DomRefDemo() {
const inputRef = useRef<HTMLInputElement>(null);
const panelRef = useRef<HTMLDivElement>(null);
const [size, setSize] = useState("未读取");
function focusInput() {
inputRef.current?.focus();
}
function scrollAndMeasure() {
const panel = panelRef.current;
if (!panel) return;
panel.scrollIntoView({ behavior: "smooth", block: "center" });
const rect = panel.getBoundingClientRect();
setSize(`${Math.round(rect.width)} × ${Math.round(rect.height)} px`);
}
return (
<main style={{ minHeight: 900, padding: 24 }}>
<input ref={inputRef} placeholder="输入内容" />
<button onClick={focusInput}>聚焦输入框</button>
<div ref={panelRef} style={{ marginTop: 500, padding: 24 }}>
目标区域
</div>
<button onClick={scrollAndMeasure}>滚动并读取尺寸</button>
<p>尺寸:{size}</p>
</main>
);
}预期结果
点击“聚焦输入框”:输入光标进入输入框。
点击“滚动并读取尺寸”:页面滚动到目标区域,尺寸文本更新为类似 720 × 72 px。尺寸会随窗口宽度、样式和缩放比例变化。需要在浏览器绘制前测量并同步调整布局时使用 useLayoutEffect;普通读取优先放在点击事件或 useEffect 中。
风险与边界
首次渲染期间节点尚未挂载,直接执行 ref.current.focus() 可能因 current 为 null 报错,应使用可选链或显式判空。
不要通过 ref 随意修改由 React 管理的文本、属性或子节点,否则后续渲染可能覆盖修改。ref 更适合调用浏览器命令、读取布局或接入第三方 DOM 库。
服务端渲染环境没有真实 DOM,尺寸读取和滚动操作只能在客户端事件或 Effect 中执行。
排障清单
current一直为null:确认 ref 已绑定到原生元素,且目标元素当前确实被渲染。- 自定义组件无法取得节点:组件需要接收并转交 ref,或提供明确的节点访问接口。
- 尺寸为
0:检查元素是否被display: none隐藏,或是否在布局完成前读取。 - 修改
current后页面不更新:ref 变化不会触发渲染,需要展示的数据应写入 state。
使用 useRef 保存定时器标识、实例或其他不应触发渲染的可变值。
使用 useRef 保存非渲染数据
定时器标识、WebSocket 实例、AbortController 或上一次值需要跨渲染保留,但变化后不应刷新页面时,使用 useRef 保存。数据存放在 ref.current,组件整个挂载周期内保持同一个容器。
基本语法
const timerRef = useRef<number | null>(null);
timerRef.current = window.setTimeout(() => {
console.log("done");
}, 1000);预期输出
done赋值给 current 不会触发重新渲染。需要把值显示到页面时,应同时使用 useState,不要依赖 ref 自动刷新界面。
高频用法
下面的组件使用 ref 保存定时器标识和累计次数,并阻止重复启动定时器。
import { useEffect, useRef, useState } from "react";
export default function TimerRefDemo() {
const timerRef = useRef<number | null>(null);
const tickRef = useRef(0);
const [status, setStatus] = useState("已停止");
function start() {
// 已运行时直接返回,避免创建多个并行定时器。
if (timerRef.current !== null) return;
timerRef.current = window.setInterval(() => {
tickRef.current += 1;
console.log(`tick=${tickRef.current}`);
}, 1000);
setStatus("运行中");
}
function stop() {
if (timerRef.current === null) return;
window.clearInterval(timerRef.current);
timerRef.current = null;
setStatus("已停止");
}
useEffect(() => {
return () => {
// 组件卸载时清理外部资源,避免后台任务继续执行。
if (timerRef.current !== null) {
window.clearInterval(timerRef.current);
timerRef.current = null;
}
};
}, []);
return (
<section>
<p>状态:{status}</p>
<button onClick={start}>开始</button>
<button onClick={stop}>停止</button>
</section>
);
}预期输出
页面初始显示:状态:已停止
点击“开始”后显示:状态:运行中
控制台约每秒输出:
tick=1
tick=2
tick=3
点击“停止”后不再继续输出。适合保存的值
适合放入 ref 的通常是定时器标识、请求取消控制器、第三方库实例、媒体播放器对象、最新回调函数以及只供事件处理逻辑读取的计数器。
会直接影响页面内容、样式或条件渲染的数据应使用 state。判断标准是:值变化后用户是否需要立即看到新的渲染结果。
风险与边界
组件卸载后仍运行定时器、订阅或网络连接,会造成资源泄漏和重复回调。创建外部资源时必须同时设计清理逻辑,并在 Effect 的清理函数中释放。
事件回调可能捕获旧 state。需要读取最新值但不希望重建订阅时,可以把最新值同步到 ref;如果变化需要驱动页面更新,仍应以 state 为准。
不要在渲染过程中随意读取或修改业务 ref。并发渲染下,渲染函数可能被重新执行或放弃,副作用应放在事件处理函数或 Effect 中。
排障清单
- 点击开始后出现多倍输出:增加
current !== null的重复启动保护。 - 页面没有显示最新 ref 值:使用 state 保存需要展示的数据。
- 切换页面后仍有日志或请求:检查 Effect 是否返回了清理函数。
- TypeScript 报定时器类型冲突:浏览器项目使用
number | null和window.setInterval,避免混用 Node.js 定时器类型。