Referenz der Embed API

Jeder Befehl und jedes Ereignis der Icon Map Embed API, generiert aus dem TypeScript-Vertrag des SDK. Jeder Befehl ist eine Methode an dem Handle, das embed() zurückgibt, und wird mit dem angegebenen Ergebnis aufgelöst oder mit einem EmbedError abgelehnt, dessen code einer der Fehlercodes ist.

Ein mit read gekennzeichneter Befehl benötigt zusätzlich den Schalter Read state and events des Autors. Die hier genannten Typen (EmbedCamera, EmbedScene ...) werden von @iconmap/embed exportiert.

Befehle

Sitzung

Immer verfügbar, sobald eine Sitzung geöffnet ist. Unterliegt nicht der Richtlinie des Autors.

Befehl Argumente Wird aufgelöst mit Hinweise
ping - { protocol: number; uptimeMs: number } Hin und zurück zum Viewer. Nützlich als Lebenszeichenprüfung und um eine frühere asynchrone Nachricht abklingen zu lassen.
getCapabilities - EmbedCapabilities Erneut der Capability-Deskriptor (dasselbe Objekt, mit dem ready aufgelöst wurde).
setToken { token: string } - Ein frisches Einbettungstoken übergeben, bevor das alte abläuft (siehe tokenExpiring). Nur veröffentlichte Karten.
setLanguage { language: string } - Die Anzeigesprache wechseln. Nur eine Sprache aus capabilities.map.locales; alles andere wird mit invalid_args abgelehnt, nie stillschweigend ersetzt.

Kamera

Die Ansicht bewegen und auslesen. Richtliniengruppe: camera.

Befehl Argumente Wird aufgelöst mit Hinweise
getView - EmbedViewState read Die Kamera und die sichtbaren Grenzen.
setView Partial<EmbedCamera> & { animate?: boolean } - Beliebige Werte aus center / zoom / bearing / pitch setzen. Springt, sofern animate nicht true ist.
flyTo Partial<EmbedCamera> & { durationMs?: number; curve?: number } - Ein animierter Flug zu einer Kameraposition.
fitBounds { bounds: EmbedBounds; padding?: EmbedPadding; maxZoom?: number; animate?: boolean; pitch?: number; bearing?: number } - Einen Begrenzungsrahmen einpassen. pitch / bearing sind die Werte, auf denen die Kamera landet; ohne sie behält sie ihre aktuelle Neigung (übergeben Sie nach einem geneigten Flug pitch: 0, bearing: 0 für einen flachen, nach Norden ausgerichteten Ausschnitt).
fitLayer { layerId: string; padding?: EmbedPadding; maxZoom?: number; pitch?: number; bearing?: number } - Die Daten einer Ebene in ihrem aktuell gefilterten Zustand einpassen. unknown_id, wenn die Ebene keine Ausdehnung hat. pitch / bearing wie bei fitBounds.
zoomBy { delta: number; animate?: boolean } - Um ein Delta hinein- oder herauszoomen, begrenzt auf den Zoombereich der Karte.
resize - - Der Karte mitteilen, dass sich die Größe ihres Containers geändert hat (nachdem Sie das übergeordnete Element des Frames angepasst haben).
setMaxBounds { bounds: EmbedBounds | null } - Das Verschieben auf einen Rahmen beschränken; null hebt die Beschränkung auf.

Ebenen und Sichtbarkeit

Ein- und ausblenden, was der Autor veröffentlicht hat. Nur Sichtbarkeit, niemals Styling. Richtliniengruppe: layers.

Befehl Argumente Wird aufgelöst mit Hinweise
getLayers - EmbedLayerInfo[] read Die Ebenen der Karte: ID, Name, Art und ob jede gerade angezeigt wird.
getVisibility - EmbedVisibility read Jeder Schalter der Szene, vollständig befüllt: Ebenen, Beschriftungen und Featuregruppen der Grundkarte, Tag-Nacht-Grenze, Schummerung, Visuals.
setVisibility EmbedVisibility { skipped: string[] } | void Einen teilweisen Sichtbarkeits-Snapshot anwenden; was Sie weglassen, bleibt unverändert. Unbekannte IDs werden übersprungen und gemeldet. Das Ausblenden eines Datenschnitts schaltet ihn AUS, wie in einem Lesezeichen: Seine Auswahl filtert nicht mehr, bis er wieder angezeigt wird. Um die Karte zu filtern, ohne eine Kachel des Datenschnitts zu zeigen, verwenden Sie die Gruppe filters (setFilters).
setLayerVisibility { layerId: string; visible: boolean } - Eine Ebene ein- oder ausblenden.
resetVisibility - - Jeden Schalter auf den vom Autor veröffentlichten Zustand zurücksetzen.
getVisuals - EmbedVisualInfo[] read Die Diagramme, Datenschnitte, Textfelder und anderen Visuals auf der Karte, mit ihrer Sichtbarkeit.
getLayerStats { layerId: string } { layerId: string; visibleFeatureCount: number } read Wie viele Features die Ebene gerade enthält, nach Filtern und Datenschnitten.

Deklarierte Filter

Werte für die Filter, die der Autor auf der Karte deklariert hat. Nur veröffentlichte Karten. Richtliniengruppe: filters.

Befehl Argumente Wird aufgelöst mit Hinweise
getFilterSchema - EmbedFilterSchemaEntry[] read Die vom Autor deklarierten Filter: Name, Typ, Operatoren, Standardwert. Bauen Sie daraus Ihre eigene Filteroberfläche.
getFilters - EmbedFilterValues read Die aktuell angewendeten Filterwerte.
setFilters EmbedFilterValues - Die Filterwerte ersetzen. Ein Name, den der Autor nicht deklariert hat, führt zur Ablehnung mit undeclared_filter, bevor irgendetwas angewendet wird.
updateFilters { operation: EmbedFilterOperation; filters?: EmbedFilterValues; display?: Record<string, EmbedFilterDisplay> } - Einzelne Filter hinzufügen, ersetzen oder entfernen, wie in Power BI, mit optionalen Anzeigeeinstellungen pro Filter (locked, hidden, displayName).
clearFilters - - Alle Filterwerte des Hosts entfernen.

Daten

Live-Abfragen erneut ausführen. Nur veröffentlichte Karten. Richtliniengruppe: data.

Befehl Argumente Wird aufgelöst mit Hinweise
refreshData { bindingIds?: string[] } | void { refreshed: string[] } Live-Abfragen am Ergebniscache vorbei erneut ausführen. Wird mit den aktualisierten Bindungs-IDs aufgelöst (leer bei einer Snapshot-Karte).

Datenschnitte

Die Datenschnitte des Betrachters steuern. Richtliniengruppe: slicers.

Befehl Argumente Wird aufgelöst mit Hinweise
getSlicers - EmbedSlicerInfo[] read Die Datenschnitte der Karte und ihr aktueller Zustand.
getSlicerValues { slicerId: string; search?: string } { values: unknown[]; truncated: boolean } read Die Werte, die ein Listen-Datenschnitt anbietet, optional durch einen Suchbegriff eingegrenzt. Funktioniert auch für einen ausgeblendeten Datenschnitt.
setSlicerState { slicerId: string; state: EmbedSlicerState } - Die Auswahl eines Datenschnitts setzen, genau so, als hätte der Betrachter es getan.
clearSlicer { slicerId: string } - Einen Datenschnitt zurücksetzen.
clearAllSlicers - - Alle Datenschnitte zurücksetzen.

Auswahl und Hervorhebung

Features auswählen, Diagramme kreuzfiltern, hervorheben ohne auszuwählen. Richtliniengruppe: selection.

Befehl Argumente Wird aufgelöst mit Hinweise
getSelection - EmbedSelection read Die ausgewählten Feature-Schlüssel, nach Ebenen-ID.
setSelection EmbedSelection { skipped: string[] } | void Die Auswahl ersetzen. Unbekannte Ebenen-IDs werden übersprungen und gemeldet.
clearSelection - - Die Auswahl aufheben.
selectByKey { layerId: string; keys: Array<string | number>; field?: string; zoomTo?: boolean } { matched: number } Features über Ihre eigenen Schlüssel auswählen: Mit field werden die Schlüssel mit den Werten dieses Felds abgeglichen („Anlage 41B“); ohne sind es Feature-Schlüssel, wie featureClick sie gemeldet hat. zoomTo passt das Ergebnis ein. Höchstens 500 Schlüssel. field muss eine Spalte sein, die die veröffentlichte Karte enthält. Eine veröffentlichte Karte enthält nur die Spalten, die sie verwendet (QuickInfos, Styling, Beschriftungen, Datenschnitte). Eine Schlüsselspalte, die sonst nirgends verwendet wird, ist also nicht vorhanden und findet nichts: Der Autor fügt sie den QuickInfo-Feldern der Ebene hinzu.
getChartSelection - Record<string, EmbedChartDatum[]> read Die in jedem Diagramm ausgewählten Datenpunkte (der Kreuzfilter der Karte), nach Diagramm-ID.
setChartSelection { chartId: string; datums: EmbedChartDatum[] } - Datenpunkte in einem Diagramm auswählen, was die Karte wie ein Klick kreuzfiltert.
clearChartSelection { chartId?: string } | void - Die Auswahl eines Diagramms oder aller Diagramme aufheben.
closePopups - - Das Feature-Popup schließen, falls eines geöffnet ist.
highlight { layerId: string; keys: Array<string | number>; field?: string } { matched: number } Vorübergehende Hervorhebung: stellt keys auf layerId als ausgewählt dar, OHNE die Auswahl zu ändern. Kein Popup, keine Bereichseingrenzung, kein selectionChanged. Der nächste Klick eines Betrachters ersetzt sie. Mit field werden die Schlüssel wie bei selectByKey über dieses Feld aufgelöst.
clearHighlight - - Eine mit highlight gesetzte Hervorhebung entfernen.

Szenen, Lesezeichen und Touren

Den gesamten Sitzungszustand erfassen und wiederherstellen. Richtliniengruppe: scenes.

Befehl Argumente Wird aufgelöst mit Hinweise
captureScene { include?: Array<keyof EmbedScene>; opaque?: boolean } | void EmbedScene | { state: string } read Der gesamte Sitzungszustand als ein serialisierbares Objekt: Kamera, Sichtbarkeit, Datenschnitte, Filter, Auswahl, Grundkarte. Speichern Sie es oder machen Sie mit sceneToUrl einen Link daraus.
applyScene { scene: EmbedScene | { state: string }; animate?: boolean } { skipped: string[] } Eine erfasste Szene wiederherstellen. IDs, die die Karte nicht mehr hat, werden übersprungen und gemeldet, sodass eine Szene eine erneute Veröffentlichung übersteht.
resetScene - - Alles auf den vom Autor veröffentlichten Zustand zurücksetzen.
getBookmarks - EmbedBookmarkInfo[] read Die Lesezeichen des Autors. Leer, sofern der Autor beim Veröffentlichen der Karte nicht festgelegt hat, Lesezeichen anzubieten.
applyBookmark { bookmarkId: string; animate?: boolean } - Ein Lesezeichen auf demselben Weg anwenden, den die Lesezeichenleiste verwendet.
getTours - EmbedTourInfo[] read Die Touren des Autors.
playTour { tourId: string } - Eine Tour starten. Kameraereignisse, die während der Wiedergabe ausgelöst werden, enthalten reason: "tour".
stopTour - - Die laufende Tour anhalten.

Darstellung

Grundkarte, Bedienelemente, Design, Legende, Bildexport. Richtliniengruppe: presentation.

Befehl Argumente Wird aufgelöst mit Hinweise
getBasemaps - EmbedBasemapInfo[] read Die Grundkarten, die der Autor für diese Karte veröffentlicht hat, und welche aktiv ist.
setBasemap { basemapId: string } - Zu einer der veröffentlichten Grundkarten wechseln. Einen eigenen Stil zu laden ist nicht möglich.
setChrome EmbedChromeSettings - Die eigenen Bedienelemente der Karte aus- oder einblenden (Legende, Ebenensteuerelement, Popups, Lesezeichenleiste, Tour-Steuerung, Suche). Ein Schalter kann ein vom Autor konfiguriertes Bedienelement ausblenden, aber keines hinzufügen, das er nicht konfiguriert hat.
setTheme EmbedThemeSettings - Hell, dunkel oder der Karte folgen.
setBackground { background: "default" | "transparent" } - Die Seite hinter der Karte transparent machen, damit Ihr eigener Hintergrund durchscheint.
getLegend - EmbedLegendEntry[] read Die Legende im aktuell dargestellten Zustand, als Daten. Bauen Sie Ihre eigene Legende außerhalb des Frames.
getMapInfo - EmbedMapInfo read Die Beschreibung der Karte: Titel, Beschreibung, Datenmodus, Sprachen und die Quellenangabe, die Sie anzeigen müssen, wenn Sie unsere Bedienelemente ausblenden.
print - - Den Druckdialog des Browsers für die Karte öffnen. Wird mit denied_capability abgelehnt, wenn eine Vertraulichkeitsbezeichnung keinen Export zulässt.
exportImage EmbedExportImageArgs | void EmbedExportedImage read Ein PNG oder JPEG der Karte, wie der Betrachter sie sieht, als Daten-URL. Wird mit denied_capability abgelehnt, wenn eine Vertraulichkeitsbezeichnung keinen Export zulässt.

Befehle im Popup-Menü

Dem Feature-Popup eigene Aktionen hinzufügen. Richtliniengruppe: commands.

Befehl Argumente Wird aufgelöst mit Hinweise
addMenuCommand EmbedMenuCommand - Dem Feature-Popup eine eigene Aktion hinzufügen. Nur ein reiner Text-Titel und eine ID gelangen in den Frame, niemals HTML oder Skript. Ein Klick darauf löst menuCommandTriggered aus.
removeMenuCommand { id: string } - Eine von Ihnen hinzugefügte Popup-Aktion entfernen.
getMenuCommands - Array<{ id: string; title: string }> read Die Popup-Aktionen, die Sie hinzugefügt haben.

Analyse

Die Analyse-Engine einer Ebene ausführen, sofern eine Karte eine hat. Richtliniengruppe: analysis.

Befehl Argumente Wird aufgelöst mit Hinweise
getAnalysisOps - EmbedAnalysisOp[] read Die Analyseoperationen, die diese Karte beantwortet, jeweils mit Ebene und Hinweisen zu den Argumenten. Leer, wenn die Karte keine Analyse-Engine hat.
runAnalysis { op: string; layerId?: string; args?: Record<string, unknown> } EmbedAnalysisResult Eine Analyseoperation ausführen. Pro Ebene läuft jeweils eine; bis zu 4 warten (darüber hinaus busy); 60 pro Minute und Sitzung (budget_exceeded). Große Ergebnisse werden gekappt und als truncated markiert.
getClock { layerId?: string } | void EmbedClockState | null read Die Simulationsuhr einer Analyseebene oder null, wenn sie keine hat.
setClock { simSeconds: number; layerId?: string } EmbedClockState Die Simulationsuhr einer Analyseebene verstellen.

Nur am Handle

Diese laufen in Ihrer Seite, nicht in der Karte, und erscheinen daher nie in capabilities.commands.

Member Funktion
ready Ein Promise für den Capability-Deskriptor. Wird mit denied_origin abgelehnt, wenn Ihr Ursprung nicht zugelassen ist.
capabilities, protocol Was dieser Viewer beantwortet, sobald bekannt.
on(name, handler) / off(name) Ein Ereignis abonnieren; on gibt eine Funktion zum Abbestellen zurück.
render(options) Eine verzögerte Einbettung abschließen (deferRender: true).
reload() Den Frame neu laden. Abonnements werden wiederhergestellt, wenn die neue Sitzung geöffnet ist.
fullscreen() / exitFullscreen() Den Frame im Vollbild anzeigen. Aus einem Klick-Handler aufrufen: Browser verlangen eine Benutzeraktion auf Ihrer Seite.
destroy() Den Frame entfernen und alles, was noch unterwegs ist, mit destroyed ablehnen.
iframe Das eingebundene <iframe>-Element.

Ereignisse

Es wird nichts gesendet, bis Sie ein Abonnement einrichten (handle.on(name, handler) oder die Option events). Jedes Ereignis enthält eine sitzungsweite seq; eine Lücke bedeutet, dass eines verworfen wurde. Zustandsereignisse enthalten einen reason ("user", "command", "bookmark", "tour", "scene" oder "load"), damit eine Synchronisierung in beide Richtungen ihr eigenes Echo ignorieren kann.

Ereignis Nutzdaten Hinweise
loaded - Die Karte wurde dargestellt (das onLoad aus v1).
rendered { durationMs: number } Erstes Bild im Leerlauf: Die eigenen Daten der Karte sind auf dem Bildschirm. durationMs gilt ab dem Start des Frames.
viewChanged EmbedViewState & { reason: EmbedChangeReason } Die Kamera ist zur Ruhe gekommen (oder hat sich mit continuousView bewegt). Gedrosselt; der letzte Wert kommt immer an.
visibilityChanged { visibility: EmbedVisibility; reason: EmbedChangeReason } Ein Schalter für eine Ebene, ein Visual oder die Grundkarte hat sich geändert.
filtersChanged { filters: EmbedFilterValues; reason: EmbedChangeReason } Die Filterwerte des Hosts haben sich geändert.
slicerChanged { slicerId: string; state: EmbedSlicerState; reason: EmbedChangeReason } Die Auswahl eines Datenschnitts hat sich geändert.
selectionChanged { selection: EmbedSelection; reason: EmbedChangeReason } Die Auswahl hat sich geändert.
featureClick EmbedFeatureClick | null Der Betrachter hat auf ein Feature geklickt (null = auf eine leere Stelle der Karte geklickt). fields enthält nur die QuickInfo-Felder der Ebene, also das, was der Betrachter ohnehin sehen kann.
featureHover EmbedFeatureClick | null Der Zeiger hat ein Feature erreicht (null = verlassen). Nur aktiv, wenn Sie es abonnieren; im Abstand von mindestens 100 ms, und ein Verlassen wird nie verzögert.
linkClicked { url: string; layerId?: string; featureKey?: string | number; buttonId?: string } Ein Hyperlink oder eine Link-Schaltfläche wurde angeklickt, wenn hyperlinkBehavior den Wert raiseEvent oder navigateAndRaiseEvent hat. Leiten Sie ihn innerhalb Ihrer eigenen App weiter.
menuCommandTriggered { commandId: string; layerId: string; featureKey: string | number; fields: Record<string, unknown> } Der Betrachter hat eine Popup-Aktion gewählt, die Sie mit addMenuCommand hinzugefügt haben.
chartSelectionChanged { chartId: string; datums: EmbedChartDatum[]; reason: EmbedChangeReason } Die ausgewählten Datenpunkte eines Diagramms haben sich geändert.
bookmarkApplied { bookmarkId: string } Ein Lesezeichen wurde angewendet: vom Betrachter, von einer Tour oder von Ihnen.
tourStateChanged { tourId: string | null; state: "started" | "keyframe" | "ended" } Eine Tour wurde gestartet, hat einen Keyframe erreicht oder ist beendet.
basemapChanged { basemapId: string } Die aktive Grundkarte hat sich geändert.
themeChanged { mode: string } Das Design hat sich geändert.
dataStateChanged { state: "loading" | "ready" | "stale" | "error"; bindingIds?: string[]; reason?: string } Livedaten werden geladen, sind bereit, sind veraltet oder sind fehlgeschlagen.
tokenExpiring { expiresInMs: number } Das Einbettungstoken läuft in expiresInMs ab (60 s vorher ausgelöst). Antworten Sie mit setToken.
error EmbedErrorInfo Ein Viewer-Fehler, nachdem die Sitzung geöffnet wurde.
viewerResized { width: number; height: number } Die Größe des Kartencontainers hat sich geändert.
analysisResult EmbedAnalysisResult & { reason: EmbedChangeReason } Eine Analyseoperation ist abgeschlossen, egal ob der Betrachter geklickt oder der Host sie angefordert hat.
clockChanged EmbedClockState & { reason: EmbedChangeReason } Die Engine-Uhr einer Analyseebene hat sich bewegt (gedrosselt, EMBED_LIMITS.clockIntervalMs).

Fehlercodes

Code Bedeutung
unsupported_protocol Viewer und SDK haben keine gemeinsame Protokollversion.
unsupported_command Dieser Viewer-Build, diese Art der Einbettung oder diese Karte beantwortet den Befehl nicht. Prüfen Sie zuerst capabilities.commands.
denied_capability Der Autor der Karte hat die Gruppe des Befehls (oder den Lesezugriff) nicht aktiviert, oder eine Vertraulichkeitsbezeichnung verweigert einen Export.
denied_origin Der Ursprung Ihrer Seite steht nicht unter den zulässigen Ursprüngen der Karte, daher wurde keine Steuerungssitzung geöffnet.
invalid_args Die Argumente haben die Validierung nicht bestanden. message nennt das betroffene.
not_ready Der Teil der Karte, den der Befehl benötigt, war nicht innerhalb von 10 Sekunden verfügbar. Früh gesendete Befehle werden zurückgehalten, nicht abgelehnt; dies bedeutet also, dass die Karte nicht starten konnte. Prüfen Sie onError.
unknown_id Eine ID einer Ebene, eines Lesezeichens, einer Tour, eines Datenschnitts, eines Diagramms, einer Grundkarte oder einer Analyseoperation, die diese Karte nicht hat.
undeclared_filter setFilters hat einen Filter genannt, den der Autor nicht deklariert hat. detail.undeclared listet sie auf.
rate_limited Mehr als 60 Befehle in einer Sekunde, oder das Ratenlimit des Backends bei einer Datenaktualisierung.
budget_exceeded Das Analysebudget pro Sitzung oder das Abfragebudget der Veröffentlichung ist aufgebraucht.
too_large Die Befehlsnachricht hat EMBED_LIMITS.maxCommandBytes überschritten.
busy Auf dieser Ebene warten bereits zu viele Analysebefehle.
data_error Das Backend konnte eine Datenanfrage nicht ausführen. Geben Sie requestId in einer Supportanfrage an.
auth_required Das Einbettungstoken fehlt, ist abgelaufen oder wurde abgelehnt. Geben Sie getToken an oder rufen Sie setToken auf.
timeout Der Viewer hat nicht innerhalb des Befehls-Timeouts geantwortet (SDK-seitig).
destroyed Das Handle wurde zerstört oder der Frame neu geladen, während der Befehl unterwegs war (SDK-seitig).
internal Der Befehl hat unerwartet eine Ausnahme ausgelöst. detailedMessage enthält die Ursache.

Limits

Vom Viewer festgelegt (EMBED_LIMITS im SDK). Ein Host kann sie nicht erhöhen, ein Autor kann sie nicht senken.

Limit Wert
Größte Befehlsnachricht 64 KB; größere werden mit too_large abgelehnt
Größte Nutzdaten eines Ereignisses 32 KB; größere werden verworfen (Sie sehen eine Lücke in seq)
Schlüssel in einem highlight / selectByKey 500
IDs in einem Analyseergebnis 1000, danach truncated: true
Zeilen in einem Analyseergebnis 200, danach truncated: true
Analysebefehle pro Sitzung 60 pro Minute, danach budget_exceeded
Analysebefehle, die auf einer Ebene warten 4, danach busy
Abstand von featureHover 100 ms (der letzte Wert kommt immer an)
Abstand von clockChanged 250 ms (der letzte Wert kommt immer an)
Befehle pro Sekunde 60, danach rate_limited