Ogni dashboard logistico, listato immobiliare e app di consegna di cibo hanno una cosa in comune: una mappa. Se il tuo sito non ne ha ancora una, stai perdendo contesto. Un contesto che aiuta gli utenti a comprendere posizione, prossimità e relazioni spaziali a colpo d'occhio.
Questo tutorial ti guida attraverso l'aggiunta di una mappa completamente interattiva a qualsiasi progetto JavaScript. Inizierai con una mappa renderizzata, aggiungerai marcatori e popup, collegherai la ricerca degli indirizzi con l'API di Geocodifica e terminerai con un componente React pronto per la produzione che si integra perfettamente in Next.js.
Ecco cosa costruirai alla fine:
- Una mappa vettoriale dal vivo autenticata con la tua chiave API
- Marcatori cliccabili con contenuto popup personalizzato
- Una funzione di ricerca degli indirizzi alimentata da geocodifica
- Un componente React riutilizzabile con corretta pulizia e gestione SSR di Next.js
- Una lista di controllo di ottimizzazioni delle prestazioni per la produzione
Prerequisiti
Prima di iniziare, assicurati di avere:
- Una chiave API MapAtlas (iscriviti gratuitamente, nessuna carta di credito necessaria). Questa singola chiave autentica ogni servizio MapAtlas: tile, geocodifica e routing.
- Un progetto JavaScript. HTML semplice, React, Vue o Svelte funzionano tutti.
- Node.js 18+ se stai installando via npm.
Passo 1: Installa l'SDK MapAtlas
Incorpora l'SDK nel tuo progetto con npm:
npm install @mapmetrics/mapmetrics-gl
Se stai lavorando con una semplice pagina HTML, rilascia i link CDN nel tuo <head>:
<link rel="stylesheet" href="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css" />
<script src="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.js"></script>
Non saltare l'importazione CSS. Senza di essa, i controlli della mappa e i popup si renderizzano senza stile. Funzionale, ma visivamente rotto.
Passo 2: Crea un Contenitore di Mappa
L'SDK riempie qualsiasi elemento a cui lo indirizzi, quindi hai bisogno di un <div> con un'altezza esplicita. Questo è l'errore di configurazione singolarmente più comune: se il contenitore ha height: 0, la mappa si inizializza ma rimane invisibile.
<div id="map" style="width: 100%; height: 500px;"></div>
Un valore in pixel fisso o un'unità di viewport (100vh, 50vh) funzionano entrambi. Le altezze percentuali funzionano solo se l'elemento padre ha anche un'altezza definita.
Passo 3: Renderizza la Tua Prima Mappa Interattiva
Tre righe di configurazione sono tutto quello che serve: un contenitore, un URL di stile con la tua chiave API e una posizione iniziale.
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
const map = new mapmetricsgl.Map({
container: 'map',
style: 'https://tiles.mapatlas.eu/styles/basic/style.json?key=YOUR_API_KEY',
center: [4.9041, 52.3676],
zoom: 12,
});
Apri la pagina e vedrai una mappa vettoriale che puoi trascinare, scorrere e pizzicare per navigare. I tile si caricano su richiesta dai server MapAtlas, quindi non c'è nessun scaricamento pesante anticipato.
Scelta di uno Stile di Mappa
Scambia il segmento del percorso nell'URL dello stile per cambiare completamente l'aspetto:
| Stile | Percorso URL | Migliore per |
|---|---|---|
| Basic | /styles/basic/style.json | App di uso generale |
| Bright | /styles/bright/style.json | Overlay di visualizzazione dei dati |
| Dark | /styles/dark/style.json | Dashboard, modalità scura, analisi |
Vittoria veloce: Usa lo stile Dark per i pannelli di amministrazione e gli strumenti utilizzati in ambienti con scarsa illuminazione. Riduce l'affaticamento degli occhi e fa risaltare i layer di dati come mappe di calore e linee di percorso sullo sfondo.
Passo 4: Aggiungi Marcatori e Popup alla Tua Mappa
Una mappa senza marcatori è solo un'immagine di sfondo. I marcatori trasformano una vista statica in qualcosa con cui gli utenti possono interagire.
Marcatore Singolo con un Popup
const popup = new mapmetricsgl.Popup().setHTML(`
<strong>Amsterdam Central</strong>
<p>Stationsplein, 1012 AB Amsterdam</p>
`);
new mapmetricsgl.Marker({ color: '#97C70A' })
.setLngLat([4.9001, 52.3791])
.setPopup(popup)
.addTo(map);
Clicca sul marcatore e il popup si apre. Puoi inserire qualsiasi HTML all'interno: indirizzi, miniature, pulsanti CTA, qualunque cosa richieda la tua UI.
Tracciare Marcatori Multipli da Dati
La maggior parte delle app del mondo reale ha bisogno di più di un segnaposto. Fai un ciclo su un array e crea un marcatore per ogni voce:
const locations = [
{ name: 'Amsterdam', coords: [4.9041, 52.3676] },
{ name: 'Rotterdam', coords: [4.4777, 51.9244] },
{ name: 'Utrecht', coords: [5.1214, 52.0907] },
];
locations.forEach(({ name, coords }) => {
const popup = new mapmetricsgl.Popup().setHTML(`<strong>${name}</strong>`);
new mapmetricsgl.Marker({ color: '#97C70A' })
.setLngLat(coords)
.setPopup(popup)
.addTo(map);
});
Nota sulle prestazioni: Una volta che superi all'incirca 100-200 marcatori, il rendering rallenta notevolmente nelle visualizzazioni con zoom ridotto. Abilita il clustering della fonte GeoJSON (supportato nativamente dall'SDK) per raggruppare marcatori vicini a bassi livelli di zoom. Controlla la documentazione dell'SDK per la configurazione del clustering.
Passo 5: Aggiungi Ricerca di Indirizzi con l'API di Geocodifica
L'API di Geocodifica trasforma una query di testo (un indirizzo stradale, un nome di città o un landmark) in coordinate su cui puoi effettuare il pan, contrassegnare o inserire in una richiesta di routing.
async function searchAddress(query) {
const url = new URL('https://api.mapatlas.eu/geocoding/v1/search');
url.searchParams.set('text', query);
url.searchParams.set('key', 'YOUR_API_KEY');
const res = await fetch(url);
const data = await res.json();
if (!data.features.length) return;
const [lng, lat] = data.features[0].geometry.coordinates;
const label = data.features[0].properties.label;
map.flyTo({ center: [lng, lat], zoom: 14 });
new mapmetricsgl.Marker({ color: '#97C70A' })
.setLngLat([lng, lat])
.setPopup(new mapmetricsgl.Popup().setHTML(`<strong>${label}</strong>`))
.addTo(map);
}
searchAddress('Rijksmuseum, Amsterdam');
I risultati tornano come feature GeoJSON, quindi si collegano direttamente a qualsiasi layer compatibile con GeoJSON, tabella dati o chiamata API a valle.
Costruisci una barra di ricerca dal vivo in meno di 30 righe: Allega
searchAddressall'eventoinputdi un campo di testo, effettua il debounce di 300ms, e hai una ricerca di mappa in stile autocomplete senza dipendenze extra.
Integrazione di Mappe Interattive con React
Un Componente di Mappa Riutilizzabile
Racchiudi l'inizializzazione della mappa in useEffect in modo che venga eseguita dopo il mount del DOM e restituisci una funzione di pulizia per evitare perdite di memoria durante l'unmount:
import { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';
export function MapAtlasMap({ apiKey, center = [4.9041, 52.3676], zoom = 12 }) {
const containerRef = useRef(null);
useEffect(() => {
const map = new mapmetricsgl.Map({
container: containerRef.current,
style: `https://tiles.mapatlas.eu/styles/basic/style.json?key=${apiKey}`,
center, zoom,
});
return () => map.remove();
}, [apiKey]);
return <div ref={containerRef} style={{ width: '100%', height: '500px' }} />;
}
Usalo ovunque nel tuo albero di componenti:
<MapAtlasMap apiKey={process.env.NEXT_PUBLIC_MAPATLAS_KEY} center={[4.9041, 52.3676]} zoom={13} />
Gestione del Rendering sul Lato Server di Next.js
L'SDK della mappa dipende da API del browser (window, document) che non esistono durante SSR. Importa il componente dinamicamente con SSR disabilitato:
import dynamic from 'next/dynamic';
const MapAtlasMap = dynamic(
() => import('./MapAtlasMap').then(m => m.MapAtlasMap),
{ ssr: false, loading: () => (<div style={{ height: 500, background: '#f0f1f3', borderRadius: 12 }} />) }
);
Il placeholder loading mantiene il tuo layout stabile mentre il bundle della mappa viene scaricato, prevenendo lo spostamento cumulativo del layout (CLS), che è importante sia per l'esperienza dell'utente che per i Core Web Vitals.
Lista di Controllo delle Prestazioni di Produzione
Prima di inviare, esegui queste ottimizzazioni:
- Carica le mappe in modo lento sotto la piega. Usa
IntersectionObserverper inizializzare la mappa solo quando il suo contenitore scorre nella vista. Questo rinvia ~200 KB di JavaScript dal caricamento della pagina iniziale. - Mantieniti con tile vettoriali. I tile vettoriali si adattano perfettamente a qualsiasi densità dello schermo, si caricano più velocemente delle immagini raster e possono essere completamente ridisegnati dal client senza ulteriori round-trip del server. MapAtlas fornisce tile vettoriali per impostazione predefinita.
- Raggruppa grandi insiemi di marcatori. Oltre 100-200 marcatori, il rendering non raggruppato in una visualizzazione con zoom ridotto causa notevole calo di frame. Il clustering risolve completamente questo problema.
- Mantieni la tua chiave API sul lato server. Non eseguire mai il commit delle chiavi in un repository pubblico. Usa variabili d'ambiente (
NEXT_PUBLIC_MAPATLAS_KEYin Next.js) o esegui il proxy delle richieste attraverso il tuo backend per operazioni sensibili. - Imposta
maxBoundsper app regionali. Se i tuoi utenti si preoccupano solo di una geografia, limita il viewport in modo che i tile al di fuori di quell'area non vengano mai richiesti. Meno chiamate di rete, caricamento più veloce.
Cosa Costruire Dopo
Hai una mappa che esegue il rendering, mostra marcatori, ricerca indirizzi e si integra con React. Ecco dove andare da qui:
- Routing API: Richiedi indicazioni turno per turno tra due coordinate. Restituisce una polilina di percorso, distanza totale e tempo di viaggio stimato.
- Isochrone API: Genera un poligono che copre ogni punto raggiungibile entro n minuti. Utilizzato per zone di consegna, mappe di copertura di servizi e analisi dell'area di cattura.
- Matrix API: Calcola il tempo di viaggio e la distanza tra più origini e destinazioni in una singola richiesta. Essenziale per il dispatch di flotta e l'ottimizzazione della logistica.
Il riferimento completo dell'SDK, la documentazione dello stile e le guide dell'API sono disponibili su docs.mapatlas.xyz.
Domande Frequenti
Posso aggiungere mappe interattive al mio sito gratuitamente?
Sì. MapAtlas offre un livello gratuito senza carta di credito necessaria alla registrazione. Include il rendering di tile vettoriali, l'API di Geocodifica e l'API di Routing. È sufficiente per lo sviluppo e l'uso di produzione su piccola scala.
Come faccio a incorporare una mappa in un'app React o Next.js?
Racchiudi l'inizializzazione della mappa in un hook useEffect in modo che venga eseguita dopo il mount del DOM. In Next.js, usa dynamic() con ssr: false per evitare errori di rendering sul lato server. Entrambi gli approcci sono coperti con esempi copia-incolla in questo tutorial.
Cosa sono i tile vettoriali e perché dovrei usarli al posto di raster?
I tile vettoriali descrivono le feature della mappa (strade, edifici, etichette) come geometria matematica piuttosto che immagini di pixel pre-renderizzate. Si adattano nitidamente a qualsiasi risoluzione, si caricano più velocemente e possono essere completamente ridisegnati dal client senza ulteriori round-trip del server.
Quanti marcatori posso aggiungere prima che le prestazioni si deteriorino?
Il rendering normalmente si degrada oltre 100-200 marcatori a bassi livelli di zoom. La correzione è il clustering: l'SDK MapAtlas supporta nativamente il clustering della fonte GeoJSON, raggruppando marcatori vicini a basso zoom e espandendoli mentre l'utente fa zoom.
Devo avere esperienza GIS per usare MapAtlas?
No. L'SDK è progettato per sviluppatori web, non per specialisti GIS. Inizializzi una mappa con coordinate e un livello di zoom, aggiungi marcatori con coppie di longitudine/latitudine e chiami l'API di Geocodifica con testo semplice. Nessun database spaziale o strumento GIS richiesto.