useImperativeHandle: valores de instancia personalizados

Cuando reenvía un ref directamente a un elemento DOM, el padre recibe ese nodo DOM sin modificar y obtiene acceso a todos sus métodos y propiedades nativos. A menudo, esto expone una superficie mayor de la que desea ofrecer.

En ocasiones, es preferible entregar al padre un objeto pequeño y cuidadosamente definido en lugar del nodo DOM completo, para mantener deliberadamente reducida la API pública del componente.

useImperativeHandle permite personalizar el valor al que apunta el ref del padre. En lugar del nodo DOM, el padre recibe el objeto que usted devuelva, por lo que decide exactamente qué métodos y valores se exponen.

Esto convierte el ref reenviado en una interfaz imperativa definida, en lugar de un paso directo que expone el elemento subyacente.

El hook recibe el ref reenviado como primer argumento y una función de fábrica como segundo. La fábrica devuelve el objeto de control que se convierte en ref.current en el padre.

Se utiliza como useImperativeHandle(ref, () => ({ ... })), construyendo dentro de la fábrica el objeto con los métodos y valores que desea poner a disposición.

Un patrón habitual es crear un input personalizado que exponga únicamente focus y clear. Dentro de la fábrica, devuelve un objeto con esos dos métodos, cada uno de los cuales opera sobre un ref interno que apunta al input real.

El padre puede enfocar o borrar el campo, pero no puede leer su atributo value sin procesar ni desencadenar comportamientos DOM arbitrarios, lo que mantiene predecible su uso.

Los controles imperativos se adaptan muy bien a los diálogos. Un componente Modal puede exponer los métodos open y close, que cambian su estado interno de visibilidad, para que el padre lo controle imperativamente sin tener que gestionar por sí mismo el booleano open.

Esto resulta práctico para el código que necesita activar un diálogo desde varios lugares, como al mostrar una confirmación después de que finalice una acción asíncrona.

Al devolver únicamente los métodos que pretende admitir, crea un contrato claro. Los consumidores dependen de un conjunto pequeño y documentado de operaciones en lugar de la extensa API del DOM, lo que hace más seguras las refactorizaciones futuras.

Una superficie imperativa reducida es más fácil de probar y de comprender, y es mucho menos probable que se rompa cuando cambie la implementación interna.

useImperativeHandle acepta un tercer argumento opcional: un array de dependencias. Cuando cambia cualquier dependencia, la fábrica se ejecuta de nuevo y el objeto de control se vuelve a crear, de forma similar a como funcionan useMemo y useEffect.

Si los métodos que expone capturan valores que pueden cambiar, incluya esos valores como dependencias para que el padre reciba siempre un objeto de control vinculado al estado actual.

useImperativeHandle solo tiene sentido dentro de un componente envuelto con forwardRef, porque necesita el ref reenviado para adjuntarle el objeto de control personalizado. Por sí solo, no habría ningún ref del padre que rellenar.

Por eso se utilizan juntos: forwardRef introduce el ref y useImperativeHandle define a qué acaba apuntando ese ref.

Para probar un objeto de control, renderice el componente con un ref, llame a los métodos mediante ref.current dentro de un bloque act y compruebe el comportamiento resultante o los cambios en el DOM.

Como la superficie expuesta es pequeña y explícita, estas pruebas son específicas y verifican que cada método documentado haga lo que promete su contrato, en lugar de examinar detalles internos.

En TypeScript, defina una interfaz que describa el objeto de control, como una que incluya los métodos focus y clear, y úsela para tipar tanto el genérico de forwardRef como el ref que conserva el padre.

Esto proporciona autocompletado y comprobaciones en tiempo de compilación en el punto de llamada, de modo que los consumidores ven exactamente qué métodos existen y los usos incorrectos se detectan antes del tiempo de ejecución.

useImperativeHandle personaliza lo que expone un ref reenviado y recibe el ref junto con una fábrica que devuelve un objeto de control. Se utiliza para ofrecer una API pequeña, como focus y clear, u open y close en un modal.

Siempre se combina con forwardRef, admite un array de dependencias para actualizar el objeto de control y funciona bien con interfaces de TypeScript y pruebas específicas. Una superficie limitada es una decisión intencionada y un buen diseño.