Creación de una API imperativa para componentes

Comience por decidir el contrato: un FocusableInput podría exponer focus, blur y getValue. Envuélvalo en forwardRef, mantenga una ref interna al input real y devuelva esos tres métodos desde useImperativeHandle.

Cada método delega en el input subyacente, por lo que el componente padre obtiene exactamente las operaciones que necesita sin tocar el elemento DOM directamente.

Un componente multimedia obtiene gran provecho de una API imperativa. Un VideoPlayer puede exponer play, pause y seekTo, y delegar cada uno en los métodos del HTMLVideoElement nativo mediante una ref interna al video.

seekTo acepta un tiempo en segundos y establece currentTime, lo que proporciona a los componentes padre un control preciso de la reproducción que sería difícil de conseguir usando únicamente props.

Un Carousel puede exponer next, prev y goToSlide para que los controles externos o los gestores de teclado puedan controlarlo. Internamente, estos métodos actualizan el estado del índice activo y el componente vuelve a renderizarse con la nueva diapositiva.

Esto combina activadores imperativos con renderizado declarativo: el componente padre ordena una transición y el carousel renderiza el resultado mediante su flujo de estado habitual.

Un handle imperativo es un contrato público, así que documente cada método, sus parámetros y su valor de retorno. Una documentación clara indica a los consumidores qué se admite y desaconseja depender de elementos internos no documentados.

Trate el handle como cualquier otra superficie de API: una referencia breve que enumere métodos como play(), pause() y seekTo(seconds) evita usos incorrectos y confusiones.

Cuando los consumidores dependen de un handle, eliminar o cambiar el nombre de un método es un cambio incompatible. Añada métodos nuevos en lugar de modificar las firmas existentes y marque los métodos como obsoletos gradualmente antes de eliminar cualquier elemento.

Considerar el handle como una API versionada evita que se rompa el código dependiente cuando amplía el componente con el tiempo.

Muchos componentes reales combinan ambos estilos. Un VideoPlayer podría aceptar de forma declarativa una prop src y una prop autoPlay, y al mismo tiempo exponer play y seekTo para situaciones que las props no expresan bien.

La pauta es utilizar props para el estado y la configuración, y reservar el handle imperativo para acciones puntuales activadas en momentos concretos.

Para probar una API imperativa, renderice el componente con una ref, envuelva las interacciones en act y llame a los métodos expuestos mediante ref.current. Después, compruebe el resultado observable, como que el video esté pausado o que cambie el índice de la diapositiva.

Un callback de ref puede capturar el handle durante el renderizado, de modo que la prueba tenga una referencia estable desde la que llamar a los métodos.

Storybook es un buen lugar para demostrar los handles imperativos. Una historia puede conservar una ref al componente y renderizar botones que llamen a sus métodos, lo que permite a los revisores probar play, pause o goToSlide de forma interactiva.

Estas historias también sirven como documentación viva, ya que muestran con precisión cómo se comporta la API imperativa de forma aislada.

Los handles imperativos son habituales al envolver bibliotecas que no son de React. Las bibliotecas de gráficos exponen métodos como redraw o update, los SDK de mapas exponen panTo y setZoom, y los editores de texto enriquecido exponen insertText o getContents.

Envolver una biblioteca de este tipo en un componente de React y ofrecer un handle limpio proporciona al resto de la aplicación una forma ordenada e idiomática de controlarla.

Los métodos de un handle suelen capturar el estado actual, así que utilice el array de dependencias de useImperativeHandle para actualizarlos cuando sea necesario y useCallback para los helpers internos, con el fin de evitar cierres obsoletos.

Un handle bien gestionado siempre opera con valores actualizados, por lo que cuando un componente padre llama a getValue o seekTo obtiene un comportamiento coherente con el renderizado más reciente.

Aplique la pauta de diseño para las API imperativas de componentes.

Diseñó handles para un FocusableInput, un VideoPlayer y un Carousel, y cada uno expone un conjunto reducido de métodos de acción. Documente y versione esos métodos, ya que los consumidores dependen de ellos como de una API pública.

Combine acciones imperativas con props declarativas, pruebe mediante ref.current dentro de act y muestre el comportamiento en Storybook. El mismo patrón permite envolver de forma limpia bibliotecas de gráficos, mapas y editores.