Nakładki na powierzchnię

Wybierz platformę: Android iOS JavaScript

Nakładki na grunt to obrazy nad powierzchnią powiązane ze współrzędnymi szerokości i długości geograficznej, dzięki czemu poruszają się podczas przeciągania lub powiększania mapy.

Przykładowe fragmenty kodu

Repozytorium ApiDemos w GitHubie zawiera przykład pokazujący nakładki naziemne:

Wprowadzenie

Nakładka naziemna to obraz, który jest na stałe umieszczony na mapie. W przeciwieństwie do znaczników nakładki naziemne są zorientowane względem powierzchni Ziemi, a nie ekranu, więc obracanie, przechylanie lub powiększanie mapy zmienia orientację obrazu. Nakładki naziemne są przydatne, gdy chcesz umieścić pojedynczy obraz w jednym obszarze na mapie. Jeśli chcesz dodać rozległe zdjęcia, które pokrywają dużą część mapy, rozważ użycie nakładki kafelkowej.

Dodawanie nakładki

Aby dodać GroundOverlay, utwórz obiekt GroundOverlayOptions, który definiuje zarówno obraz, jak i pozycję. Możesz też określić dodatkowe ustawienia, które będą miały wpływ na pozycjonowanie obrazu na mapie. Po zdefiniowaniu niezbędnych opcji przekaż obiekt do metody GoogleMap.addGroundOverlay(), aby dodać obraz do mapy. Metoda addGroundOverlay() zwraca obiekt GroundOverlay. Jeśli chcesz go później zmodyfikować, zachowaj odwołanie do niego.

Krok po kroku:

  1. Utworzenie nowego obiektu GroundOverlayOptions
  2. Określ obraz jako BitmapDescriptor.
  3. Ustaw pozycję obrazu, korzystając z jednej z dostępnych metod:
    • position(LatLng location, float width, float height)
    • position(LatLng location, float width)
    • positionFromBounds(LatLngBounds bounds)
  4. W razie potrzeby ustaw dowolne właściwości opcjonalne, takie jak transparency.
  5. Aby dodać obraz do mapy, wywołaj funkcję GoogleMap.addGroundOverlay().

Poniższy przykład pokazuje, jak dodać nakładkę naziemną do istniejącego obiektu GoogleMap.

Kotlin

val newarkLatLng = LatLng(40.714086, -74.228697)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f)
map.addGroundOverlay(newarkMap)

Java

LatLng newarkLatLng = new LatLng(40.714086, -74.228697);

GroundOverlayOptions newarkMap =
        new GroundOverlayOptions()
                .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
                .position(newarkLatLng, 8600f, 6500f);
map.addGroundOverlay(newarkMap);

Jeśli chcesz zmienić lub usunąć nakładkę naziemną po dodaniu jej do mapy, zachowaj obiekt GroundOverlay. Możesz później zmodyfikować nakładkę, wprowadzając zmiany w tym obiekcie.

Kotlin

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
val imageOverlay = map.addGroundOverlay(newarkMap)

Java

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);

Usuwanie nakładki

Nakładkę lądową możesz usunąć za pomocą metody GroundOverlay.remove().

Kotlin

imageOverlay?.remove()

Java

imageOverlay.remove();

Zmienianie nakładki

Obraz nakładki naziemnej możesz zmienić po dodaniu go do mapy za pomocą metody GroundOverlay.setImage(BitmapDescriptor).

Kotlin

// Update the GroundOverlay with a new image of the same dimension
imageOverlay?.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))

Java

// Update the GroundOverlay with a new image of the same dimension
imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));

Metoda setImage() zastąpi istniejący obraz innym obrazem o tych samych wymiarach.

Pozycjonowanie nakładki na powierzchnię

Położenie nakładki naziemnej można określić na 2 sposoby:

  • Użycie elementu LatLng do wyśrodkowania nakładki i wymiarów w metrach do określenia rozmiaru obrazu.
  • Użyj LatLngBounds, aby określić północno-wschodni i południowo-zachodni róg obrazu.

Przed dodaniem nakładki naziemnej do mapy musisz określić jej pozycję.

Używanie lokalizacji do pozycjonowania obrazu

Podczas dodawania obrazu określasz współrzędne LatLng, do których zostanie przymocowany punkt zakotwiczenia, oraz szerokość nakładki (w metrach). Domyślnie anchor jest ustawiony na środek obrazu. Opcjonalnie możesz podać wysokość nakładki (w metrach). Jeśli nie podasz wysokości nakładki, zostanie ona obliczona automatycznie, aby zachować proporcje obrazu.

Poniższy kod umieszcza obraz w pozycji 40.714086, -74.228697 o szerokości 8,6 km i wysokości 6,5 km. Obraz jest zakotwiczony w lewym dolnym rogu.

Kotlin

val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0f, 1f)
    .position(LatLng(40.714086, -74.228697), 8600f, 6500f)

Java

GroundOverlayOptions newarkMap =
        new GroundOverlayOptions()
                .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
                .anchor(0, 1)
                .position(new LatLng(40.714086, -74.228697), 8600f, 6500f);

Używanie LatLngBounds do pozycjonowania obrazu

Podajesz LatLngBounds, który zawiera obraz. LatLngBounds określa północno-wschodni i południowo-zachodni róg obrazu. Gdy obraz zostanie narysowany na mapie, zostanie obrócony, aby dopasować go do granic. Jeśli granice nie odpowiadają oryginalnemu formatowi obrazu, obraz będzie zniekształcony.

Poniższy kod umieszcza obraz na mapie, przy czym jego południowo-zachodni róg jest powiązany z 40.712216,-74.22655, a północno-wschodni – z 40.773941, -74.12544.

Kotlin

val newarkBounds = LatLngBounds(
    LatLng(40.712216, -74.22655), // South west corner
    LatLng(40.773941, -74.12544), // North east corner
)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds)

Java

LatLngBounds newarkBounds =
        new LatLngBounds(
                new LatLng(40.712216, -74.22655), // South west corner
                new LatLng(40.773941, -74.12544)); // North east corner
GroundOverlayOptions newarkMap =
        new GroundOverlayOptions()
                .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
                .positionFromBounds(newarkBounds);

Powiązywanie danych z nakładką naziemną

Możesz wywołać metodę GroundOverlay.setTag(), aby zapisać dowolny obiekt danych z nakładką naziemną, i pobrać go za pomocą metody GroundOverlay.getTag().

Poniższy przykładowy kod przechowuje opis ciągu znaków z nakładką naziemną:

Kotlin

val sydneyGroundOverlay = map.addGroundOverlay(
    GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
        .position(LatLng(-33.873, 151.206), 100f)
        .clickable(true),
)
sydneyGroundOverlay?.tag = "Sydney"

Java

GroundOverlay sydneyGroundOverlay =
        map.addGroundOverlay(
                new GroundOverlayOptions()
                        .image(
                                BitmapDescriptorFactory.fromResource(
                                        R.drawable.harbour_bridge))
                        .position(new LatLng(-33.873, 151.206), 100)
                        .clickable(true));

sydneyGroundOverlay.setTag("Sydney");

Oto kilka przykładów sytuacji, w których warto przechowywać i pobierać dane za pomocą nakładek:

  • Aplikacja może obsługiwać różne nakładki na grunt i możesz chcieć traktować je inaczej, gdy użytkownik je kliknie.
  • Możesz korzystać z systemu, który ma unikalne identyfikatory rekordów, gdzie nakładki reprezentują konkretne rekordy w tym systemie.
  • Dane nakładki mogą wskazywać priorytet określający indeks Z nakładki.

Obsługa zdarzeń nakładki naziemnej

Domyślnie nakładki na mapę nie są klikalne. Możesz włączyć i wyłączyć możliwość klikania, wywołując funkcję GroundOverlay.setClickable(boolean).

Użyj OnGroundOverlayClickListener, aby nasłuchiwać zdarzeń kliknięcia nakładki naziemnej, którą można kliknąć. Aby ustawić ten detektor na mapie, wywołaj GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener). Gdy użytkownik kliknie nakładkę naziemną, otrzymasz wywołanie zwrotne onGroundOverlayClick(GroundOverlay).