Scènes, signets et visites

Une scène est l'état complet de la carte sous la forme d'un simple objet : la position de la caméra, ce qui est affiché, les valeurs des segments et des filtres, ce qui est sélectionné et le fond de carte actif. Capturez-la, conservez-la où vous voulez, et ramenez plus tard la carte exactement à cet état.

C'est le même état que celui que contient un signet de l'auteur, plus vos filtres, la sélection et le fond de carte.

Capturer et restaurer

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

Les scènes survivent à une republication. Si l'auteur a supprimé entre-temps une couche ou un segment, cette partie de la scène est ignorée et citée dans skipped (par exemple "layer:old-depots") ; tout le reste est restauré. Rien n'échoue.

Ne capturez que ce que vous voulez transporter :

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

Remettez tout dans l'état publié par l'auteur avec map.resetScene().

Démarrer depuis une scène

Passez une scène au montage, et le lecteur ne voit jamais d'abord la vue par défaut :

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

Partager une scène sous forme de lien

sceneToUrl transforme une scène en un lien qui ouvre la carte exactement dans cet état, sans aucun code nécessaire sur la page qui l'ouvre :

const { sceneToUrl } = IconMapEmbed;

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

La scène voyage dans le fragment de l'URL (#s=...), que les navigateurs n'envoient jamais à un serveur : elle n'apparaît donc pas dans les journaux d'accès. Voir Liens profonds.

Si vous préférez stocker une chaîne opaque plutôt qu'un objet, demandez-en une ; applyScene accepte l'une ou l'autre forme :

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

Signets

Les signets sont des vues enregistrées par l'auteur de la carte. Listez-les et appliquez-en un : l'application passe par le même chemin que la barre de signets propre à la carte, si bien que les deux ne sont jamais en désaccord.

C'est l'auteur qui décide si des signets sont proposés : getBookmarks() renvoie une liste vide sauf si Show a bookmarks control in the viewer était coché lors de la publication de la carte.

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

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

Construisez votre propre navigation par signets et masquez celle de la carte :

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

Pour ouvrir la carte sur un signet, passez bookmarkId au montage.

Visites

Une visite est une séquence de vues enregistrée par l'auteur.

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

Pendant la lecture d'une visite, les événements viewChanged portent reason: "tour" : un gestionnaire de synchronisation de vue qui ne réagit qu'à "user" reste donc silencieux.

Lequel utiliser