TouchList — Schnittstelle · JavaScript-Referenz

Signatur

interface TouchList

Beschreibung

TouchList ist eine Liste von Touch-Objekten. Jedes davon steht für einen Finger oder Stift auf einer Berührungsoberfläche. Selbst erzeugt man keine TouchList. Man bekommt sie über die drei Eigenschaften eines TouchEvent: touches, targetTouches und changedTouches.

touches: alle Kontaktpunkte, die gerade die Oberfläche berühren, egal auf welchem Element.
targetTouches: nur die Kontaktpunkte, die auf dem Ziel-Element des Events begonnen haben.
changedTouches: die Kontaktpunkte, die dieses Event ausgelöst haben, zum Beispiel neu aufgesetzte Finger bei touchstart oder angehobene Finger bei touchend.

Das Interface hat nur die Eigenschaft length und die Methode item(index). Außerdem kann man per Index zugreifen (list[0]) und die Liste iterieren (for...of, Array.from()). Die Liste ist nicht „live“: Sie gibt den Zustand zum Zeitpunkt des Events wieder.

Man braucht TouchList für Multitouch-Gesten wie Pinch-Zoom oder Zwei-Finger-Wischen, für Zeichenflächen und für eigene Wischgesten. Für neue Projekte, die Maus, Stift und Touch einheitlich behandeln sollen, sind oft die Pointer Events die bessere Wahl.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Nur bei `item(index)`: nullbasierter Index des gewünschten `Touch`-Objekts.

Rückgabewert

Typ

Touch | null

Beschreibung

item(index) gibt das Touch-Objekt am Index zurück, bei ungültigem Index null. length liefert die Anzahl der Einträge als number.

Beispiele

Aktive Finger zählen (touchstart)

const area = document.querySelector('#touch-area');

const onStart = (event) => {
  // touches enthält alle aktuell aufliegenden Finger
  console.log(`Aktive Finger: ${event.touches.length}`);
  const first = event.touches.item(0);
  console.log(`Erster Finger bei ${first.clientX}/${first.clientY}`);
};

area.addEventListener('touchstart', onStart, { passive: true });

// Später wieder entfernen
// area.removeEventListener('touchstart', onStart);

Aktive Finger: 1 Erster Finger bei 120/245

Pinch-Geste: Abstand zweier Finger berechnen

const box = document.querySelector('#zoom-box');
let startDistance = 0;

const distance = (list) => {
  const [a, b] = list; // TouchList ist iterierbar
  return Math.hypot(b.clientX - a.clientX, b.clientY - a.clientY);
};

box.addEventListener('touchstart', (e) => {
  if (e.touches.length === 2) startDistance = distance(e.touches);
});

box.addEventListener('touchmove', (e) => {
  if (e.touches.length !== 2) return;
  e.preventDefault(); // Browser-Zoom verhindern
  const scale = distance(e.touches) / startDistance;
  box.style.transform = `scale(${scale.toFixed(2)})`;
}, { passive: false });

Beendete Kontakte über changedTouches verfolgen

const ongoing = new Map();

document.addEventListener('touchstart', (e) => {
  for (const t of e.changedTouches) {
    ongoing.set(t.identifier, { x: t.clientX, y: t.clientY });
  }
});

document.addEventListener('touchend', (e) => {
  // touches enthält die angehobenen Finger nicht mehr, changedTouches schon
  Array.from(e.changedTouches).forEach((t) => {
    const start = ongoing.get(t.identifier);
    const dx = t.clientX - start.x;
    console.log(`Finger ${t.identifier}: ${dx > 50 ? 'Wisch nach rechts' : 'Tipp'}`);
    ongoing.delete(t.identifier);
  });
});

Finger 0: Wisch nach rechts

// Wichtig · Fallstricke

Kein echtes Array: map, filter usw. fehlen. Vorher mit Array.from(list) oder [...list] umwandeln.
touchend: Dort sind touches und targetTouches oft leer. Die angehobenen Finger stehen nur in changedTouches.
Reihenfolge nicht stabil: Die Reihenfolge in der Liste kann sich zwischen Events ändern. Einzelne Finger daher über Touch.identifier verfolgen, nicht über den Index.
Passive Listener: Chrome und andere Browser behandeln touchstart/touchmove auf window, document und body standardmäßig als passiv. preventDefault() wirkt dort nur mit { passive: false }. Alternativ die CSS-Eigenschaft touch-action verwenden.
Kompatibilität: Unterstützt in allen mobilen Browsern und in Chrome, Edge und Firefox. Auf reinen Desktop-Geräten ohne Touchscreen feuern keine Touch-Events, und Desktop-Safari unterstützt sie gar nicht. Für Eingaben über alle Gerätearten hinweg besser Pointer Events verwenden. Feature-Erkennung: 'ontouchstart' in window.

Siehe auch

Touch TouchList.item() TouchList.length Array.from() NodeList