Construindo uma API Imperativa de Componente

Comece definindo o contrato: uma FocusableInput pode expor foco, desfoque e getValue. Envolva-a em forwardRef, mantenha uma referência interna ao campo de entrada real e retorne esses três métodos por meio de useImperativeHandle.

Cada método delega ao campo de entrada subjacente, para que o componente pai obtenha exatamente as operações de que precisa sem tocar no elemento bruto.

Um componente de mídia se beneficia muito de uma API imperativa. Um VideoPlayer pode expor reproduzir, pausar e seekTo, cada um delegando aos métodos nativos do elemento de vídeo HTML em uma referência interna ao vídeo.

seekTo aceita um tempo em segundos e define currentTime, dando aos componentes pais um controle preciso sobre a reprodução, algo que seria difícil de conduzir apenas por propriedades.

Um carrossel pode expor avançar, voltar e goToSlide para que controles externos ou manipuladores de teclado possam acioná-lo. Internamente, esses métodos atualizam o estado do índice ativo, e o componente renderiza novamente o novo item.

Isso combina acionadores imperativos com renderização declarativa: o componente pai comanda uma transição, e o carrossel renderiza o resultado por meio do fluxo normal de estado.

Uma referência imperativa é um contrato público, portanto documente cada método, seus parâmetros e seu valor de retorno. Uma documentação clara informa aos consumidores o que é compatível e desencoraja a dependência de elementos internos não documentados.

Trate a referência como qualquer outra superfície de API: uma referência breve que liste métodos como reproduzir(), pausar() e seekTo(segundos) evita uso incorreto e confusão.

Depois que os consumidores passam a depender de uma referência, remover ou renomear um método é uma alteração incompatível. Adicione novos métodos em vez de alterar assinaturas existentes e descontinue os antigos gradualmente antes de remover qualquer coisa.

Tratar a referência como uma API versionada impede que o código dependente seja interrompido à medida que você amplia o componente ao longo do tempo.

Muitos componentes reais combinam os dois estilos. Um VideoPlayer pode aceitar declarativamente uma propriedade de origem e uma propriedade autoPlay, além de expor reproduzir e seekTo para situações que as propriedades não conseguem expressar bem.

A diretriz é usar propriedades para estado e configuração e reservar a referência imperativa para ações pontuais acionadas em momentos específicos.

Para testar uma API imperativa, renderize o componente com uma referência, envolva as interações em act e chame os métodos expostos por meio de ref.current. Em seguida, verifique o resultado observável, como o vídeo estar pausado ou o índice do item ter mudado.

Um retorno de chamada de referência pode capturar a referência durante a renderização, para que seu teste tenha uma referência estável na qual chamar métodos.

O Storybook é um bom lugar para demonstrar referências imperativas. Uma história pode manter uma referência ao componente e renderizar botões que chamam seus métodos, permitindo que os revisores experimentem reproduzir, pausar ou goToSlide de forma interativa.

Essas histórias também funcionam como documentação viva, mostrando exatamente como a API imperativa se comporta de forma isolada.

Referências imperativas são comuns ao envolver bibliotecas que não são do React. Bibliotecas de gráficos expõem métodos para redesenhar ou atualizar, SDKs de mapas expõem panTo e setZoom, e editores de texto formatado expõem insertText ou getContents.

Envolver uma biblioteca desse tipo em um componente React e disponibilizar uma referência limpa oferece ao restante do aplicativo uma maneira organizada e idiomática de controlá-la.

Os métodos de uma referência frequentemente capturam o estado atual, portanto use a matriz de dependências de useImperativeHandle para atualizá-los quando necessário e useCallback para auxiliares internos, evitando fechamentos obsoletos.

Uma referência bem gerenciada sempre opera sobre valores atualizados, de modo que, ao chamar getValue ou seekTo, o componente pai obtém um comportamento consistente com a renderização mais recente.

Aplique a diretriz de projeto para APIs de componentes imperativos.

Você projetou referências para uma FocusableInput, um VideoPlayer e um carrossel, cada um expondo um pequeno conjunto de métodos de ação. Documente e versione esses métodos, pois os consumidores dependem deles como uma API pública.

Combine ações imperativas com propriedades declarativas, teste por meio de ref.current dentro de act e mostre o comportamento no Storybook. O mesmo padrão envolve bibliotecas de gráficos, mapas e editores de forma organizada.