Document.createTouch() — Methode · JavaScript-Referenz

Signatur

Document.prototype.createTouch(view, target, identifier, pageX, pageY, screenX, screenY)

Beschreibung

document.createTouch() ist eine alte Fabrikmethode aus der frühen Touch-Events-Spezifikation. Sie erzeugt ein Touch-Objekt, also einen einzelnen Kontaktpunkt (Finger oder Stift) auf einer berührungsempfindlichen Fläche. Solche Objekte werden meist mit document.createTouchList() zu einer TouchList zusammengefasst und anschließend in ein synthetisches TouchEvent eingebaut.

Der typische Einsatzzweck ist das Simulieren von Touch-Gesten, zum Beispiel in automatisierten Tests, bei der Entwicklung von Wisch-Komponenten oder in Polyfills. Für echte Nutzereingaben braucht man die Methode nicht, denn der Browser erzeugt die Touch-Objekte dann selbst.

Die Methode wurde aus dem aktuellen Standard gestrichen. Der moderne Ersatz ist der Konstruktor new Touch({ identifier, target, clientX, clientY, ... }) zusammen mit new TouchEvent(type, { touches, targetTouches, changedTouches }). Neuer Code sollte createTouch() höchstens als Rückfalllösung nach vorheriger Funktionsprüfung verwenden.

Parameter

Name	Typ	Beschreibung
$view Pflicht	Window	Das Fenster, in dem die Berührung stattfindet, meist `window`.
$target Pflicht	EventTarget	Das Element, auf dem die Berührung begonnen hat. Es wird später als `Touch.target` geliefert.
$identifier Pflicht	number	Eindeutige ID des Kontaktpunkts. Solange derselbe Finger aufliegt, muss sie gleich bleiben.
$pageX Pflicht	number	Horizontale Position relativ zum Dokument, einschließlich Scroll-Versatz.
$pageY Pflicht	number	Vertikale Position relativ zum Dokument, einschließlich Scroll-Versatz.
$screenX Pflicht	number	Horizontale Position relativ zum Bildschirm.
$screenY Pflicht	number	Vertikale Position relativ zum Bildschirm.

Rückgabewert

Typ

Touch

Beschreibung

Ein neues Touch-Objekt mit den übergebenen Werten. Nicht übergebene Werte wie clientX/clientY berechnet der Browser je nach Implementierung selbst oder setzt sie auf 0.

Beispiele

Touch-Objekt mit Funktionsprüfung und modernem Rückfallweg erzeugen

const el = document.querySelector('#slider');

const makeTouch = (target, id, x, y) => {
  // Moderner Weg: Touch-Konstruktor
  if (typeof Touch === 'function') {
    try {
      return new Touch({
        identifier: id,
        target,
        clientX: x,
        clientY: y,
        pageX: x + window.scrollX,
        pageY: y + window.scrollY,
        screenX: x,
        screenY: y
      });
    } catch (e) {
      // Konstruktor nicht erlaubt (z. B. ältere WebKit-Versionen)
    }
  }
  // Veralteter Weg
  if (typeof document.createTouch === 'function') {
    return document.createTouch(window, target, id,
      x + window.scrollX, y + window.scrollY, x, y);
  }
  throw new Error('Touch-Objekte werden nicht unterstützt');
};

const touch = makeTouch(el, 1, 120, 40);
console.log(touch.identifier, touch.target === el);

1 true

Wischgeste für einen Test simulieren (klassischer Weg)

const target = document.querySelector('#carousel');

const fireTouch = (type, x, y) => {
  const touch = document.createTouch(window, target, 0, x, y, x, y);
  const list = document.createTouchList(touch);
  const event = document.createEvent('TouchEvent');
  // Reihenfolge der Argumente entspricht der alten WebKit-Implementierung
  event.initTouchEvent(type, true, true, window, 0, x, y, x, y,
    false, false, false, false,
    type === 'touchend' ? document.createTouchList() : list,
    type === 'touchend' ? document.createTouchList() : list,
    list, 1, 0);
  target.dispatchEvent(event);
};

target.addEventListener('touchend', () => console.log('Wischen beendet'));

fireTouch('touchstart', 300, 100);
fireTouch('touchmove', 150, 100);
fireTouch('touchend', 50, 100);

Wischen beendet

Moderner Ersatz: Touch und TouchEvent per Konstruktor

const button = document.querySelector('#like');

button.addEventListener('touchstart', (e) => {
  const t = e.changedTouches[0];
  console.log(`Berührung ${t.identifier} bei ${t.clientX}/${t.clientY}`);
});

const touch = new Touch({ identifier: 7, target: button, clientX: 10, clientY: 20 });

button.dispatchEvent(new TouchEvent('touchstart', {
  bubbles: true,
  cancelable: true,
  touches: [touch],
  targetTouches: [touch],
  changedTouches: [touch]
}));

Berührung 7 bei 10/20

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Chrome hat createTouch() um Version 68 entfernt. Firefox bietet die Methode nur hinter der Einstellung dom.w3c_touch_events.legacy_apis.enabled an. Zuverlässig vorhanden ist sie vor allem noch in Safari/WebKit. Prüfe deshalb immer vorher mit typeof document.createTouch === 'function'.
WebKit-Varianten akzeptieren zum Teil weitere Argumente, etwa Radius, Drehwinkel oder Druck. Die Reihenfolge der Argumente ist nicht in allen Browsern gleich.
Auch document.createTouchList() und TouchEvent.prototype.initTouchEvent() sind veraltet und fehlen oft in denselben Browsern.
Synthetische Touch-Events haben isTrusted === false. Aktionen, die eine echte Nutzergeste voraussetzen (Vollbild, Audio-Wiedergabe, Pop-ups), lösen sie deshalb nicht aus.
Auf Desktop-Browsern ohne Touch-Unterstützung fehlen Touch und TouchEvent womöglich ganz. Für geräteunabhängige Eingaben sind PointerEvents meist die bessere Wahl.

Siehe auch

Touch Document.browsingTopics() Document.createTouchList() Document.createEvent() Document.createRange()