useTemplateRef() Obter referência de template (forma recomendada do 3.5+)
Última atualização: 2026-10-22
useTemplateRef() Obter referência de template (forma recomendada do 3.5+)
useTemplateRef() obtém a referência de template da propriedade ref de mesmo nome por chave de string, eliminando o código repetitivo de declarar uma variável com o mesmo nome.
| Grupo | Template e Auxiliares |
|---|---|
| Tipo | API |
| Escopo | No Componente |
| Versão do Vue | 3.5+ |
| Suporte a SSR | Sim |
📝 Sintaxe
const inputEl = useTemplateRef('my-input')
// template: <input ref="my-input">⚙️ Argumentos
| key | String igual ao valor do atributo ref do template |
|---|
Retorno：Um ref somente leitura, null antes da montagem
▶ Exemplo
Edite o código abaixo e veja o resultado ao vivo:
Saída：
Clicking focuses the input.💡 Pontos-chave
💡 Dica Forma recomendada no 3.5+; a forma antiga (variável ref de mesmo nome + coleta automática) continua totalmente utilizável.
⚠️ Aviso O valor é null antes da montagem: verifique contra nulo antes de acessar, ou use após onMounted.
ℹ️ Nota Dentro de v-for, resulta em um array de componentes/elementos.
🏷️ Template e Auxiliares relacionados
💡 Casos Relacionados
Mais casos em breve.
📚 Tutoriais Relacionados
❓ FAQ
P Qual a diferença de declarar diretamente uma variável ref com o mesmo nome?
R Funcionalmente iguais; useTemplateRef dispensa a restrição de mesmo nome, tem semântica mais clara e é adequado a cenários com múltiplas referências.
P Consegue obter a instância de um componente filho?
R Consegue, apontando para a instância do componente; para chamar seus métodos, é preciso expor com defineExpose no componente filho.
P E em versões abaixo do 3.5?
R Use a forma clássica: const txt = ref(null) com ref="txt" no template (coleta automática em tempo de compilação).
