DOMRectList.item() — Methode · JavaScript-Referenz

Signatur

DOMRectList.prototype.item(index)

Beschreibung

Die Methode item() liest ein einzelnes Rechteck aus einer DOMRectList. Solche Listen bekommt man vor allem von Element.prototype.getClientRects() und Range.prototype.getClientRects(). Jedes Rechteck steht für einen Layout-Kasten, zum Beispiel für eine Zeile eines umbrochenen Inline-Elements oder für einen Teil einer Textauswahl.

list.item(i) macht fast dasselbe wie die Index-Schreibweise list[i]. Der Unterschied liegt bei ungültigen Indizes: item() gibt dann null zurück, die eckigen Klammern liefern undefined. Mit item() lässt sich also eindeutig auf null prüfen.

In der Praxis braucht man item() etwa, um die Position der ersten oder letzten Zeile eines Textabschnitts zu bestimmen. Damit lassen sich Tooltips oder Popover an einer Textauswahl ausrichten oder Hervorhebungen über umbrochenen Links zeichnen. Die Koordinaten beziehen sich immer auf den Viewport, also den sichtbaren Bereich des Fensters.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nullbasierter Index des gewünschten Rechtecks. Der Wert wird in eine vorzeichenlose 32-Bit-Ganzzahl umgewandelt (`unsigned long`).

Rückgabewert

Typ

DOMRect | null

Beschreibung

Das DOMRect an Position index oder null, wenn index >= list.length.

Beispiele

Erste und letzte Zeile eines umbrochenen Links

const link = document.querySelector('a.long-link');
const rects = link.getClientRects();

const first = rects.item(0);
const last = rects.item(rects.length - 1);

if (first && last) {
  console.log(`Zeilen: ${rects.length}`);
  console.log(`Start: ${first.left}px / ${first.top}px`);
  console.log(`Ende: ${last.right}px / ${last.bottom}px`);
}

Zeilen: 2 Start: 120px / 340px Ende: 85px / 378px

Tooltip am Ende einer Textauswahl platzieren

const tooltip = document.getElementById('selection-tooltip');

document.addEventListener('mouseup', () => {
  const selection = window.getSelection();
  if (!selection || selection.rangeCount === 0 || selection.isCollapsed) {
    tooltip.hidden = true;
    return;
  }

  const rects = selection.getRangeAt(0).getClientRects();
  const lastRect = rects.item(rects.length - 1);
  if (!lastRect) return;

  tooltip.style.left = `${lastRect.right + window.scrollX}px`;
  tooltip.style.top = `${lastRect.bottom + window.scrollY + 4}px`;
  tooltip.hidden = false;
});

Unterschied zwischen item() und Index-Zugriff

const span = document.createElement('span');
span.textContent = 'Hallo';
document.body.append(span);

const rects = span.getClientRects();
console.log(rects.length);        // 1
console.log(rects.item(0) instanceof DOMRect);
console.log(rects.item(5));       // außerhalb des Bereichs
console.log(rects[5]);            // Index-Schreibweise

1 true null undefined

// Wichtig · Fallstricke

Kein Array: DOMRectList hat weder map() noch forEach(). Sie ist aber iterierbar, darum funktionieren for...of und Array.from(list).
Negative Indizes: item(-1) liefert nicht das letzte Element. Der Wert wird in eine sehr große vorzeichenlose Zahl umgewandelt, das Ergebnis ist null. Fürs letzte Element also item(list.length - 1) verwenden.
Momentaufnahme: Die Liste wird beim Aufruf von getClientRects() erzeugt und später nicht aktualisiert. Nach Scrollen, Größenänderung oder DOM-Änderungen muss man sie neu abfragen.
Leere Listen: Elemente mit display: none oder ohne Layout-Kasten liefern eine leere Liste. item(0) gibt dann null zurück, deshalb vorher auf null prüfen.
Performance: getClientRects() kann ein erzwungenes Layout (Reflow) auslösen. In Schleifen oder Scroll-Handlern Aufrufe bündeln oder mit requestAnimationFrame takten.
Kompatibilität: Wird von allen modernen Browsern unterstützt. DOMRectList gilt als Altlast-Interface und bleibt aus Kompatibilitätsgründen erhalten.

Siehe auch

DOMRectList DOMRectList.length DOMRect Element.getClientRects() Range.getClientRects() Element.getBoundingClientRect() CSSRuleList.item()