Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Element.getBoundingClientRect(): dimensioni e posizione di un DOMRect

Misura il rettangolo di delimitazione di un elemento in pixel CSS e distingui le coordinate relative al viewport da quelle del documento.

Versione: ECMAScript 2024 and the current web platform; runtime support varies

Sintassi

const rect = element.getBoundingClientRect();
const { x, y, width, height, top, right, bottom, left } = rect;

element.getBoundingClientRect() non accetta argomenti e restituisce un DOMRect. È un’API Web, non fa parte di ECMAScript. Per misurare un elemento serve un ambiente che calcoli il layout del DOM; la disponibilità dipende dall’ambiente di esecuzione.

Per un elemento HTML, la misura si basa su rettangoli allineati agli assi che corrispondono ai suoi riquadri CSS fino al bordo esterno. Include il padding e i bordi, tiene conto delle trasformazioni CSS ed esclude i margini. Usa getClientRects() per ottenere i singoli rettangoli. Se l’elenco è vuoto, come con display: none, tutti i valori sono zero. Se ogni rettangolo ha larghezza o altezza pari a zero, il metodo restituisce il primo rettangolo dell’elenco. Altrimenti, restituisce il rettangolo più piccolo che racchiude tutti quelli dell’elenco, tranne quelli con entrambe le dimensioni pari a zero. Se un elemento inline si estende su più righe, il risultato può includere gli spazi tra i frammenti. Il rettangolo da solo non dimostra che l’elemento sia visibile.

width e height sono le dimensioni del rettangolo. In questo risultato, x e y coincidono con left e top; right è left + width e bottom è top + height. Le coordinate si misurano dall’angolo in alto a sinistra del viewport, non dal bordo più vicino, e possono essere negative. Tutti i valori sono espressi in pixel CSS e possono essere frazionari.

In un DOMRect, x, y, width e height sono modificabili; le coordinate dei bordi sono calcolate e di sola lettura. In un rettangolo creato manualmente con width o height negativi, x può differire da left o y da top. Modificare il risultato non cambia l’elemento. Il risultato è un’istantanea: ripeti la misura se ti servono valori aggiornati dopo lo scorrimento o una modifica del layout.

Per ottenere l’angolo in alto a sinistra nelle coordinate del documento, usa rect.left + window.scrollX e rect.top + window.scrollY, leggendo gli scostamenti al momento della misura. Questo cambia l’origine delle coordinate, ma non annulla lo scorrimento all’interno di un contenitore annidato.

Esempi

<!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>

Risultato

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

Salva l’esempio come file HTML, aprilo in un browser e leggi l’output nella console di sviluppo. Le dimensioni includono il padding su entrambi i lati di ciascun asse; l’elemento non ha un bordo. Dopo lo spostamento, il rettangolo precedente conserva il suo `x` originale; solo una nuova misura restituisce il nuovo `x`.

Lezioni correlate

  • JavaScript · Lezione 12 · Avanzato · Versione: 4

Fonti