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

Voir aussi

• MSDN: getBoundingClientRect
• getClientRects()