Sovrapposizioni riquadri

Seleziona la piattaforma: Android iOS JavaScript

Un overlay di riquadri, a volte chiamato livello riquadro, è una raccolta di immagini che vengono visualizzate sopra i riquadri della mappa base.

Esempi di codice

Il repository ApiDemos su GitHub include un esempio che dimostra la funzionalità di overlay dei riquadri:

Introduzione

Un TileOverlay definisce un insieme di immagini che vengono aggiunte sopra i riquadri della mappa base.

Devi fornire i riquadri per ogni livello di zoom che vuoi supportare. Se hai un numero sufficiente di riquadri a più livelli di zoom, puoi integrare i dati mappa di Google per l'intera mappa.

Gli overlay riquadro sono utili quando vuoi aggiungere immagini estese alla mappa, in genere coprendo aree geografiche estese. Al contrario, gli overlay del suolo sono utili quando vuoi correggere una singola immagine in un'area della mappa.

Puoi anche utilizzare overlay di riquadri trasparenti per aggiungere ulteriori funzionalità alla mappa, impostando in modo programmatico un fattore di trasparenza sull'overlay del riquadro o fornendo immagini dei riquadri trasparenti.

Coordinate dei riquadri e livelli di zoom

L'API di Google Maps suddivide le immagini a ogni livello di zoom in un insieme di riquadri della mappa quadrati disposti in una griglia. Quando una mappa si sposta in una nuova posizione o a un nuovo livello di zoom, l'API di Google Maps determina quali riquadri sono necessari e traduce le informazioni in un insieme di riquadri da recuperare.

Il riquadro con le coordinate (0,0) si trova sempre nell'angolo nord-ovest della mappa, con i valori x che aumentano da ovest a est e i valori di y da nord a sud. I riquadri vengono indicizzati utilizzando le coordinate x,y di quell'origine.

A livello di zoom 0, il mondo intero viene visualizzato in un unico riquadro. Ogni livello di zoom aumenta l'ingrandimento di un fattore di due. Quindi, a livello di zoom 1, la mappa viene visualizzata come una griglia di riquadri 2x2. A livello di zoom 2, è una griglia 4 x 4. A livello di zoom 3, si tratta di una griglia 8x8 e così via.

Ad esempio, a livello di zoom 2, la Terra viene divisa in 16 riquadri. È possibile fare riferimento a ogni riquadro tramite una combinazione univoca di x, y e zoom:

Mappa del mondo divisa in quattro righe e quattro colonne di riquadri.

Quando crei immagini per un livello riquadro, devi creare un'immagine per ogni riquadro a ogni livello di zoom che vuoi supportare. Google Maps sceglie come target 256 dp (pixel indipendenti dal dispositivo) durante la visualizzazione dei riquadri. Per i dispositivi ad alta risoluzione, consigliamo di restituire riquadri con DPI elevato (512 x 512 px). Consulta la documentazione per gli sviluppatori Android per informazioni sul supporto di diverse dimensioni e densità dello schermo.

Nota: i livelli di zoom supportati dalla fotocamera dipendono da vari fattori e non sono correlati ai livelli di zoom supportati dai riquadri.

  1. GoogleMap.getMaxZoomLevel() restituisce il livello massimo di zoom disponibile nella posizione corrente della fotocamera. Questo prende in considerazione il tipo di mappa attualmente in uso. Ad esempio, una mappa satellitare o del rilievo può avere un livello di zoom massimo inferiore rispetto ai riquadri della mappa base.
  2. GoogleMap.getMinZoomLevel() restituisce il livello di zoom minimo, che è lo stesso per tutte le località (a differenza del livello massimo di zoom), ma può variare in base al dispositivo e alle dimensioni della mappa.

Aggiungere un overlay riquadro

Il modo più semplice e più comune per creare un overlay riquadro è fornire un URL che rimandi all'immagine riquadro pertinente. UrlTileProvider è un'implementazione parziale di TileProvider che fornisce riquadri di immagini basati su un URL. Questa classe richiede che tutte le immagini abbiano le stesse dimensioni.

Dovrai implementare UrlTileProvider.getTileUrl(), che accetta le coordinate del riquadro (x, y, zoom) e restituisce un URL che rimanda all'immagine da utilizzare per il riquadro. Il metodo deve restituire null se non è presente alcun riquadro per i valori x, y e zoom specificati. Un URL può indirizzare a una risorsa web, a un asset Android o a un file sul disco locale.

Configura la tua stock di immagini riquadri su un server, definito per tutte le coordinate x,y e i livelli di zoom che intendi supportare. Poi aggiungi l'overlay dei riquadri:

  1. Definisci un UrlTileProvider per fornire le immagini dei riquadri.
  2. Sostituisci getTileUrl() per creare l'URL per ogni immagine riquadro.
  3. Fornisci un oggetto TileOverlayOptions con le opzioni pertinenti:
    • fadeIn: valore booleano. Consente di specificare se i riquadri devono essere dissolvenza in entrata. Il valore predefinito è true. Può essere utile disattivare la dissolvenza in entrata quando si passa rapidamente da un overlay di un riquadro all'altro. Per informazioni sulla relazione tra trasparenza e dissolvenza in entrata, consulta la sezione sulla trasparenza di seguito.
    • tileProvider: il valore TileProvider da utilizzare per questo overlay.
    • transparency: mobile. Imposta un fattore di trasparenza per le immagini riquadro. Il valore deve essere compreso nell'intervallo [0.0f, 1.0f], dove 0.0f indica completamente opaco (predefinito) e 1.0f indica completamente trasparente. Consulta la sezione sulla trasparenza riportata di seguito per un esempio di codice e sulla relazione tra trasparenza e dissolvenza in entrata.
    • visible: valore booleano. Specifica la visibilità dell'overlay del riquadro. Un overlay riquadro invisibile (valore false) non viene tracciato sulla mappa, ma conserva tutte le altre proprietà. Il valore predefinito è true.
    • zIndex: determina l'ordine in cui verrà disegnato l'overlay riquadro rispetto ad altri overlay, inclusi overlay del suolo , cerchi, polilinee e poligoni. Gli overlay con uno z-index più elevato vengono disegnati sopra quelli con z-index più bassi. L'ordine delle sovrapposizioni con lo stesso z-index è arbitrario. Il valore predefinito di z-index è 0. Tieni presente che gli indicatori sono sempre tracciati sopra gli altri overlay, indipendentemente dallo z-index degli altri overlay.
  4. Chiama GoogleMap.addTileOverlay() per aggiungere l'overlay alla mappa.

Kotlin



private lateinit var map: GoogleMap

var tileProvider: TileProvider = object : UrlTileProvider(256, 256) {
    override fun getTileUrl(x: Int, y: Int, zoom: Int): URL? {

        /* Define the URL pattern for the tile images */
        val url = "http://my.image.server/images/$zoom/$x/$y.png"
        return if (!checkTileExists(x, y, zoom)) {
            null
        } else try {
            URL(url)
        } catch (e: MalformedURLException) {
            throw AssertionError(e)
        }
    }

    /*
     * Check that the tile server supports the requested x, y and zoom.
     * Complete this stub according to the tile range you support.
     * If you support a limited range of tiles at different zoom levels, then you
     * need to define the supported x, y range at each zoom level.
     */
    private fun checkTileExists(x: Int, y: Int, zoom: Int): Boolean {
        val minZoom = 12
        val maxZoom = 16
        return zoom in minZoom..maxZoom
    }
}

val tileOverlay = map.addTileOverlay(
    TileOverlayOptions()
        .tileProvider(tileProvider)
)

      

Java


private GoogleMap map;

TileProvider tileProvider = new UrlTileProvider(256, 256) {

    @Override
    public URL getTileUrl(int x, int y, int zoom) {

        /* Define the URL pattern for the tile images */
        String s = String.format("http://my.image.server/images/%d/%d/%d.png", zoom, x, y);

        if (!checkTileExists(x, y, zoom)) {
            return null;
        }

        try {
            return new URL(s);
        } catch (MalformedURLException e) {
            throw new AssertionError(e);
        }
    }

    /*
     * Check that the tile server supports the requested x, y and zoom.
     * Complete this stub according to the tile range you support.
     * If you support a limited range of tiles at different zoom levels, then you
     * need to define the supported x, y range at each zoom level.
     */
    private boolean checkTileExists(int x, int y, int zoom) {
        int minZoom = 12;
        int maxZoom = 16;

        return (zoom >= minZoom && zoom <= maxZoom);
    }
};

TileOverlay tileOverlay = map.addTileOverlay(new TileOverlayOptions()
    .tileProvider(tileProvider));

      

Per vedere un esempio di UrlTileProvider in azione, consulta TileOverlayDemoActivity nel codice campione abbinato all'SDK Google Play Services.

Impostare la trasparenza per gli overlay dei riquadri

Può essere utile sovrapporre riquadri trasparenti sulla mappa, in modo che gli utenti possano vedere la mappa base sotto i riquadri sovrapposti. A tale scopo, puoi fornire i tuoi riquadri trasparenti o impostare in modo programmatico un fattore di trasparenza sull'overlay del riquadro.

Il seguente esempio di codice imposta la trasparenza dell'overlay del riquadro da 0.5f a 0.0f:

Kotlin



private var tileOverlayTransparent: TileOverlay? = null

override fun onMapReady(map: GoogleMap) {
    tileOverlayTransparent = map.addTileOverlay(
        TileOverlayOptions()
            .tileProvider(object : UrlTileProvider(256, 256) {
                // ...
            })
            .transparency(0.5f)
    )
}

// Switch between 0.0f and 0.5f transparency.
fun toggleTileOverlayTransparency() {
    tileOverlayTransparent?.let {
        it.transparency = 0.5f - it.transparency
    }
}

      

Java


private TileOverlay tileOverlayTransparent;

@Override
public void onMapReady(GoogleMap map) {
    tileOverlayTransparent = map.addTileOverlay(new TileOverlayOptions()
        .tileProvider(new UrlTileProvider(256, 256) {
            // ...
        })
        .transparency(0.5f));
}

// Switch between 0.0f and 0.5f transparency.
public void toggleTileOverlayTransparency() {
    if (tileOverlayTransparent != null) {
        tileOverlayTransparent.setTransparency(0.5f - tileOverlayTransparent.getTransparency());
    }
}

      

La trasparenza è implementata come un moltiplicatore di canali alfa per le immagini riquadro. Per impostare la trasparenza di un overlay riquadro, fornisci un oggetto TileOverlayOptions con transparency nell'intervallo [0.0f, 1.0f], come mostrato nell'esempio precedente. Il valore 0.0f indica che l'overlay del riquadro è completamente opaco, mentre 1.0f indica che è completamente trasparente. Il valore predefinito è 0.0f (opaco).

Puoi accedere alla trasparenza dell'overlay del riquadro chiamando TileOverlay.getTransparency(), e puoi modificarla chiamando TileOverlay.setTransparency().

Trasparenza, animazione e dissolvenza in entrata

Non è presente alcuna animazione quando viene modificata la trasparenza. L'opzione di trasparenza opera insieme all'opzione fadeIn.

La dissolvenza in entrata fornisce un'animazione di trasparenza al caricamento dei riquadri. Se imposti un valore di trasparenza, i riquadri presentano una dissolvenza in entrata da completamente trasparente al valore di trasparenza definito. Se modifichi la trasparenza durante la dissolvenza in entrata, l'animazione continua verso la nuova trasparenza target.

Rimuovere un overlay riquadro

Puoi rimuovere un overlay riquadro con il metodo TileOverlay.remove().

Kotlin



tileOverlay?.remove()

      

Java


tileOverlay.remove();

      

Cancella riquadri inattivi

Se i riquadri forniti dall'overlay dei riquadri diventano "inattivi", puoi chiamare clearTileCache() per forzare l'aggiornamento. Di conseguenza, tutti i riquadri dell'overlay verranno ricaricati. Ad esempio, se i riquadri forniti da TileProvider cambiano, devi chiamare clearTileCache() successivamente per assicurarti che non venga più eseguito il rendering dei riquadri precedenti.

Kotlin



tileOverlay?.clearTileCache()

      

Java


tileOverlay.clearTileCache();