Comandos

Cada comando é um método do handle, recebe um objeto de argumentos (ou nenhum) e retorna uma promise. Esta página os apresenta por área, com os padrões que aparecem em portais reais. Para os tipos exatos de argumentos e resultados, veja a referência da API.

Cada área é um grupo que o autor do mapa pode desativar. Se um grupo estiver desativado, seus comandos não aparecem em capabilities.commands e são rejeitados com denied_capability.

Câmera

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

As coordenadas são sempre [longitude, latitude]. padding é um número de pixels ou { top, right, bottom, left }; use-o quando parte do mapa ficar sob uma sobreposição da sua página.

fitBounds e fitLayer mantêm a inclinação da câmera, a menos que você diga onde ela deve parar. Depois de um flyTo inclinado, passe pitch: 0, bearing: 0 para um enquadramento plano, com o norte para cima:

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

Se você redimensionar o elemento em que o mapa está, avise-o:

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

Camadas e visibilidade

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

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

As camadas são apenas uma das coisas que um leitor pode alternar. getVisibility retorna todas elas, e setVisibility aceita qualquer subconjunto; o que você não incluir fica como está:

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 que o mapa não tem mais são ignorados e retornados como { skipped: [...] }, sem serem tratados como erro, para que o código escrito para uma publicação continue funcionando na seguinte.

:::note Ocultar uma segmentação a desativa A visibilidade funciona como em um indicador: uma segmentação oculta fica desativada, então sua seleção deixa de filtrar até que ela volte a ser exibida. Se a sua página fornece a interface de filtro e o mapa não deve mostrar nenhum cartão de segmentação, filtre com filtros declarados (setFilters) em vez de definir segmentações ocultas. :::

getLayerStats({ layerId }) informa quantas feições uma camada contém depois dos filtros e das segmentações, útil para um rótulo de "n resultados".

:::note Camadas desativadas quando o mapa é publicado Um mapa publicado também leva os dados das camadas desativadas, para que sua página possa exibir uma delas com setLayerVisibility e para que o controle de camadas e os indicadores do próprio mapa funcionem como o autor os projetou. O autor pode deixar de fora uma camada oculta (Publish > Include data for the layers that are switched off); essa camada é publicada vazia: ativá-la não mostra nada, e getLayerStats informa 0.

Os mapas publicados antes da inclusão desse recurso (setembro de 2026) não têm dados das camadas que estavam desativadas naquele momento. Uma nova publicação os inclui. :::

Segmentações de dados

As segmentações de dados são os controles voltados ao leitor que o autor colocou no mapa. Controlar uma delas é exatamente igual ao leitor usá-la: tudo o que estiver vinculado a ela acompanha.

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

O formato de state depende do kind da segmentação, que getSlicers() informa. null limpa uma segmentação.

getSlicerValues também responde para uma segmentação oculta, então uma página que desenha a própria interface de filtro ainda consegue listar os valores.

Veja funcionando: Filtrar com segmentações.

Para filtros que são seus, e não do leitor, use filtros declarados.

Seleção e realce

O padrão que a maioria dos portais quer é uma lista na página e um mapa ao lado, cada um controlando o outro.

Do mapa para a sua página: inscreva-se em featureClick. Ele traz a chave da feição e os campos que a camada mostra na dica de ferramenta:

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

Da sua página para o mapa: selectByKey. Com field, você passa os seus identificadores e o mapa encontra as feições; sem ele, as chaves são os valores de featureKey que featureClick lhe forneceu.

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

Selecionar funciona como um clique: a feição é destacada, os painéis e gráficos limitados à seleção acompanham, e selectionChanged é disparado.

:::note A coluna de chave precisa ser publicada Um mapa publicado leva apenas as colunas que usa (dicas de ferramenta, estilo, rótulos, segmentações), então uma coluna de chave que nada mais usa não está nele, e selectByKey com esse field não encontra nada ({ matched: 0 }). O autor do mapa publica uma chave adicionando-a aos Campos da dica de ferramenta da camada. O mesmo vale para highlight. :::

Passar o mouse sem selecionar: highlight pinta feições como selecionadas sem alterar a seleção: sem pop-up, sem painéis, sem evento. Foi feito para o hover em listas.

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

O próximo clique do leitor no mapa substitui um realce. Uma chamada pode indicar até 500 chaves.

Os gráficos aplicam filtro cruzado ao mapa quando o leitor clica em uma barra ou fatia. Você pode fazer o mesmo:

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

Cenas, indicadores e tours

captureScene e applyScene salvam e restauram a vista inteira em um único objeto. Eles têm sua própria página.

Apresentação

Faça o mapa parecer parte do seu aplicativo.

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 Fundo transparente em uma página escura background: "transparent" deixa sua página aparecer onde o mapa não pinta, por exemplo no espaço ao redor de um globo. Se a sua página declara color-scheme: dark, atribua também ao frame o esquema do mapa:

#map iframe { color-scheme: light; }

Quando o esquema de cores de um frame difere do da página, os navegadores pintam um fundo opaco atrás do frame; sem isso, o fundo continua branco e a opção parece não ter efeito. :::

setChrome pode ocultar um controle que o autor configurou; não pode adicionar um que ele não configurou. As chaves são legend, layerControl, clickPopups, selection, bookmarksBar, tourTransport e search.

Se você ocultar a legenda, crie a sua a partir do mesmo modelo que o mapa renderiza:

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

Idioma. setLanguage({ language: "de" }) muda o idioma do leitor. Só é aceito um idioma listado em capabilities.map.locales.

Tela inteira é executada na sua página, e não no mapa, porque os navegadores só permitem isso em resposta a um gesto do usuário ali. Chame-a a partir de um manipulador de clique:

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

Exportação de imagem e impressão

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

A imagem é o mapa exatamente como o leitor o vê naquele momento. A altura segue a proporção do frame, a menos que você informe uma.

Se algum dado por trás do mapa tiver um rótulo de confidencialidade que não permite exportação, os dois comandos são rejeitados com denied_capability. Quando um rótulo permite a exportação com um aviso, o resultado traz labelVerdict: "warn", para que você possa exibir seu próprio aviso. Veja em Segurança e permissões como o Icon Map trata os rótulos de confidencialidade.

Comandos do menu pop-up

Adicione sua própria ação ao pop-up que o leitor vê ao clicar em uma feição:

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

Só o ID e um título em texto simples entram no mapa, nunca HTML ou script. Omita layerIds para oferecer a ação em todas as camadas.

Análise

Alguns mapas têm um mecanismo de análise em uma camada, por exemplo uma rede de água que pode fazer um rastreamento a partir de uma adutora rompida. Quando existe um, você pode executá-lo e receber os 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 },
});

As operações e seus argumentos pertencem ao mecanismo, portanto descubra-os com getAnalysisOps() em vez de fixá-los no código. Em um mapa sem mecanismo, o comando retorna uma lista vazia.

Seja a operação executada por você ou pelo leitor com um clique, analysisResult é disparado com o mesmo payload, então um único manipulador cobre os dois casos:

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

A análise é racionada para que uma página não sobrecarregue o mapa: uma operação é executada por camada de cada vez, mais quatro podem aguardar (depois disso, busy), e uma sessão tem direito a 60 por minuto (budget_exceeded). Resultados grandes são limitados (1.000 IDs ou 200 linhas por lista) e marcados como truncated.

As camadas com um relógio de simulação o expõem por meio de getClock / setClock e do evento clockChanged.