API useSyncExternalStore i parametry

useSyncExternalStore przyjmuje maksymalnie trzy argumenty: subscribe, getSnapshot oraz opcjonalny getServerSnapshot. Razem informują one Reacta, jak nasłuchiwać zmian i jak odczytywać bieżącą wartość.

Zrozumienie każdego argumentu jest kluczowe, ponieważ drobne błędy w tych funkcjach są najczęstszym źródłem problemów podczas korzystania z tego hooka.

subscribe otrzymuje callback od Reacta i musi zarejestrować go w store'ze, aby callback był uruchamiany za każdym razem, gdy store się zmieni. Funkcja musi zwrócić funkcję anulującą subskrypcję, którą React wywołuje podczas sprzątania.

React wykorzystuje ją do ustalenia, kiedy należy ponownie odczytać snapshot, dlatego subscribe służy wyłącznie do konfigurowania i usuwania powiadomień o zmianach.

getSnapshot zwraca bieżącą wartość store'a. React wywołuje tę funkcję podczas renderowania, aby odczytać stan, a następnie ponownie po otrzymaniu powiadomień, aby wykryć, czy wartość się zmieniła.

Co najważniejsze, gdy bazowe dane się nie zmieniły, funkcja musi zwracać wynik stabilny referencyjnie — tę samą referencję zamiast za każdym razem tworzyć nowy obiekt.

Opcjonalny getServerSnapshot dostarcza wartość używaną podczas renderowania po stronie serwera oraz w początkowej fazie hydratacji. Jest potrzebny, ponieważ przeznaczony wyłącznie dla przeglądarki getSnapshot może korzystać z API, które nie istnieją na serwerze.

Jego podanie zapobiega niezgodnościom podczas hydratacji, ponieważ serwer otrzymuje sensowną wartość do wyrenderowania, zgodną z początkowym wynikiem po stronie klienta.

Hook zwraca bieżącą wartość snapshotu, której używają Państwo bezpośrednio w komponencie tak jak każdej innej części stanu. Gdy store się zmieni, React ponownie renderuje komponent, a hook zwraca zaktualizowany snapshot.

Z perspektywy komponentu wygląda to jak odczytywanie reaktywnego stanu, mimo że źródło prawdy znajduje się w całości poza Reactem.

getSnapshot musi działać synchronicznie i zwracać wartość wyprowadzoną wyłącznie z bieżącego stanu store'a. Nie powinien wykonywać pracy asynchronicznej ani zwracać różnych wyników dla tych samych danych bazowych.

React polega na wielokrotnym wywoływaniu tej funkcji i porównywaniu wyników, dlatego niedeterminizm lub efekty uboczne w jej wnętrzu mogą prowadzić do nieprawidłowego działania.

W store'ach przechowujących niezmienny stan implementacja getSnapshot jest prosta, ponieważ referencja bieżącego obiektu stanu zmienia się tylko wtedy, gdy zmienią się dane. Zwracanie tej referencji zapewnia stabilne porównania bez dodatkowego wysiłku.

Właśnie dlatego wzorce niezmiennych aktualizacji tak dobrze współpracują z tym hookiem: te same dane oznaczają tę samą referencję, a React pomija niepotrzebne ponowne renderowanie.

Częstym błędem jest zwracanie zupełnie nowego obiektu lub tablicy przy każdym wywołaniu getSnapshot, na przykład przez wykonanie w nim mapowania lub filtrowania. React za każdym razem widzi nową referencję i uznaje, że wartość się zmieniła.

Prowadzi to do nieskończonego ponownego renderowania lub ostrzeżeń. Rozwiązaniem jest buforowanie wyprowadzonej wartości i zwracanie tej samej referencji do momentu rzeczywistej zmiany danych źródłowych.

Aby uniknąć tej pętli, należy obliczać dane wyprowadzone poza getSnapshot albo je zapamiętywać, tak aby funkcja zwracała zbuforowaną referencję. Wzorzec oparty na selektorze, używany przez wiele bibliotek, służy właśnie do zarządzania tą stabilnością.

Najważniejsza zasada mówi, że dwa wywołania getSnapshot przy niezmienionych danych store'a muszą zwrócić dokładnie tę samą referencję.

W praktyce należy napisać subscribe, które dodaje i usuwa listener, getSnapshot odczytujące stabilną bieżącą wartość oraz — na potrzeby SSR — getServerSnapshot zwracające wartość bezpieczną dla serwera.

Gdy wszystkie trzy elementy są poprawne, hook zapewnia spójne i bezpieczne współbieżnie odczyty z zewnętrznego store'a bez zbędnej otoczki.

Proszę określić rolę getSnapshot.

Hook przyjmuje subscribe, getSnapshot oraz opcjonalnie getServerSnapshot. subscribe podłącza listener i zwraca funkcję anulującą subskrypcję; getSnapshot synchronicznie odczytuje bieżącą wartość i musi być stabilne referencyjnie; getServerSnapshot dostarcza wartość bezpieczną dla SSR.

Klasyczną pułapką jest zwracanie nowego obiektu przy każdym wywołaniu, co powoduje nieskończone pętle. Należy buforować wyprowadzone wartości, aby niezmienione dane zwracały tę samą referencję.