getCoalescedEvents CDP : Qu'est-ce que c'est ?

Vous voulez comprendre la méthode JavaScript `getCoalescedEvents()` ? Elle sert à récupérer des mouvements de curseur que le navigateur fusionne pour gagner en performance.

Ce guide vous explique comment l’utiliser pour un suivi précis, avec un exemple de code.

Syntaxe et utilisation

La méthode `getCoalescedEvents()` appartient à l’interface `PointerEvent`. Elle ne fonctionne que dans un contexte sécurisé, c’est-à-dire sur un site en HTTPS.

Syntaxe

L’appel est direct depuis un objet `event` de type `PointerEvent`.

event.getCoalescedEvents();

Paramètres

Cette fonction ne prend aucun paramètre.

Valeur de retour

La méthode retourne une séquence (un tableau) d’instances `PointerEvent`. Ce tableau contient tous les `events` qui ont été fusionnés dans l’événement `pointermove` principal.

Exemple d’implémentation pratique

Le meilleur moyen de comprendre est de visualiser. Le code suivant permet de voir la différence entre les `pointermove events` classiques et les `coalesced events` récupérés.

Code HTML

Il suffit d’un simple élément `

<canvas id="target" width="600" height="300"></canvas>

Code JavaScript

Ce script va dessiner deux types de cercles : un pour l’événement principal et un autre pour les événements fusionnés.

const canvas = document.getElementById("target");
const ctx = canvas.getContext("2d");

const pointerEvents = [];

function drawCircle(x, y, color) {
  ctx.clearRect(0, 0, canvas.width, canvas.height);

  // draw the last 20 events
  if (pointerEvents.length > 20) {
    pointerEvents.shift();
  }
  pointerEvents.push({ x, y, color });

  for (const pointerEvent of pointerEvents) {
    ctx.beginPath();
    ctx.arc(pointerEvent.x, pointerEvent.y, 10, 0, 2 * Math.PI);
    ctx.strokeStyle = pointerEvent.color;
    ctx.stroke();
  }
}

canvas.addEventListener("pointermove", (e) => {
  // draw a circle for the current event
  drawCircle(e.clientX, e.clientY, "black");

  const coalescedEvents = e.getCoalescedEvents();
  for (let coalescedEvent of coalescedEvents) {
    // give it an offset so we can see the difference and color it red
    drawCircle(coalescedEvent.clientX + 20, coalescedEvent.clientY + 20, "red");
  }
});

Explication du résultat

Quand vous exécutez ce code et bougez la souris sur le canvas, voici ce qui se passe :

Un cercle noir est dessiné à chaque fois que le navigateur envoie un événement `pointermove`.
Le script appelle ensuite `e.getCoalescedEvents()` pour récupérer les `events` intermédiaires.
Pour chaque `coalesced event`, un cercle rouge est dessiné avec un petit décalage.

Vous verrez que lors de mouvements rapides et larges (`fast and large movements`), beaucoup de cercles rouges apparaissent entre deux cercles noirs. Cela montre visuellement tous les points de passage que le navigateur aurait ignorés sans cette méthode. On récupère ainsi toute la granularité du mouvement.

Pourquoi getCoalescedEvents est-il nécessaire ? Le contexte historique

Pour comprendre l’intérêt de `getCoalescedEvents`, il faut revenir sur le fonctionnement de l’event handling des mouvements de curseur.

Avant, les événements comme `mousemove` ou `pointermove` pouvaient être déclenchés très souvent, parfois plus vite que la fréquence de rafraîchissement de l’écran (généralement 60 Hz). Pour les `applications` qui devaient mettre à jour le `DOM` à chaque mouvement, c’était un problème de performance. Le navigateur se retrouvait à calculer des mises à jour qui n’allaient de toute façon pas être affichées à temps.

L’ancienne solution : `requestAnimationFrame`

Les développeurs ont adopté une technique avec `requestAnimationFrame` (rAF). Le principe était simple : l’écouteur d’événement (`addEventListener`) se contentait de stocker les coordonnées du pointeur. Puis, un callback `rAF` se chargeait de lire ces coordonnées et de mettre à jour l’affichage juste avant la prochaine « peinture » de l’écran. Ça évitait de bloquer l’interface utilisateur.

Mais même avec `rAF`, un problème persistait, surtout pour les `drawing applications` (applications de dessin). Le navigateur, pour optimiser les performances, fusionnait déjà plusieurs mouvements en un seul `pointermove event`. Résultat : on recevait peu de points de coordonnées. Si un `user` dessinait une courbe rapide, le tracé apparaissait anguleux, pas fluide. On perdait `the granularity and` la précision du geste.

Le fonctionnement détaillé de getCoalescedEvents

Les navigateurs modernes (d’abord Chrome, puis Firefox) ont changé leur approche pour régler ce souci. Deux modifications majeures ont été apportées.

Premièrement, les `pointermove events` sont maintenant alignés sur la fréquence de rafraîchissement. Le navigateur ne déclenche plus qu’un seul `pointermove` par frame, ce qui rend l’utilisation de `rAF` moins critique pour la performance pure, car le `event handling` est déjà optimisé.

Deuxièmement, la méthode `getCoalescedEvents` a été introduite. Elle est la solution au problème de précision. Elle permet de récupérer la liste de tous les `pointer events` qui se sont produits entre le `pointermove` précédent et celui en cours. Ces événements intermédiaires sont parfois appelés `pointerrawmove` et sont des instances `PointerEvent` plus légères.

Cette approche combine le meilleur des deux mondes :

Performance : Le code principal ne s’exécute qu’une fois par frame, sans surcharger le navigateur.
Précision : On a accès à tous les points de passage du curseur pour, par exemple, dessiner une ligne parfaitement lisse.

Pour l’intégrer, il suffit de vérifier si la `function` existe sur l’objet `event`. Ensuite, on boucle sur le tableau retourné par `the getCoalescedEvents method` pour traiter chaque point intermédiaire. C’est une bonne pratique, car tous les navigateurs ne supportent pas encore `this feature`.

Compatibilité des navigateurs

La prise en charge de `getCoalescedEvents` n’est pas encore universelle. Il faut donc être prudent lors de son utilisation.

Rappel important : La méthode `PointerEvent.getCoalescedEvents()` ne fonctionne que sur des pages servies en HTTPS. C’est une contrainte de sécurité.

Voici l’état actuel du support par les principaux navigateurs :

Chrome 74+ (Desktop & Mobile) : ✅ Supporté
Firefox 67+ (Desktop) : ✅ Supporté
Firefox 67+ (Mobile) : 🚫 Non supporté
Safari 12 & 13 : 🚫 Non supporté
Edge (anciennes versions) : 🚫 Non supporté
Internet Explorer 11 : 🚫 Non supporté

Pour des détails techniques plus poussés, vous pouvez consulter la Spécification Pointer Events officielle du W3C.

La méthode `PointerEvent.getCoalescedEvents()` est donc un outil très utile pour les `applications` web qui ont besoin d’une grande précision dans le suivi des mouvements du `pointer`. C’est le cas des outils de dessin, d’annotation ou de signature en ligne. Des produits comme PSPDFKit for Web l’utilisent pour garantir que les annotations manuscrites de `the user` soient aussi fluides et naturelles que possible.