Come stilizzare una mappa con brand personalizzato (modalita scura, colori, senza filigrane)

Ogni mappa che hai mai visto nell'app di un concorrente usa lo stesso stile predefinito. Le strade beige generiche, l'acqua color teal medio, le icone POI sovraffollate che lottano per l'attenzione con la tua interfaccia utente: questi sono i valori predefiniti universali, progettati per non dispiacere a nessuno e per non entusiasmare nessuno. Comunicano una cosa chiaramente: questo prodotto sta usando una libreria mappa, non possedendo la propria esperienza cartografica.

La stilizzazione personalizzata della mappa cambia tutto ciò. Una mappa in modalità scura su un dashboard logistico, una rete stradale verde-brand su un'app immobiliare, uno stile minimalista pulito con il tuo logo al posto della filigrana di attribuzione: questi sono dettagli che elevano uno strumento a prodotto.

Questo tutorial illustra la Mapbox Style Specification implementata da MapAtlas, dalla struttura del JSON dello stile fino a un toggle luce/scuro completo in React. Non hai bisogno di esperienza GIS: devi sentirti a tuo agio con JSON e JavaScript.

Se non hai ancora configurato una mappa di base, inizia con Come aggiungere mappe interattive al tuo sito web prima, poi torna qui per la stilizzazione.

Perché gli stili predefiniti delle mappe sembrano generici

Lo stile predefinito di un tile provider è progettato per essere universalmente leggibile per il pubblico più ampio possibile, nel contesto più ampio possibile. Privilegia la densità informativa rispetto all'opinione estetica. Le strade devono essere visibili. Le etichette devono avere contrasto. Le icone POI devono essere riconoscibili.

Nessuno di questi obiettivi si allinea con gli obiettivi del tuo prodotto. La tua app probabilmente si preoccupa di un sottoinsieme ridotto di ciò che è sulla mappa: percorsi di consegna, posizioni delle proprietà, strutture sanitarie, e tutto il resto è rumore visivo.

La stilizzazione personalizzata ti consente di sopprimere ciò di cui non hai bisogno, evidenziare ciò che ti serve e garantire che la mappa sembri parte del tuo prodotto piuttosto che un widget di terze parti inserito.

Capire la specifica di stile

Uno stile MapAtlas è un documento JSON con cinque sezioni principali:

{
  "version": 8,
  "name": "My Brand Style",
  "sources": { ... },
  "glyphs": "https://tiles.mapatlas.eu/fonts/{fontstack}/{range}.pbf?key=YOUR_API_KEY",
  "sprite": "https://tiles.mapatlas.eu/sprites/basic?key=YOUR_API_KEY",
  "layers": [ ... ]
}

• sources: da dove provengono i dati della mappa (endpoint dei vector tile di MapAtlas)
• glyphs: da dove caricare i file di font per il rendering delle etichette
• sprite: da dove caricare le immagini delle icone per i marker POI
• layers: l'elenco ordinato dei layer visivi, ognuno con proprietà di paint e layout

L'array layers è dove passi la maggior parte del tempo. Ogni layer specifica un tipo di dato (fill, line, symbol, circle, fill-extrusion), quali feature della sorgente disegnare, e come renderle.

Ecco uno stile minimale ma completo che renderizza una base di vector tile:

{
  "version": 8,
  "name": "Brand Base",
  "sources": {
    "mapatlas": {
      "type": "vector",
      "tiles": ["https://tiles.mapatlas.eu/v1/tiles/{z}/{x}/{y}.mvt?key=YOUR_API_KEY"],
      "minzoom": 0,
      "maxzoom": 14
    }
  },
  "glyphs": "https://tiles.mapatlas.eu/fonts/{fontstack}/{range}.pbf?key=YOUR_API_KEY",
  "sprite": "https://tiles.mapatlas.eu/sprites/basic?key=YOUR_API_KEY",
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": { "background-color": "#f5f0eb" }
    }
  ]
}

Questo renderizza una tela bianca nel colore di sfondo scelto. Da qui aggiungi layer per acqua, uso del suolo, strade, edifici ed etichette.

Modalità scura: cambiare i colori principali

Una mappa in modalità scura non è semplicemente un'immagine raster invertita. È un insieme completamente diverso di proprietà di paint applicate alla stessa geometria vettoriale. Questo è uno dei motivi principali per cui esistono i vector tile: una sola tile, infinite interpretazioni visive.

I colori chiave da aggiornare per un tema scuro:

Ecco come applicarlo in un layer di stile:

{
  "id": "water",
  "type": "fill",
  "source": "mapatlas",
  "source-layer": "water",
  "paint": {
    "fill-color": "#0d3b66",
    "fill-opacity": 1
  }
}

{
  "id": "road-major",
  "type": "line",
  "source": "mapatlas",
  "source-layer": "transportation",
  "filter": ["==", "class", "primary"],
  "layout": {
    "line-join": "round",
    "line-cap": "round"
  },
  "paint": {
    "line-color": "#3a3a5c",
    "line-width": ["interpolate", ["linear"], ["zoom"], 10, 1, 16, 4]
  }
}

L'espressione interpolate in line-width scala la larghezza della strada in base al livello di zoom: stretta a basso zoom, più larga man mano che si ingrandisce. Si tratta di stilizzazione basata sui dati senza richieste di rete aggiuntive.

Applicare i colori del brand

La maggior parte dei sistemi di design definisce un colore primario (ad esempio #97C70A), un colore secondario e una palette neutra. La mappa dovrebbe usare esattamente questi valori, non approssimazioni.

Punta a questi layer per l'applicazione del colore brand:

Strade come elementi del brand. Se il colore del tuo brand è abbastanza vivace, usalo per le strade principali o i percorsi evidenziati:

{
  "id": "road-highlighted",
  "type": "line",
  "source": "mapatlas",
  "source-layer": "transportation",
  "filter": ["==", "class", "primary"],
  "paint": {
    "line-color": "#97C70A",
    "line-width": 3,
    "line-opacity": 0.8
  }
}

Marker POI personalizzati. Sostituisci le icone sprite predefinite con le tue ospitando uno sprite sheet personalizzato e aggiornando l'URL sprite. Poi fai riferimento alle tue icone nei layer symbol:

{
  "id": "brand-poi",
  "type": "symbol",
  "source": "mapatlas",
  "source-layer": "poi",
  "layout": {
    "icon-image": "brand-pin",
    "icon-size": 1.2,
    "text-field": ["get", "name"],
    "text-font": ["Inter Bold", "Noto Sans Regular"],
    "text-size": 12,
    "text-offset": [0, 1.5],
    "text-anchor": "top"
  },
  "paint": {
    "text-color": "#97C70A",
    "text-halo-color": "#1a1a2e",
    "text-halo-width": 1
  }
}

Font personalizzati per le etichette della mappa

I font predefiniti delle etichette della mappa sono generici. Se il tuo brand usa Inter, Roboto o un carattere tipografico personalizzato, puoi usarlo anche per le etichette della mappa.

MapAtlas serve glifi dal proprio endpoint di glifo, che supporta il formato glifo Mapbox standard. Per usare un font personalizzato:

1. Genera file di glifo .pbf dal tuo carattere tipografico usando uno strumento come fontnik.
2. Ospita i file di glifo su una CDN o sul tuo server.
3. Aggiorna il campo glyphs nel tuo JSON di stile:

{
  "glyphs": "https://your-cdn.com/fonts/{fontstack}/{range}.pbf"
}

4. Fai riferimento al font nella proprietà text-font di qualsiasi layer symbol:

"text-font": ["Inter Bold", "Noto Sans Regular"]

Fornisci sempre un font di fallback (Noto Sans copre i caratteri Unicode che il tuo font primario potrebbe non includere). Il renderer usa il primo font nell'array che contiene un glifo per ogni carattere.

Rimozione di filigrane e attribuzioni

MapAtlas consente la distribuzione white-label completa. Puoi rimuovere completamente il logo MapAtlas dalla mappa.

Nell'SDK, l'attribuzione è gestita da un controllo che puoi disabilitare:

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,
  attributionControl: false,  // Remove the default attribution control
});

Se vuoi mantenere l'attribuzione ma stilizzarla per corrispondere alla tua interfaccia utente, nascondi il controllo predefinito e aggiungine uno tuo:

map.addControl(
  new mapmetricsgl.AttributionControl({
    customAttribution: 'Map data © OpenStreetMap contributors',
    compact: true,
  }),
  'bottom-left'
);

Questo sostituisce il branding con un'attribuzione minimale e legalmente conforme che rispetta la licenza di OpenStreetMap adattandosi alla tua interfaccia utente. A differenza di Google Maps, che richiede che il suo logo rimanga visibile in ogni momento indipendentemente dal tuo piano, MapAtlas ti dà il pieno controllo.

Toggle luce/scuro in React

Ecco un componente React completo che gestisce una mappa con un toggle luce/scuro, usando le proprietà CSS personalizzate per mantenere il tema sincronizzato con il resto della tua interfaccia:

import { useEffect, useRef, useState } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const STYLES = {
  light: 'https://tiles.mapatlas.eu/styles/basic/style.json?key=YOUR_API_KEY',
  dark:  'https://tiles.mapatlas.eu/styles/dark/style.json?key=YOUR_API_KEY',
};

export function BrandedMap({ center = [4.9041, 52.3676], zoom = 12 }) {
  const containerRef = useRef(null);
  const mapRef       = useRef(null);
  const [theme, setTheme] = useState('light');

  useEffect(() => {
    const map = new mapmetricsgl.Map({
      container:        containerRef.current,
      style:            STYLES.light,
      center,
      zoom,
      attributionControl: false,
    });

    map.addControl(
      new mapmetricsgl.AttributionControl({ compact: true }),
      'bottom-left'
    );

    mapRef.current = map;
    return () => map.remove();
  }, []);

  useEffect(() => {
    if (mapRef.current) {
      mapRef.current.setStyle(STYLES[theme]);
    }
  }, [theme]);

  return (
    <div style={{ position: 'relative' }}>
      <div ref={containerRef} style={{ width: '100%', height: '500px' }} />
      <button
        onClick={() => setTheme(t => t === 'light' ? 'dark' : 'light')}
        style={{
          position: 'absolute',
          top: 12,
          right: 12,
          padding: '8px 16px',
          background: theme === 'dark' ? '#ffffff' : '#1a1a2e',
          color:      theme === 'dark' ? '#1a1a2e' : '#ffffff',
          border: 'none',
          borderRadius: 6,
          cursor: 'pointer',
          zIndex: 1,
        }}
      >
        {theme === 'light' ? 'Dark mode' : 'Light mode'}
      </button>
    </div>
  );
}

La chiamata setStyle ri-renderizza la mappa con il nuovo schema di colori. I dati tile già in cache non vengono recuperati di nuovo: cambia solo l'interpretazione visiva.

Ospitare un JSON di stile personalizzato

Per il pieno controllo, ospita il tuo JSON di stile come file statico sulla tua CDN o su S3. Questo ti consente di:

• Versionare il tuo stile insieme al codice dell'applicazione.
• Aggiornare il design visivo senza ridistribuire l'applicazione (basta aggiornare il JSON ospitato).
• Usare stili diversi per ambienti diversi (anteprima vs. produzione).

Carica uno stile ospitato a runtime:

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://your-cdn.com/styles/brand-dark.json',
  center: [4.9041, 52.3676],
  zoom: 12,
});

L'unico vincolo è il CORS: il JSON di stile deve essere servito con Access-Control-Allow-Origin: * (o il tuo dominio specifico) in modo che il browser possa recuperarlo cross-origin.

Workflow di sviluppo dello stile

Il modo più veloce per costruire uno stile personalizzato è iterativo: vedere i cambiamenti in tempo reale senza riscrivere codice.

1. Inizia con un JSON di stile base di MapAtlas come fondamento. Scaricalo recuperando https://tiles.mapatlas.eu/styles/basic/style.json?key=YOUR_API_KEY.
2. Modifica il JSON nel tuo editor, osservando quale layer influisce su quale elemento visivo.
3. Ricarica la mappa con il tuo JSON di stile modificato per vedere il risultato.
4. Una volta stabile, effettua il commit del JSON di stile nel tuo repository e ospitalo sulla tua CDN.

Per personalizzazioni più approfondite, consulta la documentazione Map Visualization & Styling per il riferimento completo dei layer, i tipi di proprietà di paint e la sintassi delle espressioni.

Se vieni da Mapbox e vuoi sapere cosa è cambiato, consulta Mapbox vs. MapAtlas: quale Maps API è giusta per il tuo progetto EU? per un confronto diretto di funzionalità e prezzi.

E per la base architetturale del perché i vector tile rendono possibile tutto questo, Vector Tiles vs. Raster Tiles spiega il pipeline di rendering in dettaglio.

Riepilogo

La stilizzazione personalizzata della mappa non è un lusso: è la differenza tra una mappa che sembra un widget di terze parti e una che sembra costruita per il tuo prodotto. Con MapAtlas:

• La specifica di stile è JSON standard compatibile con gli strumenti Mapbox GL JS.
• La modalità scura è uno scambio del JSON di stile, non un nuovo set di tile o una configurazione del server.
• I colori del brand si applicano a strade, etichette e icone POI tramite le proprietà di paint.
• I font personalizzati si caricano da qualsiasi endpoint glifo che controlli.
• Le filigrane e l'attribuzione sono completamente configurabili: il white-label è supportato su tutti i piani a pagamento.
• L'intero stile può essere cambiato a runtime senza ricaricare la pagina.

Inizia subito a costruire la tua mappa con brand personalizzato. Registrati per una chiave API MapAtlas gratuita e carica il JSON di stile base come punto di partenza. Il primo stile personalizzato richiede circa 30 minuti per essere messo a punto; le iterazioni successive richiedono minuti.