Pointer events

Der Zustand, wenn ein Pointer einen ungleich null Wert für die buttons Eigenschaft hat. Zum Beispiel, im Fall eines Stiftes, wenn der Stift physischen Kontakt mit dem Digitalisierer hat oder mindestens ein Knopf gedrückt wird, während er schwebt.

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

Ein Sensorgerät mit einer Oberfläche, die Kontakt erkennen kann. Meistens ist das Sensorgerät ein berührungsempfindlicher Bildschirm, der Eingaben von einem Eingabegerät wie einem Stift, Stylus oder Finger erfassen kann. Einige Sensorgeräte können die Nähe des Eingabegeräts erkennen, und der Zustand wird als Schwebeposition im Vergleich zur Maus ausgedrückt.

Der Prozess, den der Browser verwendet, um ein Zielelement für ein Pointer-Ereignis zu bestimmen. Typischerweise wird dies bestimmt, indem die Position des Zeigers und die visuelle Anordnung der Elemente in einem Dokument auf einem Bildschirmmedium berücksichtigt werden.

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

Die Zeigererfassung ermöglicht es, dass die Ereignisse für einen Zeiger an ein bestimmtes Element weitergeleitet werden, das nicht das normale Ergebnis des Treffer-Tests an der Position des Zeigers ist. Siehe Erfassen des Zeigers für ein Beispiel.

Note: Zeigererfassung unterscheidet sich von Pointer Lock, das physisch verhindert, dass der Zeiger einen Bereich verlässt.

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

Die Hauptschnittstelle ist die PointerEvent Schnittstelle, die einen Konstruktor sowie verschiedene Ereignistypen und zugehörige globale Ereignishandler hat.

Der Standard beinhaltet auch einige Erweiterungen der Element und Navigator Schnittstellen.

Die folgenden Unterabschnitte enthalten kurze Beschreibungen jeder Schnittstelle und Eigenschaft.

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

altitudeAngle Schreibgeschützt

Stellt den Winkel zwischen der Achse eines Wandlers (eines Zeigers oder Stylus) und der X-Y-Ebene eines Gerätescreens dar.

azimuthAngle Schreibgeschützt

Stellt den Winkel zwischen der Y-Z-Ebene und der Ebene dar, die sowohl die Achse des Wandlers (eines Zeigers oder Stylus) als auch die Y-Achse enthält.

PointerEvent.persistentDeviceId Schreibgeschützt Experimentell

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

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) in CSS-Pixeln der Kontaktgeometrie des Zeigers.

height Schreibgeschützt

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

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 erkennen kann.

tangentialPressure Schreibgeschützt

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

tiltX Schreibgeschützt

Der Plane-Winkel (in Grad, im Bereich von -90 bis 90) zwischen der Y-Z-Ebene und der Ebene, die sowohl die Achse des Zeigers (z.B. eines Stiftes) als auch die Y-Achse enthält.

tiltY Schreibgeschützt

der Plane-Winkel (in Grad, im Bereich von -90 bis 90) zwischen der X-Z-Ebene und der Ebene, die sowohl die Achse des Zeigers (z.B. eines Stiftes) als auch die X-Achse enthält.

twist Schreibgeschützt

Die im Uhrzeigersinn erfolgende Drehung des Zeigers (z.B. eines Stiftes) 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, etc.).

isPrimary Schreibgeschützt

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

Pointer-Ereignisse haben zehn Ereignistypen, von denen sieben ähnliche Semantiken wie ihre Mausereignis-Gegenstücke haben (down, up, move, over, out, enter und leave).

Im Folgenden finden Sie eine kurze Beschreibung jedes Ereignistyps.

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()

Gibt die zuvor für ein bestimmtes Pointer-Ereignis gesetzte Zeigererfassung frei (stoppt sie).

setPointerCapture()

Designiert ein bestimmtes Element als Erfassungsziel für zukünftige 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 Nutzung der Pointer-Ereignis-Schnittstellen.

Dieses Beispiel registriert einen Handler für jeden Ereignistyp für das angegebene 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, wie auf alle Eigenschaften eines Pointer-Ereignisses zugegriffen wird.

<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 gibt es möglicherweise mehrere Zeiger (z. B. ein Gerät mit einem Touchscreen und einer Maus) oder einen Zeiger, der mehrere Kontaktpunkte unterstützt (z. B. ein Touchscreen, der mehrere Fingerberührungen unterstützt). Die Anwendung kann die isPrimary Eigenschaft verwenden, um einen Hauptzeiger unter den aktiven Zeigern 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, daher wird sie immer der primäre Zeiger sein. Für Berührungseingaben wird ein Zeiger als primär betrachtet, wenn der Benutzer den Bildschirm berührt hat, während keine anderen Berührungen aktiv waren. Für Stift- und Stylus-Eingaben wird ein Zeiger als primär angesehen, wenn der Stift des Benutzers den Bildschirm berührt hat, während keine anderen Stifte aktiv den Bildschirm berührten.

Einige Zeigegeräte (wie Maus und Stift) unterstützen mehrere Knöpfe, und die Knopfdrücke können chordiert sein (d.h. durch gleichzeitiges Drücken eines weiteren Knopfes, während bereits ein anderer Knopf am Zeigegerät gedrückt wird).

Um den Zustand der Knopfdrücke festzustellen, verwenden die Pointer-Ereignisse die button und buttons Eigenschaften der MouseEvent Schnittstelle (von der PointerEvent erbt).

Die folgende Tabelle bietet die Werte von button und buttons für die verschiedenen Geräteknopfzustände.

Die Zeigererfassung ermöglicht es, dass Ereignisse für ein bestimmtes Pointer-Ereignis an ein bestimmtes Element weitergeleitet werden, anstatt dem normalen Hit-Test an der Position des Zeigers. Dies kann verwendet werden, um sicherzustellen, dass ein Element weiterhin Zeigerereignisse empfängt, selbst wenn sich der Kontakt des Zeigegeräts vom Element wegbewegt (zum Beispiel durch Scrollen oder Schwenken).

Die Zeigererfassung führt dazu, dass das Ziel alle nachfolgenden Zeigerereignisse erfasst, als ob sie über dem erfassenden Ziel auftreten würden. Folglich werden pointerover, pointerenter, pointerleave und pointerout nicht ausgelöst, solange diese Erfassung eingestellt ist. Für Touchscreen-Browser, die direct manipulation ermöglichen, wird eine implizite Zeigererfassung auf dem Element aufgerufen, wenn ein pointerdown-Ereignis ausgelöst wird. Die Erfassung kann manuell freigegeben werden, indem element.releasePointerCapture auf dem Zielelement aufgerufen wird, oder sie wird nach einem pointerup- oder pointercancel-Ereignis implizit freigegeben.

Das folgende Beispiel zeigt, wie Zeigererfassung auf einem 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 eine Zeigererfassung, die freigegeben wird (wenn ein pointercancel Ereignis auftritt. Der Browser macht 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);
}

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 standardmäßiges (natürliches) Berührungsverhalten (wie Zoomen oder Schwenken) auf eine Region anwenden soll oder nicht. Diese Eigenschaft kann auf alle Elemente außer nicht ersetzten Inline-Elementen, Tabellenzeilen, Zeilengruppen, Tabellenspalten und Spaltengruppen angewendet werden.

Ein Wert von auto bedeutet, dass der Browser frei ist, sein Standard-Berührungsverhalten auf die angegebene Region anzuwenden, und der Wert von none deaktiviert das Standard-Berührungsverhalten des Browsers für die Region. Die Werte pan-x und pan-y bedeuten, dass Berührungen, die auf der angegebenen Region beginnen, nur für horizontales bzw. vertikales Scrollen sind. Der Wert manipulation bedeutet, dass der Browser Berührungen, die auf dem Element beginnen, nur zum Scrollen und Zoomen in Betracht ziehen kann.

Im folgenden Beispiel ist das standardmäßige Berührungsverhalten für einige button-Elemente deaktiviert.

button#tiny {
  touch-action: none;
}

Im folgenden Beispiel wird das Ziel-Element, wenn es berührt wird, nur in horizontaler Richtung verschoben.

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

Obwohl die Schnittstellen für Pointer-Ereignisse es Anwendungen ermöglichen, verbesserte Benutzererfahrungen auf Geräten mit Zeigern zu schaffen, ist die Realität, dass der Großteil der heutigen Webinhalte so konzipiert ist, dass er nur mit Mauseingaben funktioniert. Folglich muss ein Browser, auch wenn er Pointer-Ereignisse unterstützt, dennoch Mausereignisse verarbeiten, damit Inhalte, die nur Maus-Eingaben voraussetzen, so wie sie sind, ohne direkte Änderungen funktionieren. Ideal wäre es, wenn eine Anwendung mit Pointer-Unterstützung keine explizite Handhabung von Mauseingaben benötigt. Da der Browser jedoch Mausereignisse verarbeiten muss, gibt es möglicherweise einige Kompatibilitätsprobleme, die behandelt werden müssen. Dieser Abschnitt enthält Informationen über die Interaktion von Pointer- und Mausereignissen und die Auswirkungen auf Anwendungsentwickler.

Der Browser kann generische Pointer-Ereignisse für die Kompatibilität mit mausbasierter Inhalte in Mausereignisse umwandeln. Diese Umwandlung von Ereignissen wird Kompatibilitäts-Mausereignisse genannt. Autoren können die Produktion bestimmter Kompatibilitäts-Mausereignisse verhindern, indem sie das pointerdown-Ereignis abbrechen, beachten Sie jedoch:

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

Hier sind einige Best Practices, die Sie beim Verwenden von Pointer-Ereignissen beachten sollten:

• Minimieren Sie die Menge an Arbeit, die in Ereignishandlern durchgeführt wird.
• Fügen Sie die Ereignishandler zu einem bestimmten Ziel-Element hinzu (anstatt zum gesamten Dokument oder Knoten höher im Dokumentenbaum).
• Das Ziel-Element (Knoten) sollte groß genug sein, um die größte Kontaktoberfläche aufzunehmen (typischerweise ein Finger). Wenn das Zielgebiet zu klein ist, könnte das Berühren zu Ereignissen für angrenzende Elemente führen.

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