Ereignisse

Ereignisse teilen Ihrer Seite mit, was in der Karte passiert. Sie sind Opt-in: Die Karte sendet nichts, bis Sie ein Abonnement einrichten. Eine Einbettung, die nur eine Karte anzeigt, verursacht also keinen Mehraufwand.

Abonnieren

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

Sie können abonnieren, bevor die Karte bereit ist, und Ereignisse schon beim Einbinden angeben, damit beim Start nichts verloren geht:

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

Abonnements bleiben über map.reload() hinweg bestehen.

reason: Echo-Schleifen vermeiden

Wenn Ihre Seite und die Karte einander spiegeln (eine Liste, die der Karte folgt, eine URL, die die Ansicht speichert), kommt jeder Ihrer eigenen Befehle als Ereignis zu Ihnen zurück. Ohne Vorsicht entsteht eine Schleife.

Jedes Zustandsereignis sagt deshalb, warum es eingetreten ist:

Eine Synchronisierung in beide Richtungen ist damit eine einzige Zeile:

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

Die Ereignisse, die Sie am häufigsten verwenden

viewChanged

Wird ausgelöst, wenn die Kamera zur Ruhe kommt, mit derselben Form, die getView() liefert, plus reason. Standardmäßig erhalten Sie ein Ereignis pro Geste, höchstens alle 200 ms. Beides lässt sich anpassen:

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

Die letzte Position kommt immer an, egal wie schnell sich der Betrachter bewegt.

featureClick

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

fields enthält die Felder, die die Ebene in ihrer QuickInfo zeigt (also das, was der Betrachter ohnehin sehen kann), und sonst nichts. Wenn Sie eine weitere Spalte zum Verknüpfen benötigen, bitten Sie den Autor der Karte, sie der QuickInfo der Ebene hinzuzufügen. featureKey ist für die Lebensdauer der Veröffentlichung stabil und wird von selectByKey und highlight akzeptiert.

featureHover hat dieselbe Form und ist null, wenn der Zeiger das Feature verlässt. Die Ereignisse folgen im Abstand von mindestens 100 ms; ein Verlassen wird nie verzögert, sodass Sie nie fälschlich annehmen, der Zeiger befinde sich noch über etwas.

selectionChanged, slicerChanged, filtersChanged, visibilityChanged

Jedes davon liefert den neuen Zustand und einen reason. Verwenden Sie sie, um Ihre eigenen Bedienelemente aktuell zu halten, wenn der Betrachter die der Karte benutzt:

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

linkClicked

Karten können Hyperlinks und Link-Schaltflächen enthalten. Standardmäßig navigiert ein Klick. Um ihn stattdessen in Ihrer Anwendung zu behandeln, legen Sie das Verhalten beim Einbinden fest:

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

"navigateAndRaiseEvent" macht beides.

menuCommandTriggered

Wird ausgelöst, wenn der Betrachter eine Aktion wählt, die Sie mit addMenuCommand hinzugefügt haben.

analysisResult

Wird ausgelöst, wenn eine Analyseoperation abgeschlossen ist, egal ob Ihre Seite sie ausgeführt hat oder der Betrachter. Siehe Analyse.

loaded, rendered, dataStateChanged

loaded bedeutet, dass die Karte läuft; rendered bedeutet, dass ihr erstes Bild auf dem Bildschirm ist, mit durationMs ab dem Start des Frames. Nützlich für Ihr eigenes Performance-Monitoring. dataStateChanged meldet für Livedaten loading, ready, stale oder error.

tokenExpiring

Wird bei Karten mit Token-Schutz eine Minute vor Ablauf des Einbettungstokens ausgelöst. Antworten Sie mit setToken. Siehe Erste Schritte.

error

Probleme, nachdem die Sitzung geöffnet wurde. Fehler beim Start gehen stattdessen an die Option onError und führen dazu, dass ready abgelehnt wird.

Reihenfolge und verworfene Ereignisse

Jedes Ereignis enthält eine seq, die über die Lebensdauer der Sitzung um jeweils eins steigt. Das SDK kümmert sich darum; relevant ist sie nur, wenn Sie Ereignisse protokollieren und eine Lücke sehen. Das bedeutet, dass eines verworfen wurde. Die Karte verwirft ein Ereignis, statt ein fehlerhaftes zu senden, in genau einem Fall: bei Nutzdaten über 32 KB.

Die Sequenz beginnt neu, wenn der Frame neu geladen wird.

Die vollständige Liste

Jedes Ereignis mit seinem Nutzdatentyp finden Sie in der API-Referenz. Welche Ereignisse die Karte auslösen kann, teilt sie Ihnen außerdem in capabilities.events mit.