Riferimento stile per l'API Maps JavaScript

Seleziona la piattaforma: Android iOS JavaScript

Con le opzioni di stile puoi personalizzare la presentazione degli stili di mappa standard di Google, modificando la visualizzazione di elementi come strade, parchi, attività e altri punti d'interesse. Oltre a modificare lo stile di queste funzionalità, puoi nasconderle completamente. Ciò significa che puoi enfatizzare determinati componenti della mappa o integrare la mappa nello stile della pagina circostante.

Esempi

La seguente dichiarazione di stile JSON trasforma tutti gli elementi della mappa in grigio, poi colora in blu la geometria delle strade principali e nasconde completamente le etichette del paesaggio:

[
  {
    "featureType": "all",
    "stylers": [
      { "color": "#C0C0C0" }
    ]
  },{
    "featureType": "road.arterial",
    "elementType": "geometry",
    "stylers": [
      { "color": "#CCFFFF" }
    ]
  },{
    "featureType": "landscape",
    "elementType": "labels",
    "stylers": [
      { "visibility": "off" }
    ]
  }
]

L'oggetto JSON

Una dichiarazione di stile JSON è composta dai seguenti elementi:

  • (Facoltativo) featureType: le funzionalità da selezionare per questa modifica dello stile. Gli elementi sono caratteristiche geografiche sulla mappa, tra cui strade, parchi, specchi d'acqua e altro ancora. Se non specifichi una funzionalità, vengono selezionate tutte le funzionalità.
  • (Facoltativo) elementType: la proprietà della funzionalità specificata da selezionare. Gli elementi sono sottoparti di un elemento, come etichette e geometria. Se non specifichi un elemento, vengono selezionati tutti gli elementi della caratteristica.
  • stylers: le regole da applicare alle funzionalità e agli elementi selezionati. Gli stili di stile indicano il colore, la visibilità e il peso dell'elemento. Puoi applicare uno o più stili di stile a un elemento.

Per specificare uno stile, devi combinare un insieme di selettori featureType e elementType e stylers in un array di stile. Puoi scegliere come target qualsiasi combinazione di caratteristiche in un singolo array. Tuttavia, il numero di stili che puoi applicare contemporaneamente è limitato. Se l'array di stili supera il numero massimo di caratteri, non viene applicato nessuno stile.

Il resto di questa pagina contiene ulteriori informazioni su funzionalità, elementi e stili.

featureType

Il seguente snippet JSON seleziona tutte le strade sulla mappa:

{
  "featureType": "road"
}

Gli elementi o i tipi di elementi sono caratteristiche geografiche sulla mappa, tra cui strade, parchi, specchi d'acqua, attività commerciali e altro ancora.

Le caratteristiche formano un albero delle categorie, con all come radice. Se non specifichi una funzionalità, vengono selezionate tutte le funzionalità. Specificare una funzionalità di all ha lo stesso effetto.

Alcune caratteristiche contengono caratteristiche secondarie specificate utilizzando una notazione dei punti. Ad esempio, landscape.natural o road.local. Se specifichi solo la funzionalità principale, come road, gli stili specificati per l'elemento principale si applicano a tutte le funzionalità secondarie, ad esempio road.local e road.highway.

Tieni presente che le funzionalità principali possono includere alcuni elementi non inclusi in tutte le rispettive funzionalità secondarie.

Sono disponibili le seguenti funzionalità:

  • all (impostazione predefinita) seleziona tutte le funzionalità.
  • administrative seleziona tutte le aree amministrative. Lo stile influisce solo sulle etichette delle aree amministrative, non sui confini geografici o sui riempimenti.
    • administrative.country seleziona i paesi.
    • administrative.land_parcel seleziona lotti di terreno.
    • administrative.locality seleziona le località.
    • administrative.neighborhood seleziona i quartieri.
    • administrative.province seleziona le province.
  • landscape seleziona tutti i paesaggi.
    • landscape.man_made seleziona elementi creati dall'uomo, come edifici e altre strutture.
    • landscape.natural seleziona elementi naturali come montagne, fiumi, deserti e ghiacciai.
    • landscape.natural.landcover seleziona gli elementi di copertura del suolo, il materiale fisico che ricopre la superficie terrestre, ad esempio foreste, praterie, paludi e terra nuda.
    • landscape.natural.terrain seleziona gli elementi del terreno di una superficie terrestre, come altitudine, pendenza e orientamento.
  • poi seleziona tutti i punti d'interesse.
    • poi.attraction seleziona le attrazioni turistiche.
    • poi.business seleziona le attività.
    • poi.government seleziona gli edifici governativi.
    • poi.medical seleziona servizi di emergenza, tra cui ospedali, farmacie, polizia, medici e altri.
    • poi.park seleziona i parchi.
    • poi.place_of_worship seleziona i luoghi di culto, tra cui chiese, templi, moschee e altri ancora.
    • poi.school seleziona le scuole.
    • poi.sports_complex seleziona complessi sportivi.
  • road seleziona tutte le strade.
    • road.arterial seleziona le strade principali.
    • road.highway seleziona le autostrade.
    • road.highway.controlled_access seleziona le autostrade con accesso controllato.
    • road.local seleziona le strade locali.
  • transit seleziona tutte le stazioni e le linee di trasporto pubblico.
    • transit.line seleziona le linee di trasporto pubblico.
    • transit.station seleziona tutte le stazioni di trasporto pubblico.
    • transit.station.airport seleziona gli aeroporti.
    • transit.station.bus seleziona le fermate dell'autobus.
    • transit.station.rail seleziona le stazioni ferroviarie.
  • water seleziona masse d'acqua.

elementType

Il seguente snippet JSON seleziona le etichette per tutte le strade locali:

{
  "featureType": "road.local",
  "elementType": "labels"
}

Gli elementi sono suddivisioni di un elemento. Una strada, ad esempio, è composta dalla linea grafica (la geometria) sulla mappa e anche dal testo che ne indica il nome (un'etichetta).

Sono disponibili i seguenti elementi, ma tieni presente che una funzionalità specifica potrebbe supportare nessuno, alcuni o tutti gli elementi:

  • all (impostazione predefinita) seleziona tutti gli elementi della funzionalità specificata.
  • geometry seleziona tutti gli elementi geometrici della caratteristica specificata.
    • geometry.fill seleziona solo il riempimento della geometria dell'elemento.
    • geometry.stroke seleziona solo il tratto della geometria dell'elemento.
  • labels seleziona le etichette di testo associate alla funzionalità specificata.
    • labels.icon seleziona solo l'icona visualizzata all'interno dell'etichetta dell'elemento.
    • labels.text seleziona solo il testo dell'etichetta.
    • labels.text.fill seleziona solo il riempimento dell'etichetta. Il riempimento di un'etichetta solitamente viene visualizzato sotto forma di contorno colorato che circonda il testo dell'etichetta.
    • labels.text.stroke seleziona solo il tratto del testo dell'etichetta.

stylers

Gli stili di stile sono opzioni di formattazione che puoi applicare a elementi ed elementi della mappa.

Il seguente snippet JSON mostra una funzionalità di colore verde brillante, con un valore RGB:

"stylers": [
  { "color": "#99FF33" }
]

Questo snippet rimuove ogni intensità dal colore di una caratteristica, indipendentemente dal suo colore iniziale. L'effetto è il rendering della caratteristica in scala di grigi:

"stylers": [
  { "saturation": -100 }
]

Questo snippet nasconde completamente una funzionalità:

    "stylers": [
      { "visibility": "off" }
    ]

Sono supportate le seguenti opzioni di stile:

  • hue (una stringa esadecimale RGB del formato #RRGGBB) indica il colore di base.

    Nota: questa opzione imposta la tonalità mantenendo la saturazione e la luminosità specificate nello stile predefinito di Google (o in altre opzioni di stile che definisci sulla mappa). Il colore risultante è relativo allo stile della mappa base. Se Google apporta modifiche allo stile della mappa di base, le modifiche influiscono sugli elementi della mappa con uno stile hue. Se possibile, è meglio utilizzare lo styler color assoluto.

  • lightness (un valore in virgola mobile compreso tra -100 e 100) indica la variazione percentuale della luminosità dell'elemento. I valori negativi aumentano l'oscurità (dove -100 specifica il nero), mentre i valori positivi aumentano la luminosità (dove +100 specifica il bianco).

    Nota: questa opzione imposta la luminosità mantenendo la saturazione e la tonalità specificate nello stile predefinito di Google (o in altre opzioni di stile che definisci sulla mappa). Il colore risultante è relativo allo stile della mappa base. Se Google apporta modifiche allo stile della mappa di base, le modifiche influiscono sugli elementi della mappa con uno stile lightness. Se possibile, è preferibile utilizzare lo styler color assoluto.

  • saturation (un valore in virgola mobile compreso tra -100 e 100) indica la variazione percentuale dell'intensità del colore di base da applicare all'elemento.

    Nota: questa opzione imposta la saturazione mantenendo la tonalità e la luminosità specificate nello stile predefinito di Google (o in altre opzioni di stile che definisci sulla mappa). Il colore risultante è relativo allo stile della mappa base. Se Google apporta modifiche allo stile della mappa di base, le modifiche influiscono sugli elementi della mappa con uno stile saturation. Se possibile, è preferibile utilizzare lo strumento di stile color assoluto.

  • gamma (un valore in virgola mobile compreso tra 0.01 e 10.0, dove 1.0 non applica alcuna correzione) indica la quantità di correzione gamma da applicare all'elemento. Le correzioni gamma modificano la luminosità dei colori in modo non lineare, senza influire sui valori del bianco o del nero. In genere, la correzione gamma viene utilizzata per modificare il contrasto di più elementi. Ad esempio, puoi modificare la gamma per aumentare o diminuire il contrasto tra i bordi e l'interno degli elementi.

    Nota: questa opzione regola la luminosità in base allo stile Google predefinito, utilizzando una curva gamma. Se Google apporta modifiche allo stile della mappa base, le modifiche influiscono sugli elementi della mappa con lo stile gamma. È preferibile utilizzare lo strumento di stile color assoluto, se possibile.

  • invert_lightness (se true) inverte la luminosità esistente. Questo è utile, ad esempio, per passare rapidamente a una mappa più scura con testo bianco.

    Nota: questa opzione inverte semplicemente lo stile predefinito di Google. Se Google apporta modifiche allo stile della mappa di base, le modifiche influiscono sugli elementi della mappa con lo stile invert_lightness. Se possibile, è preferibile utilizzare lo strumento di stile color assoluto.

  • visibility (on, off o simplified) indica se e come l'elemento viene visualizzato sulla mappa. Una visibilità simplified rimuove alcuni elementi di stile dagli elementi interessati; le strade, ad esempio, vengono semplificate in linee più sottili senza contorni, mentre i parchi perdono il testo dell'etichetta ma mantengono l'icona dell'etichetta.
  • color (una stringa esadecimale RGB del formato #RRGGBB) imposta il colore della funzionalità.
  • weight (un valore intero maggiore o uguale a zero) imposta il peso della funzionalità in pixel. L'impostazione di un valore elevato per la ponderazione potrebbe causare tagli vicino ai bordi dei riquadri.

Le regole di stile vengono applicate nell'ordine specificato. Non combinare più operazioni in un'unica operazione di stile. Definisci invece ogni operazione come voce separata nell'array di stile.

Nota: l'ordine è importante, poiché alcune operazioni non sono commutative. Le caratteristiche e/o gli elementi modificati tramite operazioni di stile (di solito) dispongono già di stili esistenti. Le operazioni agiscono sugli stili esistenti, se presenti.

Il modello di tonalità, saturazione e chiarezza

Le mappe con stili utilizzano il modello HSL (tonalità, saturazione e chiarezza) per indicare il colore nelle operazioni dello strumento di stile. La tonalità indica il colore di base, la saturazione indica l'intensità di quel colore, mentre la lucezza indica la quantità relativa di bianco o nero nel colore che lo costituisce.

La correzione gamma modifica la luminosità sullo spazio cromatico, in genere per aumentare o diminuire il contrasto. Inoltre, il modello HSL definisce il colore all'interno di uno spazio di coordinate in cui hue indica l'orientamento all'interno di una ruota dei colori, mentre la saturazione e la luminosità indicano le ampiezze su assi diversi. Le tonalità vengono misurate all'interno di uno spazio colore RGB, che è simile alla maggior parte degli spazi colore RGB, ad eccezione del fatto che le tonalità di bianco e nero sono assenti.

Modello di tonalità, saturazione e luminosità

Sebbene hue utilizzi un valore colore esadecimale HTML, questo valore viene utilizzato solo per determinare il colore di base, ovvero l'orientamento intorno alla ruota dei colori, non la saturazione o la luminosità, che vengono indicate separatamente come variazioni percentuali.

Ad esempio, puoi definire la tonalità del verde puro come hue:0x00ff00 o hue:0x000100. Entrambe le tonalità sono identiche. Entrambi i valori puntano al verde puro nel modello di colore HSL.

Ruota dei colori RGB

I valori hue RGB, composti da parti uguali di rosso, verde e blu, non indicano una tonalità, perché nessuno di questi valori indica un orientamento nello spazio delle coordinate HSL. Alcuni esempi sono "#000000" (nero), "#FFFFFF" (bianco) e tutte le sfumature pure di grigio. Per indicare il nero, il bianco o il grigio, devi rimuovere tutti gli elementi saturation (impostare il valore su -100) e regolare invece lightness.

Inoltre, quando modifichi gli elementi esistenti che hanno già una combinazione di colori, la modifica di un valore come hue non cambia il valore saturation o lightness esistente.