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

CKTIS / JavaScript

PointerEvent — événements de pointeur et capture

PointerEvent unifie les entrées de la souris, du tactile et du stylet. Découvrez comment les identifiants de pointeur, les coordonnées de la fenêtre, le cycle de vie d’une interaction et la capture facilitent l’implémentation du glisser-déposer.

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

new PointerEvent(type, options)
element.addEventListener('pointerdown', handler)
element.setPointerCapture(event.pointerId)
element.releasePointerCapture(event.pointerId)

PointerEvent est une interface Web API du navigateur qui hérite de MouseEvent et regroupe les entrées de la souris, du tactile et du stylet. Elle ne relève pas d’une édition particulière d’ECMAScript. Vérifiez sa disponibilité avec 'PointerEvent' in window ; la présence de Node 24 dans un dépôt ne prouve pas la prise en charge par le navigateur.

PointerEvent.pointerId identifie un pointeur actif ; les identifiants peuvent être réutilisés ultérieurement et ne sont pas des identifiants permanents d’appareil. PointerEvent.isPrimary désigne le pointeur principal de son type, et non un pointeur unique à l’échelle globale. La souris et le tactile peuvent donc avoir chacun un pointeur principal simultanément. PointerEvent.clientX et PointerEvent.clientY, hérités de MouseEvent, fournissent des coordonnées relatives à la fenêtre en pixels CSS, et non des coordonnées relatives à l’élément ou à l’origine du document.

Le cycle d’interaction comprend pointerdown, pointermove, puis une fin par pointerup ou pointercancel. Effacez également l’état de l’interaction en cas d’annulation, par exemple lorsque le navigateur prend en charge un geste. pointerover/pointerout et pointerenter/pointerleave décrivent les limites des éléments ; ils ne remplacent pas la fin de l’interaction.

Appeler element.setPointerCapture(event.pointerId) pendant un véritable pointerdown dirige les événements suivants de ce pointeur vers l’élément, même en dehors de ses limites. gotpointercapture et lostpointercapture signalent le début et la perte de la capture ; element.releasePointerCapture(event.pointerId) la libère explicitement. Elle est également libérée après pointerup ou pointercancel. Le tactile peut bénéficier d’une capture implicite. Gérez la perte de capture pour éviter qu’un glissement reste actif.

Pour des gestes personnalisés, déclarez le CSS touch-action approprié avant le début de l’interaction ; preventDefault() seul n’empêche ni le déplacement ni le zoom de la fenêtre. L’exemple déclenche volontairement des événements synthétiques : il vérifie les propriétés et le nettoyage de l’état, mais pas une entrée matérielle réelle ni la capture du pointeur.

Exemples

const target = document.createElement('div');
const active = new Map();
const lines = [];

for (const type of ['pointerdown', 'pointermove', 'pointerup', 'pointercancel']) {
  target.addEventListener(type, (event) => {
    const { pointerId, isPrimary, clientX, clientY } = event;
    if (type === 'pointerdown') active.set(pointerId, true);
    if (!active.has(pointerId)) return;
    lines.push(`${type} ${pointerId} ${isPrimary} ${clientX},${clientY}`);
    if (type === 'pointerup' || type === 'pointercancel') {
      active.delete(pointerId);
    }
  });
}

for (const [type, clientX, clientY] of [
  ['pointerdown', 10, 20],
  ['pointermove', 15, 25],
  ['pointerup', 15, 25]
]) {
  target.dispatchEvent(new PointerEvent(type, {
    pointerId: 7, pointerType: 'touch', isPrimary: true,
    clientX, clientY
  }));
}
console.log(lines.join('\n'));
console.log(`active=${active.size}`);

Résultat

pointerdown 7 true 10,20
pointermove 7 true 15,25
pointerup 7 true 15,25
active=0

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