useMutation para alterações de dados
useMutation(MUTATION), mutate(), estratégias de atualização do cache e respostas otimistas.
useMutation para alterações de dados é uma aula grátis de Vue Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Vue Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Vue Academy inclui 4 aulas no total.
Alterando dados com mutações
As consultas leem dados; as mutações os alteram — criam, atualizam e excluem. O composable useMutation executa uma mutação GraphQL e fornece uma função mutate para ser chamada quando necessário.
Uso básico de useMutation
Passe um documento de mutação. Diferentemente de useQuery, ele não é executado imediatamente — retorna uma função mutate que você chama em um evento.
import { useMutation } from '@vue/apollo-composable'
import { gql } from '@apollo/client/core'
const { mutate } = useMutation(gql(
'mutation { addPost { id } }'
))Acionando a mutação
Chame mutate() a partir de um manipulador de eventos, como o envio de um formulário. Ela retorna uma promessa que é resolvida com o resultado.
async function submit() {
await mutate()
}Passando variáveis
Passe um objeto de variáveis para mutate. O documento da mutação as declara usando a sintaxe $.
const { mutate } = useMutation(gql(
'mutation($title: String!) { addPost(title: $title) { id title } }'
))
function add(title) {
return mutate({ title })
}Carregamento e erro
useMutation também retorna refs de loading e error, para que você possa desabilitar o botão de envio e exibir falhas.
<template>
<button :disabled="loading" @click="submit">Save</button>
<p v-if="error">{{ error.message }}</p>
</template>Reagindo ao sucesso
O gancho onDone é executado após uma mutação bem-sucedida — limpe um formulário, exiba uma notificação breve ou navegue para outra página.
const { mutate, onDone } = useMutation(ADD_POST)
onDone((res) => {
console.log('Created', res.data.addPost.id)
})Atualizando o cache
Após uma mutação, o cache do Apollo pode estar desatualizado. A função update permite modificar o cache diretamente, para que a interface reflita a alteração sem uma nova consulta.
useMutation(ADD_POST, {
update(cache, { data }) {
const existing = cache.readQuery({ query: GET_POSTS })
cache.writeQuery({
query: GET_POSTS,
data: { posts: [...existing.posts, data.addPost] }
})
}
})Por que update é melhor que uma nova consulta
Um update do cache evita uma ida e volta adicional à rede. O novo item aparece instantaneamente porque você o gravou no cache que todos os useQuery consultam.
Executando as consultas novamente
Se editar o cache manualmente for trabalhoso demais, use refetchQueries para executar novamente consultas específicas depois que a mutação for concluída.
useMutation(ADD_POST, {
refetchQueries: [{ query: GET_POSTS }]
})Respostas otimistas
Uma optimisticResponse atualiza a interface antes de o servidor responder, presumindo que a operação será bem-sucedida. Se a solicitação falhar, o Apollo desfaz a alteração automaticamente.
mutate(
{ title: 'New' },
{
optimisticResponse: {
addPost: { __typename: 'Post', id: 'temp', title: 'New' }
}
}
)Por que a interface otimista é importante
As atualizações otimistas fazem o aplicativo parecer instantâneo — o usuário vê sua ação surtir efeito imediatamente. Combinado com update, o item temporário é substituído pelos dados reais do servidor quando eles chegam.
Verificação rápida
Teste seus conhecimentos sobre mutações.
Recapitulação
Você aprendeu sobre mutações:
- useMutation retorna uma função mutate que você chama em eventos.
- Passe variáveis para mutate(); use loading/error e onDone.
- A função update edita o cache depois de uma mutação, evitando uma nova consulta.
- optimisticResponse atualiza a interface instantaneamente e desfaz a alteração automaticamente em caso de falha.
Perguntas Frequentes
A aula “useMutation para alterações de dados” é grátis?
Sim — o texto completo de “useMutation para alterações de dados” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Vue Academy, atualize para CoddyKit PRO. O curso de Vue Academy inclui 4 aulas no total.
O que vou aprender em “useMutation para alterações de dados”?
useMutation(MUTATION), mutate(), estratégias de atualização do cache e respostas otimistas. Você pratica Vue Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar Vue Academy?
Nenhuma experiência prévia é necessária. Vue Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.
Quanto tempo leva a aula “useMutation para alterações de dados”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de Vue Academy?
Sim. Cada aula de Vue Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Configuração do Apollo Client no Vue 3
- useQuery para busca de dados
- useMutation para alterações de dados
- Assinaturas em tempo real com useSubscription