Element.getBoundingClientRect()

Metoda Element.getBoundingClientRect() zwraca rozmiar  oraz  położenie elementu względem okna widoku (viewport).

Syntaks

rectObject = object.getBoundingClientRect();

Wynik

Zwrócony  jest obiekt DOMRect,  wyznaczony z tablicy prostokątów zwróconych przez  metodę getClientRects(), zastosowaną do danego elementu, czyli wyznaczony ze wszystkich pudełek  CSS związanych z danym elementem.

Zwrócony obiekt  DOMRect posiada następujące (tylko do odczytu) właściwości: left, top, right and bottom,  opisujące parametry otaczającego element pudełka w  pikselach. Właściwości top and left  oznaczają odległość od górnego-lewego rogu aktualnego okna widoku.

Puste pudełka są całkowicie ignorowane. Jeśli wszystkie elementy pudełka są puste, to zwrócony prostokąt ma wysokość i szerokość równą zero zaś własności top oraz left dotyczą pierwszego pudełka CSS (w porządku kontekstowym) który zawiera dany element.

Efekt przewijania (scrolling) okna widoku  (lub dowolnego innego przewijalnego elementu) jest uwzględniany podczas wyznaczania otaczającego pudełka. Zatem, właściwości top and left zmieniają się natychmiast po dowolnym przewinięciu (są więc względne w stosunku do widoku, a więc nie są absolutne). W celu wyznaczenia absolutnego położenie elementu  należy do właściwości top oraz left dodać aktualne pozycje przesuwania (scrolling position)  (można je uzyskać za  pomocą window.scrollX and window.scrollY).

Skrypty wymagające  zgodności z różnymi przeglądarkami mogą korzystać z metod  window.pageXOffset oraz window.pageYOffset zamiast window.scrollX and window.scrollY. Skrypty które nie mają dostępu do  window.pageXOffset, window.pageYOffset, window.scrollX ani window.scrollY mogą stosować następujący kod :

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

Przykład

// rect jest obiektem DOMRect z sześcioma własnościami: left, top, right, bottom, width, height
var rect = obj.getBoundingClientRect();

Specyfikacja

Uwagi

Metoda getBoundingClientRect() została wprowadzona po raz pierwszy w  modelu MS IE DHTML.

Wynik metody getBoundingClientRect() jest  obiektem zamrożonym.

Zgodność z przeglądarkami

[1] specyfikacja CSS dla elementu 'use'  wskazującego na element  'symbol' wymaga aby domyślne wartości atrybutów  width oraz height elementu 'use' ustawione były na 100%. Również,  specyfikacja CSS dla atrybutów width oraz height elementu 'svg' wymaga 100%  jako wartości domyślne. Google Chrome nie przestrzega tych wymagań dla elementów  'use'. Chrome nie uwzględnia również  'stroke-width'. Zatem metoda   getBoundingClientRect() może zwrócić inny prostokąt w  Chrome  niż w Firefox.

[2] W IE8, oraz we wcześniejszych wersjach, obiekt  DOMRect zwrócony przez getBoundingClientRect() nie zawiera właściwości height ani width. Żadne dodatkowe właściwości (w tym height oraz width) nie mogą być dodane do tych obiektów DOMRect.

Począwszy od Gecko 12.0 (Firefox 12.0 / Thunderbird 12.0 / SeaMonkey 2.9), efekt  transformacji CSS jest uwzględniany w algorytmie wyznaczania otaczającego pudełka (bounding rectangle).

Patrz również

• MSDN: getBoundingClientRect Method
• getClientRects()