ref() Criar uma referência reativa
Última atualização: 2026-10-22
ref() Criar uma referência reativa
ref() envolve qualquer valor em um objeto reativo acessado por meio de .value. É a forma de guardar primitivos e valores que você quer substituir como um todo.
| Grupo | Reatividade: Essencial |
|---|---|
| Tipo | API |
| Escopo | No Componente |
| Versão do Vue | 3.0+ |
| Suporte a SSR | Sim |
📝 Sintaxe
import { ref } from "vue"
const count = ref(0)
count.value++ // leitura/escrita via .value no script
template: {{ count }} // desembrulhado automaticamente no template⚙️ Argumentos
| value | O valor inicial de qualquer tipo; undefined quando omitido |
|---|
Retorno：Um objeto reativo (Ref) com a propriedade .value
▶ Exemplo
Edite o código abaixo e veja o resultado ao vivo:
Saída：
The page shows 'Clicked 0 times'; each click increments the number.💡 Pontos-chave
⚠️ Aviso No script, use sempre count.value — escrever count++ religa a variável a um novo número e quebra a reatividade.
💡 Dica Quando um ref é retornado do setup, o template o desembrulha automaticamente: escreva {{ count }}, não {{ count.value }}.
ℹ️ Nota Use ref quando o valor for substituído por inteiro; use reactive() para objetos profundamente reativos.
🏷️ Essencial relacionados
💡 Casos Relacionados
Mais casos em breve.
📚 Tutoriais Relacionados
❓ FAQ
P Por que .value é obrigatório?
R O JavaScript não consegue rastrear leituras/escritas em primitivos, então um wrapper com getter/setter captura o acesso — essa propriedade do wrapper é o .value.
P Objetos dentro de um ref perdem a reatividade?
R Não. ref(obj) cria internamente um proxy profundo do objeto, então mutações via .value.foo continuam disparando atualizações.
P Quando usar ref ou reactive?
R Prefira ref por padrão (qualquer tipo, substituível, mantém a reatividade ao desestruturar); reactive só serve para objetos e perde a reatividade ao ser desestruturado.
