shallowRef() Referência reativa superficial
Última atualização: 2026-10-22
shallowRef() Referência reativa superficial
shallowRef() só rastreia a substituição de .value e não cria proxy profundo dos objetos internos: só a substituição completa dispara atualização; alterações em propriedades internas não disparam.
| Grupo | Reatividade: Avançado |
|---|---|
| Tipo | API |
| Escopo | No Componente |
| Versão do Vue | 3.0+ |
| Suporte a SSR | Sim |
📝 Sintaxe
const big = shallowRef({ list: [] })
big.value = { list: [1] } // ✅ dispara
big.value.list.push(2) // ❌ não dispara (o interior não é proxy)⚙️ Argumentos
| value | Qualquer valor inicial (objetos internos não recebem proxy profundo) |
|---|
Retorno：Um objeto ref superficial
▶ Exemplo
Edite o código abaixo e veja o resultado ao vivo:
Saída：
Pushing inside leaves the number unchanged; replacing the whole value shows 3.💡 Pontos-chave
💡 Dica Adequado para grandes conjuntos de dados, instâncias de bibliotecas de terceiros e objetos de mapa/gráfico: só importa a substituição completa, sem necessidade de reatividade profunda.
⚠️ Aviso Alterações internas podem disparar manualmente com triggerRef, mas a substituição completa é mais recomendada.
ℹ️ Nota isShallow() permite verificar se um ref é superficial.
🏷️ Avançado relacionados
💡 Casos Relacionados
Mais casos em breve.
📚 Tutoriais Relacionados
Reatividade em profundidade
Lição 15: proxies profundos e superficiais e o compromisso de desempenho
❓ FAQ
P Quando é obrigatório usar shallowRef?
R Ao envolver grandes estruturas somente leitura (como grandes arrays vindos de APIs) que também serão substituídas por inteiro — economiza o custo de criação do proxy profundo.
P Por que a página não muda depois do push?
R Os objetos internos não têm proxy, então o Vue não consegue rastrear essa alteração; só a substituição completa de .value notifica a atualização.
P A diferença de desempenho em relação a ref(null) é grande?
R Para objetos grandes e profundos a diferença é evidente (elimina proxy recursivo e coleta de dependências); para objetos pequenos é desprezível.
