useImperativeHandle: valori personalizzati dell'istanza

Quando si inoltra un ref direttamente a un elemento DOM, il padre riceve il nodo DOM grezzo e ottiene accesso a ogni suo metodo e proprietà nativi. Spesso si tratta di una superficie esposta più ampia di quanto si desideri.

A volte è preferibile fornire al padre un oggetto piccolo e selezionato invece del nodo DOM completo, mantenendo deliberatamente ristretta l'API pubblica del componente.

useImperativeHandle consente di personalizzare il valore a cui punta il ref del padre. Al posto del nodo DOM, il padre riceve l'oggetto restituito, quindi è Lei a decidere esattamente quali metodi e valori esporre.

In questo modo il ref inoltrato diventa un'interfaccia imperativa definita, invece di un semplice passaggio trasparente verso l'elemento sottostante.

L'hook accetta come primo argomento il ref inoltrato e come secondo una funzione factory. La factory restituisce l'oggetto handle che diventa ref.current nel componente padre.

Lo si chiama come useImperativeHandle(ref, () => ({ ... })), costruendo all'interno della factory l'oggetto con i metodi e i valori che si desidera rendere disponibili.

Uno schema comune consiste in un input personalizzato che espone soltanto focus e clear. All'interno della factory si restituisce un oggetto con questi due metodi, ciascuno dei quali opera su un ref interno collegato al vero input.

Il padre può quindi mettere a fuoco o svuotare il campo, ma non può leggere il suo attributo value grezzo né attivare comportamenti DOM arbitrari, rendendo l'utilizzo prevedibile.

Gli handle imperativi si adattano bene alle finestre di dialogo. Un componente Modal può esporre i metodi open e close, che modificano lo stato di visibilità interno, consentendo al padre di controllarlo imperativamente senza dover gestire direttamente il booleano open.

È comodo per il codice che deve attivare una finestra di dialogo da più punti, ad esempio per mostrare una conferma al completamento di un'azione asincrona.

Restituendo solo i metodi che si intende supportare, si crea un contratto chiaro. I consumatori dipendono da un insieme ridotto e documentato di operazioni, invece che dalla vasta API del DOM, rendendo più sicuri i refactoring futuri.

Una superficie imperativa ristretta è più facile da testare e da comprendere, ed è molto meno soggetta a rotture quando si modifica l'implementazione interna.

useImperativeHandle accetta un terzo argomento facoltativo: un array delle dipendenze. Quando una dipendenza cambia, la factory viene eseguita nuovamente e l'oggetto handle viene ricreato, in modo simile a quanto avviene con useMemo e useEffect.

Se i metodi esposti acquisiscono valori che possono cambiare, inserisca tali valori tra le dipendenze, così che il padre riceva sempre un handle associato allo stato corrente.

useImperativeHandle ha senso solo all'interno di un componente avvolto con forwardRef, perché ha bisogno del ref inoltrato a cui associare l'handle personalizzato. Da solo non esisterebbe alcun ref del padre da valorizzare.

Perciò i due strumenti vengono utilizzati insieme: forwardRef introduce il ref, mentre useImperativeHandle definisce a cosa finirà per puntare quel ref.

Per testare un handle, esegua il rendering del componente con un ref, quindi chiami i metodi tramite ref.current all'interno di un blocco act e verifichi il comportamento risultante o le modifiche al DOM.

Poiché la superficie esposta è ridotta ed esplicita, questi test sono mirati: verificano che ogni metodo documentato faccia ciò che il suo contratto promette, invece di esaminare i dettagli interni.

In TypeScript si definisce un'interfaccia che descrive l'handle, ad esempio un'interfaccia con i metodi focus e clear, quindi la si utilizza per tipizzare sia il generico di forwardRef sia il ref conservato dal padre.

Questo fornisce il completamento automatico e i controlli in fase di compilazione nel punto di chiamata, così che i consumatori vedano esattamente quali metodi esistono e gli utilizzi errati vengano rilevati prima del runtime.

Confermi a cosa serve realmente useImperativeHandle.

useImperativeHandle personalizza ciò che espone un ref inoltrato, accettando il ref e una factory che restituisce un oggetto handle. Lo si utilizza per esporre una piccola API, come focus e clear oppure open e close su un Modal.

Viene sempre usato insieme a forwardRef, supporta un array delle dipendenze per aggiornare l'handle e si abbina bene alle interfacce TypeScript e ai test mirati. Una superficie limitata è una scelta intenzionale e una buona pratica di progettazione.