Cenas, indicadores e tours

Uma cena é o estado completo do mapa como um único objeto simples: onde está a câmera, o que é exibido, como estão definidos as segmentações e os filtros, o que está selecionado e qual mapa base está ativo. Capture-a, guarde-a onde quiser e coloque o mapa exatamente de volta nesse ponto depois.

É o mesmo estado que um dos indicadores do autor guarda, mais os seus filtros, a seleção e o mapa base.

Capturar e restaurar

const scene = await map.captureScene();
localStorage.setItem("last-view", JSON.stringify(scene));

// ... later, even after the map has been re-published
const { skipped } = await map.applyScene({ scene: JSON.parse(localStorage.getItem("last-view")), animate: true });

// EmbedScene
{
  v: 1,
  camera: { center: [lng, lat], zoom, bearing, pitch },
  visibility: { layers: { ... }, labels, hillshade, terminator, features: { ... }, visuals: { ... } },
  slicers: { "slicer-region": { ... } },
  filters: { region: ["EMEA"] },
  selection: { assets: ["41B"] },
  basemapId: "slate"
}

As cenas sobrevivem a uma nova publicação. Se o autor tiver removido uma camada ou uma segmentação nesse meio-tempo, essa parte da cena é ignorada e citada em skipped (por exemplo "layer:old-depots"); todo o resto é restaurado. Nada falha.

Capture só o que você quer levar:

const viewOnly = await map.captureScene({ include: ["camera", "visibility"] });

Volte tudo para o que o autor publicou com map.resetScene().

Começar a partir de uma cena

Passe uma cena na montagem, e o leitor nunca verá a vista padrão primeiro:

embed(el, { publishId, scene: JSON.parse(localStorage.getItem("last-view")) });

Compartilhar uma cena como link

sceneToUrl transforma uma cena em um link que abre o mapa exatamente ali, sem precisar de código na página que o abre:

const { sceneToUrl } = IconMapEmbed;

const scene = await map.captureScene();
const link = sceneToUrl("https://embed.iconmap.ai/v/pub_...", { scene });

A cena vai no fragmento da URL (#s=...), que os navegadores nunca enviam a um servidor, então ela não aparece em logs de acesso. Veja Links diretos.

Se você preferir guardar uma string opaca em vez de um objeto, peça uma; applyScene aceita qualquer um dos dois:

const { state } = await map.captureScene({ opaque: true });
await map.applyScene({ scene: { state } });

Indicadores

Os indicadores são vistas que o autor do mapa salvou. Liste-os e aplique um: o caminho é o mesmo da barra de indicadores do próprio mapa, então os dois nunca divergem.

O autor decide se os indicadores são oferecidos: getBookmarks() retorna uma lista vazia, a menos que Show a bookmarks control in the viewer estivesse marcado quando o mapa foi publicado.

const bookmarks = await map.getBookmarks();      // [{ id, name, description? }]
await map.applyBookmark({ bookmarkId: bookmarks[0].id, animate: true });

map.on("bookmarkApplied", ({ bookmarkId }) => highlightMyTab(bookmarkId));

Crie sua própria navegação por indicadores e oculte a do mapa:

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

Para abrir em um indicador, passe bookmarkId na montagem.

Tours

Um tour é uma sequência de vistas que o autor gravou.

const tours = await map.getTours();              // [{ id, name }]
await map.playTour({ tourId: tours[0].id });
await map.stopTour();

map.on("tourStateChanged", ({ tourId, state }) => { /* "started" | "keyframe" | "ended" */ });

Enquanto um tour é reproduzido, os eventos viewChanged trazem reason: "tour", então um manipulador de sincronização de vista que só age em "user" fica quieto.

O que usar