Pointer events

Die Bedingung, wenn ein Pointer einen Wert ungleich null für die buttons-Eigenschaft hat. Zum Beispiel im Fall eines Stifts, wenn der Stift physischen Kontakt zum Digitalisierer hat oder mindestens ein Knopf gedrückt ist, während man hovert.

Jedes Eingabegerät, das Ereignisse erzeugen kann. Ein Pointer gilt als aktiv, wenn er noch weitere Ereignisse erzeugen kann. Zum Beispiel gilt ein Stift im heruntergeklappten Zustand als aktiv, da er weitere Ereignisse erzeugen kann, wenn der Stift angehoben oder bewegt wird.

Ein Erfassungsgerät mit einer Oberfläche, die Kontakt erkennen kann. Meistens ist das Erfassungsgerät ein Touch-fähiger Bildschirm, der Eingaben von einem Eingabegerät wie einem Stift, Stylus oder Finger erkennen kann. Einige Erfassungsgeräte können die nahe Nähe des Eingabegeräts erkennen, und der Zustand wird als Hover im Sinne der Maus ausgedrückt.

Der Prozess, den der Browser verwendet, um ein Ziel-Element für ein Pointer Event zu bestimmen. Typischerweise wird dies bestimmt, indem die Position des Pointers und auch das visuelle Layout von Elementen in einem Dokument auf Bildschirmmedien berücksichtigt wird.

Eine hardware-unabhängige Darstellung von Eingabegeräten, die auf eine bestimmte Koordinate (oder einen Satz von Koordinaten) auf einem Bildschirm abzielen können. Beispiele für Pointer-Eingabegeräte sind Maus, Stift/Stylus und Touch Kontakte.

Pointer Capture erlaubt es, die Ereignisse für einen Pointer auf ein bestimmtes Element umzulenken, abweichend vom normalen Hit-Test-Ergebnis der Pointer-Position. Siehe Erfassung des Pointers für ein Beispiel.

Ein DOM-event, das für einen Pointer ausgelöst wird.

Die hauptsächliche Schnittstelle ist die PointerEvent-Schnittstelle, die einen constructor plus mehrere Ereignistypen und zugehörige globale Ereignishandler hat.

Der Standard umfasst außerdem einige Erweiterungen für die Element- und Navigator-Schnittstellen.

Die folgenden Unterabschnitte enthalten kurze Beschreibungen jeder Schnittstelle und ihrer Eigenschaften.

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

altitudeAngle Schreibgeschützt

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

azimuthAngle Schreibgeschützt

Repräsentiert den Winkel zwischen der Y-Z-Ebene und der Ebene, die sowohl die Wandlerachse 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 (Magnitude auf der X-Achse), in CSS-Pixeln, der Kontaktgeometrie des Pointers.

height Schreibgeschützt

Die Höhe (Magnitude auf der Y-Achse), in CSS-Pixeln, der Kontaktgeometrie des Pointers.

pressure Schreibgeschützt

Der normalisierte Druck der Zeigereingabe im Bereich von 0 bis 1, wobei 0 und 1 den minimalen und maximalen Druck darstellen, den die Hardware erfassen kann.

tangentialPressure Schreibgeschützt

Der normalisierte tangentiale Druck der Zeigereingabe (auch bekannt als Fassdruck oder Zylinderstress) im Bereich von -1 bis 1, wobei 0 die neutrale Position der Steuerung 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 Wandlerachse 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 Wandlerachse als auch die X-Achse enthält.

twist Schreibgeschützt

Die Drehung des Pointers (z.B. Stift-Stylus) um seine Hauptachse im Uhrzeigersinn 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, etc.).

isPrimary Schreibgeschützt

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

Pointer Events haben zehn Ereignistypen, sieben davon haben ähnliche Semantik wie ihre Maus-Ereignis-Pendants (down, up, move, over, out, enter, und leave).

Nachfolgend ist eine kurze Beschreibung jedes Ereignistyps.

Es gibt drei Erweiterungen der Element-Schnittstelle:

hasPointerCapture()

Gibt an, ob das aufgerufene Element Pointer Capture für den durch die gegebene Zeiger-ID identifizierten Zeiger hat.

releasePointerCapture()

Gibt die zuvor für ein bestimmtes Zeigerereignis gesetzte Pointer Capture frei (stoppt).

setPointerCapture()

Bestimmt ein bestimmtes Element als Capture-Ziel zukünftiger Zeigerereignisse.

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

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

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

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

function over_handler(event) {}
function enter_handler(event) {}
function down_handler(event) {}
function move_handler(event) {}
function up_handler(event) {}
function cancel_handler(event) {}
function out_handler(event) {}
function leave_handler(event) {}
function rawUpdate_handler(event) {}
function gotCapture_handler(event) {}
function lostCapture_handler(event) {}

function init() {
  const el = document.getElementById("target");
  // Register pointer event handlers
  el.onpointerover = over_handler;
  el.onpointerenter = enter_handler;
  el.onpointerdown = down_handler;
  el.onpointermove = move_handler;
  el.onpointerup = up_handler;
  el.onpointercancel = cancel_handler;
  el.onpointerout = out_handler;
  el.onpointerleave = leave_handler;
  el.onpointerrawupdate = rawUpdate_handler;
  el.ongotpointercapture = gotCapture_handler;
  el.onlostpointercapture = lostCapture_handler;
}

document.addEventListener("DOMContentLoaded", init);

Dieses Beispiel zeigt das Zugreifen auf alle Eigenschaften eines Pointer Events.

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

const id = -1;

function process_id(event) {
  // Process this event based on the event's identifier
}
function process_mouse(event) {
  // Process the mouse pointer event
}
function process_pen(event) {
  // Process the pen pointer event
}
function process_touch(event) {
  // Process the touch pointer event
}
function process_tilt(tiltX, tiltY) {
  // Tilt data handler
}
function process_pressure(pressure) {
  // Pressure handler
}
function process_non_primary(event) {
  // Non primary handler
}

function down_handler(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) process_id(ev);

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

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

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

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

function init() {
  const el = document.getElementById("target");
  // Register pointerdown handler
  el.onpointerdown = down_handler;
}

document.addEventListener("DOMContentLoaded", init);

In einigen Szenarien kann es mehrere Zeiger geben (zum Beispiel ein Gerät mit Touchscreen und Maus) oder ein Zeiger, der mehrere Kontaktpunkte unterstützt (zum Beispiel ein Touchscreen, der mehrere Fingerberührungen unterstützt). Die Anwendung kann die isPrimary-Eigenschaft verwenden, um einen Hauptzeiger aus 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, sodass sie immer der primäre Zeiger sein wird. Für Touch-Eingaben gilt ein Zeiger als primär, wenn der Benutzer den Bildschirm berührt hat, während keine anderen aktiven Berührungen vorhanden waren. Bei Stift- und Stylus-Eingaben gilt ein Zeiger als primär, wenn der Stift des Benutzers den Bildschirm zuerst berührt hat, während keine anderen aktiven Stifte den Bildschirm berührten.

Einige Zeigegeräte (wie Maus und Stift) unterstützen mehrere Knöpfe, und die Knopfdrücke können akkordiert sein (d.h. das Drücken eines zusätzlichen Knopfes, während ein anderer Knopf des Zeigegeräts bereits gedrückt ist).

Um den Zustand der Knopfdrücke zu bestimmen, verwenden Pointer Events die button- und buttons-Eigenschaften des MouseEvent-Interfaces, von dem PointerEvent erbt.

Die folgende Tabelle gibt die Werte von button und buttons für die verschiedenen Knopfzustände des Geräts an.

Pointer Capture ermöglicht es den Ereignissen für ein bestimmtes Pointer Event, auf ein bestimmtes Element umgeleitet zu werden, anstatt dem normalen Hit-Test bei der Zeigerposition. Dies kann verwendet werden, um sicherzustellen, dass ein Element weiterhin Zeigerereignisse erhält, selbst wenn der Kontakt des Zeigegeräts das Element verlässt (beispielsweise durch Scrollen oder Ziehen).

Pointer Capture sorgt dafür, dass das Ziel alle nachfolgenden Zeigerereignisse so erfasst, als ob sie über dem erfassten Ziel stattfinden würden. Dementsprechend werden pointerover, pointerenter, pointerleave und pointerout nicht ausgelöst, solange diese Erfassung eingestellt ist. Für Touchscreen-Browser, die direkte Manipulation unterstützen, wird eine implizite Zeigererfassung auf dem Element aufgerufen, wenn ein pointerdown-Ereignis ausgelöst wird. Die Erfassung kann manuell durch den Aufruf von element.releasePointerCapture am Ziel-Element freigegeben werden oder sie wird implizit nach einem pointerup- oder pointercancel-Ereignis freigegeben.

Das folgende Beispiel zeigt die Zeigererfassung, die auf ein Element eingestellt 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);
}

function init() {
  const el = document.getElementById("target");
  el.onpointerdown = downHandler;
}

document.addEventListener("DOMContentLoaded", init);

Das folgende Beispiel zeigt die Freigabe einer Zeigererfassung (wenn ein pointercancel Ereignis auftritt. Der Browser führt dies automatisch aus, 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);
}

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

document.addEventListener("DOMContentLoaded", init);

Die touch-action CSS-Eigenschaft wird verwendet, um festzulegen, ob der Browser sein Standard-(natürliches) Touch-Verhalten (wie Zoomen oder Scrollen) in einem Bereich 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 sein Standard-Touch-Verhalten (auf den angegebenen Bereich) frei anwenden kann, und der Wert none deaktiviert das Standard-Touch-Verhalten des Browsers für den Bereich. Die Werte pan-x und pan-y bedeuten, dass Berührungen, die auf dem angegebenen Bereich beginnen, nur für das horizontale bzw. vertikale Scrollen gelten. Der Wert manipulation bedeutet, dass der Browser Berührungen, die auf dem Element beginnen, nur für das Scrollen und Zoomen berücksichtigen kann.

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

button#tiny {
  touch-action: none;
}

Im folgenden Beispiel wird, wenn das target-Element berührt wird, nur in horizontaler Richtung gescrollt.

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

Obwohl die Pointer Event-Schnittstellen es Anwendungen ermöglichen, verbesserte Benutzererfahrungen auf zeigerfähigen Geräten zu schaffen, ist die Realität, dass der Großteil der heutigen Webinhalte nur für die Arbeit mit Mausteingaben ausgelegt ist. Folglich muss der Browser, selbst wenn er Pointer Events unterstützt, dennoch Mausereignisse verarbeiten, sodass Inhalte, die nur auf Maus-Eingaben ausgelegt sind, unverändert funktionieren. Idealerweise muss eine zeigerfähige Anwendung Mausinhalte nicht explizit handhaben. Da der Browser jedoch Mausereignisse verarbeiten muss, kann es einige Kompatibilitätsprobleme geben, die behandelt werden müssen. Dieser Abschnitt enthält Informationen zur Interaktion von Pointer- und Mausereignissen und den Konsequenzen für Anwendungsentwickler.

Der Browser kann allgemeine Pointer-Eingaben in Mausereignisse für die Kompatibilität mit Maus-basierten Inhalten umsetzen. Diese Umsetzung von Ereignissen wird als Kompatibilitäts-Mausereignisse bezeichnet. Autoren können die Erzeugung bestimmter Kompatibilitäts-Mausereignisse verhindern, indem sie das pointerdown-Ereignis abbrechen, beachten Sie jedoch, dass:

• Mausereignisse können nur verhindert werden, wenn der Zeiger gedrückt ist.
• Hovernde Zeiger (z.B. eine Maus ohne gedrückte Knöpfe) können ihre Mausereignisse nicht verhindert haben.
• Die Ereignisse mouseover, mouseout, mouseenter und mouseleave werden niemals verhindert (selbst wenn der Zeiger gedrückt ist).

Hier sind einige Best Practices zu beachten, wenn Sie Pointer Events verwenden:

• Minimieren Sie die Menge an Arbeit, die in Ereignishandlern ausgeführt wird.
• Fügen Sie die Ereignishandler einem spezifischen Ziel-Element hinzu (anstatt dem gesamten Dokument oder Knoten, die weiter oben im Dokumentbaum stehen).
• Das Ziel-Element (der Knoten) sollte groß genug sein, um die größte Kontaktflächen zu beherbergen (typischerweise eine Fingerberührung). Wenn das Zielgebiet zu klein ist, könnte das Berühren dazu führen, dass andere Ereignisse für benachbarte Elemente ausgelöst werden.

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