Pointer events

Terminologie

Aktiver Tastenstatus

Der Zustand, wenn ein Zeiger einen nicht-nullwertigen buttons-Eigenschaftswert hat. Zum Beispiel, bei einem Stift, wenn der Stift physischen Kontakt mit dem Digitalisierer hat oder mindestens eine Taste gedrückt ist, während er schwebt.

Aktiver Zeiger

Jedes Zeiger Eingabegerät, das Ereignisse erzeugen kann. Ein Zeiger wird als aktiv betrachtet, wenn er weiterhin weitere Ereignisse erzeugen kann. Zum Beispiel gilt ein Stift, der in einem gedrückten Zustand ist, als aktiv, da er zusätzliche Ereignisse erzeugen kann, wenn der Stift angehoben oder bewegt wird.

Digitalisierer

Ein Erfassungsgerät mit einer Oberfläche, die Kontakt erfassen kann. Meistens handelt es sich um einen touchfähigen Bildschirm, der Eingaben von einem Eingabegerät wie einem Stift, Stylus oder Finger erfassen kann. Einige Erfassungsgeräte können die nahe Nähe des Eingabegeräts erkennen, und der Zustand wird als Schwebezustand wie bei der Maus ausgedrückt.

Treffer-Test

Der Prozess, den der Browser verwendet, um ein Ziel-Element für ein Zeiger-Ereignis zu bestimmen. Typischerweise wird dies durch Betrachtung der Position des Zeigers und auch des visuellen Layouts der Elemente im Dokument auf Bildschirmmedien bestimmt.

Zeiger

Eine hardwareunabhängige Darstellung von Eingabegeräten, die auf eine bestimmte Koordinate (oder ein Koordinatenset) auf einem Bildschirm zielen können. Beispiele für Zeiger-Eingabegeräte sind Maus, Stift/Stylus und Touchkontakte.

Zeiger-Erfassung

Die Zeigererfassung ermöglicht, dass die Ereignisse für einen Zeiger auf ein bestimmtes Element umgeleitet werden, anstatt auf das normale Ergebnis eines Treffer-Tests der Zeigerposition. Sehen Sie sich das Einfangen des Zeigers für ein Beispiel an.

Zeiger-Ereignis

Ein DOM-Ereignis, das für ein Zeiger ausgelöst wird.

Schnittstellen

Die primäre Schnittstelle ist die PointerEvent-Schnittstelle, die einen Konstruktor plus mehrere Ereignistypen und zugehörige globale Ereignis-Handler hat.

Der Standard umfasst auch einige Erweiterungen der Element- und Navigator-Schnittstellen.

Die folgenden Unterabschnitte enthalten kurze Beschreibungen jeder Schnittstelle und Eigenschaft.

PointerEvent-Schnittstelle

Die PointerEvent-Schnittstelle erweitert die MouseEvent-Schnittstelle und hat die folgenden Eigenschaften.

altitudeAngle Schreibgeschützt

Repräsentiert den Winkel zwischen einer Wandlerachse (einem Zeiger oder Stylus) und der X-Y-Ebene eines Gerätdisplays.

azimuthAngle Schreibgeschützt

Repräsentiert den Winkel zwischen der Y-Z-Ebene und der Ebene, die sowohl die Wandlerachse (ein Zeiger oder Stylus) als auch die Y-Achse enthält.

PointerEvent.persistentDeviceId Schreibgeschützt

Eine eindeutige Kennung für das Zeigegerät, das das PointerEvent erzeugt.

pointerId Schreibgeschützt

Eine eindeutige Kennung für den Zeiger, der das Ereignis verursacht.

width Schreibgeschützt

Die Breite (Größe auf der X-Achse) der Kontaktgeometrie des Zeigers in CSS-Pixeln.

height Schreibgeschützt

Die Höhe (Größe auf der Y-Achse) der Kontaktgeometrie des Zeigers in CSS-Pixeln.

pressure Schreibgeschützt

Der normalisierte Druck der Zeigereingabe im Bereich von 0 bis 1, wobei 0 und 1 den minimalen bzw. maximalen Druck darstellen, den die Hardware zu erkennen vermag.

tangentialPressure Schreibgeschützt

Der normalisierte tangentiale Druck der Zeigereingabe (auch bekannt als Fassdruck oder Zylinderstress) im Bereich zwischen -1 bis 1, wobei 0 die neutrale Position der Kontrolle ist.

tiltX Schreibgeschützt

Der Ebenenwinkel (in Grad, im Bereich von -90 bis 90) zwischen der Y–Z-Ebene und der Ebene, die sowohl die Zeigerachse (z.B. Pen Stylus) als auch die Y-Achse enthält.

tiltY Schreibgeschützt

Der Ebenenwinkel (in Grad, im Bereich von -90 bis 90) zwischen der X–Z-Ebene und der Ebene, die sowohl die Zeigerachse (z.B. Pen Stylus) als auch die X-Achse enthält.

twist Schreibgeschützt

Die Drehung des Zeigers (z.B. Pen Stylus) im Uhrzeigersinn um seine Hauptachse in Grad, mit einem Wert im Bereich von 0 bis 359.

pointerType Schreibgeschützt

Gibt den Gerätetyp an, der das Ereignis verursacht hat (Maus, Stift, Touch usw.).

isPrimary Schreibgeschützt

Gibt an, ob der Zeiger den primären Zeiger dieses Zeigertyps darstellt.

Ereignistypen und globale Ereignis-Handler

Zeiger-Ereignisse haben zehn Ereignistypen, von denen sieben ähnliche Semantik wie ihre Maus-Ereignis-Pendants haben (down, up, move, over, out, enter und leave).

Im Folgenden eine kurze Beschreibung jedes Ereignistyps.

Elementerweiterungen

Es gibt drei Erweiterungen der Element-Schnittstelle:

hasPointerCapture()

Gibt an, ob das Element, auf dem es aufgerufen wird, die Zeigererfassung für den durch die gegebene Zeiger-ID identifizierten Zeiger hat.

releasePointerCapture()

Hebt die Zeigererfassung auf, die zuvor für ein bestimmtes Zeiger-Ereignis festgelegt wurde.

setPointerCapture()

Bestimmt ein bestimmtes Element als Erfassungsziel zukünftiger Zeiger-Ereignisse.

Navigator-Erweiterung

Die Navigator.maxTouchPoints-Eigenschaft wird verwendet, um die maximale Anzahl gleichzeitiger Berührungspunkte zu bestimmen, die zu einem bestimmten Zeitpunkt unterstützt werden.

Beispiele

Dieser Abschnitt enthält Beispiele für die grundlegende Verwendung der Zeigerereignisse-Schnittstellen.

Registrieren von Ereignis-Handlern

Dieses Beispiel registriert einen Handler für jeden Ereignistyp für das gegebene Element.

<div id="target">Touch me…</div>

function overHandler(event) {}
function enterHandler(event) {}
function downHandler(event) {}
function moveHandler(event) {}
function upHandler(event) {}
function cancelHandler(event) {}
function outHandler(event) {}
function leaveHandler(event) {}
function rawUpdateHandler(event) {}
function gotCaptureHandler(event) {}
function lostCaptureHandler(event) {}

const el = document.getElementById("target");
// Register pointer event handlers
el.onpointerover = overHandler;
el.onpointerenter = enterHandler;
el.onpointerdown = downHandler;
el.onpointermove = moveHandler;
el.onpointerup = upHandler;
el.onpointercancel = cancelHandler;
el.onpointerout = outHandler;
el.onpointerleave = leaveHandler;
el.onpointerrawupdate = rawUpdateHandler;
el.ongotpointercapture = gotCaptureHandler;
el.onlostpointercapture = lostCaptureHandler;

Eigenschaften von Ereignissen

Dieses Beispiel zeigt, wie auf alle Eigenschaften eines Zeigerereignisses zugegriffen wird.

<div id="target">Touch me…</div>

const id = -1;

function processId(event) {
  // Process this event based on the event's identifier
}
function processMouse(event) {
  // Process the mouse pointer event
}
function processPen(event) {
  // Process the pen pointer event
}
function processTouch(event) {
  // Process the touch pointer event
}
function processTilt(tiltX, tiltY) {
  // Tilt data handler
}
function processPressure(pressure) {
  // Pressure handler
}
function processNonPrimary(event) {
  // Non primary handler
}

function downHandler(ev) {
  // Calculate the touch point's contact area
  const area = ev.width * ev.height;

  // Compare cached id with this event's id and process accordingly
  if (id === ev.identifier) processId(ev);

  // Call the appropriate pointer type handler
  switch (ev.pointerType) {
    case "mouse":
      processMouse(ev);
      break;
    case "pen":
      processPen(ev);
      break;
    case "touch":
      processTouch(ev);
      break;
    default:
      console.log(`pointerType ${ev.pointerType} is not supported`);
  }

  // Call the tilt handler
  if (ev.tiltX !== 0 && ev.tiltY !== 0) processTilt(ev.tiltX, ev.tiltY);

  // Call the pressure handler
  processPressure(ev.pressure);

  // If this event is not primary, call the non primary handler
  if (!ev.isPrimary) processNonPrimary(ev);
}

const el = document.getElementById("target");
// Register pointerdown handler
el.onpointerdown = downHandler;

Bestimmen des primären Zeigers

In einigen Szenarien kann es mehrere Zeiger geben (zum Beispiel ein Gerät mit sowohl Touchscreen als auch Maus) oder einen Zeiger, der mehrere Kontaktpunkte unterstützt (zum Beispiel einen Touchscreen, der mehrere Fingertipps unterstützt). Die Anwendung kann die isPrimary-Eigenschaft verwenden, um einen Hauptzeiger unter der Menge der aktiven Zeiger für jeden Zeigertyp zu identifizieren. Wenn eine Anwendung nur einen primären Zeiger unterstützen möchte, kann sie alle Zeigerereignisse ignorieren, die nicht primär sind.

Eine Maus hat nur einen Zeiger, also wird dieser immer der primäre Zeiger sein. Für Touch-Eingaben wird ein Zeiger als primär betrachtet, wenn der Benutzer den Bildschirm berührt hat, als es keine anderen aktiven Berührungen gab. Für Stift- und Stylus-Eingaben wird ein Zeiger als primär betrachtet, wenn der Stift des Benutzers den Bildschirm initial berührt hat, während keine anderen aktiven Stifte den Bildschirm berührten.

Bestimmen der Tastenstatus

Einige Zeigegeräte (wie Maus und Stift) unterstützen mehrere Tasten, und die Tastenbetätigungen können überlagert sein (d.h. eine zusätzliche Taste wird gedrückt, während eine andere Taste am Zeigegerät bereits gedrückt ist).

Um den Zustand der Tastenbetätigungen zu bestimmen, verwenden Zeiger-Ereignisse die button- und buttons-Eigenschaften der MouseEvent-Schnittstelle (von der PointerEvent erbt).

Die folgende Tabelle liefert die Werte von button und buttons für die verschiedenen Gerätezustände der Tasten.

Erfassen des Zeigers

Die Zeiger-Erfassung ermöglicht, dass Ereignisse für ein bestimmtes Zeiger-Ereignis auf ein bestimmtes Element umgeleitet werden, anstatt dem normalen Treffer-Test an der Position des Zeigers zu folgen. Dies kann verwendet werden, um sicherzustellen, dass ein Element weiterhin Zeigerereignisse empfängt, auch wenn der Kontakt des Zeigegeräts das Element verlässt (zum Beispiel durch Scrollen oder Panning).

Die Zeigererfassung sorgt dafür, dass das Ziel alle nachfolgenden Zeigerereignisse erfasst, als ob sie über dem erfassenden Ziel stattfinden würden. Folglich werden pointerover, pointerenter, pointerleave und pointerout nicht ausgelöst, solange diese Erfassung gesetzt ist. Für Browser mit Touchscreens, die direkte Manipulation zulassen, wird eine implizite Zeigererfassung auf dem Element aufgerufen, wenn ein pointerdown-Ereignis ausgelöst wird. Die Erfassung kann manuell aufgehoben werden, indem element.releasePointerCapture auf das Ziel-Element aufgerufen wird, oder sie wird implizit nach einem pointerup- oder pointercancel-Ereignis freigegeben.

Das folgende Beispiel zeigt, wie die Zeigererfassung auf ein Element gesetzt wird.

<div id="target">Touch me…</div>

function downHandler(ev) {
  const el = document.getElementById("target");
  // Element 'target' will receive/capture further events
  el.setPointerCapture(ev.pointerId);
}

const el = document.getElementById("target");
el.onpointerdown = downHandler;

Das folgende Beispiel zeigt, wie eine Zeigererfassung freigegeben wird (wenn ein pointercancel-Ereignis eintritt. Der Browser erledigt dies automatisch, wenn ein pointerup- oder pointercancel-Ereignis auftritt.

<div id="target">Touch me…</div>

function downHandler(ev) {
  const el = document.getElementById("target");
  // Element "target" will receive/capture further events
  el.setPointerCapture(ev.pointerId);
}

function cancelHandler(ev) {
  const el = document.getElementById("target");
  // Release the pointer capture
  el.releasePointerCapture(ev.pointerId);
}

const el = document.getElementById("target");
// Register pointerdown and pointercancel handlers
el.onpointerdown = downHandler;
el.onpointercancel = cancelHandler;

touch-action CSS-Eigenschaft

Die touch-action CSS-Eigenschaft wird verwendet, um anzugeben, ob der Browser sein Standardverhalten (nativ) bei Berührung (wie Zoomen oder Panning) auf eine Region anwenden soll oder nicht. Diese Eigenschaft kann auf alle Elemente angewendet werden, außer: nicht ersetzte Inline-Elemente, Tabellenzeilen, Zeilengruppen, Tabellenspalten und Spaltengruppen.

Ein Wert von auto bedeutet, dass der Browser frei ist, sein Standard-Touch-Verhalten (auf die angegebene Region) anzuwenden, und der Wert none deaktiviert das Standard-Touch-Verhalten des Browsers für die Region. Die Werte pan-x und pan-y bedeuten, dass Berührungen, die auf der angegebenen Region beginnen, nur horizontal bzw. vertikal scrollen sollen. Der Wert manipulation bedeutet, dass der Browser Berührungen, die auf dem Element beginnen, nur zum Scrollen und Zoomen in Betracht ziehen darf.

Im folgenden Beispiel ist das Standard-Touch-Verhalten für einige button-Elemente deaktiviert.

button#tiny {
  touch-action: none;
}

Im folgenden Beispiel wird das target-Element, wenn es berührt wird, nur in der horizontalen Richtung verschoben.

#target {
  touch-action: pan-x;
}

Kompatibilität mit Mausereignissen

Obwohl die Zeiger-Ereignis-Schnittstellen Anwendungen ermöglichen, verbesserte Benutzererfahrungen auf zeigerfähigen Geräten zu schaffen, ist die Realität, dass der Großteil der heutigen Webinhalte nur auf Maus-Eingaben ausgelegt ist. Folglich muss ein Browser, selbst wenn er Zeiger-Ereignisse unterstützt, weiterhin Mausereignisse verarbeiten, damit Inhalte, die nur Maus-Eingaben voraussetzen, ohne direkte Anpassung funktionieren. Idealerweise muss eine zeigerfähige Anwendung nicht explizit mit Maus-Eingaben umgehen. Da jedoch der Browser Mausereignisse verarbeiten muss, kann es einige Kompatibilitätsprobleme geben, die angesprochen werden müssen. Dieser Abschnitt enthält Informationen über die Interaktion von Zeiger- und Mausereignissen und deren Auswirkungen für Anwendungsentwickler.

Der Browser kann generische Zeigereingaben Ereignisse auf Mausereignisse abbilden, um Kompatibilität mit mausbasierter Inhalte zu gewährleisten. Diese Zuordnung von Ereignissen wird als Mauskompatibilitätsereignisse bezeichnet. Autoren können die Erzeugung bestimmter Mauskompatibilitätsereignisse verhindern, indem sie das pointerdown-Ereignis abbrechen, aber beachten Sie:

• Mausereignisse können nur verhindert werden, wenn der Zeiger unten ist.
• Schwebende Zeiger (z.B. eine Maus ohne gedrückte Tasten) können ihre Mausereignisse nicht verhindern.
• Die Ereignisse mouseover, mouseout, mouseenter und mouseleave werden niemals verhindert (selbst wenn der Zeiger unten ist).

Beste Praktiken

Hier sind einige beste Praktiken, die bei der Verwendung von Zeiger-Ereignissen zu beachten sind:

• Minimieren Sie die Menge an Arbeit, die in Ereignis-Handlern durchgeführt wird.
• Fügen Sie die Ereignis-Handler einem spezifischen Ziel-Element (statt des gesamten Dokuments oder Knoten weiter oben im Dokumentbaum) hinzu.
• Das Ziel-Element (Knoten) sollte groß genug sein, um den größten Kontaktflächenbereich (typischerweise eine Fingerberührung) aufzunehmen. Wenn das Zielgebiet zu klein ist, könnte das Berühren dazu führen, dass andere Ereignisse für benachbarte Elemente ausgelöst werden.

Spezifikationen

Browser-Kompatibilität

Einige zusätzliche Werte sind für die CSS-touch-action-Eigenschaft als Teil der Pointer Events-Spezifikation definiert, aber derzeit haben diese Werte begrenzte Implementierungsunterstützung.

Siehe auch

• Touch-Ereignisse
• Pointer Events Working Group
• Mail-Liste
• W3C #pointerevents IRC-Kanal
• Touch-/Zeiger-Tests und Demos von Patrick H. Lauke