element.getBoundingClientRect

Cette traduction est en cours.

La méthode Element.getBoundingClientRect() retourne un objet DOMRect fournissant des informations sur la taille d'un élément et sa position relative par rapport à la zone d'affichage.

Syntaxe

objetRect = object.getBoundingClientRect();

Valeur de retour

La valeur de retour est un objet DOMRect qui est le plus petit rectangle contenant l'élément en entier, incluant sa zone de remplissage et la largeur de sa bordure. Les propriétés left, top, right, bottom, x, y, width, et height, décrivent la position et la taille du rectangle en pixels. Les propriétés autres que width et height sont relatives au coin en haut à gauche de la zone d'affichage.Schéma d'un élément dans sa zone de remplissage, décrivant les propriétés retournées par la méthode.

Les propriétés width et height de l'objet DOMRect retourné par la méthode incluent le padding et border-width, et non pas seulement la largeur/hauteur du contenu. Avec le modèle standard de boîte, cela correspondrait à la propriété width ou height de l'élément + padding + border-width. Mais si box-sizing: border-box est définit pour l'élément, cela correpondrait seulement width ou height.

La valeur retournée peut être conceptualisée comme l'union des rectangles retournés par getClientRects() pour l'élément, i.e. les boîtes de bordure CSS associées à l'élément.

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 alors un rectangle pour lequel width et height valent 0 et où 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.

La distance de défilement qui a été parcourue dans la zone d'affichage (ou n'importe quel élément que l'on peut faire défiler) est prise en compte pour calculer le rectangle de délimitation. Cela signifie que les côtés du rectangle de délimitation (top, right, bottom, left) change ses valeurs à chaque fois que la position de défilement change (parce que les valeurs sont relatives à la zone d'affichage et ne sont pas absolues).

Si vous avez besoin d'un rectangle de délimitation relatif au coin supérieur gauche du document, ajoutez simplement la position actuelle de défilement aux propriétés top et left (elles peuvent être obtenues en utilisant window.scrollX et window.scrollY) pour avoir un rectangle de délimitation indépendant de la position de défilement actuelle.

Solution de prise en charge multi-navigateurs

Les scripts qui doivent avoir une haute compatibilité pour l'ensemble des navigateurs peuvent 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

Ce simple exemple récupère l'objet DOMRect représentant le rectangle de délimitation dans le client d'un simple élément div, et affiche ses propriétés dessous.

<div></div>
div {
  width: 400px;
  height: 200px;
  padding: 20px;
  margin: 50px auto;
  background: purple;
}
let elem = document.querySelector('div');
let rect = elem.getBoundingClientRect();
for (var key in rect) {
  if(typeof rect[key] !== 'function') {
    let para = document.createElement('p');
    para.textContent  = `${ key } : ${ rect[key] }`;
    document.body.appendChild(para);
  }
}

Spécifications

Spécification État Commentaires
CSS Object Model (CSSOM) View Module
La définition de 'Element.getBoundingClientRect()' dans cette spécification.
Version de travail Définition initiale.

Notes

L'objet DOMRect retourné peut être modifié dans les navigateurs modernes. Cela n'était pas le cas avec ceux plus anciens qui retournaient effectivement DOMRectReadOnly. Dans IE et Edge, ne pas pouvoir ajouter les propriétés manquantes à l'objet ClientRect qu'ils retournent empêche d'ajouter le support de x et y.

En raison de problèmes de comptabilité (voir ci-dessous), il est plus sûr de se limiter aux propriétés topleft, right, et bottom.

Les propriétés dans l'objet DOMRect retourné ne sont pas possèdées pas ce dernier. Tandis que les opérateurs in et for...in vont trouver les propriétés retournées, les autres APIs comme Object.keys échoueront. De plus, et de façon inattendue, les fonctionnalités ES2015 et plus récentes telles que Object.assign() et les paramètres du reste / la décomposition d'un objet, ne réussiront pas à copier les propriétés retournées.

rect = elt.getBoundingClientRect()
// The result in emptyObj is {} 
emptyObj = Object.assign({}, rect)
emptyObj = { ...rect }
{ width, ...emptyObj } = rect

Les propriétés top, left, right, et bottom de DOMRect sont calculées en utilisant les valeurs des autres propriétés de l'objet.

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidFirefox pour AndroidOpera pour AndroidSafari sur iOSSamsung Internet
getBoundingClientRectChrome Support complet 2Edge Support complet 12Firefox Support complet 3IE Support complet 4Opera Support complet 9.5Safari Support complet 6WebView Android Support complet ≤37Chrome Android Support complet 18Firefox Android Support complet 4Opera Android Support complet 10.1Safari iOS Support complet 4
Notes
Support complet 4
Notes
Notes Safari for iOS will modify the effective viewport based on the user zoom. This results in incorrect values whenever the user has zoomed.
Samsung Internet Android Support complet 1.0
heightChrome Support complet OuiEdge Support complet 12Firefox Support complet 3.5IE Support complet 9Opera Support complet OuiSafari Support complet OuiWebView Android Support complet OuiChrome Android Support complet OuiFirefox Android ? Opera Android Support complet OuiSafari iOS Support complet OuiSamsung Internet Android Support complet Oui
widthChrome Support complet OuiEdge Support complet 12Firefox Support complet 3.5IE Support complet 9Opera Support complet OuiSafari Support complet OuiWebView Android Support complet OuiChrome Android Support complet OuiFirefox Android ? Opera Android Support complet OuiSafari iOS Support complet OuiSamsung Internet Android Support complet Oui
xChrome Support complet OuiEdge Support complet 79Firefox Support complet OuiIE Aucun support Non
Notes
Aucun support Non
Notes
Notes Returns a ClientRectList with ClientRect objects (which do not contain x and y properties) instead of DOMRect objects.
Opera Support complet OuiSafari Support complet 11WebView Android Support complet OuiChrome Android Support complet OuiFirefox Android ? Opera Android Support complet OuiSafari iOS Support complet 11Samsung Internet Android Support complet Oui
yChrome Support complet OuiEdge Support complet 79Firefox Support complet OuiIE Aucun support Non
Notes
Aucun support Non
Notes
Notes Returns a ClientRectList with ClientRect objects (which do not contain x and y properties) instead of DOMRect objects.
Opera Support complet OuiSafari Support complet 11WebView Android Support complet OuiChrome Android Support complet OuiFirefox Android ? Opera Android Support complet OuiSafari iOS Support complet 11Samsung Internet Android Support complet Oui

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Compatibilité inconnue  
Compatibilité inconnue
Voir les notes d'implémentation.
Voir les notes d'implémentation.

Voir aussi