Construire une API de composant impérative

Commencez par définir le contrat : un FocusableInput peut exposer les opérations de mise en focus, de perte de focus et getValue. Enveloppez-le dans forwardRef, conservez une référence interne vers le véritable champ de saisie, puis renvoyez ces trois méthodes depuis useImperativeHandle.

Chaque méthode délègue son appel au champ sous-jacent, afin que le composant parent dispose exactement des opérations dont il a besoin sans manipuler l’élément brut.

Un composant multimédia bénéficie grandement d’une API impérative. Un VideoPlayer peut exposer les opérations de lecture, de pause et seekTo, chacune déléguant son appel aux méthodes natives de l’élément vidéo HTML interne référencé.

seekTo accepte une durée en secondes et définit currentTime, ce qui donne aux composants parents un contrôle précis de la lecture, difficile à obtenir uniquement avec des propriétés.

Un carrousel peut exposer les opérations suivant, précédent et goToSlide afin que des commandes externes ou des gestionnaires de clavier puissent le piloter. En interne, ces méthodes mettent à jour l’état de l’indice actif, puis le composant effectue un nouveau rendu sur la nouvelle diapositive.

Cela associe des déclencheurs impératifs à un rendu déclaratif : le composant parent commande une transition, et le carrousel affiche le résultat via son flux d’état habituel.

Une référence impérative constitue un contrat public : documentez donc chaque méthode, ses paramètres et sa valeur de retour. Une documentation claire indique aux utilisateurs ce qui est pris en charge et les dissuade de dépendre d’éléments internes non documentés.

Traitez cette référence comme toute autre surface d’API : une courte référence listant des méthodes telles que lecture(), pause() et seekTo(secondes) évite les utilisations incorrectes et la confusion.

Dès que des utilisateurs dépendent d’une référence impérative, supprimer ou renommer une méthode constitue une modification incompatible. Ajoutez de nouvelles méthodes plutôt que de modifier les signatures existantes, et rendez progressivement obsolètes les anciennes avant de les supprimer.

Considérer cette référence comme une API versionnée empêche le code dépendant de se briser lorsque vous enrichissez le composant au fil du temps.

De nombreux composants réels combinent les deux styles. Un VideoPlayer peut accepter une propriété de source et une propriété autoPlay de manière déclarative, tout en exposant les opérations impératives de lecture et seekTo pour les situations que les propriétés expriment difficilement.

La règle consiste à utiliser les propriétés pour l’état et la configuration, et à réserver la référence impérative aux actions ponctuelles déclenchées à des moments précis.

Pour vérifier une API impérative, affichez le composant avec une référence, entourez les interactions de act et appelez les méthodes exposées via ref.current. Vérifiez ensuite le résultat observable, par exemple que la vidéo est en pause ou que l’indice de la diapositive a changé.

Un rappel de référence peut capturer la référence pendant le rendu, afin que votre vérification dispose d’une référence stable sur laquelle appeler les méthodes.

Storybook est un bon endroit pour démontrer les références impératives. Un récit peut conserver une référence vers le composant et afficher des boutons qui appellent ses méthodes, afin de permettre aux réviseurs d’essayer interactivement la lecture, la pause ou goToSlide.

Ces récits servent également de documentation vivante et montrent précisément le comportement de l’API impérative de manière isolée.

Les références impératives sont courantes lorsqu’on encapsule des bibliothèques qui ne reposent pas sur React. Les bibliothèques de graphiques exposent des méthodes de redessin ou de mise à jour, les SDK cartographiques exposent panTo et setZoom, et les éditeurs de texte enrichi exposent insertText ou getContents.

Encapsuler une telle bibliothèque dans un composant React et en exposer une référence claire donne au reste de votre application un moyen propre et idiomatique de la piloter.

Les méthodes d’une référence capturent souvent l’état actuel dans leur fermeture. Utilisez donc le tableau de dépendances de useImperativeHandle pour les actualiser lorsque cela est nécessaire, et useCallback pour les fonctions auxiliaires internes afin d’éviter les fermetures obsolètes.

Une référence bien gérée fonctionne toujours avec des valeurs à jour : un composant parent qui appelle getValue ou seekTo obtient ainsi un comportement cohérent avec le rendu le plus récent.

Appliquez la règle de conception des API impératives de composants.

Vous avez conçu des références pour un FocusableInput, un VideoPlayer et un carrousel, chacun exposant un petit ensemble de méthodes d’action. Documentez et versionnez ces méthodes, car les utilisateurs en dépendent comme d’une API publique.

Associez les actions impératives aux propriétés déclaratives, vérifiez via ref.current dans act et présentez le comportement dans Storybook. Le même modèle encapsule proprement les bibliothèques de graphiques, de cartes et d’éditeurs.