Événements

Les événements informent votre page de ce qui se passe dans la carte. Ils sont à la demande : la carte n'envoie rien tant que vous ne vous êtes pas abonné, si bien qu'une incorporation qui se contente d'afficher une carte ne coûte rien de plus.

S'abonner

const stop = map.on("viewChanged", (view) => { /* ... */ });
stop();                        // remove this handler
map.off("viewChanged");        // remove every handler for the event

Vous pouvez vous abonner avant que la carte soit prête, et nommer des événements au montage pour ne rien manquer pendant le démarrage :

embed(el, { publishId, events: ["rendered", "featureClick"] });

Les abonnements survivent à map.reload().

reason : éviter les boucles d'écho

Si votre page et la carte se reflètent mutuellement (une liste qui suit la carte, une URL qui stocke la vue), chacune de vos propres commandes vous revient sous forme d'événement. Sans précaution, cela tourne en boucle.

Chaque événement d'état indique donc pourquoi il s'est produit :

Une synchronisation bidirectionnelle tient donc en une ligne :

map.on("viewChanged", (v) => { if (v.reason === "user") writeViewToUrl(v); });

Les événements que vous utiliserez le plus

viewChanged

Déclenché lorsque la caméra se stabilise, avec la même forme que celle renvoyée par getView(), plus reason. Par défaut, vous recevez un événement par geste, au plus toutes les 200 ms. Ces deux comportements sont réglables :

embed(el, { publishId, events: ["viewChanged"], subscribeOptions: { viewChangedThrottleMs: 500 } });
embed(el, { publishId, events: ["viewChanged"], subscribeOptions: { continuousView: true } });   // while moving, too

La dernière position arrive toujours, quelle que soit la vitesse des mouvements du lecteur.

featureClick

map.on("featureClick", (f) => {
  if (!f) return closeMyPanel();            // the reader clicked empty map
  // f = { layerId, layerName, featureKey, fields, lngLat }
});

fields contient les champs que la couche affiche dans son info-bulle, c'est-à-dire ce que le lecteur voit déjà, et rien d'autre. Si vous avez besoin d'une autre colonne pour effectuer une jointure, demandez à l'auteur de la carte de l'ajouter à l'info-bulle de la couche. featureKey reste stable pendant toute la durée de vie de la publication et c'est la valeur qu'acceptent selectByKey et highlight.

featureHover a la même forme, et vaut null lorsque le pointeur quitte l'entité. Il est espacé d'au moins 100 ms ; une sortie n'est jamais retardée, vous ne croirez donc pas à tort que le pointeur survole encore quelque chose.

selectionChanged, slicerChanged, filtersChanged, visibilityChanged

Chacun porte le nouvel état et une reason. Utilisez-les pour garder vos propres contrôles à jour lorsque le lecteur utilise ceux de la carte :

map.on("visibilityChanged", ({ visibility }) => {
  for (const [id, on] of Object.entries(visibility.layers ?? {})) myToggles[id].checked = on;
});

linkClicked

Les cartes peuvent contenir des liens hypertexte et des boutons de lien. Par défaut, un clic déclenche la navigation. Pour le gérer plutôt dans votre application, définissez le comportement au montage :

const map = embed(el, { publishId, hyperlinkBehavior: "raiseEvent", events: ["linkClicked"] });
map.on("linkClicked", ({ url, layerId, featureKey, buttonId }) => router.push(toMyRoute(url)));

"navigateAndRaiseEvent" fait les deux.

menuCommandTriggered

Déclenché lorsque le lecteur choisit une action que vous avez ajoutée avec addMenuCommand.

analysisResult

Déclenché lorsqu'une opération d'analyse se termine, qu'elle ait été lancée par votre page ou par le lecteur. Voir Analyse.

loaded, rendered, dataStateChanged

loaded signifie que la carte est opérationnelle ; rendered signifie que sa première image est à l'écran, avec durationMs mesuré depuis le démarrage du cadre, utile pour votre propre suivi des performances. dataStateChanged signale les états des données en direct loading, ready, stale ou error.

tokenExpiring

Pour les cartes protégées par jeton, déclenché une minute avant l'expiration du jeton d'intégration. Répondez avec setToken. Voir Prise en main.

error

Problèmes survenus après l'ouverture de la session. Les échecs au démarrage sont transmis à l'option onError et font rejeter ready.

Ordre et événements perdus

Chaque événement porte un seq qui augmente de un pendant toute la durée de la session. Le SDK le gère pour vous ; il n'a d'importance que si vous journalisez les événements et constatez un trou, signe qu'un événement a été perdu. La carte n'abandonne un événement plutôt que d'en envoyer un incomplet que dans un seul cas : une charge utile de plus de 32 KB.

La séquence redémarre lorsque le cadre est rechargé.

La liste complète

Chaque événement, avec le type de sa charge utile, figure dans la référence de l'API. La carte vous indique aussi quels événements elle peut déclencher, dans capabilities.events.