useImperativeHandle: Valores Personalizados da Instância

Quando você encaminha uma referência diretamente para um elemento do DOM, o pai recebe o nó bruto do DOM e obtém acesso a todos os métodos e propriedades nativos dele. Isso geralmente representa uma superfície de acesso maior do que você deseja expor.

Às vezes, é melhor fornecer ao pai um objeto pequeno e cuidadosamente selecionado em vez do nó completo do DOM, mantendo a API pública do componente deliberadamente restrita.

useImperativeHandle permite personalizar o valor para o qual a referência do pai aponta. Em vez do nó do DOM, o pai recebe o objeto que você retornar, de modo que você decide exatamente quais métodos e valores serão expostos.

Isso transforma a referência encaminhada em uma interface imperativa definida, em vez de um simples repasse que deixa escapar o elemento subjacente.

Essa função recebe a referência encaminhada como primeiro argumento e uma função geradora como segundo. A função geradora retorna o objeto de controle que se torna ref.current no pai.

Você a chama como useImperativeHandle(ref, () => ({ ... })), construindo dentro da função geradora o objeto com os métodos e valores que deseja disponibilizar.

Um padrão comum é um campo de entrada personalizado que expõe apenas as operações de foco e limpeza. Dentro da função geradora, você retorna um objeto com esses dois métodos, cada um operando sobre uma referência interna ao campo de entrada real.

Agora o pai pode focalizar ou limpar o campo, mas não pode ler seu valor bruto nem acionar comportamentos arbitrários do DOM, o que mantém o uso previsível.

Os identificadores imperativos combinam bem com diálogos. Um componente Modal pode expor operações de abrir e fechar que alteram seu estado interno de visibilidade, permitindo que o pai o controle imperativamente sem gerenciar sozinho o valor booleano de abertura.

Isso é conveniente para códigos que precisam acionar um diálogo a partir de vários lugares, como ao exibir uma confirmação depois que uma ação assíncrona é concluída.

Ao retornar somente os métodos que pretende oferecer, você cria um contrato claro. Os consumidores dependem de um conjunto pequeno e documentado de operações, em vez da extensa API do DOM, o que torna futuras refatorações mais seguras.

Uma superfície imperativa restrita é mais fácil de testar e de compreender, e tem muito menos probabilidade de ser afetada quando você altera a implementação interna.

useImperativeHandle aceita um terceiro argumento opcional: uma lista de dependências. Quando qualquer dependência muda, a função geradora é executada novamente e o objeto de controle é recriado, de modo semelhante ao que ocorre com useMemo e useEffect.

Se os métodos expostos capturarem valores que podem mudar, liste esses valores como dependências para que o pai sempre receba um objeto de controle associado ao estado atual.

useImperativeHandle só faz sentido dentro de um componente encapsulado com forwardRef, porque precisa da referência encaminhada para associar a ela o objeto de controle personalizado. Sozinho, ele não teria uma referência do pai para preencher.

Por isso, os dois são usados juntos: forwardRef recebe a referência, e useImperativeHandle define para o que essa referência acaba apontando.

Para testar um objeto de controle, renderize o componente com uma referência, depois chame os métodos por meio de ref.current dentro de um bloco act e verifique o comportamento resultante ou as alterações no DOM.

Como a superfície exposta é pequena e explícita, esses testes são focados: verificam se cada método documentado faz o que seu contrato promete, em vez de examinar detalhes internos.

Em TypeScript, você define uma interface que descreve o objeto de controle, como uma que contenha métodos de foco e limpeza, e então a usa para tipar tanto o parâmetro genérico de forwardRef quanto a referência mantida pelo pai.

Isso oferece preenchimento automático e verificações em tempo de compilação no local da chamada, para que os consumidores vejam exatamente quais métodos existem e os usos incorretos sejam identificados antes da execução.

useImperativeHandle personaliza o que uma referência encaminhada expõe, recebendo a referência e uma função geradora que retorna um objeto de controle. Use-o para disponibilizar uma API pequena, como foco e limpeza, ou abrir e fechar em uma janela modal.

Ele sempre é combinado com forwardRef, aceita uma lista de dependências para atualizar o objeto de controle e combina bem com interfaces TypeScript e testes focados. Uma superfície limitada é intencional e representa um bom projeto.