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);
  // ...
}

查看更多示例。

参数

🌐 Parameters

• value：你想要延迟的值。它可以是任何类型。
• 可选 initialValue：在组件的初始渲染期间使用的值。如果省略此选项，useDeferredValue 在初始渲染期间不会延迟，因为没有可以替代渲染的 value 的之前版本。

返回

🌐 Returns

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

注意事项

🌐 Caveats

• 当更新位于过渡中时，useDeferredValue 总是返回新的 value，并且不会生成延迟渲染，因为更新已经被延迟。
• 你传给 useDeferredValue 的值应该是原始值（比如字符串和数字）或者是在渲染之外创建的对象。如果你在渲染过程中创建一个新对象并立即传给 useDeferredValue，每次渲染时它都会不同，从而导致不必要的后台重新渲染。
• 当 useDeferredValue 接收到与 Object.is 不同的值时，除了当前渲染（此时仍使用先前的值）之外，它还会在后台安排一次使用新值的重新渲染。后台重新渲染是可中断的：如果 value 又有了新的更新，React 将从头重新启动后台重新渲染。例如，如果用户在输入框中输入的速度比图表接收其延迟值并重新渲染的速度快，图表将仅在用户停止输入后才重新渲染。
• useDeferredValue 已与 <Suspense> 集成。如果新值引起的后台更新导致 UI 暂停，用户将看不到回退值。他们将看到旧的延迟值，直到数据加载完成。
• useDeferredValue 本身不能阻止额外的网络请求。
• useDeferredValue 本身不会导致固定延迟。一旦 React 完成原始的重新渲染，React 将立即开始使用新的延迟值进行后台重新渲染。由事件（如输入）引起的任何更新将中断后台重新渲染，并优先处理这些更新。
• useDeferredValue 引起的后台重新渲染在提交到屏幕之前不会触发 Effects。如果后台重新渲染被挂起，其 Effects 会在数据加载和 UI 更新之后运行。

用法

🌐 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);
  // ...
}

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

在更新期间， 延迟值 会“落后于”最新的 值。特别是，React 会首先在不更新延迟值的情况下重新渲染，然后尝试在后台使用新接收到的值重新渲染。

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

在此示例中，SearchResults 组件在获取搜索结果时会suspend。尝试输入 "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.

一个常见的替代用户界面模式是延迟更新结果列表，并在新结果准备好之前继续显示之前的结果。调用 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，以便当其 props 相同时跳过重新渲染。要做到这一点，将其封装在 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 会接收到新的 props，并重新渲染其整个树，这会导致输入感觉卡顿。在这种情况下，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.