Touch — Schnittstelle · JavaScript-Referenz

Signatur

interface Touch

Beschreibung

Ein Touch-Objekt beschreibt einen einzelnen Berührungspunkt auf einem Touchscreen oder Touchpad. Du legst es normalerweise nicht selbst an. Der Browser liefert es in den Listen touches, targetTouches und changedTouches eines TouchEvent mit, also bei touchstart, touchmove, touchend und touchcancel.

Wichtige Eigenschaften (alle nur lesbar):

identifier: eindeutige Nummer des Kontaktpunkts. Sie bleibt gleich, solange der Finger auf der Fläche liegt.
clientX/clientY: Position relativ zum Viewport
pageX/pageY: Position relativ zum Dokument, Scrollen eingerechnet
screenX/screenY: Position relativ zum Bildschirm
target: das Element, auf dem die Berührung begonnen hat
radiusX, radiusY, rotationAngle: Ellipse, die der Kontaktfläche ungefähr entspricht
force: Druck von 0 bis 1

Du brauchst Touch für Mehrfinger-Gesten wie Pinch-Zoom und Drehen, für Wischgesten und für eigene Zeichenflächen. Über identifier ordnest du Bewegungen in touchmove dem richtigen Finger zu. Die Reihenfolge in einer TouchList ist nämlich nicht garantiert.

Mit dem Konstruktor new Touch(init) lassen sich Berührungen künstlich erzeugen, zum Beispiel für Tests. Er ist aber nicht in allen Browsern verfügbar.

Parameter

Name	Typ	Default	Beschreibung
$init Pflicht	TouchInit		Nur für den Konstruktor `new Touch(init)`. Objekt mit den Pflichtfeldern `identifier` (number) und `target` (EventTarget). Optional: `clientX`, `clientY`, `screenX`, `screenY`, `pageX`, `pageY`, `radiusX`, `radiusY`, `rotationAngle`, `force` (Standardwert jeweils `0`).

Rückgabewert

Typ

Touch

Beschreibung

Der Konstruktor gibt ein neues, unveränderliches Touch-Objekt zurück. Im Normalfall bekommst du Touch-Objekte über die TouchList-Eigenschaften eines TouchEvent.

Beispiele

Position des ersten Fingers auslesen

const box = document.querySelector('#box');

box.addEventListener('touchstart', (event) => {
  const touch = event.changedTouches[0];
  console.log(`Finger ${touch.identifier} bei ${touch.clientX}/${touch.clientY}`);
  console.log('Druck:', touch.force);
}, { passive: true });

Finger 0 bei 132/245 Druck: 0.5

Mehrere Finger über identifier verfolgen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const ongoing = new Map(); // identifier -> letzte Position

canvas.addEventListener('touchstart', (e) => {
  e.preventDefault(); // Scrollen und Zoomen verhindern
  for (const t of e.changedTouches) {
    ongoing.set(t.identifier, { x: t.pageX, y: t.pageY });
  }
}, { passive: false });

canvas.addEventListener('touchmove', (e) => {
  e.preventDefault();
  const rect = canvas.getBoundingClientRect();
  for (const t of e.changedTouches) {
    const prev = ongoing.get(t.identifier);
    if (!prev) continue;
    ctx.beginPath();
    ctx.moveTo(prev.x - rect.left - scrollX, prev.y - rect.top - scrollY);
    ctx.lineTo(t.pageX - rect.left - scrollX, t.pageY - rect.top - scrollY);
    ctx.stroke();
    ongoing.set(t.identifier, { x: t.pageX, y: t.pageY });
  }
}, { passive: false });

const endTouch = (e) => {
  for (const t of e.changedTouches) ongoing.delete(t.identifier);
};
canvas.addEventListener('touchend', endTouch);
canvas.addEventListener('touchcancel', endTouch);

Pinch-Abstand zweier Finger berechnen

const distance = (a, b) => Math.hypot(a.clientX - b.clientX, a.clientY - b.clientY);
let startDist = null;

document.addEventListener('touchstart', (e) => {
  if (e.touches.length === 2) startDist = distance(e.touches[0], e.touches[1]);
});

document.addEventListener('touchmove', (e) => {
  if (e.touches.length === 2 && startDist) {
    const scale = distance(e.touches[0], e.touches[1]) / startDist;
    console.log('Zoomfaktor:', scale.toFixed(2));
  }
});

Zoomfaktor: 1.37

Touch künstlich erzeugen (z. B. für Tests)

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

const touch = new Touch({
  identifier: Date.now(),
  target: el,
  clientX: 50,
  clientY: 20,
  radiusX: 2.5,
  radiusY: 2.5,
  force: 0.5
});

const event = new TouchEvent('touchstart', {
  touches: [touch],
  targetTouches: [touch],
  changedTouches: [touch],
  bubbles: true,
  cancelable: true
});

el.dispatchEvent(event);
console.log(touch.clientX, touch.target === el);

50 true

// Wichtig · Fallstricke

target ändert sich nicht: Die Eigenschaft zeigt immer auf das Element, auf dem die Berührung begonnen hat, auch wenn der Finger längst über einem anderen Element liegt. Das aktuelle Element unter dem Finger bekommst du mit document.elementFromPoint(touch.clientX, touch.clientY).
Richtige Liste wählen: Bei touchend ist der abgehobene Finger nicht mehr in touches enthalten, sondern nur noch in changedTouches.
Passive Listener: Chrome und andere Browser registrieren touchstart/touchmove auf window, document und body standardmäßig als passiv. preventDefault() wirkt dort nur mit { passive: false }. Alternativ nutzt du die CSS-Eigenschaft touch-action.
Hardware-Unterschiede: force, radiusX/radiusY und rotationAngle werden nicht von jeder Hardware geliefert und sind dann oft 0 oder 1.
Kompatibilität: Touch-Events gibt es in allen mobilen Browsern. Desktop-Browser unterstützen sie teilweise nur auf Touch-Geräten, eine Prüfung ist mit 'ontouchstart' in window möglich. Den Konstruktor new Touch() unterstützt Safari nicht. Für Code, der Maus, Stift und Touch gleichermaßen abdecken soll, sind Pointer Events (PointerEvent) meist die bessere Wahl.

Siehe auch

Lock Cache Fence GPU Node