useImperativeHandle : valeurs d’instance personnalisées

Lorsque vous transmettez directement une référence à un élément DOM, le parent reçoit le nœud DOM brut et peut accéder à chacune de ses propriétés et méthodes natives. Cela représente souvent une surface plus vaste que celle que vous souhaitez exposer.

Vous préférerez parfois fournir au parent un petit objet soigneusement choisi plutôt que le nœud DOM complet, afin de maintenir délibérément l’API publique de votre composant dans des limites restreintes.

useImperativeHandle permet de personnaliser la valeur vers laquelle pointe la référence du parent. Au lieu du nœud DOM, le parent reçoit l’objet que vous renvoyez ; vous décidez ainsi exactement quelles méthodes et quelles valeurs sont exposées.

La référence transmise devient ainsi une interface impérative définie, plutôt qu’un simple relais laissant fuir l’accès à l’élément sous-jacent.

Le hook reçoit la référence transmise comme premier argument et une fonction d’usine comme second. Cette fonction d’usine renvoie l’objet poignée qui devient ref.current dans le parent.

Vous l’appelez ainsi : useImperativeHandle(ref, () => ({ ... })), en construisant dans la fonction d’usine l’objet contenant les méthodes et les valeurs que vous souhaitez rendre disponibles.

Un modèle courant consiste à créer un champ de saisie personnalisé qui n’expose que focus et clear. Dans la fonction d’usine, vous renvoyez un objet contenant ces deux méthodes, chacune agissant sur une référence interne vers le véritable champ de saisie.

Le parent peut alors donner le focus au champ ou l’effacer, mais ne peut pas lire son attribut value brut ni déclencher un comportement DOM arbitraire, ce qui rend son utilisation prévisible.

Les poignées impératives conviennent particulièrement bien aux boîtes de dialogue. Un composant Modal peut exposer les méthodes open et close, qui modifient son état de visibilité interne, afin qu’un parent puisse le contrôler impérativement sans gérer lui-même la valeur booléenne d’ouverture.

C’est pratique pour le code qui doit déclencher une boîte de dialogue depuis de nombreux endroits, par exemple pour afficher une confirmation après la fin d’une action asynchrone.

En ne renvoyant que les méthodes que vous avez l’intention de prendre en charge, vous créez un contrat clair. Les utilisateurs dépendent d’un petit ensemble documenté d’opérations plutôt que de l’API DOM très étendue, ce qui rend les refactorisations futures plus sûres.

Une surface impérative restreinte est plus facile à tester et à comprendre, et elle risque beaucoup moins de se rompre lorsque vous modifiez l’implémentation interne.

useImperativeHandle accepte un troisième argument facultatif : un tableau de dépendances. Lorsqu’une dépendance change, la fonction d’usine s’exécute de nouveau et l’objet poignée est recréé, comme avec useMemo et useEffect.

Si les méthodes que vous exposez capturent des valeurs susceptibles de changer, indiquez ces valeurs comme dépendances afin que le parent reçoive toujours une poignée liée à l’état actuel.

useImperativeHandle n’a de sens qu’au sein d’un composant encapsulé avec forwardRef, car il a besoin de la référence transmise pour y attacher la poignée personnalisée. Utilisé seul, il n’y aurait aucune référence de parent à renseigner.

Les deux outils s’utilisent donc ensemble : forwardRef fait entrer la référence et useImperativeHandle définit ce vers quoi cette référence finit par pointer.

Pour tester une poignée, affichez le composant avec une référence, puis appelez les méthodes via ref.current dans un bloc act et vérifiez le comportement obtenu ou les modifications du DOM.

Comme la surface exposée est restreinte et explicite, ces tests restent ciblés : ils vérifient que chaque méthode documentée respecte son contrat plutôt que d’examiner les détails internes.

Avec TypeScript, vous définissez une interface décrivant la poignée, par exemple une interface contenant les méthodes focus et clear, puis vous l’utilisez pour typer à la fois le type générique de forwardRef et la référence détenue par le parent.

Vous bénéficiez ainsi de la complétion automatique et de vérifications à la compilation au point d’appel : les utilisateurs voient exactement quelles méthodes existent et les mauvaises utilisations sont détectées avant l’exécution.

Confirmez à quoi sert réellement useImperativeHandle.

useImperativeHandle personnalise ce qu’une référence transmise expose en recevant la référence ainsi qu’une fonction d’usine qui renvoie un objet poignée. Vous l’utilisez pour exposer une petite API comme focus et clear, ou open et close sur une fenêtre modale.

Il est toujours associé à forwardRef, prend en charge un tableau de dépendances pour actualiser la poignée et s’associe bien aux interfaces TypeScript ainsi qu’aux tests ciblés. Une surface restreinte est un choix intentionnel et relève d’une bonne conception.