Se hai scritto qualsiasi codice che interagisce con una libreria di mappe, hai scritto codice che tocca il viewport. Il viewport è lo stato runtime della mappa: dove è centrata, quanto è zoomata, in che direzione punta, e opzionalmente quanto è inclinata. Ogni pan, zoom, rotazione e click dipende da esso.
Questa guida spiega cos'è davvero un viewport, i quattro valori principali che lo descrivono, come interagisce con i tile e i bounding box, e i pattern in produzione per salvare, ripristinare e condividere lo stato del viewport.
I Quattro Valori Principali
Il viewport di una mappa web moderna è descritto da fino a quattro valori:
- Center (
{ lat, lng }): la coordinata geografica al centro dello schermo. - Zoom (un numero, spesso un float): quanto è zoomata la mappa. Numeri più alti mostrano aree più piccole con più dettaglio.
- Bearing (un numero in gradi, default 0): la rotazione della mappa rispetto al "nord su". 90 significa che l'est è in alto.
- Pitch (un numero in gradi, da 0 a circa 85): l'inclinazione 3D. 0 è piatto dall'alto, 60 è una forte vista prospettica.
Ogni libreria di mappe moderna (MapLibre GL, Mapbox GL, OpenLayers, Leaflet, MapAtlas Dynamic Maps) espone questi come stato leggibile e scrivibile. Una libreria solo-2D come Leaflet potrebbe non esporre bearing o pitch.
I Livelli di Zoom in Dettaglio
Il livello di zoom è il più richiesto dei quattro. È un numero intero (o frazionario) che mappa il mondo su una piramide di tile:
- Zoom 0: intero mondo in un tile 256x256
- Zoom 1: mondo diviso in 4 tile
- Zoom 2: 16 tile
- ...
- Zoom 14: circa 268 milioni di tile, scala di quartiere
- Zoom 18: scala di edificio
- Zoom 22+: di solito renderizzato con upscaling dello stile vettoriale anziché nuovi dati di tile
Una buona regola empirica all'equatore: ogni aumento del livello di zoom dimezza la larghezza visibile sullo schermo. Al livello 14, uno schermo tipicamente mostra qualche isolato. Al livello 10, un'area metropolitana. Al livello 6, un paese. La risoluzione effettiva dipende dalle dimensioni dello schermo e dalla proiezione (Web Mercator distorce la direzione nord-sud man mano che ci si avvicina ai poli).
La maggior parte del codice in produzione memorizza lo zoom come float (es. 14.5) perché le animazioni di zoom fluido interpolano tra zoom interi. I fetch dei tile avvengono al livello intero arrotondato per difetto o per eccesso, a seconda della convenzione della libreria.
Viewport vs Bounding Box
Un viewport è lo stato della camera. Un bounding box è il rettangolo geografico attualmente visibile. Calcoli il bbox dal viewport ogni volta che hai bisogno di chiedere al server "cosa dovrei mostrare all'interno di questa vista?".
In codice:
const bbox = map.getBounds(); // restituisce { _sw: {lat, lng}, _ne: {lat, lng} }
const params = new URLSearchParams({
bbox: `${bbox._sw.lng},${bbox._sw.lat},${bbox._ne.lng},${bbox._ne.lat}`,
});
const features = await fetch(`/api/places?${params}`).then(r => r.json());
Questo pattern (calcola bbox dal viewport, invia al server, renderizza le feature restituite) è il cuore di ogni esperienza di ricerca basata sul viewport: immobiliare, listing, localizzatori di negozi, tracciamento della flotta, ride-sharing.
Come il Viewport Guida il Caricamento dei Tile
Quando il viewport cambia, la libreria di mappe determina quali tile coprono la nuova area visibile al livello di zoom corrente, scarica i tile mancanti dal server (o dalla sua cache in memoria) e li renderizza. I tile già in cache vengono riutilizzati; i tile fuori dal viewport vengono tenuti in giro nel caso l'utente torni indietro.
Un pan e zoom fluidi sembrano senza soluzione di continuità perché la libreria fa questo lavoro in modo asincrono: disegna ciò che ha, scarica ciò di cui ha bisogno e aggiorna il canvas man mano che arrivano nuovi tile. Le pipeline di vector tile fanno lavoro extra per renderizzare la geometria in pixel sulla GPU, il che è il motivo per cui le mappe web moderne rimangono nitide a qualsiasi zoom e rotazione.
Salvare e Condividere lo Stato del Viewport
Memorizzare il viewport nell'URL è il pattern standard per i link di mappe condivisibili. La maggior parte dei prodotti usa un hash URL come #map=14.5/52.5200/13.4050 (zoom, lat, lng). Al caricamento della pagina, analizza l'hash e applica il viewport. Al cambio del viewport, debounce di qualche centinaio di millisecondi e aggiorna l'hash in modo che il pulsante Indietro del browser rimanga utile.
Per lo stato interno del browser tra tab o sessioni, una chiave localStorage con la stessa forma funziona bene. Per le pagine renderizzate lato server, il viewport appare spesso come parametri di query per URL SEO-friendly (?zoom=14&lat=52.52&lng=13.405).
Viewport Bias per la Ricerca e l'Autocomplete
Le geocoding API accettano il viewport (o il suo bbox) come parametro di bias. MapAtlas espone boundary.rect.* per un filtro rigido e focus.point.* per un bias morbido. Senza un bias, l'autocomplete per "Springfield" restituisce qualsiasi Springfield sia più popolare a livello globale. Con un viewport bias, l'utente che digita all'interno della sua mappa del Massachusetts ottiene prima i risultati del Massachusetts.
Applica questo bias ad ogni pressione del tasto. Il costo è un parametro e suggerimenti significativamente più rilevanti.
Viewport Iniziale: Da Dove Partire
La prima cosa che ogni app di mappe deve decidere è da dove partire. Pattern comuni:
- Default al locale dell'utente: un utente in Germania atterra su un viewport sopra Berlino, uno in Francia sopra Parigi.
- Default all'ultimo viewport dell'utente: persisti il viewport tra le sessioni.
- Default ai dati: se la tua mappa mostra risultati di ricerca, adatta il bbox di quei risultati al rendering iniziale.
- Default alla geolocalizzazione IP dell'utente: bassa precisione, nessun permesso richiesto, buon fallback.
- Chiedi la geolocalizzazione del browser solo quando l'utente accetta esplicitamente: mai al primo caricamento senza il consenso dell'UI.
Scegliere un viewport iniziale sensato è un piccolo dettaglio con un grande effetto sulla qualità percepita.
Come MapAtlas Espone lo Stato del Viewport
Il componente Dynamic Maps di MapAtlas espone le stesse API getCenter, getZoom, getBearing, getPitch e setView che ogni mappa web di livello developer fornisce, con l'aggiunta di hosting solo in UE e parametri di viewport bias coerenti tra gli endpoint Geocoding e Search. Per uno sguardo più approfondito su come il viewport interagisce con tile e proiezioni, vedi Cos'è un Vector Tile e Cos'è Web Mercator.
Domande frequenti
Cos'è un map viewport?
Un map viewport è la finestra visibile di una mappa: l'area geografica attualmente visualizzata sullo schermo, descritta da una coordinata centrale (latitudine e longitudine), un livello di zoom (quanto è ingrandita o rimpicciolita la mappa) e opzionalmente un bearing (rotazione) e un pitch (inclinazione 3D). Ogni mappa web moderna (Google Maps, MapLibre, Mapbox GL, MapAtlas) espone il viewport come stato che puoi leggere e impostare in modo programmativo. Il viewport cambia ogni volta che l'utente fa pan, zoom, ruota o inclina la mappa.
Cos'è un livello di zoom?
Il livello di zoom è un numero intero (o frazionario) che controlla quanta parte del mondo è visibile in un tile di dimensione fissa. Al livello 0 l'intero mondo sta in un singolo tile 256x256. Ogni livello di zoom successivo raddoppia la risoluzione: lo zoom 1 ha 4 tile, lo zoom 2 ne ha 16, e così via. Lo zoom 14 è circa a scala di quartiere, lo zoom 18 è circa a scala di edificio. La maggior parte delle mappe in produzione supporta livelli di zoom da 0 a 22 o oltre, anche se i tile sottostanti esistono solo fino a un certo zoom e vengono sovracampionati oltre tale livello.
Qual è la differenza tra viewport e bounding box?
Un viewport è lo stato della camera (centro, zoom, bearing, pitch). Un bounding box è il rettangolo geografico che la camera mostra attualmente. Calcoli il bbox dal viewport: dati un centro, uno zoom e le dimensioni dello schermo, la libreria di mappe calcola quale rettangolo lat/lng è visibile. Il bbox è ciò che passi alla geocoding API come viewport bias, ciò con cui interroghi il database per le feature visibili, e ciò che registri quando vuoi sapere cosa stava guardando l'utente.
Come salvo e ripristino un map viewport?
Serializza i quattro valori principali (latitudine del centro, longitudine del centro, zoom, bearing se supporti la rotazione) nell'URL o nel localStorage. Un pattern comune è un hash come #map=14.5/52.5200/13.4050 per zoom 14.5 al centro di Berlino. Al caricamento della pagina, analizza l'hash e chiama map.setView(...) o map.flyTo(...). MapAtlas, MapLibre e Mapbox GL espongono tutti un'API getCenter / getZoom / getBearing e un equivalente setView, quindi questo round-trip è una singola funzione helper in qualsiasi codebase in produzione.
