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

CKTIS / JavaScript

Element.setPointerCapture — capturer un pointeur

La méthode setPointerCapture(pointerId) dirige les événements suivants d’un pointeur donné vers un élément choisi, même lorsque le pointeur quitte ses limites. Elle facilite les opérations de glissement à la souris, au toucher ou au stylet.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

element.setPointerCapture(pointerId)

Appelez Element.setPointerCapture sur un élément, généralement dans un gestionnaire pointerdown, en lui passant event.pointerId. La capture remplace la sélection normale de la cible selon la position, de sorte que l’élément continue de recevoir, par exemple, les événements pointermove en dehors de ses limites. La méthode renvoie undefined ; elle ne déplace ni ne verrouille le curseur.

L’appel établit une capture en attente : hasPointerCapture(pointerId) peut renvoyer true immédiatement, avant même gotpointercapture. releasePointerCapture(pointerId) libère explicitement la capture ; après pointerup ou pointercancel, le navigateur la libère automatiquement. Utilisez lostpointercapture pour nettoyer l’état de l’interaction. Le toucher peut déjà disposer d’une capture implicite.

Un identifiant qui ne correspond à aucun pointeur actif provoque NotFoundError. Un élément déconnecté ou un Pointer Lock actif dans son document provoque InvalidStateError. Ce n’est qu’après avoir vérifié l’identifiant du pointeur, la connexion de l’élément et l’état de Pointer Lock que la méthode examine les autres conditions : s’il n’y a ni bouton enfoncé ni contact, ou si le document de l’élément n’est pas le document actif du pointeur, la méthode n’établit pas de capture et ne déclenche pas d’erreur.

La capture ne désactive ni le défilement ni le zoom par toucher ; l’exemple utilise touch-action: none uniquement sur sa zone de démonstration. Il s’agit d’une API de navigateur définie par Pointer Events, et non d’une fonctionnalité d’une édition particulière d’ECMAScript. La présence de Node 24 ne garantit pas sa disponibilité : vérifiez la méthode et testez les navigateurs ciblés.

Exemples

const pad = document.createElement('div');
pad.textContent = 'Press, move outside, release';
pad.style.cssText = 'width:220px;height:100px;background:lightblue;touch-action:none;user-select:none';
const log = document.createElement('pre');
document.body.append(pad, log);

if (typeof pad.setPointerCapture !== 'function') {
  log.textContent = 'unsupported';
} else {
  let activeId = null;
  pad.addEventListener('pointerdown', (event) => {
    if (activeId !== null) return;
    pad.setPointerCapture(event.pointerId);
    activeId = event.pointerId;
    log.textContent = `pending: ${pad.hasPointerCapture(activeId)}`;
  });
  pad.addEventListener('pointermove', (event) => {
    if (event.pointerId === activeId) {
      log.textContent = 'moving';
    }
  });
  pad.addEventListener('lostpointercapture', (event) => {
    if (event.pointerId === activeId) {
      activeId = null;
      log.textContent = 'released';
    }
  });
}

Résultat

released

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources