WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

Zeigererfassung: einen Ziehvorgang abschließen oder abbrechen

Verfolge einen Ziehvorgang anhand der `pointerId` und beende ihn nur einmal: Übernimm das Ergebnis beim Loslassen oder verwirf es bei einem Abbruch oder vorzeitigem Erfassungsverlust.

Version: Current web platform; runtime support varies

Syntax

// Handler sketch: supply the element and the five callbacks in your application.
element.addEventListener("pointerdown", onDown);
element.addEventListener("pointermove", onMove);
element.addEventListener("pointerup", onUp);
element.addEventListener("pointercancel", onCancel);
element.addEventListener("lostpointercapture", onLostCapture);

// In onDown, after accepting the pointer for the drag:
// element.setPointerCapture(event.pointerId);
// In onMove, only if the active drag should release capture early:
// element.releasePointerCapture(event.pointerId);

Speichere in pointerdown die pointerId des Zeigers, mit dem du den Ziehvorgang startest. Das Ereignis tritt auf, wenn die erste Maustaste gedrückt wird oder ein Finger bzw. eine Stiftspitze die Oberfläche berührt. Aktualisiere den Zustand nur bei pointermove-Ereignissen mit der gespeicherten ID. pointermove kann eine Positionsänderung oder eine Änderung etwa des Drucks melden und auch ohne Tastendruck oder Berührung auftreten.

Rufe element.setPointerCapture(pointerId) auf, um den Ziehvorgang auch außerhalb des Elements zu verfolgen. Direkte Berührung kann die Erfassung automatisch aktivieren. Wenn du sie vorzeitig freigeben musst, verwende releasePointerCapture(). Beide Methoden können NotFoundError auslösen, wenn die ID keinem aktiven Zeiger entspricht.

Übernimm das Ergebnis bei pointerup: Der Finger oder Stift wird angehoben, oder die letzte gedrückte Maustaste wird losgelassen. Anders als mousedown und mouseup werden pointerdown und pointerup nicht bei jeder Änderung einer Maustaste ausgelöst. Verwirf den vorläufigen Zustand bei pointercancel: Der Browser hat die Interaktion unterbrochen, etwa um eine Scroll- oder Zoomgeste zu übernehmen.

Lösche in beiden Fällen die gespeicherte ID, damit die automatische Freigabe nach pointerup oder pointercancel den Ziehvorgang nicht ein zweites Mal beendet. lostpointercapture meldet den Verlust der Erfassung, nicht unbedingt das Ende des Kontakts. Brich den Vorgang nur ab, wenn er noch läuft und das Ereignis dieselbe ID hat.

Die Erfassung blockiert keine Browsergesten: Lege die Gestenbehandlung vorab mit CSS touch-action fest und beschränke none auf den nötigen Bereich. Die APIs gehören zur Webplattform, nicht zu ECMAScript 2024; die Verfügbarkeit hängt von der Laufzeitumgebung ab.

Beispiele

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Drag with pointer capture</title>
  <style>
    #pad {
      position: fixed;
      top: 16px;
      left: 16px;
      z-index: 9999;
      width: 220px;
      height: 100px;
      padding: 12px;
      background: #def;
      color: #123;
      border: 2px solid #246;
      touch-action: none;
      user-select: none;
    }
  </style>
</head>
<body>
  <div id="pad">Start dragging here</div>
  <script>
    (() => {
      const pad = document.getElementById('pad');
      let activeId = null;
      let moved = false;

      pad.addEventListener('pointerdown', (event) => {
        if (activeId !== null || event.button !== 0) return;
        pad.setPointerCapture(event.pointerId);
        activeId = event.pointerId;
        moved = false;
        console.log('pointerdown');
      });

      pad.addEventListener('pointermove', (event) => {
        if (event.pointerId !== activeId) return;
        if (!moved) {
          moved = true;
          console.log('pointermove');
        }
        if (event.shiftKey && pad.hasPointerCapture(event.pointerId)) {
          pad.releasePointerCapture(event.pointerId);
        }
      });

      function finish(event, result) {
        if (event.pointerId !== activeId) return;
        activeId = null;
        console.log(`${event.type}: ${result}`);
      }

      pad.addEventListener('pointerup', (event) => finish(event, 'commit'));
      pad.addEventListener('pointercancel', (event) => finish(event, 'abort'));
      pad.addEventListener('lostpointercapture', (event) => finish(event, 'abort'));
    })();
  </script>
</body>
</html>

Ergebnis

pointerdown
pointermove
pointerup: commit

Speichere das Beispiel als HTML-Datei, öffne es im Browser und beobachte die Entwicklerkonsole. Beginne mit der primären Maustaste innerhalb des Felds und lass sie außerhalb los, ohne die Umschalttaste zu halten. Beginne bei einem zweiten Ziehvorgang erst mit der Bewegung, halte dann die Umschalttaste gedrückt und bewege die Maus bei weiterhin gedrückter Maustaste, um den vorzeitigen Erfassungsverlust zu testen. Die Zeile `pointermove` erscheint höchstens einmal pro Ziehvorgang.

Zugehörige Lektionen

  • JavaScript · Lektion 35 · Mittlere Stufe · Version: 3

Quellen