Escenas, marcadores y recorridos

Una escena es todo el estado del mapa en un único objeto simple: dónde está la cámara, qué se muestra, cómo están las segmentaciones y los filtros, qué está seleccionado y qué mapa base está activo. Captúrela, guárdela donde quiera y devuelva el mapa exactamente a ese punto más tarde.

Es el mismo estado que guarda uno de los marcadores del autor, más sus filtros, la selección y el mapa base.

Capturar y 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"
}

Las escenas sobreviven a una nueva publicación. Si desde entonces el autor ha quitado una capa o una segmentación, esa parte de la escena se omite y se indica en skipped (por ejemplo, "layer:old-depots"); todo lo demás se restaura. Nada falla.

Capture solo lo que quiera conservar:

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

Devuelva todo a lo que publicó el autor con map.resetScene().

Empezar desde una escena

Pase una escena al montar el mapa y el lector nunca verá primero la vista predeterminada:

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

Compartir una escena como vínculo

sceneToUrl convierte una escena en un vínculo que abre el mapa exactamente ahí, sin necesidad de código en la página que lo abre:

const { sceneToUrl } = IconMapEmbed;

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

La escena viaja en el fragmento de la URL (#s=...), que los navegadores nunca envían a un servidor, por lo que no aparece en los registros de acceso. Consulte Vínculos profundos.

Si prefiere guardar una cadena opaca en lugar de un objeto, pídala; applyScene acepta cualquiera de las dos:

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

Marcadores

Los marcadores son vistas que guardó el autor del mapa. Enumérelos y aplique uno: pasa por la misma ruta que la barra de marcadores del propio mapa, así que ambos nunca discrepan.

El autor decide si se ofrecen marcadores: getBookmarks() devuelve una lista vacía a menos que se marcara Show a bookmarks control in the viewer al publicar el mapa.

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

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

Cree su propia navegación por marcadores y oculte la del mapa:

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

Para abrir el mapa en un marcador, pase bookmarkId al montarlo.

Recorridos

Un recorrido es una secuencia de vistas que grabó el autor.

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" */ });

Mientras se reproduce un recorrido, los eventos viewChanged llevan reason: "tour", de modo que un controlador de sincronización de vista que solo actúa con "user" permanece inactivo.

Qué usar