Nakładki na powierzchnię

Wybierz platformę: Android iOS JavaScript

Nakładki na powierzchnię to nakładki graficzne powiązane ze współrzędnymi geograficznymi, więc przesuwają się, gdy przeciągasz lub powiększasz mapę.

Przykładowe fragmenty kodu

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

Wprowadzenie

Nakładka na powierzchnię to obraz przypięty do mapy. W przeciwieństwie do znaczników nakładki na powierzchnię są zorientowane względem powierzchni Ziemi, a nie ekranu, więc obracanie, przechylanie lub powiększanie mapy spowoduje zmianę orientacji obrazu. Nakładki na powierzchnię są przydatne, gdy chcesz przypiąć pojedynczy obraz do określonego obszaru na mapie. Jeśli chcesz dodać rozbudowane zdjęcia obejmujące dużą część mapy, rozważ użycie nakładki z kafelkami.

Dodawanie nakładki

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 położenie obrazu na mapie. Gdy zdefiniujesz niezbędne opcje, przekaż obiekt do metody GoogleMap.addGroundOverlay(), aby dodać obraz do mapy. Metoda addGroundOverlay() zwraca obiekt GroundOverlay. Jeśli chcesz go później zmodyfikować, zachowaj do niego odniesienie.

Krok po kroku:

  1. Utwórz instancję nowego obiektu GroundOverlayOptions.
  2. Określ obraz jako BitmapDescriptor.
  3. Ustaw położenie obrazu za pomocą 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, np. transparency.
  5. Aby dodać obraz do mapy, wywołaj metodę GoogleMap.addGroundOverlay().

Poniższy przykład pokazuje, jak dodać nakładkę na powierzchnię 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 po dodaniu nakładki na powierzchnię do mapy chcesz ją zmienić lub usunąć, 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ę na powierzchnię możesz usunąć za pomocą metody GroundOverlay.remove().

Kotlin

imageOverlay?.remove()

Java

imageOverlay.remove();

Zmienianie nakładki

Po dodaniu nakładki na powierzchnię do mapy możesz zmienić jej obraz 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 dotychczasowy obraz innym obrazem o tych samych wymiarach.

Pozycjonowanie nakładki na powierzchnię

Pozycję nakładki na powierzchnię można określić na 2 sposoby:

  • Użycie LatLng, aby wyśrodkować nakładkę, oraz wymiarów w metrach, aby określić rozmiar obrazu.
  • Użycie LatLngBounds, aby określić północno-wschodni i południowo-zachodni róg obrazu.

Pozycję nakładki na powierzchnię musisz określić przed dodaniem jej do mapy.

Używanie lokalizacji do pozycjonowania obrazu

Gdy dodajesz obraz, określasz LatLng, do którego zostanie przypięty 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 automatycznie obliczona, aby zachować proporcje obrazu.

Poniższy kod umieszcza obraz w pozycji 40.714086, -74.228697, który ma 8,6 km szerokości i 6,5 km wysokości. 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. Wartość LatLngBounds ustawia północno-wschodni i południowo-zachodni róg obrazu. Gdy obraz jest rysowany na mapie, jest obracany tak, aby pasował do granic. Jeśli granice nie pasują do pierwotnego formatu, obraz zostanie zniekształcony.

Poniższy kod umieszcza obraz na mapie, którego południowo-zachodni róg jest ograniczony do 40.712216,-74.22655, a północno-wschodni do 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ą na powierzchnię

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

Poniższy przykład kodu zapisuje opis tekstowy z nakładką na powierzchnię:

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 zapisywać i pobierać dane za pomocą nakładek na powierzchnię:

  • Twoja aplikacja może obsługiwać różne nakładki na powierzchnię i chcesz je inaczej traktować, gdy użytkownik je kliknie.
  • Możesz korzystać z systemu, który ma unikalne identyfikatory rekordów, a nakładki reprezentują konkretne rekordy w tym systemie.
  • Dane nakładki mogą wskazywać priorytet, który określa indeks z nakładki.

Obsługa zdarzeń nakładki na powierzchnię

Domyślnie nakładki na powierzchnię nie są klikalne. Klikalność możesz włączać i wyłączać, wywołując metodę GroundOverlay.setClickable(boolean).

Aby nasłuchiwać zdarzeń kliknięcia klikalnej nakładki na powierzchnię, użyj OnGroundOverlayClickListener. Aby ustawić ten detektor na mapie, wywołaj metodę GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener). Gdy użytkownik kliknie nakładkę na powierzchnię, otrzymasz wywołanie zwrotne onGroundOverlayClick(GroundOverlay).