API Reference
フック

useSyncExternalStore

リファレンス

useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot?)

外部データストアから値を読み取るために、コンポーネントのトップレベルで useSyncExternalStore を呼び出します。

これは、ストアにあるデータのスナップショットを返します。引数として 2 つの関数を渡す必要があります：

  1. subscribe 関数はストアへのサブスクライブを開始します。サブスクライブを解除する関数を返す必要があります。
  2. getSnapshot 関数は、ストアからデータのスナップショットを読み取る必要があります。

引数

  • subscribe: ストアにサブスクライブを開始し、また callback 引数を受け取る関数。この関数はストアが変更された際に渡された callback を呼び出す必要があります。これにより React は getSnapshot を呼び出し、（必要に応じて）コンポーネントを再レンダーします。subscribe 関数は、サブスクリプションをクリーンアップする関数を返す必要があります。

  • getSnapshot: コンポーネントが必要とするストアにあるデータのスナップショットを返す関数。ストアが変更されていない場合、getSnapshot への再呼び出しは同じ値を返す必要があります。ストアが変更されて返された値が（ で比較して）異なる場合、React はコンポーネントを再レンダーします。

  • 省略可能 getServerSnapshot: ストアのデータの初期スナップショットを返す関数。これはサーバレンダリング中、およびクライアント上でのサーバレンダリングされたコンテンツのハイドレーション中にのみ使用されます。サーバスナップショットはクライアントとサーバ間で同一でなければならず、通常はサーバからクライアントに渡されるシリアライズされたものです。この引数を省略すると、サーバ上でのコンポーネントのレンダリングはエラーを発生させます。

返り値

レンダリングロジックで使用できるストアの現在のスナップショット。

注意点

  • getSnapshot によって返されるストアのスナップショットはイミュータブル（immutable; 書き換え不能）でなければなりません。背後で使っているストアがミュータブルなデータを持っている場合、データが変更された場合は新しいイミュータブルなスナップショットを返し、それ以外の場合はキャッシュされた最後のスナップショットを返すようにします。

  • 再レンダー中に異なる subscribe 関数が渡された場合、React は新しく渡された subscribe 関数を使ってストアに再サブスクライブします。これを防ぐには、subscribe をコンポーネントの外で宣言します。

  • の最中にストアの書き換えが発生した場合、React はその更新をブロッキング型で行うようにフォールバックします。具体的には、トランザクションによる更新のたびに、React は DOM に更新を適用する前に getSnapshot を再度呼び出します。そこで最初の値とは異なる値が返された場合、React は更新を最初からやり直しますが、再試行時にはブロッキング型の更新を行うことで、画面上の全コンポーネントがストアからの同一バージョンの値を反映していることを保証します。

  • useSyncExternalStore から返される値に基づいてレンダーをサスペンドさせることは推奨されていません。外部ストアで起きた変更はとしてマークすることができないため、直近の が起動してしまいます。既に画面上に表示されているコンテンツがローディングスピナで隠れてしまうため、通常は望ましくないユーザ体験につながります。

    例えば以下のようなコードは推奨されません。

使用法

外部ストアへのサブスクライブ

React コンポーネントのほとんどは、、 およびからのみデータを読み取ります。しかし、コンポーネントは時間と共に変化する React 外のストアからデータを読み取る必要がある場合があります。これには以下のようなものが含まれます：

  • React の外部で状態を保持するサードパーティの状態管理ライブラリ。
  • 可変の値を、その変更にサブスクライブするためのイベントともに公開するブラウザ API。

外部データストアから値を読み取るために、コンポーネントの最上位で useSyncExternalStore を呼び出します。

これはストア内のデータのスナップショットを返します。引数として 2 つの関数を渡す必要があります：

  1. subscribe 関数は、ストアへのサブスクライブを行い、またサブスクライブを解除する関数を返します。
  2. getSnapshot 関数は、ストアからデータのスナップショットを読み取ります。

React はこれらの関数を使ってコンポーネントをストアにサブスクライブされた状態に保ち、変更があるたびに再レンダーします。

例えば、以下のサンドボックスでは、todosStore は React の外部にデータを保存する外部ストアとして実装されています。TodosApp コンポーネントは、useSyncExternalStore フックを使ってその外部ストアに接続します。

ブラウザ API へのサブスクライブ

useSyncExternalStore を追加するもう 1 つの理由は、時間とともに変化する、ブラウザが公開する値にサブスクライブしたい場合です。たとえば、コンポーネントがネットワーク接続がアクティブかどうかを表示したいとします。ブラウザは、この情報を というプロパティを介して公開します。

この値は React の知らないところで変更される可能性があるので、useSyncExternalStore でそれを読み取るべきです。

getSnapshot 関数を実装するためには、ブラウザ API から現在の値を読み取ることが必要です：

次に、subscribe 関数を実装する必要があります。例えば、navigator.onLine が変化すると、ブラウザは window オブジェクト上で および というイベントを発火します。これら対応するイベントに callback 引数を登録し、それを解除する関数を返す必要があります：

これで React は、外部の navigator.onLine API から値を読み取る方法と、その変更にサブスクライブする方法を知ることができます。ネットワークからデバイスを切断すると、コンポーネントが反応して再レンダーされることに注目してください：

ロジックをカスタムフックに抽出する

通常、useSyncExternalStore を直接コンポーネント内に記述することはありません。代わりに、自分自身のカスタムフックから呼び出すことが一般的です。これにより、異なるコンポーネントから同じ外部ストアを使用できます。

例えば、このカスタム useOnlineStatus フックはネットワークがオンラインであるかどうかを追跡します：

これで、異なるコンポーネントが、基本的な実装を繰り返すことなく useOnlineStatus を呼び出せるようになりました：

サーバーレンダリングのサポートを追加する

React アプリがを使用している場合、React コンポーネントは初期 HTML を生成するためにブラウザ環境外でも実行されます。これにより、外部ストアへの接続に関するいくつかの課題が生じます。

  • ブラウザ専用の API に接続している場合、それはサーバ上では存在しないため動作しません。
  • サードパーティのデータストアに接続している場合、サーバとクライアント間でそのデータを一致させる必要があります。

これらの問題を解決するために、useSyncExternalStore に getServerSnapshot 関数を第 3 引数として渡します：

getServerSnapshot 関数は getSnapshot と似ていますが、以下の 2 つの状況でのみ実行されます：

  • サーバ上で、HTML を生成する際に実行される。
  • クライアント上で、React がサーバ HTML をインタラクティブにするとき、つまり中に実行される。

これにより、アプリがインタラクティブになる前に使用される初期のスナップショット値を指定できます。サーバレンダリング中に意味のある初期値が存在しない場合は、この引数を省略して、ようにします。

トラブルシューティング

“The result of getSnapshot should be cached” というエラーが出る

このエラーは、getSnapshot 関数が呼ばれるたびに新しいオブジェクトを返していることを意味します。例えば：

getSnapshot の返り値が前回と異なる場合、React はコンポーネントを再レンダーします。このため、常に異なる値を返すと無限ループに入り、このエラーが発生します。

getSnapshot オブジェクトは、実際に何かが変更された場合にのみ、別のオブジェクトを返す必要があります。ストアにイミュータブルなデータが含まれている場合は、そのデータを直接返すことができます：

ストアデータがミュータブルな場合、getSnapshot 関数はそのイミュータブルなスナップショットを返す必要があります。つまり、新しいオブジェクトを作成する必要はありますが、毎回作成してはいけないということです。その代わりに、最後に計算されたスナップショットを保存しておき、ストア内のデータが変更されていない場合は前回と同じスナップショットを返すようにします。ミュータブルなデータが変更されたかどうかを判断する方法は、ミュータブルなストアによって異なります。

subscribe が毎レンダーごとに呼び出される

この subscribe 関数はコンポーネントの内部で定義されているため、再レンダーするたびに異なった値になります：

React は、再レンダー間で異なる subscribe 関数を渡すと、ストアに再サブスクライブします。これがパフォーマンスの問題を引き起こし、再サブスクライブを避けたい場合は、subscribe 関数を外部に移動してください：

あるいは、subscribe を でラップすることで、引数が変更されたときのみ再サブスクライブすることができます：