Hooki useQuery i useMutation

Tag szablonu gql z @apollo/client analizuje ciąg zapytania GraphQL i przekształca go w DocumentNode w momencie ładowania modułu. Zapytania należy definiować poza komponentami: const GET_USERS = gql`query GetUsers { users { id name email } }`.

Uwaga: w kodzie produkcyjnym należy używać ciągów znaków ujętych w pojedyncze cudzysłowy i opakowanych przez gql jako tagowany template. Tag gql akceptuje składnię literału szablonowego w kodzie źródłowym JavaScript.

useQuery(GET_USERS) zwraca { loading, error, data, refetch, fetchMore, networkStatus }. loading ma wartość true podczas początkowego pobierania. error zawiera błędy GraphQL lub sieciowe. data zawiera wynik zapytania zgodny ze strukturą zapytania.

Przed uzyskaniem dostępu do data należy najpierw sprawdzić loading i error, aby uniknąć renderowania wartości null.

Podczas gdy loading ma wartość true, należy renderować komponent szkieletowy. Jeśli error jest zdefiniowany, należy wyświetlić komunikat o błędzie (tekst błędu można odczytać za pomocą error.message). Właściwą treść należy renderować dopiero wtedy, gdy data jest zdefiniowane, a loading ma wartość false.

Ten trójstanowy wzorzec (loading / error / data) to standardowa struktura komponentu Apollo Client.

Obiekt data odzwierciedla strukturę zapytania GraphQL. W przypadku zapytania query { users { id name } } należy odczytać data.users, czyli tablicę obiektów {id, name}. Typy TypeScript będą zgodne, jeśli do wygenerowania typowanych hooków zostanie użyty graphql-codegen.

Bez codegen typ data ma wartość any. Z codegen wywołanie useQuery automatycznie zwraca dane w pełni typowane.

Zmienne należy przekazać jako drugi argument: useQuery(GET_USER, { variables: { id: userId } }). Zapytanie jest automatycznie uruchamiane ponownie, gdy userId się zmieni, podobnie jak w przypadku tablicy zależności useEffect.

Apollo Client przechowuje w cache osobno każdą unikalną kombinację zapytania i zmiennych, dlatego GET_USER z id: "1" i GET_USER z id: "2" ma niezależne wpisy w cache.

Aby zapobiec uruchomieniu zapytania, należy przekazać skip: true w opcjach: useQuery(GET_USER, { skip: !userId }). Gdy skip ma wartość true, Apollo nie wysyła żądania, loading ma wartość false, a data jest równe undefined.

Jest to odpowiednik klucza null w SWR oraz opcji enabled: false w React Query.

Funkcja refetch zwracana przez useQuery wywołuje żądanie sieciowe niezależnie od polityki pobierania. Należy wywołać refetch() po działaniu użytkownika, które mogło zmienić dane na serwerze, na przykład po przesłaniu formularza.

Do refetch można przekazać nowe zmienne: refetch({ id: newId }), aby ponownie pobrać dane z innymi parametrami.

Aby otrzymywać aktualizacje przy zmianie stanu sieci (pobieranie, ponowne pobieranie, odpytywanie i inne), należy przekazać notifyOnNetworkStatusChange: true w opcjach. Pole networkStatus zawiera kod liczbowy z enuma NetworkStatus.

Umożliwia to wyświetlanie subtelnego wskaźnika "refreshing" podczas trwającego ponownego pobierania w tle, bez ukrywania bieżących danych.

useMutation(CREATE_USER) zwraca [mutateFunction, { loading, error, data, reset }]. Funkcja mutate jest wywoływana po przesłaniu formularza przez użytkownika. Zwraca Promise z { data, errors }.

Wywołanie mutate({ variables: { name: 'Alice', email: 'alice@example.com' } }) służy do przekazania danych wejściowych do mutacji.

Do opcji useMutation należy przekazać onCompleted: (data) => navigate('/dashboard') oraz onError: (error) => showToast(error.message). Te wywołania zwrotne są wykonywane po pomyślnym zakończeniu lub odrzuceniu mutacji.

onCompleted otrzymuje dane wyniku mutacji, co pozwala uruchamiać nawigację, wyświetlać komunikaty o powodzeniu lub resetować formularze.

Opcja optimisticResponse w wywołaniu mutate natychmiast zapisuje syntetyczny wynik w cache, zanim serwer odpowie. Apollo od razu renderuje optymistyczne dane, a po nadejściu odpowiedzi serwera zastępuje je rzeczywistym wynikiem.

Jeśli mutacja się nie powiedzie, Apollo automatycznie przywraca stan cache sprzed optymistycznej aktualizacji, zachowując spójność interfejsu.

Co dzieje się z useQuery po przekazaniu skip: true?

Zapytania należy definiować za pomocą tagu gql, wywoływać useQuery(QUERY, { variables, skip }) i obsługiwać stany loading/error/data. useMutation zwraca funkcję wywołującą oraz obiekt stanu; należy wywoływać ją ze zmiennymi i obsługiwać wyniki za pomocą onCompleted i onError. Odpowiedzi optymistyczne natychmiast aktualizują cache, który w razie niepowodzenia jest automatycznie przywracany do poprzedniego stanu.

Opcja skip i ponowne pobieranie danych sterowane zmiennymi obsługują warunkowe oraz parametryzowane ładowanie danych.