customRef() Personalizar o comportamento de leitura e escrita de um ref
Última atualização: 2026-10-22
customRef() Personalizar o comportamento de leitura e escrita de um ref
customRef() personaliza o rastreamento de dependências e o momento de disparo por meio de uma função fábrica; o uso típico é aplicar debounce a um campo de entrada.
| Grupo | Reatividade: Avançado |
|---|---|
| Tipo | API |
| Escopo | No Componente |
| Versão do Vue | 3.0+ |
| Suporte a SSR | Sim |
📝 Sintaxe
function useDebounced(value, delay) {
return customRef((track, trigger) => ({
get() { track(); return value },
set(v) { clearTimeout(timer); timer = setTimeout(() => { value = v; trigger() }, delay) }
}))
}⚙️ Argumentos
| factory | (track, trigger) => { get, set }, onde track coleta dependências e trigger notifica atualizações |
|---|
Retorno：Um ref com comportamento personalizado
▶ Exemplo
Edite o código abaixo e veja o resultado ao vivo:
Saída：
Typing fast updates the line only after a 400ms pause — intermediate states are merged.💡 Pontos-chave
⚠️ Aviso É obrigatório chamar track() e trigger(): sem track, as dependências não são coletadas; sem trigger, as atualizações não disparam.
💡 Dica Empacotar como composable (useDebounced) para reutilização é a forma padrão de usar customRef.
ℹ️ Nota Adequado para estratégias de sincronização personalizadas como debounce, throttle e modelos de entrada com validação.
🏷️ Avançado relacionados
💡 Casos Relacionados
Mais casos em breve.
📚 Tutoriais Relacionados
❓ FAQ
P Por que as dependências precisam de track manual?
R customRef lhe dá controle total: quando coletar dependências e quando notificar é decisão sua, por isso precisa ser declarado explicitamente.
P No cenário de debounce é obrigatório usá-lo?
R Não: também é possível manter manualmente um ref comum com watch + setTimeout, mas a escrita com customRef é mais coesa.
P Dá para implementar throttle?
R Sim: basta controlar no set que a primeira execução é imediata e as seguintes disparam por intervalo.
