useDeferredValue

const deferredValue = useDeferredValue(value)

• リファレンス
  • useDeferredValue(value, initialValue?)
• 使用法
  • 新しいコンテンツの読み込み中に古いコンテンツを表示する
  • コンテンツが古いことを示す
  • UI の一部の再レンダリングを遅延させる

リファレンス

useDeferredValue(value, initialValue?)

コンポーネントのトップレベルで useDeferredValue を呼び出して、その値の遅延バージョンを取得します。

import { useState, useDeferredValue } from 'react';

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

以下の例をご覧ください。

パラメーター

• value: 遅延させたい値。任意の型を使用できます。
• オプション initialValue: コンポーネントの初期レンダリング中に使用する値。このオプションを省略した場合、useDeferredValue は初期レンダリング中は遅延しません。これは、代わりにレンダリングできる value の以前のバージョンがないためです。

戻り値

• currentValue: 初回レンダリング中、返される遅延値は initialValue、または指定した値と同じになります。更新中、React は最初に古い値で再レンダリングを試み（したがって、古い値を返します）、次に新しい値でバックグラウンドで別の再レンダリングを試みます（したがって、更新された値を返します）。

注意点

• 更新がトランジション内にある場合、useDeferredValue は常に新しい value を返し、更新はすでに遅延しているため、遅延レンダリングを生成しません。

• useDeferredValue に渡す値は、プリミティブ値（文字列や数値など）またはレンダリングの外部で作成されたオブジェクトのいずれかである必要があります。レンダリング中に新しいオブジェクトを作成してすぐに useDeferredValue に渡すと、レンダリングごとに異なるものになり、不必要なバックグラウンドでの再レンダリングが発生します。

• useDeferredValue が異なる値を受け取った場合（Object.is と比較）、現在のレンダリング（以前の値を使用している場合）に加えて、新しい値でバックグラウンドで再レンダリングをスケジュールします。バックグラウンドでの再レンダリングは中断可能です。つまり、value に別の更新があると、React はバックグラウンドでの再レンダリングを最初から再開します。たとえば、ユーザーが入力した内容をチャートが遅延値を受け取って再レンダリングできるよりも速く入力している場合、チャートはユーザーの入力が止まった後にのみ再レンダリングされます。

• useDeferredValue は、<Suspense>と統合されています。新しい値によって引き起こされたバックグラウンド更新が UI を中断した場合、ユーザーにはフォールバックは表示されません。データが読み込まれるまで、古い遅延値が表示されます。

• useDeferredValue は、それ自体では追加のネットワークリクエストを防ぎません。

• useDeferredValue 自体によって引き起こされる固定遅延はありません。React が元の再レンダリングを完了するとすぐに、React は新しい遅延値を使用したバックグラウンドでの再レンダリングを直ちに開始します。（タイピングのような）イベントによって引き起こされた更新は、バックグラウンドでの再レンダリングを中断し、それよりも優先されます。

• useDeferredValue によって引き起こされるバックグラウンドでの再レンダリングは、画面にコミットされるまで Effect を発火しません。バックグラウンドでの再レンダリングが中断された場合、その Effect はデータが読み込まれて UI が更新された後に実行されます。

使い方

フレッシュなコンテンツのロード中に古いコンテンツを表示する

コンポーネントの最上位レベルで useDeferredValue を呼び出して、UI の一部の更新を遅延させます。

import { useState, useDeferredValue } from 'react';

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

最初のレンダリング中、遅延値 は、提供した 値 と同じになります。

更新中、遅延値 は、最新の 値 よりも「遅れます」。特に、React は最初に遅延値を更新せずに再レンダリングし、次にバックグラウンドで新しく受信した値で再レンダリングしようとします。

これがいつ役立つかを確認するために、例を見ていきましょう。

この例では、SearchResults コンポーネントは、検索結果をフェッチ中に 中断します。"a" と入力し、結果を待ってから、"ab" に編集してみてください。"a" の結果は、ロードフォールバックに置き換えられます。

一般的な代替 UI パターンは、結果リストの更新を遅延させ、新しい結果が準備できるまで前の結果を表示し続けることです。useDeferredValue を呼び出して、遅延バージョンのクエリを渡します

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 にはしばらくの間、古い結果が表示されます。

以下の例に "a" と入力し、結果がロードされるのを待ってから、入力を "ab" に編集します。Suspense フォールバックの代わりに、新しい結果がロードされるまで、古い結果リストが表示されることに注目してください。

コンテンツが古いことを示す

上記の例では、最新のクエリに対する結果リストがまだ読み込み中であるという表示がありません。新しい結果の読み込みに時間がかかる場合、これはユーザーを混乱させる可能性があります。結果リストが最新のクエリと一致しないことをユーザーにわかりやすくするために、古い結果リストが表示されているときに視覚的な表示を追加できます。

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

この変更により、入力を開始するとすぐに、新しい結果リストが読み込まれるまで、古い結果リストがわずかに暗くなります。CSSトランジションを追加して、下にある例のように、徐々に暗くなるようにすることもできます。

UIの一部に対する再レンダリングの遅延

useDeferredValueをパフォーマンス最適化として適用することもできます。UIの一部で再レンダリングが遅く、最適化が容易ではなく、UIの残りの部分がブロックされるのを防ぎたい場合に役立ちます。

テキストフィールドと、キーストロークごとに再レンダリングされるコンポーネント（チャートや長いリストなど）がある場合を想像してください。

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

まず、SlowList の props が同じ場合に再レンダリングをスキップするように最適化します。そのためには、memoでラップします。

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

ただし、これは SlowList の props が前のレンダリング時と*同じ*である場合にのみ役立ちます。ここで直面している問題は、propsが*異なる*場合、つまり実際に異なる視覚出力を表示する必要がある場合に、処理が遅くなることです。

具体的には、主なパフォーマンスの問題は、入力にタイプするたびに、SlowList が新しい props を受け取り、そのツリー全体の再レンダリングによって、タイプ入力がぎくしゃくしたように感じられることです。この場合、useDeferredValue を使用すると、結果リストの更新（遅くてもよい）よりも入力の更新（高速でなければならない）を優先できます。

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 は可能な限り早くリストを更新しようとしますが、ユーザーがタイプ入力するのをブロックすることはありません。