Hooks useQuery e useMutation

A tag de modelo gql de @apollo/client analisa uma string de consulta GraphQL em um DocumentNode durante o carregamento do módulo. Defina as consultas fora dos componentes: const GET_USERS = gql`query GetUsers { users { id name email } }`.

Observação: no código de produção, use strings entre aspas simples encapsuladas por gql como um template com tag. A tag gql aceita a sintaxe de literal de modelo no código-fonte JavaScript.

useQuery(GET_USERS) retorna { loading, error, data, refetch, fetchMore, networkStatus }. loading é true durante a busca inicial. error contém qualquer erro do GraphQL ou da rede. data contém o resultado da consulta correspondente ao formato da consulta.

Verifique loading e error primeiro antes de acessar data para evitar renderizar valores nulos.

Renderize um componente esqueleto enquanto loading for true. Renderize uma mensagem de erro se error estiver definido (acesse error.message para obter o texto do erro). Renderize o conteúdo real somente quando data estiver definido e loading for false.

Esse padrão de três estados (loading / error / data) é a estrutura padrão de componentes do Apollo Client.

O objeto data espelha a estrutura da consulta GraphQL. Para query { users { id name } }, acesse data.users, que é uma matriz de objetos {id, name}. Os tipos TypeScript correspondem quando você usa graphql-codegen para gerar hooks tipados.

Sem codegen, data é tipado como any. Com codegen, useQuery retorna dados totalmente tipados automaticamente.

Passe as variáveis como segundo argumento: useQuery(GET_USER, { variables: { id: userId } }). A consulta é executada novamente automaticamente quando userId muda, assim como uma lista de dependências de useEffect.

O Apollo Client armazena em cache cada combinação exclusiva de consulta + variáveis separadamente, portanto GET_USER com id: "1" e GET_USER com id: "2" têm entradas de cache independentes.

Passe skip: true nas opções para impedir a execução da consulta: useQuery(GET_USER, { skip: !userId }). O Apollo não envia a solicitação quando skip é true, e loading é false e data é undefined.

Esse é o equivalente, no Apollo, à chave nula do SWR e à opção enabled: false do React Query.

A função refetch retornada por useQuery dispara uma solicitação de rede independentemente da política de busca. Chame refetch() depois de uma ação do usuário que possa ter alterado os dados do servidor: por exemplo, refetch() depois de enviar um formulário.

Passe novas variáveis para refetch: refetch({ id: newId }) para fazer uma nova busca com parâmetros diferentes.

Passe notifyOnNetworkStatusChange: true nas opções para receber atualizações quando o estado da rede mudar (buscando, fazendo nova busca, sondagem etc.). O campo networkStatus contém um código numérico da enumeração NetworkStatus.

Isso permite mostrar um indicador sutil de "atualizando" enquanto uma nova busca em segundo plano está em andamento, sem ocultar os dados atuais.

useMutation(CREATE_USER) retorna [mutateFunction, { loading, error, data, reset }]. A função de mutação é chamada quando o usuário envia um formulário. Ela retorna uma Promise com { data, errors }.

Chame mutate({ variables: { name: 'Alice', email: 'alice@example.com' } }) para passar dados à mutação.

Passe onCompleted: (data) => navigate('/dashboard') e onError: (error) => showToast(error.message) às opções de useMutation. Esses retornos de chamada são executados depois que a mutação é resolvida ou rejeitada.

onCompleted recebe os dados do resultado da mutação, sendo útil para iniciar uma navegação, exibir mensagens de sucesso ou redefinir formulários.

A opção optimisticResponse na chamada mutate grava imediatamente um resultado sintético no cache, antes que o servidor responda. O Apollo renderiza os dados otimistas instantaneamente e depois os substitui pela resposta real do servidor quando ela chega.

Se a mutação falhar, o Apollo reverte automaticamente para o estado do cache anterior à resposta otimista, mantendo a interface consistente.

O que acontece com uma chamada de useQuery quando skip: true é passado?

Defina consultas com a tag gql, chame useQuery(QUERY, { variables, skip }) e trate os estados loading/error/data. useMutation retorna uma função de disparo e um objeto de status; chame-a com variáveis e trate os resultados por meio de onCompleted e onError. Respostas otimistas atualizam o cache imediatamente, com reversão automática em caso de falha.

A opção skip e a nova busca orientada por variáveis lidam com o carregamento condicional e parametrizado de dados.