Les Refs expliquées : Comment les frameworks gèrent l'accès direct au DOM
Les frameworks frontend modernes promettent un monde déclaratif où vous décrivez à quoi l’interface utilisateur devrait ressembler, et le framework s’occupe du reste. Mais parfois, vous devez sortir de ce modèle et toucher directement le DOM réel. C’est là qu’interviennent les refs DOM.
Que vous travailliez avec les refs React, les template refs Vue, l’ElementRef d’Angular ou le bind:this de Svelte, chaque framework majeur fournit une échappatoire pour l’accès direct au DOM. Comprendre quand et comment utiliser ces outils—sans briser les garanties du framework—distingue les développeurs compétents de ceux qui créent des problèmes subtils et difficiles à déboguer.
Points clés à retenir
- Les refs fournissent des échappatoires contrôlées pour l’accès direct au DOM lorsque les patterns déclaratifs sont insuffisants
- Les cas d’usage courants incluent la gestion du focus, le défilement, la mesure de mise en page et l’intégration de bibliothèques tierces
- Chaque framework implémente les refs différemment : React utilise des objets ref mutables, Vue utilise les template refs avec
defineExpose(), Angular fournitElementRefetRenderer2, et Svelte utilisebind:this - Les refs n’existent que côté client après le montage—protégez toujours l’accès avec des vérifications de cycle de vie pendant le SSR
Pourquoi les frameworks fournissent des refs
Les frameworks gèrent le DOM à travers des couches d’abstraction. React et Vue utilisent un DOM virtuel. Angular utilise la détection de changements. Svelte compile complètement le framework. Ces abstractions permettent des mises à jour efficaces, mais elles signifient également que le framework possède la structure du DOM.
L’accès direct au DOM devient nécessaire lorsque les patterns déclaratifs sont insuffisants. Le navigateur fournit des API qui ne peuvent tout simplement pas être exprimées comme des mappages état-vers-UI.
Cas d’usage courants pour l’accès direct au DOM
La gestion du focus arrive en tête de liste. Appeler .focus() sur un élément input nécessite une référence à cet élément. Aucune manipulation d’état ne déplacera le curseur dans un champ de texte.
Le défilement présente des défis similaires. Faire défiler programmatiquement vers un élément ou une position spécifique nécessite des appels DOM impératifs.
La mesure de mise en page exige un accès direct. Vous ne pouvez pas connaître les dimensions ou la position d’un élément tant qu’il n’existe pas dans le DOM. Lire getBoundingClientRect() ou intégrer avec ResizeObserver et IntersectionObserver nécessite une référence de nœud réel.
L’intégration de bibliothèques tierces nécessite souvent des refs. Des bibliothèques comme D3, des lecteurs vidéo ou des outils basés sur canvas attendent des nœuds DOM qu’ils peuvent manipuler directement.
Le compromis fondamental
Les refs brisent le modèle déclaratif. Lorsque vous saisissez un nœud DOM et le manipulez directement, vous travaillez en dehors de la connaissance du framework. Cela crée un couplage fort entre votre code et la structure rendue.
Utilisez les refs avec parcimonie. Si vous vous retrouvez à utiliser une ref pour résoudre un problème qui pourrait être géré via l’état ou les props, reconsidérez. Les refs doivent rester une échappatoire, pas un outil principal.
Discover how at OpenReplay.com.
Implémentations spécifiques aux frameworks
Les refs React
Dans React 19, les refs peuvent être passées comme props normales aux composants fonction. Le wrapper forwardRef n’est plus obligatoire pour la plupart des cas d’usage, simplifiant considérablement la composition de composants.
Dans React 19, les callback refs peuvent retourner des fonctions de nettoyage, vous permettant de détacher des écouteurs d’événements ou d’effectuer un nettoyage lorsque l’élément se démonte (les anciennes refs reçoivent toujours null pour la rétrocompatibilité). Notez que le mode strict peut invoquer les callbacks de ref plus d’une fois pendant le développement—votre code doit gérer cela avec élégance.
Les refs React sont des conteneurs mutables. Changer .current ne déclenche pas de re-rendus, ce qui les rend idéales pour stocker des références DOM sans causer de cycles de mise à jour.
Les template refs Vue
Vue expose les refs via l’attribut ref dans les templates. Dans la Composition API, vous créez une ref avec ref(null) et accédez à l’élément après le montage.
Vue encourage l’exposition explicite des éléments internes du composant via defineExpose(). Cela empêche le couplage accidentel aux détails d’implémentation tout en permettant un accès contrôlé lorsque nécessaire.
L’ElementRef d’Angular
Angular fournit ElementRef et Renderer2 pour l’accès au DOM. La documentation les qualifie explicitement d’outils de dernier recours. Utiliser ElementRef ne rend pas automatiquement l’accès au DOM “sûr”—vous contournez toujours les abstractions d’Angular. Renderer2 aide principalement à l’abstraction de plateforme (comme le SSR), pas à la sécurité.
Privilégiez les directives et bindings intégrés d’Angular autant que possible. Réservez ElementRef aux cas où aucune alternative déclarative n’existe.
Le bind:this de Svelte
Svelte utilise bind:this pour capturer les références d’éléments. Le binding se remplit après le montage du composant, ce qui signifie que vous ne pouvez pas accéder à l’élément pendant l’exécution initiale du script.
L’accès au DOM dans Svelte se produit uniquement côté client après le montage, généralement via onMount ou $effect (Svelte 5). Le rendu côté serveur produit du HTML sans exécuter les bindings côté client, donc les refs restent undefined jusqu’à ce que l’hydratation soit terminée.
SSR et timing d’hydratation
Dans tous les frameworks, les refs n’existent que côté client après le montage. Pendant le rendu côté serveur, il n’y a pas de DOM—seulement des chaînes HTML. Votre code doit en tenir compte.
Protégez l’accès aux refs avec des vérifications de cycle de vie. Dans React, accédez aux refs dans les effets. Dans Vue, utilisez onMounted. Dans Svelte, utilisez onMount ou des déclarations réactives qui s’exécutent après l’hydratation. Tenter d’accéder aux refs pendant le SSR donnera des valeurs undefined ou des erreurs.
Quand utiliser les refs
Demandez-vous : cela peut-il être résolu de manière déclarative ? Si oui, évitez la ref. Si l’API du navigateur nécessite véritablement un nœud DOM—focus, scroll, mesure ou intégration—alors les refs sont le bon outil.
Gardez l’utilisation des refs isolée. Encapsulez la logique impérative dans des hooks personnalisés ou des composables. Cela contient le couplage et rend l’échappatoire explicite pour les autres développeurs lisant votre code.
Conclusion
Les refs ne sont ni dépréciées ni découragées. Elles font délibérément partie de la conception de chaque framework. Utilisez-les intentionnellement, comprenez leurs compromis, et vos applications resteront maintenables tout en accédant à la pleine puissance de la plateforme navigateur.
FAQ
Techniquement oui, mais vous devriez l'éviter. Manipuler directement les styles ou le contenu contourne le cycle de rendu du framework, ce qui peut entraîner des incohérences entre l'état de votre composant et le DOM réel. Utilisez plutôt des mises à jour de styles et de contenu pilotées par l'état. Réservez les refs aux opérations qui nécessitent vraiment un nœud DOM, comme le focus, le scroll ou la mesure.
Les refs se remplissent uniquement après le montage du composant. Si vous accédez à une ref pendant le rendu initial ou lors du rendu côté serveur, elle sera null ou undefined. Protégez toujours l'accès aux refs avec des hooks de cycle de vie comme useEffect dans React, onMounted dans Vue, ou onMount dans Svelte pour vous assurer que l'élément DOM existe avant d'interagir avec lui.
Généralement non. Les refs créent un couplage fort entre les composants et contournent le flux de données standard. Privilégiez les props et callbacks pour la communication parent-enfant. Utilisez les refs uniquement lorsque vous avez besoin d'un accès direct au DOM, comme déclencher le focus ou le scroll sur un élément enfant. Dans Vue, utilisez defineExpose pour contrôler ce qu'un composant enfant révèle.
Le concept est similaire, mais les implémentations diffèrent. React utilise des objets ref mutables avec une propriété current. Vue utilise des template refs accessibles via la Composition API. Angular fournit ElementRef et Renderer2. Svelte utilise des directives bind:this. Chaque approche reflète l'architecture du framework, donc consultez la documentation spécifique au framework pour une utilisation correcte.
Gain Debugging Superpowers
Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.
