Nakładki na powierzchnię

Obrazy nad powierzchnią to obrazy nad powierzchnią, które są powiązane ze współrzędnymi szerokości i długości geograficznej. Dzięki temu przesuwają się podczas przeciągania lub powiększania mapy.

Przykładowe fragmenty kodu

Repozytorium APIDemos na GitHubie zawiera przykład obrazujący nakładki na powierzchni:

• GroundOverlayDemoActivity – Java: funkcje nakładki naziemnej i odbiorniki w języku Java.
• GroundOverlayDemoActivity – Kotlin: funkcje nakładki naziemnej i nasłuchujące się w języku Kotlin.

Wprowadzenie

Nakładka na poziomie terenu to obraz na stałe umieszczony na mapie. W przeciwieństwie do znaczników nakładki na ziemi są zorientowane względem powierzchni Ziemi, a nie ekranu, dlatego obrót, przechylenie lub powiększenie mapy spowoduje zmianę orientacji obrazu. Nakładki na powierzchni są przydatne, gdy chcesz poprawić pojedynczy obraz w jednym obszarze mapy. Jeśli chcesz dodać rozległe zdjęcia obejmujące dużą część mapy, użyj nakładki z fragmentami mapy.

Dodaj nakładkę

Aby dodać GroundOverlay, utwórz obiekt GroundOverlayOptions, który definiuje zarówno obraz, jak i pozycję. Opcjonalnie możesz określić dodatkowe ustawienia, które wpłyną na pozycję 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 zmienić go później, musisz zachować odwołanie do tego obiektu.

Krok po kroku:

1. Utwórz instancję 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. Ustaw dowolne właściwości opcjonalne, takie jak transparency, zgodnie z potrzebami.
5. Zadzwoń pod numer GoogleMap.addGroundOverlay(), aby dodać zdjęcie do mapy.

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

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

      

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)

      

Jeśli po dodaniu do mapy obrazu nad powierzchnią chcesz zmienić lub usunąć go, upewnij się, że trzymasz obiekt GroundOverlay. Możesz ją później zmodyfikować, wprowadzając zmiany w tym obiekcie.

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

      

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

      

Usuwanie nakładki

Obraz nad powierzchnią możesz usunąć metodą GroundOverlay.remove().

imageOverlay.remove();

      

imageOverlay?.remove()

      

Zmiana nakładki

Obraz nad powierzchnią możesz zmienić po dodaniu go do mapy za pomocą metody GroundOverlay.setImage(BitmapDescriptor).

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

      

// Update the GroundOverlay with a new image of the same dimension

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

      

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

Umieszczanie obrazu nad powierzchnią

Położenie obrazu nad powierzchnią można określić na dwa sposoby:

• Użyj właściwości LatLng, aby wyśrodkować nakładkę, i określ wymiary w metrach, aby określić rozmiar obrazu.
• LatLngBounds służy do określania północno-wschodnich i południowo-zachodnich narożników obrazu.

Zanim dodasz obraz do mapy, musisz określić jego położenie.

Pozycjonowanie obrazu na podstawie lokalizacji

Przy dodawaniu obrazu określ długość geograficzną, na której będzie zakotwiczona, oraz szerokość nakładki (w metrach). anchor domyślnie ustawia się na środku obrazu. Opcjonalnie możesz podać wysokość nakładki (w metrach). Jeśli nie podasz wysokości nakładki, zostanie ona automatycznie obliczona w celu zachowania proporcji obrazu.

Poniższy kod umożliwia umieszczenie obrazu 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.

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

      

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

      

Pozycjonowanie obrazu za pomocą szerokości i granic pasów ruchu

Dostarczasz LatLngBounds, który zawiera obraz. LatLngBounds ustawia północno-wschodnie i południowo-zachodnie narożniki obrazu. Gdy obraz zostanie narysowany na mapie, zostanie on obrócony w celu dopasowania do granicy. Jeśli granice nie będą pasować do pierwotnego formatu obrazu, obraz będzie zniekształcony.

Podany niżej kod umieszcza na mapie obraz z południowo-zachodnim rogiem strony 40.712216,-74.22655 i północno-wschodnim rogiem oznaczającym 40.773941, -74.12544.

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

      

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)

      

Powiązywanie danych z nakładką na poziomie terenu

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

Następujący przykładowy kod zawiera opis ciągu tekstowego z nakładką na poziomie terenu:

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

      

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

      

Oto kilka przykładów sytuacji, w których przechowywanie i pobieranie danych przy użyciu obrazów na powierzchni jest przydatne:

• Twoja aplikacja może obsługiwać różne nakładki i chcesz, aby były one traktowane inaczej, gdy użytkownik je kliknie.
• Być może korzystasz z systemu, który ma unikalne identyfikatory rekordów, gdzie nakładki reprezentują określone rekordy w tym systemie.
• Dane nakładki mogą wskazywać priorytet określający priorytet nakładania się nakładki.

Obsługa zdarzeń warstwy terenu

Domyślnie obrazów nad powierzchnią nie można klikać. Aby włączyć lub wyłączyć klikalność, wywołaj parametr GroundOverlay.setClickable(boolean).

Użyj OnGroundOverlayClickListener, aby rejestrować zdarzenia kliknięcia na klikalnej nakładce na powierzchni. Aby ustawić ten detektor na mapie, zadzwoń pod numer GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener). Gdy użytkownik kliknie nakładkę na ziemi, otrzymasz wywołanie zwrotne onGroundOverlayClick(GroundOverlay).