Befehle

Jeder Befehl ist eine Methode am Handle, nimmt ein Argumentobjekt (oder keines) entgegen und gibt ein Promise zurück. Diese Seite geht die Befehle nach Bereichen durch, mit den Mustern, die in echten Portalen vorkommen. Die genauen Argument- und Ergebnistypen finden Sie in der API-Referenz.

Jeder Bereich ist eine Gruppe, die der Autor der Karte deaktivieren kann. Ist eine Gruppe deaktiviert, fehlen ihre Befehle in capabilities.commands und werden mit denied_capability abgelehnt.

Kamera

const view = await map.getView();
// { center: [lng, lat], zoom, bearing, pitch, bounds: [[west, south], [east, north]] }

await map.setView({ center: [-0.12, 51.5], zoom: 11 });              // jumps
await map.setView({ zoom: 13, animate: true });                      // eases; omitted fields stay put
await map.flyTo({ center: [2.35, 48.85], zoom: 9, durationMs: 2500 });
await map.fitBounds({ bounds: [[-5.4, 51.3], [-2.6, 53.5]], padding: 40 });
await map.fitLayer({ layerId: "depots", padding: 60, maxZoom: 14 }); // the layer's data as currently filtered
await map.zoomBy({ delta: 1 });
await map.setMaxBounds({ bounds: [[-8, 49], [2, 61]] });             // null removes the limit

Koordinaten sind immer [longitude, latitude]. padding ist eine Anzahl von Pixeln oder { top, right, bottom, left }. Verwenden Sie es, wenn ein Teil der Karte unter Ihrem eigenen Overlay liegt.

fitBounds und fitLayer behalten die Neigung der Kamera bei, sofern Sie nicht angeben, wo sie landen soll. Übergeben Sie nach einem geneigten flyTo pitch: 0, bearing: 0 für einen flachen, nach Norden ausgerichteten Ausschnitt:

await map.fitLayer({ layerId: "depots", padding: 60, pitch: 0, bearing: 0 });

Wenn Sie die Größe des Elements ändern, in dem die Karte liegt, teilen Sie es ihr mit:

new ResizeObserver(() => map.resize()).observe(container);

Ebenen und Sichtbarkeit

const layers = await map.getLayers();
// [{ id, name, kind, visible, groupId?, legendVisible?, hasData }]

await map.setLayerVisibility({ layerId: "depots", visible: false });

Ebenen sind nur eines der Dinge, die ein Betrachter ein- und ausschalten kann. getVisibility liefert alle, und setVisibility nimmt eine beliebige Teilmenge entgegen. Was Sie weglassen, bleibt unverändert:

await map.setVisibility({
  layers: { depots: false, routes: true },
  labels: false,                       // basemap place labels
  hillshade: true,
  visuals: { "chart-sales": false },   // charts, slicers, text boxes ... by visual id
});

await map.resetVisibility();           // back to what the author published

IDs, die eine Karte nicht mehr hat, werden übersprungen und als { skipped: [...] } zurückgegeben, statt als Fehler behandelt zu werden. Code, der für eine Veröffentlichung geschrieben wurde, funktioniert so auch mit der nächsten.

:::note Ein ausgeblendeter Datenschnitt ist ausgeschaltet Die Sichtbarkeit funktioniert wie in einem Lesezeichen: Ein ausgeblendeter Datenschnitt ist ausgeschaltet, seine Auswahl filtert also nicht mehr, bis er wieder angezeigt wird. Wenn Ihre Seite die Filteroberfläche bereitstellt und die Karte keine Datenschnittkacheln zeigen soll, filtern Sie mit deklarierten Filtern (setFilters) statt über ausgeblendete Datenschnitte. :::

getLayerStats({ layerId }) sagt Ihnen, wie viele Features eine Ebene nach Filtern und Datenschnitten enthält. Praktisch für eine Beschriftung wie „n Ergebnisse“.

:::note Ebenen, die beim Veröffentlichen ausgeschaltet sind Eine veröffentlichte Karte enthält auch die Daten ausgeschalteter Ebenen. So kann Ihre Seite eine solche Ebene mit setLayerVisibility einblenden, und das Ebenensteuerelement und die Lesezeichen der Karte funktionieren so, wie der Autor sie entworfen hat. Der Autor kann eine ausgeblendete Ebene weglassen (Publish > Include data for the layers that are switched off); eine solche Ebene wird leer veröffentlicht: Beim Einschalten zeigt sie nichts, und getLayerStats meldet 0.

Karten, die vor Einführung dieser Option (September 2026) veröffentlicht wurden, enthalten keine Daten für Ebenen, die damals ausgeschaltet waren. Eine erneute Veröffentlichung nimmt sie auf. :::

Datenschnitte

Datenschnitte sind die Bedienelemente für Betrachter, die der Autor auf der Karte platziert hat. Einen davon zu steuern ist genau dasselbe, als würde der Betrachter ihn benutzen: Alles, was daran gebunden ist, folgt.

const slicers = await map.getSlicers();
// [{ id, name, kind, field, state }]

const { values } = await map.getSlicerValues({ slicerId: "slicer-region", search: "wa" });
await map.setSlicerState({ slicerId: "slicer-region", state: { values: ["Wales"] } });
await map.clearSlicer({ slicerId: "slicer-region" });
await map.clearAllSlicers();

Die Form von state hängt von der kind des Datenschnitts ab, die getSlicers() meldet. null setzt einen Datenschnitt zurück.

getSlicerValues antwortet auch für einen ausgeblendeten Datenschnitt. Eine Seite, die ihre eigene Filteroberfläche zeichnet, kann die Werte also trotzdem auflisten.

In Aktion: Mit Datenschnitten filtern.

Für Filter, die Ihnen gehören und nicht dem Betrachter, verwenden Sie stattdessen deklarierte Filter.

Auswahl und Hervorhebung

Das Muster, das die meisten Portale wollen, ist eine Liste auf der Seite und eine Karte daneben, die sich gegenseitig steuern.

Von der Karte zu Ihrer Seite: Abonnieren Sie featureClick. Das Ereignis liefert den Schlüssel des Features und die Felder, die die Ebene in ihrer QuickInfo zeigt:

map.on("featureClick", (f) => f && list.scrollTo(f.featureKey));

Von Ihrer Seite zur Karte: selectByKey. Mit field übergeben Sie Ihre Bezeichner, und die Karte findet die Features; ohne field sind die Schlüssel die featureKey-Werte, die featureClick Ihnen geliefert hat.

await map.selectByKey({ layerId: "assets", field: "asset_id", keys: ["41B", "41C"], zoomTo: true });
// -> { matched: 2 }

Eine Auswahl verhält sich wie ein Klick: Das Feature wird hervorgehoben, auf die Auswahl bezogene Bereiche und Diagramme folgen, und selectionChanged wird ausgelöst.

:::note Die Schlüsselspalte muss veröffentlicht sein 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 enthalten, und selectByKey mit diesem field findet nichts ({ matched: 0 }). Der Autor der Karte veröffentlicht einen Schlüssel, indem er ihn der Ebene unter QuickInfo-Felder hinzufügt. Dasselbe gilt für highlight. :::

Hover ohne Auswahl: highlight stellt Features als ausgewählt dar, ohne die Auswahl zu ändern: kein Popup, keine Bereiche, kein Ereignis. Es ist für das Überfahren von Listeneinträgen gedacht.

row.onmouseenter = () => map.highlight({ layerId: "assets", keys: [row.dataset.key] });
row.onmouseleave = () => map.clearHighlight();

Der nächste Klick eines Betrachters auf die Karte ersetzt eine Hervorhebung. Ein Aufruf kann bis zu 500 Schlüssel enthalten.

Diagramme kreuzfiltern die Karte, wenn ein Betrachter auf einen Balken oder ein Segment klickt. Dasselbe können Sie auch:

await map.setChartSelection({ chartId: "chart-sales", datums: [{ category: "North" }] });
await map.clearChartSelection();

Szenen, Lesezeichen und Touren

captureScene und applyScene speichern die gesamte Ansicht in einem Objekt und stellen sie wieder her. Sie haben eine eigene Seite.

Darstellung

Lassen Sie die Karte wie einen Teil Ihrer Anwendung aussehen.

const basemaps = await map.getBasemaps();          // the ones the author published
await map.setBasemap({ basemapId: basemaps[1].id });

await map.setTheme({ mode: "dark" });              // "light" | "dark" | "auto"
await map.setBackground({ background: "transparent" });

await map.setChrome({ legend: false, layerControl: false, bookmarksBar: false });

:::note Ein transparenter Hintergrund auf einer dunklen Seite background: "transparent" lässt Ihre Seite überall durchscheinen, wo die Karte nichts zeichnet, zum Beispiel im Raum um einen Globus. Wenn Ihre Seite color-scheme: dark deklariert, geben Sie dem Frame zusätzlich das Farbschema der Karte:

#map iframe { color-scheme: light; }

Wenn sich das Farbschema eines Frames von dem seiner Seite unterscheidet, zeichnen Browser einen deckenden Hintergrund hinter den Frame. Ohne diese Angabe bleibt der Hintergrund also weiß, und die Option scheint wirkungslos. :::

setChrome kann ein vom Autor konfiguriertes Bedienelement ausblenden, aber keines hinzufügen, das er nicht konfiguriert hat. Die Schalter sind legend, layerControl, clickPopups, selection, bookmarksBar, tourTransport und search.

Wenn Sie die Legende ausblenden, bauen Sie Ihre eigene aus demselben Modell, das die Karte darstellt:

const legend = await map.getLegend();
// [{ layerId, title, sections: [{ caption, items: [{ kind, label, color, stops? ... }] }] }]

Sprache. setLanguage({ language: "de" }) wechselt die Anzeigesprache. Akzeptiert wird nur eine Sprache, die in capabilities.map.locales aufgeführt ist.

Vollbild läuft in Ihrer Seite und nicht in der Karte, weil Browser es dort nur als Reaktion auf eine Benutzeraktion zulassen. Rufen Sie es aus einem Klick-Handler auf:

button.onclick = () => map.fullscreen();

Bildexport und Drucken

const image = await map.exportImage({ width: 1600 });            // PNG by default
// { dataUrl, width, height, format }

const jpeg = await map.exportImage({ format: "jpeg", quality: 0.85 });
await map.print();

Das Bild zeigt die Karte genau so, wie der Betrachter sie in diesem Moment sieht. Die Höhe folgt dem Seitenverhältnis des Frames, sofern Sie keine angeben.

Tragen Daten hinter der Karte eine Vertraulichkeitsbezeichnung, die keinen Export zulässt, werden beide Befehle mit denied_capability abgelehnt. Erlaubt eine Bezeichnung den Export mit einer Warnung, enthält das Ergebnis labelVerdict: "warn", damit Sie einen eigenen Hinweis anzeigen können. Wie Icon Map mit Vertraulichkeitsbezeichnungen umgeht, lesen Sie unter Sicherheit und Berechtigungen.

Befehle im Popup-Menü

Fügen Sie dem Popup, das ein Betrachter beim Klick auf ein Feature sieht, eine eigene Aktion hinzu:

await map.addMenuCommand({ id: "raise-job", title: "Raise a job for this asset", layerIds: ["assets"] });

map.on("menuCommandTriggered", ({ commandId, layerId, featureKey, fields }) => {
  if (commandId === "raise-job") openJobForm(fields.asset_id);
});

Nur die ID und ein reiner Text-Titel gelangen in die Karte, niemals HTML oder Skript. Lassen Sie layerIds weg, um die Aktion auf jeder Ebene anzubieten.

Analyse

Manche Karten haben auf einer Ebene eine Analyse-Engine, zum Beispiel ein Wassernetz, das ab einem Rohrbruch eine Verfolgung durchführen kann. Wo eine vorhanden ist, können Sie sie ausführen und ihre Ergebnisse empfangen.

const ops = await map.getAnalysisOps();
// [{ op: "traceAt", layerId: "network", kind: "waterNetwork", description, args: { lng: "number", lat: "number" } }]

const { result, truncated } = await map.runAnalysis({
  op: "traceAt",
  layerId: "network",
  args: { lng: -3.66, lat: 51.62 },
});

Die Operationen und ihre Argumente gehören zur Engine. Ermitteln Sie sie daher mit getAnalysisOps(), statt sie fest zu codieren. Auf einer Karte ohne Engine liefert der Befehl eine leere Liste.

Ob Sie die Operation ausgeführt haben oder der Betrachter per Klick, analysisResult wird mit denselben Nutzdaten ausgelöst. Ein einziger Handler deckt also beides ab:

map.on("analysisResult", ({ op, result, reason }) => {
  if (op === "traceAt") customerList.replace(result.affectedServiceIds);
});

Analysen sind kontingentiert, damit eine Seite die Karte nicht überlasten kann: Pro Ebene läuft jeweils eine Operation, vier weitere können warten (danach busy), und eine Sitzung erhält 60 pro Minute (budget_exceeded). Große Ergebnisse werden gekappt (1.000 IDs oder 200 Zeilen pro Liste) und als truncated markiert.

Ebenen mit einer Simulationsuhr stellen diese über getClock / setClock und das Ereignis clockChanged bereit.