Commandes

Chaque commande est une méthode du handle, accepte un objet d'arguments (ou aucun) et renvoie une promesse. Cette page les présente par domaine, avec les schémas d'utilisation que l'on rencontre dans de vrais portails. Pour les types exacts des arguments et des résultats, consultez la référence de l'API.

Chaque domaine est un groupe que l'auteur de la carte peut désactiver. Si un groupe est désactivé, ses commandes sont absentes de capabilities.commands et sont rejetées avec denied_capability.

Caméra

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

Les coordonnées sont toujours au format [longitude, latitude]. padding est un nombre de pixels ou { top, right, bottom, left } : utilisez-le lorsqu'une partie de la carte se trouve sous votre propre superposition.

fitBounds et fitLayer conservent l'inclinaison de la caméra, sauf si vous indiquez où elle doit se poser. Après un flyTo incliné, passez pitch: 0, bearing: 0 pour un cadrage à plat, nord en haut :

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

Si vous redimensionnez l'élément qui contient la carte, signalez-le-lui :

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

Couches et visibilité

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

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

Les couches ne sont qu'un des éléments que le lecteur peut afficher ou masquer. getVisibility les renvoie tous, et setVisibility accepte n'importe quel sous-ensemble : ce que vous omettez n'est pas modifié :

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

Les id qu'une carte n'a plus sont ignorés et renvoyés sous la forme { skipped: [...] }, sans être traités comme une erreur : le code écrit pour une publication continue de fonctionner avec la suivante.

:::note Masquer un segment le désactive La visibilité fonctionne comme dans un signet : un segment masqué est désactivé, sa sélection cesse donc de filtrer jusqu'à ce qu'il soit de nouveau affiché. Si votre page fournit l'interface de filtrage et que la carte ne doit afficher aucune carte de segment, filtrez avec des filtres déclarés (setFilters) plutôt qu'en définissant des segments masqués. :::

getLayerStats({ layerId }) vous indique combien d'entités une couche contient après filtres et segments : pratique pour une étiquette « n résultats ».

:::note Couches désactivées au moment de la publication Une carte publiée contient aussi les données des couches désactivées : votre page peut donc en révéler une avec setLayerVisibility, et le contrôle des couches et les signets propres à la carte fonctionnent comme l'auteur les a conçus. L'auteur peut exclure une couche masquée (Publish > Include data for the layers that are switched off) ; une telle couche est alors publiée vide : l'activer n'affiche rien et getLayerStats renvoie 0.

Les cartes publiées avant l'ajout de cette option (septembre 2026) ne contiennent aucune donnée pour les couches qui étaient désactivées à ce moment-là. Une nouvelle publication les inclut. :::

Segments

Les segments sont les contrôles destinés au lecteur que l'auteur a placés sur la carte. En piloter un revient exactement au même que si le lecteur l'utilisait : tout ce qui lui est lié suit.

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();

La forme de state dépend du kind du segment, indiqué par getSlicers(). null efface un segment.

getSlicerValues répond aussi pour un segment masqué : une page qui dessine sa propre interface de filtrage peut donc quand même lister les valeurs.

Voir en action : Filtrer avec des segments.

Pour des filtres qui vous appartiennent plutôt qu'au lecteur, utilisez plutôt des filtres déclarés.

Sélection et mise en surbrillance

Le schéma que veulent la plupart des portails : une liste sur la page et une carte à côté, chacune pilotant l'autre.

De la carte vers votre page : abonnez-vous à featureClick. Il transporte la clé de l'entité et les champs que la couche affiche dans son info-bulle :

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

De votre page vers la carte : selectByKey. Avec field, vous passez vos identifiants et la carte trouve les entités ; sans lui, les clés sont les valeurs featureKey fournies par featureClick.

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

La sélection se comporte comme un clic : l'entité est mise en évidence, les panneaux et graphiques limités à la sélection suivent, et selectionChanged est déclenché.

:::note La colonne de clé doit être publiée Une carte publiée ne contient que les colonnes qu'elle utilise (info-bulles, style, étiquettes, segments) : une colonne de clé utilisée nulle part ailleurs n'y figure pas, et selectByKey avec ce field ne correspond à rien ({ matched: 0 }). L'auteur de la carte publie une clé en l'ajoutant aux Champs d'info-bulle de la couche. Il en va de même pour highlight. :::

Survoler sans sélectionner : highlight dessine des entités comme sélectionnées sans modifier la sélection : pas de fenêtre contextuelle, pas de panneaux, pas d'événement. Cette commande est conçue pour le survol d'une liste.

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

Le prochain clic du lecteur sur la carte remplace une mise en surbrillance. Un appel peut citer jusqu'à 500 clés.

Les graphiques filtrent la carte de manière croisée lorsqu'un lecteur clique sur une barre ou un secteur. Vous pouvez faire de même :

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

Scènes, signets et visites

captureScene et applyScene enregistrent et restaurent toute la vue en un seul objet. Elles ont leur propre page.

Présentation

Faites en sorte que la carte s'intègre à votre application.

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 Un arrière-plan transparent sur une page sombre background: "transparent" laisse apparaître votre page partout où la carte ne dessine rien, par exemple autour d'un globe. Si votre page déclare color-scheme: dark, donnez aussi au cadre le schéma de couleurs de la carte :

#map iframe { color-scheme: light; }

Lorsque le schéma de couleurs d'un cadre diffère de celui de sa page, les navigateurs dessinent un fond opaque derrière le cadre : sans cette règle, l'arrière-plan reste blanc et l'option semble sans effet. :::

setChrome peut masquer un contrôle configuré par l'auteur ; il ne peut pas en ajouter un que l'auteur n'a pas configuré. Les réglages sont legend, layerControl, clickPopups, selection, bookmarksBar, tourTransport et search.

Si vous masquez la légende, construisez la vôtre à partir du même modèle que celui affiché par la carte :

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

Langue. setLanguage({ language: "de" }) change la langue du lecteur. Seule une langue listée dans capabilities.map.locales est acceptée.

Le plein écran s'exécute dans votre page plutôt que dans la carte, car les navigateurs ne l'autorisent qu'en réponse à un geste de l'utilisateur sur la page. Appelez-le depuis un gestionnaire de clic :

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

Export d'image et impression

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();

L'image correspond exactement à la carte telle que le lecteur la voit à cet instant. La hauteur suit le rapport largeur/hauteur du cadre, sauf si vous en indiquez une.

Si des données de la carte portent une étiquette de confidentialité qui n'autorise pas l'exportation, les deux commandes sont rejetées avec denied_capability. Lorsqu'une étiquette autorise l'exportation avec un avertissement, le résultat porte labelVerdict: "warn" pour que vous puissiez afficher votre propre avertissement. Consultez Sécurité et autorisations pour savoir comment Icon Map traite les étiquettes de confidentialité.

Commandes du menu contextuel

Ajoutez votre propre action à la fenêtre contextuelle que voit un lecteur lorsqu'il clique sur une entité :

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);
});

Seuls l'id et un titre en texte brut entrent dans la carte, jamais de HTML ni de script. Omettez layerIds pour proposer l'action sur toutes les couches.

Analyse

Certaines cartes portent un moteur d'analyse sur une couche, par exemple un réseau d'eau capable d'effectuer un traçage à partir d'une conduite principale rompue. Lorsqu'il en existe un, vous pouvez l'exécuter et recevoir ses résultats.

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 },
});

Les opérations et leurs arguments appartiennent au moteur : découvrez-les avec getAnalysisOps() plutôt que de les coder en dur. Sur une carte sans moteur, cette commande renvoie une liste vide.

Que l'opération ait été lancée par vous ou par le lecteur en cliquant, analysisResult est déclenché avec la même charge utile : un seul gestionnaire couvre donc les deux cas :

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

L'analyse est rationnée pour qu'une page ne puisse pas submerger la carte : une seule opération s'exécute à la fois par couche, quatre autres peuvent attendre (busy au-delà), et une session dispose de 60 opérations par minute (budget_exceeded). Les résultats volumineux sont plafonnés (1 000 id ou 200 lignes par liste) et marqués truncated.

Les couches dotées d'une horloge de simulation l'exposent via getClock / setClock et l'événement clockChanged.