toRef() Converter uma propriedade em um ref que mantém o vínculo
Última atualização: 2026-10-22
toRef() Converter uma propriedade em um ref que mantém o vínculo
toRef() converte uma propriedade de um objeto reativo em um ref com vínculo bidirecional: ler ou escrever por ele equivale a operar a propriedade original.
| Grupo | Reatividade: Utilitários |
|---|---|
| Tipo | API |
| Escopo | No Componente |
| Versão do Vue | 3.0+ |
| Suporte a SSR | Sim |
📝 Sintaxe
const state = reactive({ count: 0 })
const count = toRef(state, 'count')
count.value++ // equivale a state.count++⚙️ Argumentos
| object | Um objeto reativo |
|---|---|
| key | O nome da propriedade |
Retorno：Um ref vinculado bidirecionalmente à propriedade original
▶ Exemplo
Edite o código abaixo e veja o resultado ao vivo:
Saída：
Both numbers always match: writing the ref updates state.count.💡 Pontos-chave
💡 Dica Uso padrão: converter um campo de props em um ref antes de passá-lo a um composable, para não perder a reatividade.
ℹ️ Nota toRef(state, 'a') equivale a toRefs(state).a; também funciona quando a propriedade não existe (é gravável).
⚠️ Aviso O toRef é apenas um canal e não copia os dados: se o objeto de origem for substituído por inteiro, o vínculo se rompe.
🏷️ Utilitários relacionados
💡 Casos Relacionados
Mais casos em breve.
📚 Tutoriais Relacionados
❓ FAQ
P Qual a relação entre toRef e toRefs?
R toRef trata uma única propriedade; toRefs devolve de uma vez um objeto de refs para todas as propriedades — este último é comum para desestruturar o estado inteiro.
P Por que não dá para substituir por desestruturação?
R const { count } = state devolve um número-retrato, que deixa de sincronizar com as mudanças seguintes — só o toRef mantém o vínculo.
P Funciona em objetos comuns?
R Sim, mas objetos comuns não têm reatividade; o ref é apenas um canal prático de leitura e escrita dessa propriedade.
