使用 Effect 进行同步

什么是 Effect，它与事件（event）有何不同？

在接触 Effect 之前，你需要熟悉 React 组件中的两种逻辑类型：

• 渲染代码（在 描述 UI 中有介绍）位于组件的顶层。你在这里处理 props 和 state，对它们进行转换，并返回希望在页面上显示的 JSX。渲染代码必须是纯粹的——就像数学公式一样，它只应该“计算”结果，而不做其他任何事情。

• 事件处理程序（在 添加交互性 中有介绍）是组件内部的嵌套函数，它们不光进行计算, 还会执行一些操作。事件处理程序可能会更新输入字段、提交 HTTP POST 请求来购买产品，或者将用户导航到另一个页面。事件处理程序包含由特定用户操作（例如按钮点击或输入）引起的“副作用”（它们改变了程序的状态）。

有时这还不够。考虑一个 ChatRoom 组件，它在页面上显示时必须连接到聊天服务器。连接到服务器并不是纯粹的计算（它是一个副作用），因此它不能在渲染期间发生。然而，并没有一个特定的事件（比如点击）能让 ChatRoom 被显示。

Effect 允许你指定由渲染自身，而不是特定事件引起的副作用。在聊天中发送消息是一个“事件”，因为它直接由用户点击特定按钮引起。然而，建立服务器连接是一个 Effect，因为无论哪种交互致使组件出现，它都应该发生。Effect 在 提交 结束后、页面更新后运行。此时是将 React 组件与外部系统（如网络或第三方库）同步的最佳时机。

你可能不需要 Effect

不要急着在你的组件中使用 Effect。记住，Effect 通常用于暂时“跳出” React 并与一些 外部 系统进行同步。这包括浏览器 API、第三方小部件，以及网络等等。如果你的 Effect 只是根据其他状态来调整某些状态，那么 你可能并不需要一个 Effect。

如何编写 Effect

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

1. 声明 Effect。通常 Effect 会在每次 提交 后运行。
2. 指定 Effect 依赖。大多数 Effect 应该按需运行，而不是在每次渲染后都运行。例如，淡入动画应该只在组件出现时触发。连接和断开服务器的操作只应在组件出现和消失时，或者切换聊天室时执行。你将通过指定 依赖项 来学习如何控制这一点。
3. 必要时添加清理操作。一些 Effect 需要指定如何停止、撤销，或者清除它们所执行的操作。例如，“连接”需要“断开”，“订阅”需要“退订”，而“获取数据”需要“取消”或者“忽略”。你将学习如何通过返回一个 清理函数 来实现这些。

让我们详细看看每一步。

第一步：声明 Effect

先从 React 中导入 useEffect Hook：

import { useEffect } from 'react';

再在组件顶部调用, 并在其中加入一些代码：

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 属性。控制它的唯一方式是在 DOM 元素上调用 play() 和 pause() 方法。因此，你需要将 isPlaying prop 的值（表示视频当前是否应该播放）与 play() 和 pause() 等函数的调用进行同步。

我们首先需要获取 <video> DOM 节点的 对象引用。

你可能会尝试在渲染期间调用 play() 或 pause()，但这样做是不对的：

这段代码之所以不对，是因为它试图在渲染期间对 DOM 节点进行操作。在 React 中，渲染应该是纯粹的计算 JSX，不应该包含任何像修改 DOM 这样的副作用。

而且，当第一次调用 VideoPlayer 时，对应的 DOM 节点还不存在！因为 React 在你返回 JSX 之前不知道要创建什么样的 DOM，所以没有 DOM 节点可以调用 play() 或 pause() 方法。

解决办法是 使用 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);
});

第二步：指定 Effect 的依赖项

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

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

为了演示这个问题，以下是在之前的示例中加入了一些 console.log 调用和一个更新父组件 state 的文本输入框。注意在输入时是如何触发 Effect 重新运行的：

通过在调用 useEffect 时指定一个 依赖数组 作为第二个参数，你可以让 React 跳过不必要地重新运行 Effect。首先，在上面示例的第 14 行中传入一个空数组 []：

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

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

原因在于，你的 Effect 内部代码依赖于 isPlaying prop 来决定该做什么，但你并没有显式声明这个依赖关系。为了解决这个问题，将 isPlaying 添加至依赖数组中：

  useEffect(() => {
    if (isPlaying) { // isPlaying 在此处使用……
      // ...
    } else {
      // ...
    }
  }, [isPlaying]); // ……所以它必须在此处声明！

现在所有的依赖都已经声明，所以没有错误了。指定 [isPlaying] 作为依赖数组会告诉 React：如果 isPlaying 与上次渲染时相同，就跳过重新运行 Effect。这样一来，输入框的输入不会触发 Effect 重新运行，只有按下播放/暂停按钮会触发。

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

请注意，你不能随意“选择”依赖项。如果你指定的依赖项与 React 根据 Effect 内部代码所推断出的依赖项不匹配，你将收到来自 linter 的错误提示。这有助于捕捉代码中的许多 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]);

第三步：按需添加清理（cleanup）函数

考虑一个不同的例子。假如你正在编写一个 ChatRoom 组件，该组件在显示时需要连接到聊天服务器。现在为你提供了 createConnection() API，该 API 返回一个包含 connect() 与 disconnection() 方法的对象。如何确保组件在显示时始终保持连接？

从编写 Effect 的逻辑开始：

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

如果每次重新渲染后都得进行连接，这会很慢，所以你需要添加依赖数组：

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

由于 Effect 中的代码没有使用任何 props 或 state，所以依赖数组为空数组 []。这告诉 React 仅在组件“挂载”（即首次显示在页面上）时运行此代码。

试试运行下面的代码：

这里的 Effect 仅在组件挂载时运行，所以你可能以为 "✅ 连接中……" 只会在控制台中被打印一次。然而实际情况是 "✅ 连接中……" 被打印了两次！为什么会这样？

假设 ChatRoom 组件是一个大型多页面应用中的一部分。用户最初在 ChatRoom 页面上。组件挂载并调用 connection.connect() 。接着用户可能会导航到另一个页面，比如切换到“设置”页面，于是 ChatRoom 组件被卸载。最后，当用户点击“返回”时，ChatRoom 组件再次挂载。这将建立第二个连接——但第一个连接从未被销毁！随着用户在应用中来回切换，连接将会不断累积。

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

两次出现 "✅ 连接中……" 能够帮助你注意到真正的问题：在代码中，组件被卸载时没有关闭连接。

为了解决这个问题，可以在 Effect 中返回一个 清理（cleanup）函数 。

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

React 会在每次 Effect 重新运行之前调用清理函数，并在组件卸载（被移除）时最后一次调用清理函数。让我们看看实现清理函数后会发生什么：

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

1. "✅ 连接中……"
2. "❌ 连接断开。"
3. "✅ 连接中……"

在开发环境下，这是正确的行为。通过重新挂载你的组件，React 验证了离开页面再返回不会导致代码出错。因为本就应该先断开然后再重新连接！如果你很好地实现了清理函数，那么无论是只执行一次 Effect ，还是执行、清理、再执行，都应该没有用户可见的区别。之所以会有额外的一次 connect/disconnect 调用，是因为在开发环境下 React 在检测你代码中的 bug。因此这是正常现象，不要去试图消除它！

在生产环境下，你只会看到 "✅ 连接中……" 打印一次。这是因为重新挂载组件只会在开发环境下发生，以此帮助你找到需要清理的 Effect。你可以通过关闭 严格模式 来禁用这个行为，但我们建议保留它。它可以帮助你发现许多类似上述的 bug。

如何处理在开发环境下 Effect 运行了两次？

React 有意在开发环境下重新挂载你的组件，来找到类似上例中的 bug。你需要思考的不是“如何只运行一次 Effect”，而是“如何修复我的 Effect 来让它在重新挂载后正常运行”。

通常，答案是实现清理函数。清理函数应该停止或撤销 Effect 所做的一切。原则是用户不应该感受到 Effect 只执行一次（在生产环境中）和连续执行“挂载 → 清理 → 挂载”（在开发环境中）之间的区别。

你将编写的大多数 Effect 都会符合下列的常见模式之一。

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

管理非 React 小部件

有时你需要添加不是用 React 实现的 UI 小部件。比如说你想在你的页面添加一个地图组件。它有一个 setZoomLevel() 方法，然后你希望地图的缩放比例和代码中的 zoomLevel state 保持同步。你的 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; // 重置为初始值
  };
}, []);

在开发环境中，透明度由 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' 之后到达。

在开发环境中，你会在浏览器调试工具的“网络”选项卡中看到两条请求。这是正常的。使用上述方法，第一个 Effect 将立即被清理，所以它的 ignore 变量会被设置为 true。因此，即使有额外的请求，由于有 if (!ignore) 的检查，也不会影响 state。

在生产环境中，只会有一条请求。如果开发环境中的第二次请求给你造成了困扰，最好的办法是使用一个能够对请求去重并缓存响应的方案：

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

这不仅可以提高开发体验，还可以让你的应用程序响应更快。例如，当用户点击返回按钮时，不用再等待数据重新加载，因为它已经被缓存。你可以自己构建这样的缓存机制，也可以使用很多在 Effect 中手动获取数据的替代方法。

发送分析报告

考虑以下代码，它在页面访问时发送一个分析事件：

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

在开发环境中，对于每个 URL，logVisit 都会被调用两次，因此你可能会尝试修复这个问题。我们建议保持不动。与之前示例类似，运行一次还是运行两次，在用户可见的行为上没有区别。从实际角度来看，logVisit 不应该在开发环境中执行任何操作，因为你不会想让开发设备的日志影响生产环境的统计数据。每次保存文件时组件都会重新挂载，因此在开发环境中会记录额外的访问日志。

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

为了调试发送的分析事件，你可以将应用部署到一个运行在生产模式下的暂存环境，或者暂时禁用 严格模式 及其仅在开发环境中的重新挂载检查。你还可以在路由更改的事件处理程序中发送分析数据，而不是在 Effect 中发送。对于更精确的分析，可以使用交叉观察器 来跟踪哪些组件位于视口中以及它们保持可见的时间。

不适用于 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 通过在开发环境中重新挂载组件来验证你的组件是否遵守这一原则。

综合以上内容

这个演练场可以帮助你“感受” Effect 在实际中的工作方式。

这个例子使用 setTimeout 调度一个日志记录，日志会在 Effect 运行三秒后显示输入的文本。清理函数会取消挂起的延时器。从按下“挂载组件”开始：

你首先会看到三条日志：调度 "a" 日志，取消 "a" 日志，再一条 调度 "a" 日志。三秒后，你还会看到一条日志：a。正如你先前所学，额外的调度/取消日志是因为 React 在开发环境中会重新挂载组件一次，以验证你是否正确实现了清理操作。

现在编辑输入框，输入 abc。如果输入速度足够快，你会看到 调度 "ab" 日志，紧接着 取消 "ab" 日志 和 调度 "abc" 日志。React 总是在执行下一轮渲染的 Effect 之前清理上一轮渲染的 Effect。这就是为什么即使你快速输入，最多也只有一个延时器被调度。试试多次编辑输入框，并观察控制台以了解 Effect 是如何被清理的。

在输入框中输入一些内容，然后立即按下“卸载组件”。注意卸载组件时是如何清理最后一轮渲染的 Effect 的。在这里，它会在最后一个延迟器要触发之前取消它。

最后，在上面的代码中注释掉清理函数，这样延时器就不会被取消。尝试快速输入 abcde。你觉得三秒后会发生什么？延时器中的 console.log(text) 会打印 最新 的 text 值并生成五条 abcde 日志吗？试试看吧，验证一下你的直觉！

三秒后，你应该会看到一系列的日志：a、ab、abc、abcd 与 abcde，而不是五条 abcde 日志。这是因为 每个 Effect 都会“捕获”它对应渲染时的 text 值。即使 text 的值发生了变化，渲染时 text = 'ab' 的 Effect 总是会得到 'ab'。换句话说，每个渲染的 Effect 都是相互独立的。如果你对这种机制感兴趣，可以阅读有关 闭包 的内容。

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

  return <h1>欢迎来到 {roomId}！</h1>;
}

  // 首次渲染时的 JSX（roomId 为 "general"）
  return <h1>欢迎来到 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>欢迎来到 travel！</h1>;

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