Nakładki z fragmentami mapy

Wybierz platformę: Android iOS JavaScript

Nakładka z kafelkami, czasami nazywana warstwą kafelków, to zbiór obrazów, które są wyświetlane na kafelkach mapy podstawowej.

Przykłady kodu

Repozytorium ApiDemos na GitHubie zawiera przykład, który pokazuje funkcję nakładki z kafelkami:

• TileOverlayDemoActivity – Java: funkcje nakładki z kafelkami w języku Java
• TileCoordinateDemoActivity – Java: system współrzędnych używany w przypadku nakładek z kafelkami w języku Java
• TileOverlayDemoActivity – Kotlin: funkcje nakładki z kafelkami w języku Kotlin
• TileCoordinateDemoActivity – Kotlin: system współrzędnych używany w przypadku nakładek z kafelkami w języku Kotlin

Wprowadzenie

TileOverlay określa zestaw obrazów, które są dodawane na kafelkach mapy podstawowej.

Musisz podać kafelki dla każdego poziomu powiększenia, który chcesz obsługiwać. Jeśli masz wystarczającą liczbę kafelków na różnych poziomach powiększenia, możesz uzupełnić dane mapy Google dla całej mapy.

Nakładki z kafelkami są przydatne, gdy chcesz dodać do mapy rozbudowane obrazy, które zwykle obejmują duże obszary geograficzne. Z kolei nakładki na ziemię są przydatne, gdy chcesz umieścić pojedynczy obraz w jednym obszarze na mapie.

Możesz też używać przezroczystych nakładek z kafelkami, aby dodawać do mapy dodatkowe funkcje, W tym celu ustaw współczynnik przezroczystości nakładki z kafelkami programowo lub podaj przezroczyste obrazy kafelków.

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

Interfejs API Map Google dzieli obrazy na każdym poziomie powiększenia na zestaw kwadratowych kafelków mapy ułożonych w siatce. Gdy mapa przesuwa się do nowej lokalizacji lub na nowy poziom powiększenia, interfejs API Map Google określa, które fragmenty mapy są potrzebne, i przekształca te informacje w zestaw fragmentów mapy do pobrania.

Kafelek o współrzędnych (0,0) zawsze znajduje się w lewym górnym rogu mapy, wartości x rosną z zachodu na wschód, a wartości y – z północy na południe. Kafelki są indeksowane za pomocą współrzędnych x i y od tego punktu początkowego.

Na poziomie powiększenia 0 cały świat jest renderowany w jednym kafelku. Każdy poziom powiększenia zwiększa powiększenie dwukrotnie. Dlatego na poziomie powiększenia 1 mapa będzie renderowana jako siatka kafelków 2 x 2. Na poziomie powiększenia 2 będzie to siatka 4 x 4. Na poziomie powiększenia 3 będzie to siatka 8 x 8 itd.

Na przykład na poziomie powiększenia 2 Ziemia jest podzielona na 16 kafelków. Każdy kafelek można odwołać za pomocą unikalnej kombinacji współrzędnych x, y i powiększenia:

Podczas tworzenia obrazów dla warstwy kafelków musisz utworzyć obraz dla każdego kafelka na każdym poziomie powiększenia, który chcesz obsługiwać. Podczas wyświetlania kafelków Mapy Google używają 256 dp (pikseli niezależnych od urządzenia). W przypadku urządzeń o wysokiej rozdzielczości zalecamy zwracanie kafelków o wysokiej rozdzielczości (512 x 512 pikseli). Więcej informacji o obsłudze różnych rozmiarów i gęstości ekranu znajdziesz w dokumentacji dla deweloperów Androida.

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

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

Dodawanie nakładki z kafelkami

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

Musisz zaimplementować UrlTileProvider.getTileUrl(), która akceptuje współrzędne mapy (x, y, powiększenie) i zwraca adres URL prowadzący do obrazu, który ma być używany w przypadku fragmentu mapy. Jeśli dla danego x, y i powiększenia nie ma kafelka, metoda powinna zwrócić wartość null. Adres URL może prowadzić do zasobu internetowego, zasobu Androida lub pliku na dysku lokalnym.

Skonfiguruj zasoby obrazów kafelków na serwerze, zdefiniowane dla wszystkich współrzędnych x, y i poziomów powiększenia, które chcesz obsługiwać. Następnie dodaj nakładkę z kafelkami:

1. Zdefiniuj UrlTileProvider, aby udostępniać obrazy kafelków.
2. Zastąp getTileUrl(), aby utworzyć adres URL dla każdego obrazu kafelka.
3. Podaj obiekt TileOverlayOptions z odpowiednimi opcjami:
• fadeIn: wartość logiczna. Określa, czy kafelki mają się pojawiać stopniowo. Wartość domyślna to true. Może się okazać, że warto wyłączyć stopniowe pojawianie się, gdy szybko przełączasz się między nakładkami z kafelkami. Więcej informacji o zależności między przezroczystością a stopniowym pojawianiem się znajdziesz w sekcji o przezroczystości poniżej.
• tileProvider: TileProvider, który ma być używany w przypadku tej nakładki.
• transparency: liczba zmiennoprzecinkowa. Ustawia współczynnik przezroczystości dla obrazów kafelków. Wartość musi mieścić się w zakresie [0.0f, 1.0f] gdzie 0.0f oznacza pełną nieprzezroczystość (domyślnie), a 1.0f oznacza pełną przezroczystość. Przykładowy kod i informacje o zależności między przezroczystością a stopniowym pojawianiem się znajdziesz w sekcji o przezroczystości poniżej.
• visible: wartość logiczna. Określa widoczność nakładki z kafelkami. Niewidoczna nakładka z kafelkami (wartość false) nie jest rysowana na mapie, ale zachowuje wszystkie inne właściwości. Wartość domyślna to true.
• zIndex: określa kolejność rysowania nakładki z kafelkami w stosunku do innych nakładek, w tym nakładek na ziemię , okręgów, polilinii i wielokątów. Nakładki o wyższym indeksie z są rysowane nad nakładkami o niższym indeksie z. Kolejność nakładek o tym samym indeksie z jest dowolna. Domyślny indeks z to 0. Pamiętaj, że markery są zawsze rysowane nad innymi nakładkami, niezależnie od ich indeksu z.
4. Aby dodać nakładkę do mapy, wywołaj GoogleMap.addTileOverlay().

Kotlin

val 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)
)
tileOverlay?.let {
    val isVisible = it.isVisible
    val fadeIn = it.fadeIn
    val transparency = it.transparency
    val zIndex = it.zIndex
}

      

Java

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(java.util.Locale.US, "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));

      

Aby zobaczyć przykład działania UrlTileProvider, zapoznaj się z TileOverlayDemoActivity w przykładowym kodzie dołączonym do pakietu SDK usług Google Play.

Uwaga: jeśli potrzebujesz większej kontroli, możesz zdefiniować dostawcę kafelków, implementując TileProvider interfejs.

Ustawianie przezroczystości nakładek z kafelkami

Nakładanie przezroczystych kafelków na mapę może być przydatne, aby użytkownicy mogli zobaczyć mapę podstawową pod nałożonymi kafelkami. Możesz to zrobić, udostępniając własne przezroczyste kafelki lub ustawiając współczynnik przezroczystości nakładki z kafelkami programowo.

Poniższy przykładowy kod przełącza przezroczystość nakładki z kafelkami między 0.5f a 0.0f:

Kotlin

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

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

      

Java

TileOverlay tileOverlayTransparent = map.addTileOverlay(new TileOverlayOptions()
    .tileProvider(new UrlTileProvider(256, 256) {
        // ...
    })
    .transparency(0.5f));

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

      

Przezroczystość jest implementowana 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 z kafelkami jest całkowicie nieprzezroczysta, a 1.0f – całkowicie przezroczysta. Wartość domyślna to 0.0f (nieprzezroczysta).

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

Przezroczystość, animacja i stopniowe pojawianie się

Gdy zmienisz przezroczystość, nie będzie żadnej animacji. Opcja przezroczystości działa razem z fadeIn.

Stopniowe pojawianie się zapewnia animację przezroczystości podczas wczytywania kafelka. Jeśli ustawisz wartość przezroczystości, kafelki będą się pojawiać stopniowo od pełnej przezroczystości do zdefiniowanej wartości przezroczystości. Jeśli zmienisz przezroczystość podczas stopniowego pojawiania się, animacja będzie kontynuowana w kierunku nowej docelowej przezroczystości.

Usuwanie nakładki z kafelkami

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

Kotlin

tileOverlay?.remove()

      

Java

tileOverlay.remove();

      

Czyszczenie nieaktualnych kafelków

Jeśli kafelki udostępniane przez nakładkę z kafelkami staną się „nieaktualne”, możesz wywołać clearTileCache() aby wymusić odświeżenie. Spowoduje to ponowne wczytanie wszystkich kafelków w tej nakładce. Jeśli na przykład kafelki udostępniane przez TileProvider ulegną zmianie, musisz wywołać clearTileCache() afterwards, aby poprzednie kafelki nie były już renderowane.

Kotlin

tileOverlay?.clearTileCache()

      

Java

tileOverlay.clearTileCache();