Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Capture du pointeur : valider ou abandonner un glissement

Suivez un glissement à l’aide de `pointerId` et terminez-le une seule fois : validez-le au relâchement ou abandonnez-le en cas d’annulation ou de perte anticipée de capture.

Version : Current web platform; runtime support varies

Syntaxe

// 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);

Au début du glissement, mémorisez le pointerId du pointeur accepté dans pointerdown. Cet évènement se déclenche lorsque le premier bouton de la souris est enfoncé ou qu’un doigt ou une pointe de stylet touche la surface. Ne mettez à jour l’état du glissement que pour les évènements pointermove portant cet identifiant. pointermove peut signaler un changement de position ou d’une autre propriété, comme la pression, et peut se produire en survol.

Appelez element.setPointerCapture(pointerId) pour continuer à suivre le glissement hors de l’élément. Un contact tactile direct peut activer la capture implicitement. Si vous devez la libérer plus tôt, utilisez releasePointerCapture(). Ces deux méthodes peuvent lever NotFoundError si l’identifiant ne correspond pas à un pointeur actif.

Validez le résultat sur pointerup : le doigt ou le stylet se soulève, ou le dernier bouton de souris enfoncé est relâché. Contrairement à mousedown et mouseup, pointerdown et pointerup ne se déclenchent pas à chaque changement de bouton. Abandonnez l’état temporaire sur pointercancel : le navigateur a interrompu l’interaction, par exemple pour prendre en charge un geste de défilement ou de zoom.

Dans les deux cas, effacez l’identifiant mémorisé pour que la libération automatique de la capture après pointerup ou pointercancel ne termine pas le glissement une deuxième fois. lostpointercapture signale la perte de capture, pas nécessairement la fin du contact. N’abandonnez le glissement que s’il est encore en cours et que l’évènement porte le même identifiant.

La capture ne bloque pas les gestes du navigateur : configurez-les au préalable avec la propriété CSS touch-action et limitez none à la zone qui en a besoin. Ces API relèvent de la plateforme web, pas d’ECMAScript 2024 ; leur disponibilité dépend de l’environnement d’exécution.

Exemples

<!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>

Résultat

pointerdown
pointermove
pointerup: commit

Enregistrez l’exemple dans un fichier HTML, ouvrez-le dans un navigateur et consultez la console de développement. Commencez le glissement dans le cadre avec le bouton principal de la souris, puis relâchez-le à l’extérieur sans maintenir Maj. Lors d’un autre glissement, amorcez le mouvement, puis maintenez Maj et continuez à déplacer la souris sans relâcher le bouton pour tester la perte anticipée de capture. La ligne `pointermove` apparaît au plus une fois par glissement.

Leçons associées

  • JavaScript · Leçon 35 · Intermédiaire · Version : 3

Sources