ResizeObserver
Appelle une fonction chaque fois que la taille d’un élément observé change, quelle qu’en soit la cause.
- Renvoie
- Un nouvel objet
ResizeObserver.
Exemple
#const panel = document.querySelector('#panel')
const observer = new ResizeObserver((entries) => {
for (const entry of entries) {
const border = Math.round(entry.borderBoxSize[0].inlineSize)
const content = Math.round(entry.contentRect.width)
console.log(`Panneau : ${border} px, contenu : ${content} px`)
}
})
observer.observe(panel)La première notification indique la taille juste après le début de l’observation. contentRect n’inclut pas le padding ni la bordure, c’est pourquoi il est plus étroit de 26 px. Faites glisser le coin inférieur droit du panneau dans l’aperçu, et la console affichera chaque changement.
Définition et utilisation
#ResizeObserver vous avertit quand la taille d’un élément précis change. L’événement resize sur window ne signale qu’un changement de la fenêtre, alors qu’un élément peut changer de taille pour d’autres raisons aussi : ajout de contenu, repli d’un panneau latéral ou changement de classe. L’observateur détecte chacun de ces cas.
La fonction de rappel reçoit un tableau d’objets ResizeObserverEntry. Le champ contentRect contient la largeur et la hauteur de la zone de contenu (sans le padding ni la bordure), tandis que borderBoxSize et contentBoxSize donnent les tailles sous forme de tableaux d’objets avec les champs inlineSize (la largeur, pour un texte horizontal normal) et blockSize (la hauteur).
Si l’élément est affiché, le premier appel a lieu juste après le début de l’observation, donc vous connaissez immédiatement la taille actuelle. La méthode observe() ajoute un élément, unobserve() le retire, et disconnect() met fin à l’observation. L’option box permet de choisir quelle taille suivre, par exemple { box: "border-box" }.
Faites attention à ne pas changer directement la taille de l’élément observé dans la fonction de rappel. La nouvelle taille ne peut plus être signalée dans la même image, donc le navigateur affiche l’erreur « ResizeObserver loop completed with undelivered notifications », et la notification n’arrive qu’à l’image suivante. Reportez ce genre de changement à plus tard, par exemple avec requestAnimationFrame().
Syntaxe
#new ResizeObserver(callback)
observer.observe(element)
observer.observe(element, { box })
observer.unobserve(element)
observer.disconnect()Paramètres
#callback
function (entries, observer)
La fonction appelée après un changement de taille. Elle reçoit un tableau d’entréesResizeObserverEntry.box
chaîne, optionnel (dans observe())
Quelle taille suivre :"content-box"(par défaut),"border-box"ou"device-pixel-content-box".
Plus d’exemples
#const card = document.querySelector('#card')
const nextWidths = ['300px', '200px']
const observer = new ResizeObserver(([entry]) => {
const width = Math.round(entry.borderBoxSize[0].inlineSize)
card.classList.toggle('wide', width >= 280)
console.log(`${width} px, mise en page large : ${card.classList.contains('wide')}`)
const next = nextWidths.shift()
if (next) {
setTimeout(() => {
card.style.width = next
})
}
})
observer.observe(card)Nous changeons la largeur automatiquement pour montrer d’autres notifications. Chaque changement est reporté avec setTimeout(), car changer la taille directement dans la fonction de rappel provoquerait une erreur de boucle. Dans une vraie application, la taille change par exemple après le repli d’un panneau latéral.
Compatibilité des navigateurs
#Largement disponible · depuis 2020
Fonctionne dans tous les navigateurs modernes, y compris sur mobile. Vous pouvez l’utiliser sans crainte.
- Chrome
- Edge
- Firefox
- Safari
Bonnes pratiques
#- Pour réagir à la taille d’un élément, préférez
ResizeObserverà l’événementresizesurwindow. Un élément peut changer de taille même si la fenêtre garde une taille fixe. - Dans la fonction de rappel, ne changez pas directement la taille de l’élément observé. Reportez le changement à l’image suivante, ou ne changez que ce qui n’affecte pas la taille, par exemple la couleur.
- S’il s’agit seulement d’adapter des styles à la largeur d’un conteneur, envisagez les container queries en CSS (
@container). JavaScript n’est alors pas nécessaire.
Entrées associées
#- IntersectionObserverObserve si un élément est visible dans la fenêtre ou dans un conteneur défilant, et appelle une fonction quand cela change.
- MutationObserverObserve les changements dans l’arbre du DOM : éléments ajoutés et supprimés, changements d’attributs et de texte, et les signale dans une seule fonction.
- Element.getBoundingClientRect()Renvoie la taille d’un élément et sa position par rapport à la zone visible de la fenêtre, sous la forme d’un objet DOMRect.
- requestAnimationFrame()Planifie l’appel d’une fonction juste avant le prochain rafraîchissement de l’écran. Sert à créer des animations fluides pilotées par JavaScript.
- Element.classListUn objet pour ajouter, retirer, basculer et vérifier les classes CSS d’un élément.
Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.