TouchList.item() — Methode · JavaScript-Referenz

Signatur

TouchList.prototype.item(index)

Beschreibung

TouchList.item() liefert einen einzelnen Berührungspunkt (Touch) aus einer TouchList. Solche Listen findet man in den Eigenschaften touches, targetTouches und changedTouches eines TouchEvent. Jeder Eintrag steht für einen Finger oder Stift, der den Bildschirm berührt.

Die Methode macht dasselbe wie der Zugriff über eckige Klammern (list[index]). Ein Unterschied besteht aber: Bei einem ungültigen Index gibt item() null zurück, der Klammerzugriff dagegen undefined. Die Indizes beginnen bei 0 und reichen bis list.length - 1.

Gebraucht wird item() vor allem bei Multitouch-Gesten wie Pinch-Zoom, Drehen oder Wischen mit zwei Fingern. Dort durchläuft man alle Berührungspunkte oder greift gezielt auf den ersten und zweiten Finger zu. Wichtig: Die Reihenfolge in der Liste ist nicht fest an einen bestimmten Finger gebunden. Um einen Finger über mehrere Events hinweg zu verfolgen, sollte man Touch.identifier verwenden.

Parameter

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

Rückgabewert

Typ

Touch | null

Beschreibung

Das Touch-Objekt am angegebenen Index oder null, wenn index >= list.length ist.

Beispiele

Ersten Berührungspunkt beim touchstart auslesen

const area = document.querySelector('#zeichenflaeche');

area.addEventListener('touchstart', (event) => {
  const ersterFinger = event.touches.item(0);
  if (ersterFinger) {
    console.log(`Start bei x=${ersterFinger.clientX}, y=${ersterFinger.clientY}`);
  }
}, { passive: true });

Start bei x=120, y=245

Alle geänderten Berührungspunkte durchlaufen

document.addEventListener('touchmove', (event) => {
  const list = event.changedTouches;
  for (let i = 0; i < list.length; i++) {
    const touch = list.item(i);
    console.log(`Finger ${touch.identifier}: ${touch.pageX}/${touch.pageY}`);
  }
}, { passive: true });

Finger 0: 310/512 Finger 1: 402/488

Pinch-Geste: Abstand zwischen zwei Fingern berechnen

const bild = document.querySelector('#bild');
let startAbstand = null;

const abstand = (list) => {
  const a = list.item(0);
  const b = list.item(1);
  if (!a || !b) return null; // weniger als zwei Finger
  return Math.hypot(b.clientX - a.clientX, b.clientY - a.clientY);
};

bild.addEventListener('touchstart', (e) => {
  startAbstand = abstand(e.touches);
});

bild.addEventListener('touchmove', (e) => {
  const aktuell = abstand(e.touches);
  if (startAbstand && aktuell) {
    e.preventDefault(); // natives Zoomen verhindern
    bild.style.transform = `scale(${(aktuell / startAbstand).toFixed(2)})`;
  }
}, { passive: false });

Unterschied zwischen item() und Klammerzugriff bei ungültigem Index

document.addEventListener('touchend', (event) => {
  const list = event.touches; // beim letzten Finger oft leer
  console.log(list.item(5));  // null
  console.log(list[5]);       // undefined
});

null undefined

// Wichtig · Fallstricke

Rückgabewert bei ungültigem Index: item() gibt null zurück, list[i] dagegen undefined. Prüfungen wie === undefined schlagen deshalb bei item() fehl. Am sichersten ist ein allgemeiner Falsy-Check oder der Vergleich mit length.
Negative Indizes: item(-1) liefert nicht das letzte Element. Der Wert wird in eine sehr große vorzeichenlose Zahl umgewandelt, das Ergebnis ist daher null. Für den Zugriff vom Ende her nutzt man list.item(list.length - 1).
Kein echtes Array: TouchList hat kein forEach, map usw. Sie ist aber iterierbar, Array.from(list) und for...of funktionieren also.
touchend: In touches fehlt der gerade abgehobene Finger. Er steht nur in changedTouches.
Kompatibilität: Touch Events gibt es in allen mobilen Browsern und in Chromium-basierten Desktop-Browsern. Desktop-Firefox und Desktop-Safari stellen sie ohne Touch-Hardware bzw. standardmäßig nicht bereit. Wer Maus, Stift und Touch einheitlich behandeln will, greift besser zu Pointer Events.
Performance: Rufen touchstart/touchmove-Handler kein preventDefault() auf, sollten sie mit { passive: true } registriert werden. Das hält das Scrollen flüssig.

Siehe auch

TouchList TouchList.length Touch TouchEvent TouchEvent.changedTouches Touch.identifier PointerEvent