useDeferredValue

const deferredValue = useDeferredValue(value)

• 参考
  • useDeferredValue(value, initialValue?)
• 用法
  • 在加载新内容时显示旧内容
  • 表明内容是旧的
  • 延迟部分 UI 的重新渲染

参考

¥Reference

useDeferredValue(value, initialValue?)

在组件的顶层调用 useDeferredValue 以获得该值的延迟版本。

¥Call useDeferredValue at the top level of your component to get a deferred version of that value.

import { useState, useDeferredValue } from 'react';

function SearchPage() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  // ...
}

请参阅下面的更多示例。

¥See more examples below.

参数

¥Parameters

• value：你要延迟的值。它可以有任何类型。

  ¥value: The value you want to defer. It can have any type.

可选 initialValue：在组件初始渲染期间使用的值。如果省略此选项，useDeferredValue 将不会在初始渲染期间推迟，因为没有可以替代渲染的 value 的先前版本。

¥optional initialValue: A value to use during the initial render of a component. If this option is omitted, useDeferredValue will not defer during the initial render, because there’s no previous version of value that it can render instead.

返回

¥Returns

• currentValue：在初始渲染期间，返回的延迟值将与你提供的值相同。在更新期间，React 将首先尝试使用旧值重新渲染（因此它将返回旧值），然后在后台尝试使用新值进行另一次重新渲染（因此它将返回更新后的值）。

  ¥currentValue: During the initial render, the returned deferred value will be the same as the value you provided. During updates, React will first attempt a re-render with the old value (so it will return the old value), and then try another re-render in the background with the new value (so it will return the updated value).

注意事项

¥Caveats

• 当更新在 Transition 中时，useDeferredValue 始终返回新的 value 并且不会产生延迟渲染，因为更新已被延迟。

  ¥When an update is inside a Transition, useDeferredValue always returns the new value and does not spawn a deferred render, since the update is already deferred.

• 你传递给 useDeferredValue 的值应该是原始值（如字符串和数字）或在渲染之外创建的对象。如果你在渲染期间创建一个新对象并立即将其传递给 useDeferredValue，则每次渲染时都会有所不同，从而导致不必要的背景重新渲染。

  ¥The values you pass to useDeferredValue should either be primitive values (like strings and numbers) or objects created outside of rendering. If you create a new object during rendering and immediately pass it to useDeferredValue, it will be different on every render, causing unnecessary background re-renders.

• 当 useDeferredValue 收到不同的值（与 Object.is 相比）时，除了当前渲染（当它仍然使用以前的值时）之外，它还会安排在后台使用新值重新渲染。后台重新渲染是可中断的：如果 value 有另一个更新，React 将从头开始重新启动后台重新渲染。例如，如果用户键入输入的速度快于接收延迟值的图表可以重新渲染的速度，则图表只会在用户停止输入后重新渲染。

  ¥When useDeferredValue receives a different value (compared with Object.is), in addition to the current render (when it still uses the previous value), it schedules a re-render in the background with the new value. The background re-render is interruptible: if there’s another update to the value, React will restart the background re-render from scratch. For example, if the user is typing into an input faster than a chart receiving its deferred value can re-render, the chart will only re-render after the user stops typing.

• useDeferredValue 与 <Suspense>。 集成 如果新值引起的后台更新暂停了 UI，用户将看不到回退。在数据加载之前，它们将看到旧的延迟值。

  ¥useDeferredValue is integrated with <Suspense>. If the background update caused by a new value suspends the UI, the user will not see the fallback. They will see the old deferred value until the data loads.

• useDeferredValue 本身并不能阻止额外的网络请求。

  ¥useDeferredValue does not by itself prevent extra network requests.

• useDeferredValue 本身没有固定延迟。一旦 React 完成原始重新渲染，React 将立即开始使用新的延迟值进行后台重新渲染。由事件（如类型）引起的任何更新都会中断后台重新渲染并优先于它。

  ¥There is no fixed delay caused by useDeferredValue itself. As soon as React finishes the original re-render, React will immediately start working on the background re-render with the new deferred value. Any updates caused by events (like typing) will interrupt the background re-render and get prioritized over it.

• 由 useDeferredValue 引起的背景重新渲染在提交到屏幕之前不会触发副作用。如果后台重新渲染挂起，其副作用将在数据加载和 UI 更新后运行。

  ¥The background re-render caused by useDeferredValue does not fire Effects until it’s committed to the screen. If the background re-render suspends, its Effects will run after the data loads and the UI updates.

用法

¥Usage

在加载新内容时显示旧内容

¥Showing stale content while fresh content is loading

在组件的顶层调用 useDeferredValue 以延迟更新 UI 的某些部分。

¥Call useDeferredValue at the top level of your component to defer updating some part of your UI.

import { useState, useDeferredValue } from 'react';

function SearchPage() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  // ...
}

在初始渲染期间，延迟值 将与你提供的值 相同。

¥During the initial render, the deferred value will be the same as the value you provided.

在更新期间，延迟值 将 “滞后” 最新的 值。特别是，React 将首先重新渲染而不更新延迟值，然后尝试在后台使用新接收到的值重新渲染。

¥During updates, the deferred value will “lag behind” the latest value. In particular, React will first re-render without updating the deferred value, and then try to re-render with the newly received value in the background.

让我们通过一个例子来看看这在什么时候有用。

¥Let’s walk through an example to see when this is useful.

在此示例中，SearchResults 组件 suspends 同时获取搜索结果。尝试键入 "a"，等待结果，然后将其编辑为 "ab"。"a" 的结果被加载回退替换。

¥In this example, the SearchResults component suspends while fetching the search results. Try typing "a", waiting for the results, and then editing it to "ab". The results for "a" get replaced by the loading fallback.

一种常见的替代 UI 模式是推迟更新结果列表并继续显示以前的结果，直到新结果准备就绪。调用 useDeferredValue 向下传递查询的延迟版本：

¥A common alternative UI pattern is to defer updating the list of results and to keep showing the previous results until the new results are ready. Call useDeferredValue to pass a deferred version of the query down:

export default function App() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);
  return (
    <>
      <label>
        Search albums:
        <input value={query} onChange={e => setQuery(e.target.value)} />
      </label>
      <Suspense fallback={<h2>Loading...</h2>}>
        <SearchResults query={deferredQuery} />
      </Suspense>
    </>
  );
}

query 将立即更新，因此输入将显示新值。但是，deferredQuery 将保留其先前的值，直到数据加载完毕，因此 SearchResults 将显示旧的结果。

¥The query will update immediately, so the input will display the new value. However, the deferredQuery will keep its previous value until the data has loaded, so SearchResults will show the stale results for a bit.

在下例中输入 "a"，等待结果加载，然后编辑输入为 "ab"。请注意，在加载新结果之前，你现在看到的不是 Suspense 回退，而是旧的结果列表：

¥Enter "a" in the example below, wait for the results to load, and then edit the input to "ab". Notice how instead of the Suspense fallback, you now see the stale result list until the new results have loaded:

表明内容是旧的

¥Indicating that the content is stale

在上面的示例中，没有迹象表明最新查询的结果列表仍在加载。如果新结果需要一段时间才能加载，这可能会让用户感到困惑。为了让用户更清楚地知道结果列表与最新的查询不匹配，你可以在显示旧的结果列表时添加一个视觉指示：

¥In the example above, there is no indication that the result list for the latest query is still loading. This can be confusing to the user if the new results take a while to load. To make it more obvious to the user that the result list does not match the latest query, you can add a visual indication when the stale result list is displayed:

<div style={{
  opacity: query !== deferredQuery ? 0.5 : 1,
}}>
  <SearchResults query={deferredQuery} />
</div>

通过此更改，一旦你开始键入，旧的结果列表就会稍微变暗，直到加载新的结果列表。你还可以添加 CSS 转场来延迟变暗，使其感觉渐变，如下例所示：

¥With this change, as soon as you start typing, the stale result list gets slightly dimmed until the new result list loads. You can also add a CSS transition to delay dimming so that it feels gradual, like in the example below:

延迟部分 UI 的重新渲染

¥Deferring re-rendering for a part of the UI

你还可以应用 useDeferredValue 作为性能优化。当你的 UI 的一部分重新渲染很慢，没有简单的方法来优化它，并且你想防止它阻塞 UI 的其余部分时，它很有用。

¥You can also apply useDeferredValue as a performance optimization. It is useful when a part of your UI is slow to re-render, there’s no easy way to optimize it, and you want to prevent it from blocking the rest of the UI.

假设你有一个文本字段和一个组件（如图表或长列表），它们在每次击键时重新渲染：

¥Imagine you have a text field and a component (like a chart or a long list) that re-renders on every keystroke:

function App() {
  const [text, setText] = useState('');
  return (
    <>
      <input value={text} onChange={e => setText(e.target.value)} />
      <SlowList text={text} />
    </>
  );
}

首先，优化 SlowList 以在其属性相同时跳过重新渲染。为此，将其封装在 memo 中：

¥First, optimize SlowList to skip re-rendering when its props are the same. To do this, wrap it in memo:

const SlowList = memo(function SlowList({ text }) {
  // ...
});

但是，这仅在 SlowList 属性与之前渲染期间相同时才有用。你现在面临的问题是当它们不同时速度很慢，并且当你实际需要显示不同的视觉输出时。

¥However, this only helps if the SlowList props are the same as during the previous render. The problem you’re facing now is that it’s slow when they’re different, and when you actually need to show different visual output.

具体来说，主要的性能问题是每当你键入输入时，SlowList 都会收到新的属性，重新渲染它的整个树会让输入感觉很卡顿。在这种情况下，useDeferredValue 允许你优先更新输入（必须快）而不是更新结果列表（允许更慢）：

¥Concretely, the main performance problem is that whenever you type into the input, the SlowList receives new props, and re-rendering its entire tree makes the typing feel janky. In this case, useDeferredValue lets you prioritize updating the input (which must be fast) over updating the result list (which is allowed to be slower):

function App() {
  const [text, setText] = useState('');
  const deferredText = useDeferredValue(text);
  return (
    <>
      <input value={text} onChange={e => setText(e.target.value)} />
      <SlowList text={deferredText} />
    </>
  );
}

这不会使 SlowList 的重新渲染更快。但是，它告诉 React 可以取消重新渲染列表的优先级，这样它就不会阻塞击键。该列表将 “滞后” 输入，然后是 “赶上”。和以前一样，React 会尝试尽快更新列表，但不会阻止用户输入。

¥This does not make re-rendering of the SlowList faster. However, it tells React that re-rendering the list can be deprioritized so that it doesn’t block the keystrokes. The list will “lag behind” the input and then “catch up”. Like before, React will attempt to update the list as soon as possible, but will not block the user from typing.