Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Element.getBoundingClientRect(): dimensiones y posición de un DOMRect

Mide el rectángulo delimitador de un elemento en píxeles CSS y distingue las coordenadas de la ventana gráfica de las del documento.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

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

element.getBoundingClientRect() no recibe argumentos y devuelve un DOMRect. Es una API web, no forma parte de ECMAScript. La medición requiere un entorno que calcule la disposición del DOM; la disponibilidad depende del entorno de ejecución.

Para un elemento HTML, la medición se basa en rectángulos alineados con los ejes que corresponden a sus cajas CSS hasta el borde exterior. Incluye el relleno y los bordes, tiene en cuenta las transformaciones CSS y excluye los márgenes. Usa getClientRects() para obtener los rectángulos por separado. Si la lista está vacía, como con display: none, todos los valores son cero. Si cada rectángulo tiene anchura o altura cero, el método devuelve el primero de la lista. En caso contrario, devuelve el rectángulo más pequeño que abarca todos los de la lista, excepto los que tienen ambas dimensiones iguales a cero. Si un elemento en línea ocupa varias líneas, el resultado puede abarcar huecos entre fragmentos. El rectángulo por sí solo no demuestra que el elemento sea visible.

width y height son las dimensiones del rectángulo. En este resultado, x e y coinciden con left y top; right es left + width y bottom es top + height. Las coordenadas se miden desde la esquina superior izquierda de la ventana gráfica, no desde el borde más cercano, y pueden ser negativas. Todos los valores se expresan en píxeles CSS y pueden tener decimales.

En un DOMRect se pueden modificar x, y, width y height; las coordenadas de los bordes se calculan y son de solo lectura. En un rectángulo creado manualmente con width o height negativos, x puede diferir de left o y de top. Modificar el resultado no altera el elemento. El resultado es una instantánea: vuelve a medir si necesitas valores actualizados tras un cambio de disposición o un desplazamiento.

Para obtener la esquina superior izquierda en coordenadas del documento, usa rect.left + window.scrollX y rect.top + window.scrollY, leyendo los desplazamientos al medir. Esto cambia el origen de las coordenadas, pero no anula el desplazamiento dentro de un contenedor anidado.

Ejemplos

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

Resultado

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

Guarda el ejemplo como archivo HTML, ábrelo en un navegador y consulta la salida en la consola de desarrollo. Las dimensiones incluyen el relleno a ambos lados de cada eje; el elemento no tiene borde. Tras mover el elemento, el rectángulo anterior conserva su `x` original; solo una nueva medición devuelve el nuevo `x`.

Lecciones relacionadas

  • JavaScript · Lección 12 · Avanzado · Versión: 4

Fuentes