useSyncExternalStore: API und Parameter

useSyncExternalStore akzeptiert bis zu drei Argumente: subscribe, getSnapshot und optional getServerSnapshot. Zusammen teilen sie React mit, wie Änderungen überwacht und wie der aktuelle Wert gelesen werden soll.

Es ist entscheidend, jedes Argument zu verstehen, da kleine Fehler darin beim Einsatz dieses Hooks die häufigste Ursache für Fehler sind.

subscribe erhält von React einen Callback und muss ihn beim Store registrieren, damit der Callback bei jeder Änderung des Stores ausgeführt wird. Die Funktion muss eine unsubscribe-Funktion zurückgeben, die React beim Aufräumen aufruft.

React verwendet dies, um zu erkennen, wann der Snapshot erneut gelesen werden muss. subscribe dient also ausschließlich dazu, die Änderungsbenachrichtigung einzurichten und wieder zu entfernen.

getSnapshot gibt den aktuellen Wert des Stores zurück. React ruft die Funktion während des Renderns auf, um den Zustand zu lesen, und erneut nach Benachrichtigungen, um zu erkennen, ob sich der Wert geändert hat.

Entscheidend ist, dass bei unveränderten zugrunde liegenden Daten ein referenziell stabiles Ergebnis zurückgegeben wird, also jedes Mal dieselbe Referenz statt eines neuen Objekts.

Das optionale getServerSnapshot liefert den Wert, der beim serverseitigen Rendern und beim ersten Hydration-Durchlauf verwendet wird. Es ist erforderlich, weil das nur im Browser verfügbare getSnapshot möglicherweise APIs verwendet, die auf dem Server nicht existieren.

Durch die Bereitstellung dieser Funktion vermeiden Sie Hydration-Mismatches, da der Server einen sinnvollen Wert rendert, der dem entspricht, was der Client anfangs erzeugen wird.

Der Hook gibt den aktuellen Snapshot-Wert zurück, den Sie in Ihrer Komponente direkt wie jeden anderen Zustand verwenden. Wenn sich der Store ändert, rendert React die Komponente erneut und der Hook gibt den aktualisierten Snapshot zurück.

Aus Sicht der Komponente fühlt sich das wie das Lesen eines reaktiven Zustands an, obwohl die maßgebliche Datenquelle vollständig außerhalb von React liegt.

getSnapshot muss synchron ausgeführt werden und einen Wert zurückgeben, der ausschließlich aus dem aktuellen Store-Zustand abgeleitet ist. Die Funktion sollte keine asynchronen Arbeiten ausführen oder für dieselben zugrunde liegenden Daten unterschiedliche Ergebnisse liefern.

React ruft die Funktion wiederholt auf und vergleicht die Ergebnisse. Daher können Nichtdeterminismus oder Seiteneffekte darin zu fehlerhaftem Verhalten führen.

Stores mit unveränderlichem Zustand machen getSnapshot einfach, da sich die Referenz des aktuellen Zustandsobjekts nur ändert, wenn sich die Daten ändern. Wenn Sie diese Referenz zurückgeben, erhalten Sie stabile Vergleiche ohne zusätzlichen Aufwand.

Deshalb passen Muster für unveränderliche Aktualisierungen so gut zu diesem Hook: Gleiche Daten bedeuten dieselbe Referenz, und React überspringt unnötige erneute Render-Vorgänge.

Ein häufiger Fehler besteht darin, bei jedem Aufruf von getSnapshot ein völlig neues Objekt oder Array zurückzugeben, etwa durch map oder filter innerhalb der Funktion. React sieht jedes Mal eine neue Referenz und nimmt an, dass sich der Wert geändert hat.

Das führt zu endlosen erneuten Render-Vorgängen oder Warnungen. Die Lösung besteht darin, den abgeleiteten Wert zwischenzuspeichern und bis zu einer tatsächlichen Änderung der Quelldaten dieselbe Referenz zurückzugeben.

Um die Schleife zu vermeiden, berechnen Sie abgeleitete Daten außerhalb von getSnapshot oder memoizieren Sie sie, sodass die Funktion eine zwischengespeicherte Referenz zurückgibt. Das von vielen Bibliotheken verwendete Selektor-Muster dient genau dazu, diese Stabilität zu verwalten.

Die entscheidende Regel lautet: Zwei Aufrufe von getSnapshot müssen bei unveränderten Store-Daten exakt dieselbe Referenz zurückgeben.

In der Praxis schreiben Sie ein subscribe, das einen Listener hinzufügt und entfernt, ein getSnapshot, das einen stabilen aktuellen Wert liest, und für SSR ein getServerSnapshot, das einen servergeeigneten Wert zurückgibt.

Wenn diese drei Funktionen korrekt implementiert sind, liefert der Hook mit minimalem Aufwand konsistente und bei nebenläufigem Rendering sichere Lesevorgänge aus Ihrem externen Store.

Ermitteln Sie die Aufgabe von getSnapshot.

Der Hook akzeptiert subscribe, getSnapshot und optional getServerSnapshot. subscribe richtet einen Listener ein und gibt unsubscribe zurück; getSnapshot liest den aktuellen Wert synchron und muss referenziell stabil sein; getServerSnapshot liefert einen SSR-tauglichen Wert.

Der typische Fehler besteht darin, bei jedem Aufruf ein neues Objekt zurückzugeben, was zu Endlosschleifen führt. Speichern Sie abgeleitete Werte zwischen, damit unveränderte Daten dieselbe Referenz ergeben.