Overlay riquadro

Seleziona piattaforma: Android iOS JavaScript

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

Esempi di codice

Il repository ApiDemos su GitHub include un esempio che dimostra la funzionalità dell'overlay del riquadro:

Introduzione

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

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

Gli overlay riquadro sono utili quando vuoi aggiungere immagini estese alla mappa, in genere per aree geografiche di grandi dimensioni. Al contrario, gli overlay del terreno sono utili quando vuoi correggere una singola immagine in una zona della mappa.

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

Coordinate di riquadri e livelli di zoom

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

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

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

Ad esempio, al livello di zoom 2 la terra è divisa in 16 riquadri. A ogni riquadro può essere fatto riferimento con 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 di riquadri, 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 dpi (512 x 512 px). Per informazioni su come supportare schermi di varie dimensioni e densità, consulta la documentazione per gli sviluppatori Android.

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. Tiene conto del tipo di mappa attualmente in uso. Ad esempio, una mappa satellitare o del rilievo potrebbe avere un livello di zoom massimo inferiore rispetto ai riquadri della mappa di base.
  2. GoogleMap.getMinZoomLevel() restituisce il livello minimo di zoom, che è lo stesso per tutte le località (a differenza del livello massimo di zoom), ma può variare in base al dispositivo e alla mappa.

Aggiungi un overlay riquadro

Il modo più semplice e comune per creare un overlay riquadro consiste nel fornire un URL che punta 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 rimanda 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 di riquadri su un server, definito per tutte le coordinate x,y e i livelli di zoom che intendi supportare. Quindi aggiungi l'overlay del riquadro:

  1. Definisci un UrlTileProvider per fornire le immagini 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 passare in dissolvenza. Il valore predefinito è true. Può essere utile disattivare la dissolvenza in uscita quando passi velocemente da un overlay di riquadro all'altro. Per informazioni sulla relazione tra trasparenza e dissolvenza, consulta la sezione sulla trasparenza di seguito.
    • tileProvider: il 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 indica il valore completamente opaco (impostazione predefinita) e 1.0f indica che il valore è completamente trasparente. Consulta la sezione sulla trasparenza di seguito per un esempio di codice e la relazione tra trasparenza e dissolvenza in entrata.
    • visible: valore booleano. Specifica la visibilità dell'overlay del riquadro. Un overlay invisibile del riquadro (valore false) non viene tracciato sulla mappa, ma conserva tutte le altre proprietà. Il valore predefinito è true.
    • zIndex: determina l'ordine in cui verranno disegnati gli overlay dei riquadri rispetto ad altri overlay, inclusi overlay del terreno, cerchi, polilinee e poligoni. Gli overlay con uno z-index più alto vengono disegnati sopra quelli con z-index più bassi. L'ordine degli overlay con lo stesso z-index è arbitrario. Il valore predefinito di z-index è 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 la sezione TileOverlayDemoActivity del codice campione in bundle con l'SDK Google Play Services.

Impostare la trasparenza per gli overlay riquadro

Può essere utile sovrapporre riquadri trasparenti sulla mappa, in modo che gli utenti possano visualizzare la mappa di base sotto i riquadri sovrapposti. Per farlo, fornisci i tuoi riquadri trasparenti o imposta un fattore di trasparenza sull'overlay dei riquadri 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 viene implementata come moltiplicatore di canale alpha per le immagini a mosaico. Per impostare la trasparenza di un overlay riquadro, fornisci un oggetto TileOverlayOptions con transparency nell'intervallo [0.0f, 1.0f] come mostrato nell'esempio sopra. Un 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 modificarlo chiamando TileOverlay.setTransparency().

Trasparenza, animazione e dissolvenza in entrata

Non viene visualizzata alcuna animazione quando viene modificata la trasparenza. L'opzione per la trasparenza funziona insieme all'opzione fadeIn.

La dissolvenza in entrata offre un'animazione trasparente al caricamento di riquadri. Se imposti un valore per la trasparenza, i riquadri diventano completamente trasparenti rispetto al valore definito. Se modifichi la trasparenza durante la dissolvenza, l'animazione continua verso la nuova trasparenza target.

Rimuovere un overlay riquadro

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

Java


tileOverlay.remove();

Kotlin


tileOverlay?.remove()

Cancella riquadri inattivi

Se i riquadri forniti dall'overlay del riquadro diventano "inattivi", puoi chiamare clearTileCache() per forzare l'aggiornamento. Di conseguenza, tutti i riquadri di questo overlay verranno ricaricati. Ad esempio, se i riquadri forniti dalla TileProvider cambiano, devi chiamare clearTileCache() in un secondo momento per assicurarti che i riquadri precedenti non siano più visualizzati.

Java


tileOverlay.clearTileCache();

Kotlin


tileOverlay?.clearTileCache()