Eventos

Los eventos informan a su página de lo que ocurre en el mapa. Son opcionales: el mapa no envía nada hasta que se suscribe, de modo que una inserción que solo muestra un mapa no tiene ningún coste adicional.

Suscripción

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

Puede suscribirse antes de que el mapa esté listo, y puede indicar eventos al montarlo para no perderse nada durante el inicio:

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

Las suscripciones se mantienen tras map.reload().

reason: evitar bucles de eco

Si su página y el mapa se reflejan mutuamente (una lista que sigue al mapa, una URL que guarda la vista), cada uno de sus propios comandos le vuelve como evento. Sin cuidado, se produce un bucle.

Por eso, cada evento de estado indica por qué ocurrió:

Así, una sincronización bidireccional ocupa una línea:

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

Los eventos que más usará

viewChanged

Se desencadena cuando la cámara se detiene, con la misma forma que devuelve getView() más reason. De forma predeterminada recibe un evento por gesto, como máximo cada 200 ms. Ambos aspectos se pueden ajustar:

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

La última posición siempre llega, por rápido que se mueva el lector.

featureClick

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

fields contiene los campos que la capa muestra en su información sobre herramientas (lo que el lector ya puede ver) y nada más. Si necesita otra columna para combinar datos, pida al autor del mapa que la añada a la información sobre herramientas de la capa. featureKey es estable durante toda la vida de la publicación y es lo que aceptan selectByKey y highlight.

featureHover tiene la misma forma y null cuando el puntero sale. Los eventos se espacian al menos 100 ms; una salida nunca se retrasa, así que no creerá que el puntero sigue sobre algo cuando ya no lo está.

selectionChanged, slicerChanged, filtersChanged, visibilityChanged

Cada uno lleva el nuevo estado y un reason. Úselos para mantener fieles sus propios controles cuando el lector use los del mapa:

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

linkClicked

Los mapas pueden contener hipervínculos y botones de vínculo. De forma predeterminada, un clic navega. Para gestionarlo dentro de su aplicación, establezca el comportamiento al montar el mapa:

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

"navigateAndRaiseEvent" hace ambas cosas.

menuCommandTriggered

Se genera cuando el lector elige una acción que usted añadió con addMenuCommand.

analysisResult

Se genera cuando termina una operación de análisis, tanto si la ejecutó su página como el lector. Consulte Análisis.

loaded, rendered, dataStateChanged

loaded significa que el mapa está en marcha; rendered significa que su primer fotograma está en pantalla, con durationMs desde el inicio del marco, útil para su propia supervisión del rendimiento. dataStateChanged informa del estado de los datos en directo: loading, ready, stale o error.

tokenExpiring

En los mapas protegidos con token, se desencadena un minuto antes de que caduque el token de inserción. Responda con setToken. Consulte Introducción.

error

Problemas posteriores a la apertura de la sesión. Los errores de inicio van a la opción onError y hacen que ready se rechace.

Orden y eventos descartados

Cada evento lleva un seq que aumenta de uno en uno durante toda la sesión. El SDK lo gestiona por usted; solo importa si registra eventos y ve un hueco, lo que significa que se descartó uno. El mapa descarta un evento en lugar de enviar uno defectuoso en un único caso: una carga de más de 32 KB.

La secuencia se reinicia cuando se recarga el marco.

La lista completa

Todos los eventos, con el tipo de su carga, están en la referencia de la API. El mapa también le indica qué eventos puede generar en capabilities.events.