Comandos

Cada comando es un método del identificador, recibe un objeto de argumentos (o ninguno) y devuelve una promesa. Esta página los recorre por área con los patrones que aparecen en portales reales. Para conocer los tipos exactos de argumentos y resultados, consulte la referencia de la API.

Cada área es un grupo que el autor del mapa puede desactivar. Si un grupo está desactivado, sus comandos no aparecen en capabilities.commands y se rechazan con denied_capability.

Cámara

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

Las coordenadas son siempre [longitude, latitude]. padding es un número de píxeles o { top, right, bottom, left }; úselo cuando parte del mapa quede bajo una superposición propia.

fitBounds y fitLayer mantienen la inclinación de la cámara a menos que indique dónde debe quedar. Después de un flyTo inclinado, pase pitch: 0, bearing: 0 para obtener un encuadre plano y orientado al norte:

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

Si cambia el tamaño del elemento que contiene el mapa, indíqueselo:

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

Capas y visibilidad

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

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

Las capas son solo una de las cosas que un lector puede activar y desactivar. getVisibility las devuelve todas, y setVisibility acepta cualquier subconjunto; lo que omita no se modifica:

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

Los ids que un mapa ya no tiene se omiten y se devuelven como { skipped: [...] }, sin tratarse como error, de modo que el código escrito para una publicación sigue funcionando con la siguiente.

:::note Ocultar una segmentación la desactiva La visibilidad funciona igual que en un marcador: una segmentación oculta está desactivada, por lo que su selección deja de filtrar hasta que se vuelve a mostrar. Si su página proporciona la interfaz de filtrado y el mapa no debe mostrar tarjetas de segmentación, filtre con filtros declarados (setFilters) en lugar de establecer segmentaciones ocultas. :::

getLayerStats({ layerId }) indica cuántas entidades contiene una capa después de los filtros y las segmentaciones, algo práctico para una etiqueta de "n resultados".

:::note Capas desactivadas al publicar el mapa Un mapa publicado lleva también los datos de las capas desactivadas, de modo que su página puede mostrar una con setLayerVisibility y el control de capas y los marcadores del propio mapa funcionan tal como los diseñó el autor. El autor puede dejar fuera una capa oculta (Publicar > Include data for the layers that are switched off), y esa capa se publica vacía: al activarla no muestra nada y getLayerStats informa de 0.

Los mapas publicados antes de que se añadiera esta opción (septiembre de 2026) no llevan datos de las capas que estaban desactivadas en ese momento. Al volver a publicar se incluyen. :::

Segmentaciones

Las segmentaciones son los controles orientados al lector que el autor colocó en el mapa. Controlar una es exactamente lo mismo que si el lector la usara: todo lo que está enlazado a ella la sigue.

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 forma de state depende del kind de la segmentación, que indica getSlicers(). null borra una segmentación.

getSlicerValues también responde para una segmentación oculta, de modo que una página que dibuja su propia interfaz de filtrado puede seguir enumerando los valores.

Véalo en funcionamiento: Filtrar con segmentaciones.

Para los filtros que son suyos y no del lector, use en su lugar filtros declarados.

Selección y resaltado

El patrón que quieren la mayoría de los portales es una lista en la página y un mapa al lado, cada uno controlando al otro.

Del mapa a su página: suscríbase a featureClick. Lleva la clave de la entidad y los campos que la capa muestra en su información sobre herramientas:

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

De su página al mapa: selectByKey. Con field, pasa sus identificadores y el mapa encuentra las entidades; sin él, las claves son los valores de featureKey que le dio featureClick.

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

Seleccionar se comporta como un clic: la entidad se resalta, los paneles y gráficos limitados a la selección la siguen y se desencadena selectionChanged.

:::note La columna de clave tiene que estar publicada Un mapa publicado lleva solo las columnas que usa (información sobre herramientas, estilo, etiquetas, segmentaciones), así que una columna de clave que nada más usa no está en él, y selectByKey con ese field no encuentra nada ({ matched: 0 }). El autor del mapa publica una clave añadiéndola a los Campos de información sobre herramientas de la capa. Lo mismo se aplica a highlight. :::

Pasar el puntero sin seleccionar: highlight pinta entidades como seleccionadas sin cambiar la selección: sin ventana emergente, sin paneles, sin evento. Está pensado para pasar el puntero por una lista.

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

El siguiente clic del lector en el mapa sustituye el resaltado. Una llamada puede indicar hasta 500 claves.

Los gráficos aplican un filtro cruzado al mapa cuando un lector hace clic en una barra o un sector. Usted puede hacer lo mismo:

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

Escenas, marcadores y recorridos

captureScene y applyScene guardan y restauran toda la vista en un único objeto. Tienen su propia página.

Presentación

Haga que el mapa parezca parte de su aplicación.

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 fondo transparente en una página oscura background: "transparent" deja ver su página allí donde el mapa no pinta, por ejemplo en el espacio alrededor de un globo. Si su página declara color-scheme: dark, asigne también al marco el esquema del mapa:

#map iframe { color-scheme: light; }

Cuando el esquema de color de un marco difiere del de su página, los navegadores pintan un fondo opaco detrás del marco, así que sin esto el fondo sigue siendo blanco y parece que la opción no hace nada. :::

setChrome puede ocultar un control que el autor configuró; no puede añadir uno que no configuró. Los conmutadores son legend, layerControl, clickPopups, selection, bookmarksBar, tourTransport y search.

Si oculta la leyenda, cree la suya a partir del mismo modelo que representa el mapa:

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

Idioma. setLanguage({ language: "de" }) cambia el idioma del lector. Solo se acepta un idioma que figure en capabilities.map.locales.

La pantalla completa se ejecuta en su página y no en el mapa, porque los navegadores solo la permiten allí en respuesta a un gesto del usuario. Llámela desde un controlador de clic:

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

Exportación de imagen e impresión

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

La imagen es el mapa exactamente como lo ve el lector en ese momento. La altura sigue la relación de aspecto del marco, a menos que indique una.

Si algún dato del mapa lleva una etiqueta de confidencialidad que no permite la exportación, ambos comandos se rechazan con denied_capability. Cuando una etiqueta permite la exportación con una advertencia, el resultado lleva labelVerdict: "warn" para que pueda mostrar su propio aviso. Consulte Seguridad y permisos para saber cómo trata Icon Map las etiquetas de confidencialidad.

Comandos del menú emergente

Añada una acción propia a la ventana emergente que ve un lector al hacer clic en una entidad:

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

Solo el id y un título de texto sin formato pasan al mapa, nunca HTML ni script. Omita layerIds para ofrecer la acción en todas las capas.

Análisis

Algunos mapas llevan un motor de análisis en una capa: por ejemplo, una red de agua capaz de trazar desde una tubería principal rota. Donde exista, puede ejecutarlo y recibir sus resultados.

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

Las operaciones y sus argumentos pertenecen al motor, así que descúbralos con getAnalysisOps() en lugar de codificarlos de forma fija. En un mapa sin motor devuelve una lista vacía.

Tanto si ejecutó la operación usted como si lo hizo el lector con un clic, analysisResult se desencadena con la misma carga, de modo que un solo controlador cubre ambos casos:

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

El análisis está racionado para que una página no pueda saturar el mapa: se ejecuta una operación por capa a la vez, cuatro más pueden esperar (busy a partir de ahí) y una sesión dispone de 60 por minuto (budget_exceeded). Los resultados grandes se limitan (1000 ids o 200 filas por lista) y se marcan como truncated.

Las capas con reloj de simulación lo exponen mediante getClock / setClock y el evento clockChanged.