Document.createTouchList() — Methode · JavaScript-Referenz

Signatur

Document.prototype.createTouchList(...touches)

Beschreibung

document.createTouchList() fasst einzelne Touch-Objekte (Berührungspunkte) zu einer TouchList zusammen. Eine solche Liste braucht man vor allem, wenn man ein TouchEvent selbst erzeugen möchte, zum Beispiel für automatisierte Tests von Wisch- oder Multitouch-Gesten, ohne ein echtes Touch-Gerät zu verwenden.

Früher ging man dafür so vor: Mit document.createTouch() wurden die Berührungspunkte erzeugt, mit document.createTouchList() zu Listen zusammengefasst und diese Listen dann an TouchEvent.initTouchEvent() übergeben. Alle drei APIs sind heute veraltet.

In modernem Code nutzt man stattdessen den Konstruktor new Touch({...}) und übergibt einfache Arrays an new TouchEvent(type, { touches, targetTouches, changedTouches }). Der Konstruktor wandelt die Arrays intern in TouchList-Objekte um. createTouchList() ist deshalb nur noch für älteren Code oder für alte WebKit-Umgebungen von Bedeutung.

Parameter

Name	Typ	Default	Beschreibung
$touches	Touch \| Touch[]		Null oder mehr `Touch`-Objekte, als einzelne Argumente oder (in manchen Umsetzungen) als Array übergeben. Ohne Argument entsteht eine leere `TouchList`.

Rückgabewert

Typ

TouchList

Beschreibung

Eine neue TouchList mit den übergebenen Touch-Objekten in derselben Reihenfolge.

Beispiele

Vorab prüfen, ob die Methode existiert

// Vor der Nutzung immer prüfen – in Chrome und Firefox fehlt die Methode meist
const hatTouchList = typeof document.createTouchList === 'function';
console.log(hatTouchList ? 'createTouchList verfügbar' : 'Nicht verfügbar – Touch/TouchEvent-Konstruktor nutzen');

Nicht verfügbar – Touch/TouchEvent-Konstruktor nutzen

Alter Weg: TouchList aus createTouch() erstellen

// Nur in Umgebungen, die die veralteten Methoden noch haben (z. B. ältere Safari-Versionen)
const ziel = document.querySelector('#spielfeld');

if (document.createTouch && document.createTouchList) {
  // Parameter: view, target, identifier, pageX, pageY, screenX, screenY
  const t1 = document.createTouch(window, ziel, 1, 100, 150, 100, 150);
  const t2 = document.createTouch(window, ziel, 2, 200, 150, 200, 150);

  const liste = document.createTouchList(t1, t2);
  console.log(liste.length, liste.item(0).identifier);
}

2 1

Moderne Alternative: Touch- und TouchEvent-Konstruktor

// Wischgeste in einem Test simulieren – ohne createTouchList()
const ziel = document.querySelector('#spielfeld');

const erzeugeTouch = (id, x, y) => new Touch({
  identifier: id,
  target: ziel,
  clientX: x,
  clientY: y,
  pageX: x,
  pageY: y
});

const start = erzeugeTouch(1, 50, 100);
ziel.dispatchEvent(new TouchEvent('touchstart', {
  bubbles: true,
  cancelable: true,
  touches: [start],        // Arrays werden intern zu TouchList
  targetTouches: [start],
  changedTouches: [start]
}));

ziel.addEventListener('touchstart', (e) => {
  console.log(e.touches instanceof TouchList, e.touches.length);
}, { once: true });

ziel.dispatchEvent(new TouchEvent('touchstart', { touches: [start], changedTouches: [start] }));

true 1

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Chrome (ab Version 68) und Firefox haben die Methode entfernt bzw. nie standardmäßig aktiviert. Sie ist noch in WebKit/Safari vorhanden. Neuer Code sollte sie nicht verwenden.
Als Ersatz dienen new Touch() und new TouchEvent() mit Arrays für touches, targetTouches und changedTouches.
Ein selbst erzeugtes Touch-Event hat isTrusted === false. Aktionen, die eine echte Nutzerinteraktion voraussetzen (z. B. Vollbild oder Pop-ups), werden dadurch nicht ausgelöst.
Der Touch-Konstruktor ist in Desktop-Safari teilweise nicht vorhanden. In Tests deshalb vorab prüfen, ob er existiert, oder auf PointerEvent ausweichen.
Für echte Anwendungen sind Pointer Events meist die bessere Wahl, weil sie Maus, Stift und Touch einheitlich abdecken.

Siehe auch

Touch Document.createTouch() Document.createComment() Document.createElement() Document.createEvent()