CKTIS / JavaScript
Element.getBoundingClientRect() : dimensions et position d’un DOMRect
Mesurez le rectangle englobant d’un élément en pixels CSS et distinguez les coordonnées de la zone d’affichage de celles du document.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
const rect = element.getBoundingClientRect();
const { x, y, width, height, top, right, bottom, left } = rect;element.getBoundingClientRect() ne prend aucun argument et renvoie un DOMRect. C’est une API Web, pas une fonctionnalité d’ECMAScript. La mesure exige un environnement capable de calculer la mise en page du DOM ; sa disponibilité dépend de l’environnement d’exécution.
Pour un élément HTML, la mesure repose sur des rectangles alignés sur les axes qui correspondent aux boîtes CSS jusqu’au bord extérieur de leur bordure. Elle inclut les marges intérieures et les bordures, tient compte des transformations CSS et exclut les marges extérieures. Utilisez getClientRects() pour obtenir les rectangles séparément. Si la liste est vide, par exemple avec display: none, toutes les valeurs sont nulles. Si chaque rectangle a une largeur ou une hauteur nulle, la méthode renvoie le premier rectangle de la liste. Sinon, elle renvoie le plus petit rectangle qui englobe tous ceux de la liste, à l’exception de ceux dont les deux dimensions sont nulles. Pour un élément en ligne réparti sur plusieurs lignes, le résultat peut couvrir les espaces entre les fragments. Le rectangle seul ne prouve pas que l’élément est visible.
width et height donnent les dimensions du rectangle. Dans ce résultat, x et y valent left et top ; right vaut left + width et bottom vaut top + height. Les coordonnées partent du coin supérieur gauche de la zone d’affichage, et non du bord le plus proche : elles peuvent donc être négatives. Toutes les valeurs sont en pixels CSS et peuvent être fractionnaires.
Sur un DOMRect, x, y, width et height sont modifiables ; les bords sont calculés et accessibles en lecture seule. Dans un rectangle créé manuellement avec une valeur négative pour width ou height, x peut différer de left, ou y de top. Modifier le résultat ne change pas l’élément. C’est un instantané : refaites la mesure après une modification de la mise en page ou un défilement si vous avez besoin de valeurs à jour.
Pour obtenir le coin supérieur gauche dans le repère du document, utilisez rect.left + window.scrollX et rect.top + window.scrollY, en lisant les décalages au moment de la mesure. Cela change l’origine des coordonnées sans annuler le défilement dans un conteneur imbriqué.
Exemples
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Measuring an element</title>
</head>
<body>
<script>
(() => {
const box = document.createElement('div');
box.style.cssText = 'position: fixed; left: 24.5px; top: 16px; margin: 0; box-sizing: content-box; width: 104px; height: 44px; padding: 8px; border: 0;';
document.body.append(box);
try {
const rect = box.getBoundingClientRect();
const { x, y, width, height, top, right, bottom, left } = rect;
console.log(`x=${x}, y=${y}, width=${width}, height=${height}, top=${top}, right=${right}, bottom=${bottom}, left=${left}`);
box.style.left = '44.5px';
console.log(`previous x=${rect.x}, current x=${box.getBoundingClientRect().x}`);
} finally {
box.remove();
}
})();
</script>
</body>
</html>Résultat
x=24.5, y=16, width=120, height=60, top=16, right=144.5, bottom=76, left=24.5 previous x=24.5, current x=44.5
Enregistrez l’exemple dans un fichier HTML, ouvrez-le dans un navigateur et consultez le résultat dans la console de développement. Les dimensions incluent la marge intérieure des deux côtés de chaque axe ; l’élément n’a pas de bordure. Après le déplacement, l’ancien rectangle conserve son `x` initial ; seule une nouvelle mesure donne le nouveau `x`.
Leçons associées
- JavaScript · Leçon 12 · Avancé · Version : 4