Hook useSWR: pobieranie, ładowanie i błędy

useSWR(key, fetcher, options) to główny hook. key jest kluczem pamięci podręcznej (zwykle ciągiem URL), fetcher jest funkcją asynchroniczną zwracającą dane, a options jest opcjonalnym obiektem konfiguracji.

Hook zwraca obiekt zawierający data, error, isLoading, isValidating oraz funkcję mutate.

Klucz może być adresem URL w postaci ciągu znaków, tablicą [url, params] lub wartością null. Klucze w postaci ciągów znaków odpowiadają prostym żądaniom GET. Klucze tablicowe pozwalają umieszczać zmienne, takie jak userId lub filtry, w identyfikatorze pamięci podręcznej.

Przekazanie null całkowicie wyłącza żądanie, co jest przydatne przy warunkowym pobieraniu, gdy wymagane dane nie są jeszcze dostępne.

Funkcja fetcher otrzymuje klucz (lub elementy klucza tablicowego jako osobne argumenty) i musi zwracać Promise. Rozwiązana wartość staje się wartością data. Jeśli funkcja fetcher zgłosi wyjątek, właściwość error zostaje ustawiona.

Przykład: (url) => fetch(url).then(r => { if (!r.ok) throw new Error(r.status); return r.json(); }).

data ma wartość undefined podczas pierwszego ładowania, a po pomyślnym zakończeniu pobierania jest równe wartości zwróconej przez fetcher. error ma wartość undefined, chyba że funkcja fetcher zgłosiła wyjątek — w takim przypadku zawiera obiekt zgłoszonego błędu.

Należy sprawdzać if (error), aby wyświetlić komunikat o błędzie, oraz if (!data), aby wyświetlić szkielet ładowania i zapewnić przejrzyste interfejsy zastępcze.

isLoading ma wartość true tylko wtedy, gdy nie ma danych w pamięci podręcznej, a żądanie jest w toku — podczas pierwszego wczytywania tego klucza. isValidating ma wartość true za każdym razem, gdy żądanie jest w toku, także podczas rewalidacji w tle, gdy dane z pamięci podręcznej są już dostępne.

Należy używać isLoading do wyświetlania ekranów-szkieletów, a isValidating — do subtelnego wskaźnika ładowania informującego o odświeżaniu w tle.

SWRConfig umożliwia zdefiniowanie domyślnej funkcji fetcher, dedupingInterval, refreshInterval, procedury obsługi onError i innych opcji dla wszystkich wywołań useSWR w jego poddrzewie. Dzięki temu konfiguracja jest scentralizowana i nie trzeba powtarzać opcji przy każdym hooku.

Można zagnieżdżać wielu dostawców SWRConfig, aby ustawić różne wartości domyślne dla różnych części aplikacji.

Należy przekazać null jako klucz, aby pominąć żądanie: useSWR(isLoggedIn ? '/api/user' : null, fetcher). SWR nie wykona pobierania, dopóki klucz nie przyjmie wartości różnej od null.

Jest to prostsze niż opcja skip w React Query. Zmiana klucza z null na ciąg znaków automatycznie uruchamia pierwsze pobieranie.

W przypadku zależnych żądań należy łączyć hooki SWR: const { data: user } = useSWR('/api/me', fetcher), a następnie const { data: orders } = useSWR(user ? '/api/orders/' + user.id : null, fetcher). Drugi hook czeka na rozwiązanie pierwszego.

Ten wzorzec pozwala uniknąć łańcuchów useEffect i zachować deklaratywne oraz czytelne zależności danych.

Jeśli komponent Header i komponent Sidebar wywołują useSWR('/api/user', fetcher), SWR wykonuje tylko jedno żądanie i współdzieli wynik. Oba komponenty są ponownie renderowane razem, gdy zmienią się dane lub błąd.

Deduplikacja odbywa się automatycznie w ramach przedziału dedupingInterval (domyślnie 2000ms), bez dodatkowej konfiguracji.

refreshInterval: 5000 powoduje odpytywanie co 5 sekund. refreshWhenHidden: false zatrzymuje odpytywanie, gdy karta nie jest widoczna. shouldRetryOnError: false wyłącza automatyczne ponawianie. revalidateOnFocus: false wyłącza rewalidację wywoływaną odzyskaniem fokusu.

Opcje należy łączyć zgodnie z wymaganiami dotyczącymi aktualności danych: dashboardy często korzystają z refreshInterval, natomiast w przypadku statycznej treści ustawia się revalidateOnFocus: false.

W przypadku danych stronicowanych należy umieścić numer strony w kluczu: useSWR(['/api/items', page], fetcher). Zmiana strony uruchamia nowe pobieranie danych dla tej strony, a poprzednie strony pozostają w pamięci podręcznej.

SWR udostępnia również useSWRInfinite na potrzeby wzorców opartych na kursorze lub nieskończonym przewijaniu, z funkcją getKey, która buduje klucze na podstawie indeksu strony i danych poprzedniej strony.

Co się dzieje po przekazaniu null jako klucza do useSWR?

useSWR(key, fetcher) zwraca data, error, isLoading i isValidating. Klucze null wyłączają pobieranie na potrzeby żądań warunkowych i zależnych. isLoading oznacza pierwsze ładowanie, a isValidating — dowolne żądanie będące w toku. SWRConfig centralizuje wartości domyślne, a deduplikacja żądań między komponentami odbywa się automatycznie.

Opcje takie jak refreshInterval, revalidateOnFocus i shouldRetryOnError pozwalają precyzyjnie dostosować zachowanie dotyczące aktualności danych dla poszczególnych hooków lub globalnie.