Pointer events

Der Zustand, wenn ein Zeiger einen Nicht-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 eine Taste gedrückt ist, während der Stift schwebt.

Jedes Zeiger Eingabegerät, das Ereignisse auslösen kann. Ein Zeiger wird als aktiv betrachtet, wenn er weiterhin Ereignisse auslösen kann. Zum Beispiel wird ein Stift, der sich im Abwärtszustand befindet, als aktiv betrachtet, da er zusätzliche Ereignisse auslösen kann, wenn der Stift angehoben oder bewegt wird.

Ein Erfassungsgerät mit einer Oberfläche, die Kontakt erkennen kann. Am häufigsten handelt es sich um einen Touch-fähigen Bildschirm, der Eingaben von einem Eingabegerät wie einem Stift, Stylus oder Finger erfassen kann. Einige Erfassungsgeräte können die Nähe des Eingabegeräts erkennen, und der Zustand wird als Schweben in der Nähe der Maus ausgedrückt.

Der Prozess, den der Browser verwendet, um ein Zielelement für ein Zeigerereignis zu bestimmen. Typischerweise wird dies bestimmt, indem der Standort des Zeigers und das visuelle Layout von Elementen in einem Dokument auf Bildschirmmedien berücksichtigt werden.

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

Die Zeigererfassung erlaubt es, die Ereignisse für einen Zeiger auf ein bestimmtes Element umzuverteilen, anstatt auf das normale Ergebnis des Treffertests des Zeigerstandorts. Sehen Sie sich Den Zeiger erfassen für ein Beispiel an.

Anmerkung: Zeigererfassung ist etwas anderes als Zeigersperre, die physisch verhindert, dass der Zeiger einen Bereich verlässt.

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

Das primäre Interface ist das PointerEvent Interface, welches einen Konstruktor plus mehrere Ereignistypen und zugehörige globale Ereignishandler hat.

Der Standard enthält außerdem einige Erweiterungen für die Element und Navigator Interfaces.

Die folgenden Unterabschnitte enthalten kurze Beschreibungen jedes Interfaces und jeder Eigenschaft.

Das PointerEvent Interface erweitert das MouseEvent Interface und hat die folgenden Eigenschaften.

altitudeAngle Schreibgeschützt

Stellt den Winkel zwischen der Achse des Wandlers (Ein Zeiger 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 (Ein 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 hat.

pointerId Schreibgeschützt

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

width Schreibgeschützt

Die Breite (Ausdehnung auf der X-Achse), in CSS-Pixeln, der Kontaktgeometrie des Zeigers.

height Schreibgeschützt

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

tangentialPressure Schreibgeschützt

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

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

twist Schreibgeschützt

Die im Uhrzeigersinn gerichtete Rotation des Zeigers (z.B. 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, etc.).

isPrimary Schreibgeschützt

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

Zeigerereignisse haben zehn Ereignistypen, von denen sieben ähnliche Semantik wie ihre Mausereignisgegenstücke haben (down, up, move, over, out, enter und leave).

Unten ist eine kurze Beschreibung jedes Ereignistyps.

Es gibt drei Erweiterungen des Element Interfaces:

hasPointerCapture()

Zeigt an, ob das Element, auf dem die Methode aufgerufen wird, die Zeigererfassung für den durch die Angabe identifizierten Zeiger hat.

releasePointerCapture()

Gibt (stoppt) die Zeigererfassung frei, die zuvor für ein spezifisches Zeigerereignis festgelegt wurde.

setPointerCapture()

Bezeichnet ein bestimmtes Element als Erfassungsziel für zukünftige Zeigerereignisse.

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

Dieser Abschnitt enthält Beispiele für die grundlegende Verwendung der Zeigerereignis-Interfaces.

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

<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 (z.B. ein Gerät mit einem Touchscreen und einer Maus), oder ein 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 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, daher wird es immer der primäre Zeiger sein. Für Berührungseingaben wird ein Zeiger als primär angesehen, wenn der Benutzer den Bildschirm berührte, als es keine anderen aktiven Berührungen gab. Für Stift- und Stylus-Eingaben wird ein Zeiger als primär angesehen, wenn der Benutzerstift den Bildschirm berührt hat, als es keine anderen aktiven Stifte gab.

Einige Zeigegeräte (wie Maus und Stift) unterstützen mehrere Tasten, und die Tastenpressen können akkordiert werden (d.h. durch Drücken einer zusätzlichen Taste, während eine andere Taste am Zeigegerät bereits gedrückt ist).

Um den Status der Tastenpressen zu bestimmen, verwenden Zeigerereignisse die button und buttons Eigenschaften der MouseEvent Interface (von denen PointerEvent erbt).

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

Die Zeigererfassung ermöglicht es, dass Ereignisse für ein bestimmtes Zeigerereignis auf ein bestimmtes Element umgeleitet werden, anstatt auf das normale Treffertest an der Position des Zeigers. Dies kann verwendet werden, um sicherzustellen, dass ein Element weiterhin Zeigerereignisse erhält, auch wenn der Kontakt des Zeigegeräts das Element verlässt (z.B. durch Scrollen oder Verschieben).

Die Zeigererfassung lässt das Ziel alle nachfolgenden Zeigerereignisse erfassen, als ob sie über dem erfassenden Ziel stattfinden würden. Dementsprechend werden pointerover, pointerenter, pointerleave und pointerout nicht ausgelöst, solange diese Erfassung aktiv ist. Für touch-fähige Browser, die direkte Manipulation erlauben, wird eine implizite Zeigererfassung auf dem Element ausgeführt, wenn ein pointerdown Ereignis auftritt. Die Erfassung kann manuell durch Aufrufen von element.releasePointerCapture auf dem Zielelement aufgehoben werden, oder wird nach einem pointerup oder pointercancel Ereignis automatisch aufgehoben.

Das folgende Beispiel zeigt, wie die Zeigererfassung auf einem Element festgelegt 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 eintritt). Der Browser macht dies automatisch, wenn ein pointerup oder pointercancel Ereignis eintritt.

<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 Standardverhalten (native) für Touch-Anwendungen (wie Zoomen oder Scrollen) auf eine Region anwenden soll oder nicht. Diese Eigenschaft kann auf alle Elemente angewendet werden außer: nicht-ersetzenbare Inline-Elemente, Tabellzeilen, Zeilengruppen, Tabellenspalten und Spaltengruppen.

Ein Wert von auto bedeutet, dass der Browser sein Standard-Touch-Verhalten auf die spezifizierte Region anwenden kann 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 spezifizierten Region beginnen, nur für horizontale beziehungsweise vertikale Bildläufe sind. Der Wert manipulation bedeutet, dass der Browser Berührungen, die auf dem Element beginnen, nur für Bildläufe und Zooms in Betracht ziehen kann.

Im folgenden Beispiel wird das Standard-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 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 Zeigerereignis-Interfaces Anwendungen ermöglichen, verbesserte Benutzererfahrungen auf zeigerfähigen Geräten zu erzeugen, ist die Realität, dass der Großteil der heutigen Webinhalte so entworfen ist, dass er nur mit Mauseingaben funktioniert. Folglich muss der Browser auch dann Mausereignisse verarbeiten, wenn er Zeigerereignisse unterstützt, damit Inhalte, die von Maus-Only-Eingaben ausgehen, ohne direkte Änderungen funktionieren. Idealerweise benötigt eine zeigerfähige Anwendung keine explizite Handhabung von Mauseingaben. Da der Browser Mausereignisse verarbeiten muss, können jedoch einige Kompatibilitätsprobleme auftreten, die behandelt werden müssen. Dieser Abschnitt enthält Informationen über die Interaktion zwischen Zeiger- und Mausereignissen und die Konsequenzen für Anwendungsentwickler.

Der Browser kann generische Zeigereingaben in Mausereignisse umwandeln, um die Kompatibilität mit mausbasierenden Inhalten zu gewährleisten. Diese Umwandlung von Ereignissen wird als Kompatibilitäts-Mausereignisse bezeichnet. Autoren können die Erstellung bestimmter Kompatibilitäts-Mausereignisse verhindern, indem sie das pointerdown-Ereignis stornieren, aber beachten Sie:

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

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

• Minimieren Sie die Menge der Arbeit, die in Ereignishandlern durchgefü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 Kontaktoberfläche (typischerweise eine Fingerberührung) unterzubringen. Wenn das Zielgebiet zu klein ist, könnte das Berühren dazu führen, dass andere Ereignisse für angrenzende Elemente ausgelöst werden.

• Touch/pointer Tests und Demos (von Patrick H. Lauke)

• Pointer Events Arbeitsgruppe
• Mail-Liste
• W3C #pointerevents IRC-Kanal

• Touch Events Standard