element.getBoundingClientRect

La méthode Element.getBoundingClientRect() renvoie la taille d'un élément et sa position relative par rapport à la zone d'affichage (viewport).

Syntaxe

objetRect = object.getBoundingClientRect();

Valeur de retour

La valeur renvoyée par cette méthode est un objet DOMRect formé par l'union des rectangles renvoyés par la méthode getClientRects(). Autrement dit, cela correspond à la zone décrite par les boîtes de bordure associées à l'élément.

La valeur renvoyée est un objet DOMRect qui contient uniquement les propriétés left, top, right et bottom, en lecture seule, qui décrivent la boîte de bordure (border-box) en pixels. Les valeurs désignées par top et left sont relatives au coin en haut à gauche de la zone d'affichage.

Les boîtes de bordure vides sont complètement ignorées. Si toutes les boîtes de bordure associées à l'élément sont vides, la méthode renvoie un rectangle dont la largeur et la hauteur valent 0 et pour lequel top et left correspondent au coin en haut à gauche de la première boîte de bordure (dans l'ordre du contenu) de l'élément.

Le défilement (ou plutôt la quantité de défilement) est prise en compte dans le calcul du rectangle englobant. Ainsi, les valeurs des propriétés top et left sont modifiées dès que la position de défilement change (leurs valeurs sont donc relatives au viewport et ne sont pas exprimées de façon absolue). Si vous souhaitez obtenir des valeurs absolues, il suffit d'ajouter la position actuelle du défilement grâce à window.scrollX et window.scrollY afin d'obtenir des valeurs indépendantes de la position de défilement.

Pour les scripts qui doivent respecter certaines contraintes de compatibilité, il est possible d'utiliser window.pageXOffset et window.pageYOffset plutôt que window.scrollX et window.scrollY. Les scripts qui ne peuvent pas utiliser window.pageXOffset, window.pageYOffset, window.scrollX ou window.scrollY pourront utiliser cette méthode :

// Pour scrollX
(((t = document.documentElement) || (t = document.body.parentNode))
  && typeof t.ScrollLeft == 'number' ? t : document.body).ScrollLeft
// Pour scrollY
(((t = document.documentElement) || (t = document.body.parentNode))
  && typeof t.ScrollTop == 'number' ? t : document.body).ScrollTop

Exemple

// rect est un objet DOMRect avec 6 propriétés 
// left, top, right, bottom, width, height
var rect = obj.getBoundingClientRect();

Spécifications

Notes

• getBoundingClientRect() fut initialement introduit avec le modèle objet DHTML de MS IE.
• La valeur renvoyée par getBoundingClientRect() est gelée.

Compatibilité des navigateurs

[1] La spécification CSS pour l'élément use indique que l'élément symbol nécessite des valeurs par défaut de 100% pour width et height pour l'élément use. La spécification requiert que les attributs SVG width et height valent 100% par défaut. Google Chrome ne suit pas ces règles pour l'élément use. Chrome ne prend également pas en compte stroke-width. Pour cette raison, getBoundingClientRect() peut renvoyer des rectangles différents pour Chrome et Firefox.

[2] Pour IE8 et les versions antérieures, l'objet DOMRect qui était renvoyé par getBoundingClientRect() n'avait pas les propriétés height et width et on ne pouvait pas ajouter ces propriétés aux objets DOMRect.

[3] À partir de Gecko 12.0 (Firefox 12.0 / Thunderbird 12.0 / SeaMonkey 2.9), le calcul du rectangle englobant prend en compte les effets des transformations CSS.

Voir aussi

• MSDN: getBoundingClientRect Method
• getClientRects()