Pointer events

Der Zustand, wenn ein Zeiger einen ungleich null-Wert für die buttons-Eigenschaft hat. Beispielsweise im Fall eines Stifts, wenn der Stift physischen Kontakt mit dem Digitalisierer hat oder mindestens eine Taste beim Schweben gedrückt wird.

Jedes Zeiger Eingabegerät, das Ereignisse erzeugen kann. Ein Zeiger wird als aktiv betrachtet, wenn er weiterhin Ereignisse erzeugen kann. Zum Beispiel wird ein Stift in einem Abwärtszustand als aktiv angesehen, weil er zusätzliche Ereignisse erzeugen kann, wenn der Stift angehoben oder bewegt wird.

Ein Sensorgerät mit einer Oberfläche, die Berührungen erfassen kann. Am häufigsten 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 nahe Annäherung des Eingabegeräts erkennen, und der Zustand wird als Schweben im Sinne des Mauszeigers ausgedrückt.

Der Prozess, den der Browser verwendet, um ein Zielelement für ein Zeigereignis zu bestimmen. Typischerweise wird dies bestimmt, indem die Position des Zeigers und auch das visuelle Layout von Elementen in einem Dokument auf Bildschirmen in Betracht gezogen werden.

Eine hardwareunabhängige Darstellung von Eingabegeräten, die auf bestimmte Koordinaten (oder einen Satz von Koordinaten) auf einem Bildschirm zielen können. Beispiele für Zeiger-Eingabegeräte sind Maus, Stift/Stylus und Berührungskontakte.

Zeigererfassung ermöglicht das Umleiten der Ereignisse für einen Zeiger auf ein bestimmtes Element abseits des normalen Treffer-Test-Ergebnisses der Position des Zeigers. Für ein Beispiel siehe Erfassung des Zeigers.

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

Die primäre Schnittstelle ist die PointerEvent-Schnittstelle, die einen Konstruktor sowie mehrere Ereignistypen und zugehörige globale Ereignishandler besitzt.

Der Standard umfasst 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

Repräsentiert den Winkel zwischen der Achse eines Transducers (einem Zeiger oder Stylus) und der X-Y-Ebene eines Gerätebildschirms.

azimuthAngle Schreibgeschützt

Repräsentiert den Winkel zwischen der Y-Z-Ebene und der Ebene, die sowohl die Achse des Transducers (einem Zeiger 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 erzeugt.

pointerId Schreibgeschützt

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

width Schreibgeschützt

Die Breite (Magnitude entlang der X-Achse) in CSS-Pixeln der Kontaktgeometrie des Zeigers.

height Schreibgeschützt

Die Höhe (Magnitude entlang 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 und maximalen Druck darstellen, den die Hardware erkennen kann.

tangentialPressure Schreibgeschützt

Der normalisierte tangentiale Druck der Zeigereingabe (auch bekannt als Barreldruck oder Zylinderstress) im Bereich von -1 bis 1, wobei 0 die neutrale Position der Steuerung darstellt.

tiltX Schreibgeschützt

Der Flächenwinkel (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 Stift-Stylus) als auch die Y-Achse enthält.

tiltY Schreibgeschützt

Der Flächenwinkel (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 Stift-Stylus) als auch die X-Achse enthält.

twist Schreibgeschützt

Die Drehung im Uhrzeigersinn des Zeigers (z. B. eines Stift-Stylus) 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 Hauptzeiger dieses Zeigertyps darstellt.

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

Nachfolgend eine kurze Beschreibung jedes Ereignistyps.

Es gibt drei Erweiterungen der Element-Schnittstelle:

hasPointerCapture()

Gibt an, ob das Element, auf dem es aufgerufen wird, für die durch die angegebene Zeiger-ID identifizierte Zeigererfassung aktiv ist.

releasePointerCapture()

Gibt die Zeigererfassung frei (stoppt sie), die zuvor für ein bestimmtes Zeigereignis festgelegt wurde.

setPointerCapture()

Bestimmt ein bestimmtes Element als Erfassungsziel für zukünftige Zeigereignisse.

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

Dieser Abschnitt enthält Beispiele zur grundlegenden Verwendung der Schnittstellen von Zeigereignissen.

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 veranschaulicht den Zugriff auf alle Eigenschaften eines Zeigereignisses.

<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 einen Zeiger, der mehrere Kontaktpunkte unterstützt (zum Beispiel ein Touchscreen, der Mehrfingereingaben 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 Zeigereignisse ignorieren, die nicht primär sind.

Eine Maus hat nur einen Zeiger, daher wird sie 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 Benutzer den Bildschirm zuerst kontaktiert hat, als es keine anderen aktiven Stifte mehr auf dem Bildschirm gab.

Einige Zeigegeräte (wie Maus und Stift) unterstützen mehrere Tasten, und das Drücken von Tasten kann kombiniert werden (d.h. das Drücken einer zusätzlichen Taste, während eine andere Taste auf dem Zeigegerät bereits gedrückt ist).

Um den Zustand der Tastendrücke zu bestimmen, verwenden Zeigereignisse die button- und buttons-Eigenschaften der MouseEvent-Schnittstelle (von der PointerEvent erbt).

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

Zeigererfassung ermöglicht das Umleiten von Ereignissen für ein bestimmtes Zeigereignis auf ein bestimmtes Element statt des normalen Treffer-Tests an der Position eines Zeigers. Dies kann verwendet werden, um sicherzustellen, dass ein Element weiterhin Zeigereignisse erhält, auch wenn der Kontakt des Zeigegeräts das Element verlässt (zum Beispiel durch Scrollen oder Schwenken).

Zeigererfassung bewirkt, dass das Ziel alle nachfolgenden Zeigereignisse erfasst, als würden sie über dem erfassten Ziel auftreten. Dementsprechend werden pointerover, pointerenter, pointerleave und pointerout nicht ausgelöst, solange diese Erfassung eingestellt ist. Bei Touchscreen-Browsern, die direkte Manipulation erlauben, wird eine implizite Zeigererfassung auf das Element aufgerufen, wenn ein pointerdown-Ereignis ausgelöst wird. Die Erfassung kann manuell durch das Aufrufen von element.releasePointerCapture auf dem Zuelelement freigegeben werden, oder sie wird automatisch 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);
}

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

document.addEventListener("DOMContentLoaded", init);

Das folgende Beispiel zeigt, wie eine Zeigererfassung 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 CSS-Eigenschaft touch-action wird verwendet, um anzugeben, ob der Browser sein standardmäßiges (natürliches) Touch-Verhalten (wie Zoomen oder Schwenken) auf eine Region anwenden soll oder nicht. Diese Eigenschaft kann auf alle Elemente angewendet werden, außer: nicht ersetzten Inline-Elementen, Tabellenreihen, Zeilengruppen, Tabellenspalten und Spaltengruppen.

Ein Wert von auto bedeutet, dass der Browser frei ist, sein standardmäßiges Touch-Verhalten (auf die angegebene Region) anzuwenden, und der Wert von none deaktiviert das standardmäßige 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 für horizontales und vertikales Scrollen bestimmt sind. Der Wert manipulation bedeutet, dass der Browser Touches, die auf dem Element beginnen, nur für Scrollen und Zoomen in Betracht ziehen kann.

Im folgenden Beispiel ist das standardmäßige Touch-Verhalten des Browsers für das div-Element deaktiviert.

<html lang="en">
  <body>
    <div style="touch-action:none;">Can't touch this…</div>
  </body>
</html>

Im folgenden Beispiel ist das standardmäßige 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 geschwenkt.

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

Obwohl die Zeigereignis-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 Mauskontrolle ausgelegt ist. Folglich muss selbst wenn ein Browser Zeigereignisse unterstützt, der Browser dennoch Mausereignisse verarbeiten, damit Inhalte, die nur Maus-Eingaben voraussetzen, ohne direkte Modifikation funktionieren. Idealerweise sollte eine Zeiger-fähige Anwendung Maus-Eingaben nicht explizit verarbeiten müssen. Da der Browser jedoch Mausereignisse verarbeiten muss, können einige Kompatibilitätsprobleme auftreten, die gehandhabt werden müssen. Dieser Abschnitt enthält Informationen über die Interaktion zwischen Zeigereignissen und Mausereignissen sowie die Konsequenzen für Anwendungsentwickler.

Der Browser kann generische Zeigereingaben auf Mausereignisse für die Kompatibilität mit Maus-basierendem Inhalt abbilden. Diese Abbildung von Ereignissen wird Kompatibilitäts-Mausereignisse genannt. Autoren können die Erzeugung bestimmter Kompatibilitäts-Mausereignisse verhindern, indem sie das pointerdown-Ereignis abbrechen, jedoch beachten Sie, dass:

• Mausereignisse nur verhindert werden können, wenn der Zeiger nach unten gerichtet 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 nie verhindert (auch wenn der Zeiger nach unten gerichtet ist).

Hier sind einige beste Praktiken, die bei der Verwendung von Zeigereignissen zu beachten sind:

• Minimieren Sie die Menge der Arbeit, die in Ereignishandlern ausgeführt wird.
• Fügen Sie die Ereignishandler einem spezifischen Zielelement hinzu (anstatt dem gesamten Dokument oder Knoten höher im Dokumentbaum).
• Das Zielelement (Knoten) sollte groß genug sein, um die größte Kontaktfläche (typischerweise eine Fingerberührung) unterzubringen. Wenn der Zielbereich zu klein ist, könnte ihn zu berühren dazu führen, dass Ereignisse für angrenzende Elemente ausgelöst werden.

• Touch/pointer tests and demos (by Patrick H. Lauke)

• Pointer Events Working Group
• Mail-Liste
• W3C #pointerevents IRC-Kanal

• Touch Events Standard