使用 Effects 进行同步

什么是 Effects，它们与事件有何不同？

在了解 Effects 之前，你需要先熟悉 React 组件内部的两类逻辑：

• 渲染代码（在 描述 UI 中介绍）位于组件的顶层。这是你获取 props 和 state、对它们进行转换并返回你想在屏幕上看到的 JSX 的地方。渲染代码必须是纯的。 就像数学公式一样，它应该只会 计算 结果，而不做其他事情。

• 事件处理函数（在 添加交互 中介绍）是组件内部嵌套的函数，它们会做一些事情，而不仅仅是计算。事件处理函数可能会更新输入框、提交一个用于购买商品的 HTTP POST 请求，或者把用户导航到另一个界面。事件处理函数包含由特定用户操作（例如按钮点击或输入）引起的 “副作用”（它们会改变程序的状态）。

有时这还不够。考虑一个 ChatRoom 组件：它在屏幕上可见时必须连接到聊天服务器。连接到服务器不是一个纯计算（它是一个副作用），所以它不能在渲染期间发生。然而，并没有某个像点击这样明确的事件会让 ChatRoom 显示出来。

Effects 让你可以指定由渲染本身而不是某个特定事件引起的副作用。 在聊天中发送消息是一个 事件，因为它直接由用户点击某个特定按钮触发。然而，建立服务器连接是一个 Effect，因为无论是什么交互让组件出现，它都应该发生。Effects 会在屏幕更新后的 提交 结束时运行。这是将 React 组件与某个外部系统（如网络或第三方库）同步的好时机。

你可能不需要 Effect

不要急着给组件添加 Effects。 请记住，Effects 通常用于“走出”你的 React 代码，并与某个 外部 系统同步。这包括浏览器 API、第三方组件、网络等等。如果你的 Effect 只是根据其他 state 来调整某些 state，你可能不需要 Effect。

如何编写一个 Effect

要编写一个 Effect，请遵循以下三个步骤：

1. 声明一个 Effect。 默认情况下，你的 Effect 会在每次 提交 后运行。
2. 指定 Effect 的依赖项。 大多数 Effects 只应在需要时重新运行，而不是在每次渲染后都运行。例如，一个淡入动画只应在组件出现时触发。连接和断开聊天房间也只应在组件出现和消失时，或者聊天房间变化时发生。你将学习如何通过指定依赖项来控制这一点。
3. 如有需要，添加清理。 有些 Effects 需要说明如何停止、撤销或清理它们所做的事情。例如，“connect” 需要 “disconnect”，“subscribe” 需要 “unsubscribe”，“fetch” 需要 “cancel” 或 “ignore”。你将学习如何通过返回一个 cleanup function 来实现这一点。

让我们详细看看这三个步骤。

步骤 1：声明一个 Effect

要在组件中声明一个 Effect，请从 React 中导入 useEffect Hook：

import { useEffect } from 'react';

然后，在组件顶层调用它，并在 Effect 中放入一些代码：

function MyComponent() {
  useEffect(() => {
    // 这里的代码会在*每次*渲染后运行
  });
  return <div />;
}

每次组件渲染时，React 会先更新屏幕，然后运行 useEffect 内的代码。换句话说，useEffect 会将一段代码“延后”到该次渲染已反映到屏幕上之后再执行。

让我们看看如何使用 Effect 与外部系统同步。考虑一个 <VideoPlayer> React 组件。通过向它传入 isPlaying prop 来控制它播放还是暂停会很不错：

<VideoPlayer isPlaying={isPlaying} />;

你的自定义 VideoPlayer 组件会渲染内置的浏览器 <video> 标签：

function VideoPlayer({ src, isPlaying }) {
  // TODO: 对 isPlaying 做些处理
  return <video src={src} />;
}

然而，浏览器的 <video> 标签并没有 isPlaying prop。控制它的唯一方式是手动调用 DOM 元素上的 play() 和 pause() 方法。你需要将 isPlaying prop 的值——它表示视频当前应该处于播放状态还是暂停状态——与 play() 和 pause() 之类的调用同步起来。

我们首先需要 获取一个 ref 指向 <video> 的 DOM 节点。

你可能会想在渲染期间调用 play() 或 pause()，但这是不正确的：

这段代码不正确的原因在于，它试图在渲染期间对 DOM 节点做一些事情。在 React 中，渲染应该是对 JSX 的纯计算，不应包含诸如修改 DOM 之类的副作用。

此外，当 VideoPlayer 第一次被调用时，它的 DOM 还不存在！此时还没有 DOM 节点可供调用 play() 或 pause()，因为在你返回 JSX 之前，React 并不知道需要创建什么 DOM。

这里的解决方案是：使用 useEffect 包裹这个副作用，把它移出渲染计算：

import { useEffect, useRef } from 'react';

function VideoPlayer({ src, isPlaying }) {
  const ref = useRef(null);

  useEffect(() => {
    if (isPlaying) {
      ref.current.play();
    } else {
      ref.current.pause();
    }
  });

  return <video ref={ref} src={src} loop playsInline />;
}

通过将 DOM 更新包裹在 Effect 中，你让 React 先更新屏幕。然后你的 Effect 再运行。

当 VideoPlayer 组件渲染时（无论是第一次还是重新渲染），会发生几件事。首先，React 会更新屏幕，确保 <video> 标签以正确的 props 出现在 DOM 中。然后 React 会运行你的 Effect。最后，你的 Effect 会根据 isPlaying 的值调用 play() 或 pause()。

多次按下播放/暂停，看看视频播放器如何始终与 isPlaying 的值保持同步：

在这个例子中，你同步到 React state 的“外部系统”是浏览器媒体 API。你可以用类似的方法把旧的非 React 代码（如 jQuery 插件）包装成声明式的 React 组件。

请注意，在实践中控制视频播放器要复杂得多。调用 play() 可能会失败，用户也可能通过浏览器自带的控件播放或暂停，等等。这个例子非常简化，并不完整。

const [count, setCount] = useState(0);
useEffect(() => {
  setCount(count + 1);
});

步骤 2：指定 Effect 的依赖项

默认情况下，Effects 会在每次渲染后运行。通常，这并不是你想要的：

• 有时，这很慢。与外部系统同步并不总是瞬时完成的，所以你可能希望在没有必要时跳过它。例如，你不希望在每次按键时都重新连接聊天服务器。
• 有时，这会出错。例如，你不希望在每次按键时都触发组件的淡入动画。该动画只应在组件第一次出现时播放一次。

为了演示这个问题，下面是前一个例子，加入了一些 console.log 调用，以及一个会更新父组件 state 的文本输入框。注意输入时会导致 Effect 重新运行：

你可以通过在 useEffect 调用的第二个参数中指定一个 依赖项 数组，告诉 React 跳过不必要的 Effect 重新运行。先在上面第 14 行的示例中添加一个空的 [] 数组：

  useEffect(() => {
    // ...
  }, []);

你应该会看到一个错误提示：React Hook useEffect has a missing dependency: 'isPlaying'：

问题在于，你的 Effect 内部代码依赖于 isPlaying prop 来决定要做什么，但这个依赖并没有被显式声明。要修复这个问题，请把 isPlaying 添加到依赖数组中：

  useEffect(() => {
    if (isPlaying) { // 它在这里被使用了...
      // ...
    } else {
      // ...
    }
  }, [isPlaying]); // ...所以它必须在这里被声明！

现在所有依赖都已声明，因此不会再报错。将 [isPlaying] 指定为依赖数组，会告诉 React：如果 isPlaying 与上一次渲染时相同，就跳过重新运行你的 Effect。这样修改后，输入框中的输入不会导致 Effect 重新运行，但按下播放/暂停会：

依赖数组可以包含多个依赖项。只有当你指定的所有依赖项在值上都与上一次渲染时完全相同，React 才会跳过重新运行 Effect。React 使用 Object.is 比较依赖值。详情请参见 useEffect 参考。

请注意，你不能“选择”你的依赖项。 如果你指定的依赖项与 React 根据 Effect 内部代码所期望的不匹配，你会收到 lint 错误。这有助于发现代码中的许多 bug。如果你不想让某些代码重新运行，请修改 Effect 代码本身，让它不再“需要”那个依赖。

useEffect(() => {
  // 这会在每次渲染后运行
});

useEffect(() => {
  // 这只会在挂载时运行（组件出现时）
}, []);

useEffect(() => {
  // 这会在挂载时运行，*并且*如果 a 或 b 自上一次渲染以来发生变化，也会运行
}, [a, b]);

function VideoPlayer({ src, isPlaying }) {
  const ref = useRef(null);
  useEffect(() => {
    if (isPlaying) {
      ref.current.play();
    } else {
      ref.current.pause();
    }
  }, [isPlaying]);

function VideoPlayer({ src, isPlaying }) {
  const ref = useRef(null);
  useEffect(() => {
    if (isPlaying) {
      ref.current.play();
    } else {
      ref.current.pause();
    }
  }, [isPlaying, ref]);

步骤 3：如有需要，添加清理

考虑另一个例子。你正在编写一个 ChatRoom 组件，它需要在出现时连接到聊天服务器。你会得到一个 createConnection() API，它返回一个带有 connect() 和 disconnect() 方法的对象。如何让组件在展示给用户时始终保持连接？

先写出 Effect 逻辑：

useEffect(() => {
  const connection = createConnection();
  connection.connect();
});

每次重新渲染后都连接到聊天服务器会很慢，因此你添加依赖数组：

useEffect(() => {
  const connection = createConnection();
  connection.connect();
}, []);

Effect 内部代码没有使用任何 props 或 state，所以你的依赖数组是 []（空的）。这告诉 React 只在组件“挂载”时运行这段代码，也就是组件第一次出现在屏幕上时。

让我们尝试运行这段代码：

这个 Effect 只在挂载时运行，所以你可能会以为 "✅ Connecting..." 只会在控制台打印一次。然而，如果你检查控制台，会发现 "✅ Connecting..." 被打印了两次。为什么会这样？

想象 ChatRoom 组件是一个更大应用的一部分，而这个应用有许多不同的页面。用户从 ChatRoom 页面开始他们的旅程。组件挂载并调用 connection.connect()。然后设想用户导航到另一个页面——例如设置页面。ChatRoom 组件卸载。最后，用户点击返回，ChatRoom 再次挂载。这样就会建立第二个连接——但第一个连接从未被销毁！随着用户在应用中导航，连接会不断累积。

如果没有大量的手动测试，这类 bug 很容易被忽略。为了帮助你快速发现它们，在开发环境中，React 会在每个组件初次挂载后立即再卸载并重新挂载一次。

看到 "✅ Connecting..." 这条日志出现两次，可以帮助你注意到真正的问题：组件卸载时，你的代码没有关闭连接。

要修复这个问题，请从 Effect 中返回一个 cleanup function：

  useEffect(() => {
    const connection = createConnection();
    connection.connect();
    return () => {
      connection.disconnect();
    };
  }, []);

React 会在每次 Effect 再次运行之前调用你的 cleanup function，并且在组件卸载（被移除）时最后再调用一次。让我们看看实现了 cleanup function 之后会发生什么：

现在在开发环境中你会看到三条控制台日志：

1. "✅ 正在连接..."
2. "❌ 已断开连接。"
3. "✅ 正在连接..."

这在开发环境中是正确行为。 通过重新挂载你的组件，React 验证离开再返回页面不会破坏你的代码。断开连接然后重新连接，正是应该发生的事情！当你把 cleanup 实现好之后，Effect 只运行一次，与“运行一次、清理、再运行一次”之间不应该有任何用户可见的差异。之所以会多出一对连接/断开调用，是因为 React 在开发环境中会探测你的代码是否有 bug。这很正常——不要试图把它消除掉！

在生产环境中，你只会看到 "✅ 正在连接..." 打印一次。 组件重新挂载只会在开发环境中发生，以帮助你发现那些需要清理的 Effects。你可以关闭 Strict Mode 来退出这种开发行为，但我们建议保持开启。这样你就能发现许多类似上面这样的 bug。

在开发环境中如何处理 Effect 触发两次？

React 会在开发环境中故意重新挂载你的组件，以便发现上一示例中的这类 bug。正确的问题不是“如何让 Effect 只运行一次”，而是“如何修复我的 Effect，使它在重新挂载后仍能正常工作”。

通常，答案是实现清理函数。清理函数应该停止或撤销 Effect 所做的一切。一个经验法则是：用户不应能分辨出 Effect 只运行了一次（如生产环境中那样）和一个 setup → cleanup → setup 序列（如你在开发环境中看到的那样）之间的区别。

你写的大多数 Effect 都会符合下面这些常见模式之一。

  const connectionRef = useRef(null);
  useEffect(() => {
    // 🚩 这并不能修复这个 bug！！！
    if (!connectionRef.current) {
      connectionRef.current = createConnection();
      connectionRef.current.connect();
    }
  }, []);

控制非 React 组件

有时你需要添加一些不是用 React 编写的 UI 组件。例如，假设你要在页面中添加一个地图组件。它有一个 setZoomLevel() 方法，而你希望缩放级别与 React 代码中的 zoomLevel 状态变量保持同步。你的 Effect 会像这样：

useEffect(() => {
  const map = mapRef.current;
  map.setZoomLevel(zoomLevel);
}, [zoomLevel]);

注意，这种情况下不需要清理函数。在开发环境中，React 会调用两次这个 Effect，但这不是问题，因为用同样的值调用两次 setZoomLevel 不会产生任何作用。它可能会稍微慢一点，但这无关紧要，因为在生产环境中它不会无谓地重新挂载。

某些 API 不允许你连续调用两次。例如，内置 <dialog> 元素的 showModal 方法，如果你调用两次就会抛出错误。实现清理函数，让它关闭对话框：

useEffect(() => {
  const dialog = dialogRef.current;
  dialog.showModal();
  return () => dialog.close();
}, []);

在开发环境中，你的 Effect 会先调用 showModal()，然后立即调用 close()，再调用一次 showModal()。这与在生产环境中只调用一次 showModal() 的用户可见行为是相同的。

订阅事件

如果你的 Effect 订阅了某个内容，清理函数应该取消订阅：

useEffect(() => {
  function handleScroll(e) {
    console.log(window.scrollX, window.scrollY);
  }
  window.addEventListener('scroll', handleScroll);
  return () => window.removeEventListener('scroll', handleScroll);
}, []);

在开发环境中，你的 Effect 会先调用 addEventListener()，然后立即调用 removeEventListener()，再使用同一个处理函数再次调用 addEventListener()。因此任意时刻都只会有一个有效订阅。这与生产环境中只调用一次 addEventListener() 的用户可见行为是相同的。

触发动画

如果你的 Effect 会让某些内容产生动画，那么清理函数应该将动画重置为初始值：

useEffect(() => {
  const node = ref.current;
  node.style.opacity = 1; // 触发动画
  return () => {
    node.style.opacity = 0; // 重置为初始值
  };
}, []);

在开发环境中，opacity 会被设置为 1，然后变为 0，再变回 1。这应该与直接将它设置为 1 的用户可见行为相同，而这正是生产环境中会发生的情况。如果你使用带有补间动画支持的第三方动画库，清理函数应该把时间线重置回初始状态。

获取数据

如果你的 Effect 会请求某些数据，清理函数应该中止这次请求或者忽略其结果：

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

  async function startFetching() {
    const json = await fetchTodos(userId);
    if (!ignore) {
      setTodos(json);
    }
  }

  startFetching();

  return () => {
    ignore = true;
  };
}, [userId]);

你无法“撤销”一个已经发生的网络请求，但你的清理函数应该确保那些_不再相关_的请求不会继续影响你的应用。如果 userId 从 'Alice' 变为 'Bob'，清理过程会确保即使 'Alice' 的响应在 'Bob' 之后到达，也会被忽略。

在开发环境中，你会在 Network 面板里看到两个请求。 这没有任何问题。使用上面的方案时，第一个 Effect 会立即被清理，因此它对应的 ignore 变量会被设为 true。所以即使多发出了一次请求，也不会因为 if (!ignore) 检查而影响状态。

在生产环境中，只会有一个请求。 如果开发环境中的第二个请求让你感到困扰，最好的办法是使用一种可以对请求去重并在组件之间缓存响应的方案：

function TodoList() {
  const todos = useSomeDataLibrary(`/api/user/${userId}/todos`);
  // ...

这不仅会改善开发体验，也会让你的应用感觉更快。例如，用户按下后退按钮时，不必再等待某些数据重新加载，因为它已经被缓存了。你可以自己构建这样的缓存，或者使用其他多种替代手动在 Effect 中获取数据的方案之一。

发送分析数据

考虑这段在页面访问时发送分析事件的代码：

useEffect(() => {
  logVisit(url); // 发送一个 POST 请求
}, [url]);

在开发环境中，每个 URL 的 logVisit 都会被调用两次，所以你可能会想要修复它。我们建议保持这段代码不变。 和前面的例子一样，运行一次和运行两次之间没有任何用户可见的行为差异。从实际角度来看，logVisit 在开发环境中不应该做任何事情，因为你不希望开发机器上的日志扭曲生产环境的指标。每次你保存文件时，组件都会重新挂载，所以它在开发环境中本来就会额外记录访问。

在生产环境中，不会有重复的访问日志。

如果你想调试发送出去的分析事件，可以把应用部署到预发布环境（以生产模式运行），或者临时关闭 Strict Mode 及其仅在开发环境下进行的重新挂载检查。你也可以从路由变化事件处理函数中发送分析数据，而不是通过 Effects。对于更精确的分析，交叉观察器可以帮助你跟踪哪些组件位于视口中，以及它们保持可见的时间。

不是 Effect：初始化应用

有些逻辑只应该在应用启动时运行一次。你可以把它放到组件外部：

if (typeof window !== 'undefined') { // 检查我们是否在浏览器中运行。
  checkAuthToken();
  loadDataFromLocalStorage();
}

function App() {
  // ...
}

这可以保证此类逻辑只会在浏览器加载页面后运行一次。

不是 Effect：购买商品

有时，即使你写了清理函数，也无法阻止 Effect 运行两次所带来的用户可见后果。例如，也许你的 Effect 会发送一个 POST 请求，比如购买商品：

useEffect(() => {
  // 🔴 错误：这个 Effect 在开发环境中会触发两次，暴露出代码中的问题。
  fetch('/api/buy', { method: 'POST' });
}, []);

你不会希望把商品买两次。然而，这也正是你不应该把这段逻辑放进 Effect 的原因。如果用户去了另一个页面，然后按下返回键呢？你的 Effect 还会再次运行。你不希望用户在访问某个页面时完成购买；你希望在用户点击购买按钮时完成购买。

购买不是由渲染引起的；它是由某个特定交互引起的。它应该只在用户按下按钮时运行。删除这个 Effect，并把你的 /api/buy 请求移动到购买按钮的事件处理函数中：

  function handleClick() {
    // ✅ 购买是一个事件，因为它是由某次特定交互引起的。
    fetch('/api/buy', { method: 'POST' });
  }

这说明，如果重新挂载破坏了你应用的逻辑，这通常是在揭示已有的 bug。 从用户的角度来看，访问一个页面、点击一个链接再按下返回键回到该页面，和直接访问该页面不应该有区别。React 通过在开发环境中对组件重新挂载一次，来验证你的组件是否遵循这一原则。

把它们组合起来

这个示例可以帮助你在实践中“感受” Effects 的工作方式。

这个示例使用 setTimeout 来安排一次控制台日志输出：Effect 运行后三秒，显示输入框中的文本。清理函数会取消待处理的超时。先点击“挂载组件”开始：

你最开始会看到三条日志：安排 "a" 的日志、取消 "a" 的日志，然后 আবার 安排 "a" 的日志。三秒后还会看到一条 a 的日志。正如你前面学到的，多出来的一组安排/取消，是因为 React 在开发环境中会重新挂载一次组件，以验证你是否正确实现了清理。

现在把输入内容改成 abc。如果你操作够快，你会立刻看到 安排 "ab" 的日志，紧接着是 取消 "ab" 的日志 和 安排 "abc" 的日志。React 总是在下一次渲染的 Effect 之前，先清理上一次渲染的 Effect。 这就是为什么即使你快速输入，任意时刻也最多只有一个 timeout 在等待执行。多试几次并观察控制台，感受一下 Effects 是如何被清理的。

在输入框里输入一些内容，然后立刻点击“卸载组件”。注意卸载会如何清理最后一次渲染的 Effect。这里，它会在最后一个 timeout 有机会触发之前把它清除掉。

最后，编辑上面的组件并注释掉清理函数，这样 timeout 就不会被取消。试着快速输入 abcde。你觉得三秒后会发生什么？timeout 内部的 console.log(text) 会打印 最新的 text 并输出五条 abcde 日志吗？试试看，验证一下你的直觉！

三秒后，你应该会看到一串日志（a、ab、abc、abcd 和 abcde），而不是五条 abcde 日志。每个 Effect 都会“捕获”其对应渲染中的 text 值。 text 状态变了并不重要：来自 text = 'ab' 那次渲染的 Effect 永远只会看到 'ab'。换句话说，每次渲染中的 Effects 都是彼此隔离的。如果你好奇这是怎么做到的，可以阅读 闭包 相关内容。

export default function ChatRoom({ roomId }) {
  useEffect(() => {
    const connection = createConnection(roomId);
    connection.connect();
    return () => connection.disconnect();
  }, [roomId]);

  return <h1>Welcome to {roomId}!</h1>;
}

  // 第一次渲染的 JSX（roomId = "general"）
  return <h1>Welcome to general!</h1>;

  // 第一次渲染的 Effect（roomId = "general"）
  () => {
    const connection = createConnection('general');
    connection.connect();
    return () => connection.disconnect();
  },
  // 第一次渲染的依赖项（roomId = "general"）
  ['general']

  // 第二次渲染的 JSX（roomId = "general"）
  return <h1>Welcome to general!</h1>;

  // 第二次渲染的 Effect（roomId = "general"）
  () => {
    const connection = createConnection('general');
    connection.connect();
    return () => connection.disconnect();
  },
  // 第二次渲染的依赖项（roomId = "general"）
  ['general']

  // 第三次渲染的 JSX（roomId = "travel"）
  return <h1>Welcome to travel!</h1>;

  // 第三次渲染的 Effect（roomId = "travel"）
  () => {
    const connection = createConnection('travel');
    connection.connect();
    return () => connection.disconnect();
  },
  // 第三次渲染的依赖项（roomId = "travel"）
  ['travel']