Nakładki z fragmentami mapy

Wybierz platformę: Android iOS JavaScript

Nakładka z kafelkami (czasami nazywana warstwami kafelków) to zbiór obrazów wyświetlanych na kafelkach mapy podstawowej.

Przykłady kodów

Repozytorium ApiDemos na GitHubie zawiera przykład pokazujący funkcję nakładki kafelków:

Wstęp

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

Musisz udostępnić kafelki każdego poziomu powiększenia, który ma być obsługiwany. 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 zdjęcia, zwykle obejmujące duże obszary geograficzne. Nakładki na powierzchni są natomiast przydatne, gdy chcesz poprawić pojedynczy obraz w jednym obszarze mapy.

Możesz też użyć przezroczystych nakładek, aby dodać do mapy dodatkowe funkcje. W tym celu możesz automatycznie ustawić współczynnik przezroczystości dla nakładki z kafelkami lub przesyłając przezroczyste obrazy.

Współrzędne kafelków i poziomy powiększenia

Interfejs API Map Google dzieli zdjęcia przy każdym poziomie powiększenia na zestaw kwadratowych fragmentów mapy ułożonych w siatkę. Gdy mapa zostanie przeniesiona do nowej lokalizacji lub do nowego poziomu powiększenia, interfejs API Map Google określa, które kafelki są potrzebne, i przekształca je na zestaw kafelków do pobrania.

Kafelek ze współrzędnymi (0,0) znajduje się zawsze w północno-zachodnim rogu mapy, gdzie wartości x rosną z zachodu na wschód, a wartości y – z północy na południe. Kafelki są indeksowane przy użyciu współrzędnych x,y danego punktu początkowego.

Przy powiększeniu 0 cały świat jest przedstawiany w jednym kafelku. Każdy poziom powiększenia zwiększa dwukrotnie powiększenie. W powiększeniu 1. mapa jest renderowana jako siatka 2 x 2 kafelków. Przy powiększeniu 2. jest to siatka 4 x 4. Przy powiększeniu 3. siatka ma format 8 x 8 itd.

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

Mapa świata podzielona na cztery rzędy i cztery kolumny z kafelkami.

Podczas tworzenia obrazów do 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 w Mapach Google obowiązuje kierowanie na 256 dp (piksele niezależne od urządzenia). W przypadku urządzeń o wysokiej rozdzielczości zalecamy zwracanie kafelków o 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 kamerę zależą od różnych czynników i nie są związane z poziomami obsługiwanymi przez Twoje kafelki.

  1. GoogleMap.getMaxZoomLevel() zwraca maksymalny poziom powiększenia dostępny w bieżącej pozycji kamery. Uwzględnia obecnie używany typ mapy. Na przykład mapa satelitarna lub terenowa może mieć mniejszy 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 się różnić w zależności od urządzenia i rozmiaru mapy.

Dodaj nakładkę z kafelkami

Najprostszym i najprostszym sposobem utworzenia nakładki z kafelkami jest podanie adresu URL wskazującego odpowiedni obraz płytki. UrlTileProvider to częściowa implementacja usługi TileProvider, która udostępnia kafelki obrazów na podstawie adresu URL. Ta klasa wymaga, aby wszystkie obrazy miały te same wymiary.

Musisz wdrożyć funkcję UrlTileProvider.getTileUrl(), która akceptuje współrzędne kafelka (x, y, powiększenie) i zwraca URL wskazujący obraz, który ma być używany dla kafelka. Jeśli dla danych x, y i powiększenia nie ma kafelka, metoda powinna zwrócić wartość null. Adres URL może wskazywać zasób internetowy, zasób Androida lub plik na dysku lokalnym.

Umieść na serwerze zestaw obrazów kafelków zdefiniowanych dla wszystkich współrzędnych x i y oraz poziomów powiększenia, które mają być obsługiwane. Następnie dodaj nakładkę z kafelkami:

  1. Określ UrlTileProvider, aby dostarczać obrazy kafelków.
  2. Zastąp getTileUrl(), aby utworzyć adres URL dla każdego obrazu kafelka.
  3. Udostępnij obiekt TileOverlayOptions z odpowiednimi opcjami:
    • fadeIn: wartość logiczna. Określa, czy kafelki mają się rozjaśnić. Wartością domyślną jest true. Szybkie przełączanie się między nakładkami z kafelkami może być przydatne, jeśli chcesz wyłączyć zanikanie. Informacje na temat związku między przezroczystością a zanikaniem znajdziesz w sekcji poświęconej przejrzystości poniżej.
    • tileProvider: TileProvider używany w tej nakładce.
    • transparency: swobodna. 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 całkowitą nieprzejrzystość (domyślnie), a 1.0f oznacza pełną przezroczystość. W poniższej sekcji o przejrzystości znajdziesz przykładowy kod oraz związek między przezroczystością a zanikaniem.
    • visible: wartość logiczna. Określa widoczność nakładki z kafelkami. Niewidoczna nakładka z kafelkami (wartość false) nie jest narysowana na mapie, ale zachowuje wszystkie swoje pozostałe właściwości. Wartość domyślna to true.
    • zIndex: określa kolejność, w jakiej zostanie narysowana nakładka z kafelkami w stosunku do innych warstw, w tym nakładki na powierzchni , okręgi, linie łamane i wielokąty. Nakładki o wyższej kolejności nakładania elementów są rysowane nad te o niższej wartości. Kolejność nakładek o tej samej kolejności nakładania elementów jest dowolna. Domyślna wartość kolejności nakładania elementów to 0. Pamiętaj, że znaczniki są zawsze rysowane nad innymi nakładkami, niezależnie od kolejności nakładania się pozostałych nakładek.
  4. Aby dodać nakładkę do mapy, wywołaj GoogleMap.addTileOverlay().

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

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

Ustaw przezroczystość dla nakładek z kafelkami

Nałożenie na mapę przezroczystych kafelków 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 automatycznie ustawiając na nim współczynnik przezroczystości.

Ten przykładowy kod przełącza przezroczystość nakładki z kafelkami między 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());
    }
}

Przezroczystość jest zaimplementowana jako mnożnik kanału alfa w przypadku 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 przykładzie powyżej. Wartość 0.0f oznacza, że nakładka z kafelkami jest całkowicie nieprzezroczysta, a 1.0f – że jest całkowicie przezroczysta. Wartość domyślna to 0.0f (nieprzezroczyste).

Aby uzyskać dostęp do przezroczystości nakładki kafelków, wywołaj funkcję TileOverlay.getTransparency(). Możesz ją zmienić, wywołując TileOverlay.setTransparency().

Przezroczystość, animacja i rozjaśnianie

Po zmianie przezroczystości nie ma animacji. Opcja przezroczystości działa równolegle z opcją fadeIn.

Rozjaśnienie zapewnia animację przezroczystości po wczytaniu kafelków. Jeśli ustawisz wartość przezroczystości, kafelki będą stopniowo przechodzić z pełnej przezroczystości do określonej wartości przezroczystości. Jeśli zmienisz przezroczystość podczas rozjaśniania, animacja będzie kontynuowana w kierunku nowej przezroczystości docelowej.

Usuwanie nakładki z kafelkami

Nakładkę kafelków możesz usunąć za pomocą metody TileOverlay.remove().

Kotlin



tileOverlay?.remove()

Java


tileOverlay.remove();

Usuń nieaktualne kafelki

Jeśli kafelki udostępnione w nakładce z kafelkami staną się nieaktualne, możesz wywołać clearTileCache(), aby wymusić odświeżenie. Spowoduje to ponowne załadowanie wszystkich kafelków na tej nakładce. Jeśli na przykład kafelki udostępnione przez funkcję TileProvider się zmienią, musisz później wywołać clearTileCache(), aby poprzednie kafelki nie były już renderowane.

Kotlin



tileOverlay?.clearTileCache()

Java


tileOverlay.clearTileCache();