Overlay riquadro

Seleziona piattaforma: Android iOS JavaScript

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

Esempi di codice

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

Introduzione

Un elemento 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 disponi di riquadri sufficienti a più livelli di zoom, puoi integrare i dati della mappa di Google per l'intera mappa.

Gli overlay dei riquadri sono utili quando vuoi aggiungere immagini estese alla mappa, che in genere coprono aree geografiche di grandi dimensioni. 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 un fattore di trasparenza sull'overlay del riquadro in modo programmatico o fornendo immagini del riquadro trasparenti.

Coordinate dei riquadri e livelli di zoom

L'API di Google Maps suddivide le immagini a ciascun livello di zoom in un insieme di riquadri di mappe quadrate disposti in una griglia. Quando una mappa passa a una nuova posizione o a un nuovo livello di zoom, l'API di Maps determina quali riquadri sono necessari e traduce tali informazioni in una serie di riquadri da recuperare.

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

A livello di zoom 0, l'intero mondo viene visualizzato in un'unica sezione. Ogni livello di zoom aumenta l'ingrandimento di un fattore due. Quindi, al livello di zoom 1 la mappa verrà visualizzata come una griglia 2x2 di riquadri. Al livello di zoom 2 è una griglia 4x4. Al livello di zoom 3, è una griglia 8x8 e così via.

Ad esempio, al livello di zoom 2 la terra è divisa in 16 riquadri. Ogni riferimento può essere fatto riferimento a una combinazione unica di x, y e zoom:

Durante la creazione di immagini per un livello di 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) quando mostra i riquadri. Per i dispositivi ad alta risoluzione, consigliamo di restituire riquadri ad alta risoluzione (512 x 512 px). Leggi la documentazione per gli sviluppatori Android per avere informazioni su come supportare schermi di diverse dimensioni e densità.

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

  1. GoogleMap.getMaxZoomLevel() restituisce il livello di zoom massimo disponibile nella posizione corrente della fotocamera. Tiene conto del tipo di mappa attualmente in uso. Ad esempio, una mappa satellitare o a rilievo potrebbe 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 di zoom massimo), ma può variare tra i dispositivi e le dimensioni della mappa.

Aggiungi un overlay del riquadro

Il modo più semplice e comune per creare un overlay del riquadro è fornire un URL che rimandi all'immagine del riquadro pertinente. UrlTileProvider è un'implementazione parziale di TileProvider che fornisce riquadri immagine in base a 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 punta all'immagine da utilizzare per il riquadro. Il metodo dovrebbe 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 il tuo stock di immagini su un server, definito per tutte le coordinate X e Y e per i livelli di zoom che vuoi supportare. Quindi aggiungi l'overlay del riquadro:

  1. Definisci un UrlTileProvider per fornire le immagini del riquadro.
  2. Sostituisci getTileUrl() per creare l'URL per ogni immagine a mosaico.
  3. Fornisci un oggetto TileOverlayOptions con le opzioni pertinenti:
    • fadeIn: valore booleano. Specifica se i riquadri devono dissolversi. Il valore predefinito è true. Potrebbe essere utile disattivare la dissolvenza quando passi rapidamente da un riquadro all'altro. Per informazioni sul rapporto tra trasparenza e dissolvenza, consulta la sezione sulla trasparenza più avanti.
    • tileProvider: la proprietà TileProvider da utilizzare per questo overlay.
    • transparency: numero in virgola mobile. Imposta un fattore di trasparenza per le immagini riquadro. Il valore deve essere compreso nell'intervallo [0.0f, 1.0f] dove 0.0f significa completamente opaco (impostazione predefinita) e 1.0f significa completamente trasparente. Consulta la sezione sulla trasparenza riportata di seguito per un esempio di codice e sulla relazione tra trasparenza e dissolvenza.
    • visible: valore booleano. Specifica la visibilità dell'overlay del riquadro. L'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 del riquadro in relazione ad altri overlay, inclusi overlay del suolo, cerchi, polilinee e poligoni. Gli overlay con uno z-index superiore vengono disegnati sopra a quelli con z-index inferiori. L'ordine degli overlay con lo stesso z-index è arbitrario. Il valore z-index predefinito è 0. Tieni presente che gli indicatori vengono sempre tracciati sopra gli altri overlay, a prescindere dallo z-index degli altri overlay.
  4. Chiama GoogleMap.addTileOverlay() per aggiungere l'overlay alla mappa.

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));

      

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)
)

      

Per vedere un esempio di UrlTileProvider in azione, consulta il TileOverlayDemoActivity nel codice di esempio incluso nell'SDK di Google Play Services.

Impostare la trasparenza sugli overlay dei riquadri

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

Il seguente esempio di codice attiva/disattiva la trasparenza dell'overlay del riquadro tra 0.5f e 0.0f:

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());
    }
}

      

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
    }
}

      

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

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

Trasparenza, animazione e dissolvenza

Non è presente alcuna animazione quando la trasparenza viene modificata. L'opzione relativa alla trasparenza funziona insieme all'opzione fadeIn.

La dissolvenza fornisce un'animazione di trasparenza al caricamento del riquadro. Se imposti un valore di trasparenza, i riquadri passano da un livello di trasparenza totale a quello definito. Se modifichi la trasparenza durante la dissolvenza, l'animazione continua verso il nuovo livello di trasparenza target.

Rimuovere un overlay del riquadro

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

Java


tileOverlay.remove();

      

Kotlin


tileOverlay?.remove()

      

Cancella riquadri non attivi

Se i riquadri forniti dall'overlay riquadro diventano 'stale' puoi chiamare clearTileCache() per forzare un aggiornamento. In questo modo, tutti i riquadri di questo overlay verranno ricaricati. Ad esempio, se i riquadri forniti da TileProvider cambiano, devi chiamare clearTileCache() in seguito per assicurarti che i riquadri precedenti non vengano più visualizzati.

Java


tileOverlay.clearTileCache();

      

Kotlin


tileOverlay?.clearTileCache()