Nakładki z płytkami

Wybierz platformę: Android iOS JavaScript

Nakładka z kafelkami to kolekcja obrazów, które są wyświetlane na górze kafelków mapy podstawowej.

Przykłady kodów

Repozytorium ApiDemos w GitHubie zawiera przykład, który przedstawia funkcję nakładania kafelków:

Wprowadzenie

TileOverlay określa zbiór obrazów, które zostaną dodane do podstawowych kafelków mapy.

Musisz dodać kafelki dla każdego poziomu powiększenia, który chcesz obsługiwać. Jeśli masz odpowiednio dużo kafelków przy wielu poziomach powiększenia, możesz uzupełnić dane map Google obejmujące całą mapę.

Nakładki z fragmentami mapy są przydatne, gdy chcesz dodać do mapy rozbudowane zdjęcia, które zwykle obejmują duże obszary geograficzne. Natomiast nakładki na powierzchnię są przydatne, gdy chcesz poprawić pojedynczy obraz na jednym obszarze na mapie.

Możesz też dodać nakładki mapy, korzystając z przezroczystych nakładek. Możesz też automatycznie ustawić współczynnik przezroczystości na nałożonych kafelkach albo dodać przezroczyste obrazy kafelków.

Współrzędne fragmentu i poziomy powiększenia

Interfejs API Map Google dzieli zdjęcia na każdym poziomie powiększenia na zbiór kwadratowych kafelków mapy ułożonych w siatkę. Gdy mapa zostanie przeniesiona do nowej lokalizacji lub na nowy poziom powiększenia, interfejs API Map Google określi, jakie kafelki są potrzebne, i przekształci te informacje na zestaw kafelków do pobrania.

Kafelek ze współrzędnymi (0,0) zawsze jest na północnym zachodzie mapy, gdzie x wartości rośnie z zachodu na wschód i z półki z północy na południe. Kafelki są indeksowane przy użyciu współrzędnych x,y z tego źródła.

Na poziomie 0 cały świat jest renderowany na jednym kafelku. Każdy poziom powiększenia zwiększa powiększenie o dwa poziomy. W przypadku powiększenia na poziomie 1 mapa będzie renderowana jako siatka 2 x 2. Na poziomie powiększenia 2 to siatka 4 x 4. Na poziomie 3 jest to siatka 8 x 8 itd.

Na przykład na poziomie 2 Ziemia jest podzielona na 16 kafelków. Do każdego kafelka może się odwoływać unikalna kombinacja zmiennych x, y i powiększenia:

Mapa świata podzielona na 4 wiersze i 4 kolumny.

Tworząc obrazy dla warstwy kafelków, musisz utworzyć obraz dla każdego kafelka na każdym poziomie powiększenia, który chcesz obsługiwać. Gdy wyświetlasz kafelki, Mapy Google kierują reklamy na 256 dp (piksele niezależne od urządzenia). W przypadku urządzeń o wysokiej rozdzielczości zaleca się zwracanie fragmentów w wysokiej rozdzielczości (512 x 512 pikseli). Informacje o obsłudze różnych rozmiarów i gęstości ekranu znajdziesz w dokumentacji dla deweloperów aplikacji na Androida.

Uwaga: poziomy powiększenia obsługiwane przez aparat zależą od różnych czynników i nie są związane z poziomami powiększenia obsługiwanych przez kafelki.

  1. GoogleMap.getMaxZoomLevel() zwraca maksymalny poziom powiększenia dostępny w danej pozycji kamery. Uwzględnia to typ aktualnie używanej mapy. Na przykład mapa satelitarna lub terenowa może mieć niższy maksymalny poziom powiększenia niż fragmenty mapy podstawowej.
  2. GoogleMap.getMinZoomLevel() zwraca minimalny poziom powiększenia, który jest taki sam dla każdej lokalizacji (w przeciwieństwie do maksymalnego poziomu powiększenia), ale może różnić się w zależności od urządzenia i rozmiaru mapy.

Dodaj nakładkę z kafelkami

Najprostszym i najpowszechniejszym sposobem tworzenia nakładki z kafelkami jest podanie adresu URL prowadzącego do odpowiedniego obrazu. UrlTileProvider to częściowa implementacja TileProvider, która udostępnia kafelki na podstawie adresu URL. Ta klasa wymaga, aby wszystkie obrazy miały te same wymiary.

Musisz wdrożyć tag UrlTileProvider.getTileUrl(), który akceptuje współrzędne (x, y, zoom) i zwraca adres URL obrazu, który ma być użyty na kafelku. Metoda powinna zwrócić wartość null, jeśli w przypadku konkretnych obiektów x, y i zoom nie ma kafelka. Adres URL może wskazywać zasób internetowy, zasób Androida lub plik na dysku lokalnym.

Skonfiguruj zbiór kafelków na serwerze zgodnie ze wszystkimi współrzędnymi x, y i zoomem,które chcesz obsługiwać. Następnie dodaj nakładkę kafelka:

  1. Określ UrlTileProvider, aby dostarczać obrazy kafelków.
  2. Zastąp getTileUrl(), aby utworzyć adres URL każdego obrazu.
  3. Podaj obiekt TileOverlayOptions z odpowiednimi opcjami:
    • fadeIn: wartość logiczna. Określa, czy kafelki mają się pojawiać. Wartością domyślną jest true. Przydatne jest szybkie wyłączenie zanikania podczas przełączania się między kafelkami nakładek. Informacje na temat zależności między przejrzystością a przyciemnieniem obrazu znajdziesz w sekcji dotyczącej przejrzystości poniżej.
    • tileProvider: TileProvider używane na potrzeby tej nakładki.
    • transparency: liczba zmiennoprzecinkowa. Ustawia współczynnik przezroczystości obrazów kafelków. Wartość musi się mieścić w zakresie [0.0f, 1.0f], gdzie 0.0f oznacza pełną nieprzezroczystość (domyślnie), a 1.0f oznacza pełną przezroczystość. Poniżej znajdziesz przykładowy przejrzystość – przykładowy kod i relację między przezroczystością a efektem zanikania.
    • visible: wartość logiczna. Określa widoczność nakładki z kafelkami. Niewidoczna nakładka kafelkowa (wartość false) nie jest rysowana na mapie, ale zachowuje wszystkie pozostałe właściwości. Wartość domyślna to true.
    • zIndex: określa kolejność rysowania kafelków względem innych nakładek, w tym nakładek ziemi, okręgów, linii łamanych i wielokątów. Nakładki z wyższym kolejności nakładania elementów są nakładane na nakładki. Kolejność nakładek z tym samym ustawieniem kolejności nakładania elementów jest arbitralna. Domyślna wartość kolejności nakładania elementów wynosi 0. Pamiętaj, że znaczniki są zawsze rysowane nad innymi nakładkami, niezależnie od ich kolejności nakładania elementów.
  4. Wywołaj GoogleMap.addTileOverlay(), aby dodać nakładkę do mapy.

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

      

Aby zobaczyć przykład działania UrlTileProvider, zapoznaj się z TileOverlayDemoActivity w przykładowym kodzie, który jest dołączony do pakietu SDK Usług Google Play.

Ustaw przezroczystość nałożonych kafelków

Dobrze jest nałożyć przezroczyste kafelki na mapę, tak aby użytkownicy widzieli mapę podstawową pod nakładanymi kafelkami. Możesz to zrobić, dodając własne przezroczyste kafelki lub automatycznie ustawiając współczynnik przezroczystości na nakładce.

Poniższy przykładowy kod włącza przezroczystość nakładki kafelka między 0.5f a 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
    }
}

      

Przezroczystość jest zaimplementowana jako mnożnik kanału alfa dla obrazów kafelków. Aby ustawić przezroczystość nakładki z kafelkami, podaj obiekt TileOverlayOptions z transparency w zakresie [0.0f, 1.0f], jak pokazano w powyższym przykładzie. Wartość 0.0f oznacza, że nakładka jest całkowicie nieprzezroczysta, a 1.0f jest całkowicie przezroczysta. Wartość domyślna to 0.0f (nieprzezroczysta).

Możesz uzyskać dostęp do przezroczystości nakładki, klikając TileOverlay.getTransparency(). Możesz też ją zmienić, wywołując opcję TileOverlay.setTransparency().

Przezroczystość, animacja i zanikanie

Animacja nie działa po zmianie przezroczystości. Opcja przezroczystości działa razem z opcją fadeIn.

Rozjaśnianie zapewnia animację przezroczystości po wczytaniu kafelka. Jeśli ustawisz wartość przezroczystości, kafelki zmienią się z pełnej przezroczystości na określoną przezroczystość. Jeśli zmienisz przezroczystość podczas rozjaśniania, animacja będzie kierowana do nowej przezroczystości docelowej.

Usuwanie nakładki z kafelkami

Możesz usunąć nakładkę z kafelkami za pomocą metody TileOverlay.remove().

Java


tileOverlay.remove();

      

Kotlin


tileOverlay?.remove()

      

Usuń nieaktualne kafelki

Jeśli kafelki podane przez nakładkę na kafelek zmienią się na „nieaktualne”, możesz wywołać clearTileCache(), aby wymusić odświeżenie. Spowoduje to ponowne załadowanie wszystkich kafelków tej nakładki. Na przykład po zmianie kafelków udostępnionych w polu TileProvider musisz później wywołać metodę clearTileCache(), by upewnić się, że poprzednie kafelki nie są już renderowane.

Java


tileOverlay.clearTileCache();

      

Kotlin


tileOverlay?.clearTileCache()