Eventos

Os eventos informam à sua página o que está acontecendo no mapa. Eles são opcionais: o mapa não envia nada até que você se inscreva, então uma incorporação que só exibe um mapa não tem custo extra.

Inscrição

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

Você pode se inscrever antes de o mapa estar pronto e pode indicar eventos na montagem, para que nada se perca durante a inicialização:

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

As inscrições sobrevivem a map.reload().

reason: como evitar loops de eco

Se a sua página e o mapa espelham um ao outro (uma lista que acompanha o mapa, uma URL que guarda a vista), cada comando seu volta para você como um evento. Sem cuidado, isso vira um loop.

Por isso, todo evento de estado informa por que aconteceu:

Assim, uma sincronização bidirecional cabe em uma linha:

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

Os eventos que você mais vai usar

viewChanged

É disparado quando a câmera se estabiliza, com o mesmo formato que getView() retorna, mais reason. Por padrão, você recebe um evento por gesto, no máximo a cada 200 ms. Os dois comportamentos são ajustáveis:

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

A última posição sempre chega, por mais rápido que o leitor se mova.

featureClick

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

fields contém os campos que a camada mostra na dica de ferramenta (o que o leitor já pode ver) e nada mais. Se você precisar de outra coluna para fazer uma junção, peça ao autor do mapa que a adicione à dica de ferramenta da camada. featureKey é estável durante toda a vida da publicação e é o que selectByKey e highlight aceitam.

featureHover tem o mesmo formato e vale null quando o ponteiro sai. Os eventos têm um intervalo mínimo de 100 ms; uma saída nunca é atrasada, então você não vai ficar achando que o ponteiro ainda está sobre algo.

selectionChanged, slicerChanged, filtersChanged, visibilityChanged

Cada um traz o novo estado e um reason. Use-os para manter seus próprios controles fiéis quando o leitor usar os do mapa:

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

linkClicked

Os mapas podem conter hiperlinks e botões de link. Por padrão, um clique navega. Para tratá-lo dentro do seu aplicativo, defina o comportamento na montagem:

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

"navigateAndRaiseEvent" faz as duas coisas.

menuCommandTriggered

Gerado quando o leitor escolhe uma ação que você adicionou com addMenuCommand.

analysisResult

Gerado quando uma operação de análise termina, seja ela executada pela sua página ou pelo leitor. Veja Análise.

loaded, rendered, dataStateChanged

loaded significa que o mapa está ativo; rendered significa que o primeiro quadro dele está na tela, com durationMs desde o início do frame, útil para o seu próprio monitoramento de desempenho. dataStateChanged informa o estado dos dados ao vivo: loading, ready, stale ou error.

tokenExpiring

Para mapas protegidos por token, é disparado um minuto antes de o token de incorporação expirar. Responda com setToken. Veja Introdução.

error

Problemas depois que a sessão foi aberta. As falhas de inicialização vão para a opção onError e fazem ready ser rejeitado.

Ordem e eventos descartados

Todo evento traz um seq que aumenta de um em um durante a vida da sessão. O SDK cuida disso para você; só importa se você registrar os eventos e notar uma lacuna, o que significa que um foi descartado. O mapa descarta um evento, em vez de enviar um evento corrompido, em um único caso: um payload acima de 32 KB.

A sequência recomeça quando o frame é recarregado.

A lista completa

Todos os eventos, com o tipo de payload de cada um, estão na referência da API. O mapa também informa quais eventos pode gerar em capabilities.events.