Znaczniki

Znaczniki wskazują lokalizacje na mapie. Domyślny znacznik używa standardowej ikony, która jest typowa dla Map Google. Za pomocą interfejsu API można zmienić kolor, obraz lub punkt zakotwiczenia ikony. Znaczniki to obiekty typu Marker, które są dodawane do mapy za pomocą metody GoogleMap.addMarker(markerOptions).

Znaczniki są interaktywne. Domyślnie odbierają zdarzenia click i często są używane z detektorami zdarzeń do wyświetlania okien informacyjnych. Ustawienie właściwości draggable znacznika na true umożliwia użytkownikowi zmianę pozycji znacznika. Przytrzymaj, aby aktywować możliwość przesuwania znacznika.

Domyślnie, gdy użytkownik kliknie znacznik, w prawym dolnym rogu mapy pojawi się pasek narzędzi mapy, który zapewnia użytkownikowi szybki dostęp do aplikacji mobilnej Mapy Google. Możesz wyłączyć pasek narzędzi. Więcej informacji znajdziesz w przewodniku po ustawieniach.

Dodaj znacznik

Poniższy przykład pokazuje, jak dodać znacznik do mapy. Znacznik jest tworzony na współrzędnych -33.852,151.211 (Sydney, Australia) i po kliknięciu wyświetla w oknie informacyjnym ciąg znaków „Znacznik w Sydney”.

// Add a marker in Sydney, Australia,
// and move the map's camera to the same location.
val sydney = LatLng(-33.852, 151.211)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"),
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

      

// Add a marker in Sydney, Australia,
// and move the map's camera to the same location.
LatLng sydney = new LatLng(-33.852, 151.211);
map.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

      

Wyświetlanie dodatkowych informacji o znaczniku

Często wymagane jest wyświetlanie dodatkowych informacji o miejscu lub lokalizacji, gdy użytkownik kliknie znacznik na mapie. Zapoznaj się z przewodnikiem po oknach informacyjnych.

Powiązywanie danych ze znacznikiem

Możesz przechowywać dowolny obiekt danych ze znacznikiem, używając Marker.setTag(), i pobierać obiekt danych, używając Marker.getTag(). Poniższy przykład pokazuje, jak za pomocą tagów zliczać kliknięcia znacznika:

val PERTH = LatLng(-31.952854, 115.857342)
val SYDNEY = LatLng(-33.87365, 151.20689)
val BRISBANE = LatLng(-27.47093, 153.0235)

val markerPerth = map.addMarker(
    MarkerOptions()
        .position(PERTH)
        .title("Perth"),
)
markerPerth?.tag = 0

val markerSydney = map.addMarker(
    MarkerOptions()
        .position(SYDNEY)
        .title("Sydney"),
)
markerSydney?.tag = 0

val markerBrisbane = map.addMarker(
    MarkerOptions()
        .position(BRISBANE)
        .title("Brisbane"),
)
markerBrisbane?.tag = 0

// Set a listener for marker click.
map.setOnMarkerClickListener { marker ->
    // Retrieve the data from the marker.
    val clickCount = marker.tag as? Int

    // Check if a click count was set, then display the click count.
    clickCount?.let {
        val newClickCount = it + 1
        marker.tag = newClickCount
        Toast.makeText(
            context,
            "${marker.title} has been clicked $newClickCount times.",
            Toast.LENGTH_SHORT,
        ).show()
    }

    // Return false to indicate default behavior.
    false
}

      

final LatLng PERTH = new LatLng(-31.952854, 115.857342);
final LatLng SYDNEY = new LatLng(-33.87365, 151.20689);
final LatLng BRISBANE = new LatLng(-27.47093, 153.0235);

Marker markerPerth = map.addMarker(new MarkerOptions().position(PERTH).title("Perth"));
markerPerth.setTag(0);

Marker markerSydney = map.addMarker(new MarkerOptions().position(SYDNEY).title("Sydney"));
markerSydney.setTag(0);

Marker markerBrisbane =
        map.addMarker(new MarkerOptions().position(BRISBANE).title("Brisbane"));
markerBrisbane.setTag(0);

// Set a listener for marker click.
map.setOnMarkerClickListener(
        new GoogleMap.OnMarkerClickListener() {
            @Override
            public boolean onMarkerClick(final Marker marker) {
                // Retrieve the data from the marker.
                Integer clickCount = (Integer) marker.getTag();

                // Check if a click count was set, then display the click count.
                if (clickCount != null) {
                    clickCount = clickCount + 1;
                    marker.setTag(clickCount);
                    Toast.makeText(
                                    context,
                                    marker.getTitle()
                                            + " has been clicked "
                                            + clickCount
                                            + " times.",
                                    Toast.LENGTH_SHORT)
                            .show();
                }

                // Return false to indicate default behavior should occur.
                return false;
            }
        });

      

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

• Twoja aplikacja może obsługiwać różne typy znaczników i możesz chcieć traktować je inaczej, gdy użytkownik je kliknie. Aby to zrobić, możesz zapisać String ze znacznikiem wskazującym typ.
• Możesz korzystać z systemu, który ma unikalne identyfikatory rekordów, gdzie znaczniki reprezentują konkretne rekordy w tym systemie.
• Dane znacznika mogą wskazywać priorytet, który ma być używany podczas określania indeksu Z znacznika.

Umożliwianie przeciągania znacznika

Po dodaniu znacznika do mapy możesz zmienić jego pozycję, o ile jego właściwość draggable jest ustawiona na true. Przytrzymaj znacznik, aby włączyć przeciąganie. Gdy zdejmiesz palec z ekranu, znacznik pozostanie w tej pozycji.

Domyślnie znaczników nie można przeciągać. Musisz wyraźnie ustawić znacznik jako możliwy do przeciągania za pomocą MarkerOptions.draggable(boolean) przed dodaniem go do mapy lub Marker.setDraggable(boolean) po dodaniu go do mapy. Możesz nasłuchiwać zdarzeń przeciągania znacznika, jak opisano w sekcji Zdarzenia przeciągania znacznika.

Poniższy fragment kodu dodaje znacznik, który można przeciągać, w Perth w Australii.

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .draggable(true),
)

      

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(new MarkerOptions().position(perthLocation).draggable(true));

      

Dostosowywanie znacznika

Ten film pokazuje, jak używać znaczników do wizualizacji lokalizacji na mapie.

Znaczniki mogą definiować niestandardowy obraz, który będzie wyświetlany zamiast ikony domyślnej. Zdefiniowanie ikony obejmuje ustawienie szeregu właściwości, które wpływają na wizualne zachowanie znacznika.

Znaczniki można dostosowywać za pomocą tych właściwości:

Stanowisko (wymagane)

Wartość LatLng pozycji znacznika na mapie. Jest to jedyna wymagana właściwość obiektu Marker.

Kotwica

Punkt na obrazie, który zostanie umieszczony w pozycji LatLng znacznika. Domyślnie jest to środek dolnej krawędzi obrazu.

Alfa

Ustawia nieprzezroczystość znacznika. Domyślna wartość to 1.0.

Tytuł

Ciąg znaków wyświetlany w oknie informacyjnym, gdy użytkownik kliknie znacznik.

Krótki opis

Dodatkowy tekst wyświetlany pod tytułem.

Ikona

Bitmapa wyświetlana zamiast domyślnego obrazu znacznika.

Element przeciągalny

Ustaw wartość true, jeśli chcesz zezwolić użytkownikowi na przesuwanie znacznika. Domyślna wartość to false.

Widoczne

Ustaw wartość false, aby znacznik był niewidoczny. Domyślna wartość to true.

Orientacja płaska lub billboardowa

Domyślnie znaczniki są wyświetlane w orientacji billboardu, co oznacza, że są rysowane względem ekranu urządzenia, a nie powierzchni mapy. Obracanie, pochylanie i powiększanie mapy nie zmienia orientacji znacznika. Możesz ustawić orientację znacznika tak, aby był on płaski względem powierzchni ziemi. Płaskie znaczniki obracają się, gdy mapa jest obracana, i zmieniają perspektywę, gdy mapa jest przechylana. Podobnie jak w przypadku znaczników billboardowych, znaczniki płaskie zachowują swój rozmiar podczas powiększania i pomniejszania mapy.

Obrót

Orientacja znacznika określona w stopniach w prawo. Jeśli znacznik jest płaski, domyślna pozycja ulega zmianie. Domyślna pozycja płaskiego znacznika jest wyrównana do północy. Jeśli znacznik nie jest płaski, domyślnie jest skierowany w górę i obraca się tak, aby zawsze był zwrócony w stronę kamery.

Poniższy fragment kodu tworzy prosty znacznik z domyślną ikoną.

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation),
)

      

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne = map.addMarker(new MarkerOptions().position(melbourneLocation));

      

Dostosowywanie koloru znacznika

Możesz dostosować kolor domyślnego obrazu znacznika, przekazując obiekt BitmapDescriptor do metody icon(). Możesz użyć zestawu wstępnie zdefiniowanych kolorów w obiekcie BitmapDescriptorFactory lub ustawić niestandardowy kolor znacznika za pomocą metody BitmapDescriptorFactory.defaultMarker(float hue). Odcień to wartość z zakresu od 0 do 360, która reprezentuje punkty na kole kolorów.

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
        .icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_AZURE)),
)

      

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne =
        map.addMarker(
                new MarkerOptions()
                        .position(melbourneLocation)
                        .icon(
                                BitmapDescriptorFactory.defaultMarker(
                                        BitmapDescriptorFactory.HUE_AZURE)));

      

Dostosowywanie nieprzezroczystości znacznika

Przezroczystość znacznika możesz kontrolować za pomocą metody MarkerOptions.alpha(). Wartość alfa powinna być liczbą zmiennoprzecinkową z zakresu od 0,0 do 1,0, gdzie 0 oznacza pełną przezroczystość, a 1 – pełną nieprzezroczystość.

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
        .alpha(0.7f),
)

      

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne =
        map.addMarker(new MarkerOptions().position(melbourneLocation).alpha(0.7f));

      

Dostosowywanie obrazu znacznika

Domyślny obraz znacznika możesz zastąpić niestandardowym obrazem, który często nazywa się ikoną. Ikony niestandardowe są zawsze ustawiane jako BitmapDescriptor i definiowane za pomocą jednej z metod w klasie BitmapDescriptorFactory.

fromAsset(String assetName)

Tworzy niestandardowy znacznik, używając nazwy obrazu bitmapowego w katalogu zasobów.

fromBitmap(Bitmap image)

Tworzy niestandardowy znacznik na podstawie obrazu bitmapowego.

fromFile(String fileName)

Tworzy ikonę niestandardową, używając nazwy pliku obrazu bitmapowego znajdującego się w pamięci wewnętrznej.

fromPath(String absolutePath)

Tworzy znacznik niestandardowy na podstawie bezwzględnej ścieżki pliku obrazu bitmapowego.

fromResource(int resourceId)

Tworzy niestandardowy znacznik, używając identyfikatora zasobu obrazu bitmapowego.

Poniższy fragment kodu tworzy znacznik z ikoną niestandardową.

val melbourneLocation = LatLng(-37.813, 144.962)
val melbourne = map.addMarker(
    MarkerOptions()
        .position(melbourneLocation)
        .title("Melbourne")
        .snippet("Population: 4,137,400")
        .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)),
)

      

final LatLng melbourneLocation = new LatLng(-37.813, 144.962);
Marker melbourne =
        map.addMarker(
                new MarkerOptions()
                        .position(melbourneLocation)
                        .title("Melbourne")
                        .snippet("Population: 4,137,400")
                        .icon(BitmapDescriptorFactory.fromResource(R.drawable.arrow)));

      

Spłaszczanie znacznika

Ikony znaczników są zwykle rysowane względem ekranu. Obracanie, przechylanie i powiększanie mapy nie zmienia orientacji znacznika. Możesz ustawić orientację znacznika, aby był płaski względem ziemi. Znaczniki zorientowane w ten sposób będą się obracać, gdy mapa będzie obracana, i zmieniać perspektywę, gdy mapa będzie przechylana. Płaskie znaczniki zachowują swój rozmiar podczas powiększania i pomniejszania mapy.

Aby zmienić orientację znacznika, ustaw jego właściwość flat na true.

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .flat(true),
)

      

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(new MarkerOptions().position(perthLocation).flat(true));

      

Obracanie znacznika

Możesz obrócić znacznik wokół jego punktu zakotwiczenia za pomocą Marker.setRotation(). Obrót jest mierzony w stopniach zgodnie z ruchem wskazówek zegara od pozycji domyślnej. Gdy znacznik jest płaski na mapie, domyślną pozycją jest północ. Jeśli znacznik nie jest płaski, domyślnie jest skierowany w górę i obrócony tak, że zawsze jest zwrócony w stronę kamery.

W przykładzie poniżej znacznik jest obrócony o 90°. Ustawienie punktu zakotwiczenia na 0.5,0.5 powoduje, że znacznik jest obracany wokół środka, a nie podstawy.

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .anchor(0.5f, 0.5f)
        .rotation(90.0f),
)

      

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth =
        map.addMarker(
                new MarkerOptions()
                        .position(perthLocation)
                        .anchor(0.5f, 0.5f)
                        .rotation(90.0f));

      

Kolejność nakładania znaczników

Indeks Z określa kolejność stosu tego znacznika względem innych znaczników na mapie. Znacznik o wysokim indeksie Z jest rysowany nad znacznikami o niższych indeksach Z. Domyślna wartość Z-index to 0.

Ustaw indeks Z w obiekcie opcji znacznika, wywołując MarkerOptions.zIndex(), jak pokazano w tym fragmencie kodu:

map.addMarker(
    MarkerOptions()
        .position(LatLng(10.0, 10.0))
        .title("Marker z1")
        .zIndex(1.0f),
)

      

map.addMarker(
        new MarkerOptions().position(new LatLng(10, 10)).title("Marker z1").zIndex(1.0f));

      

Możesz uzyskać dostęp do indeksu z znacznika, wywołując funkcję Marker.getZIndex(), i zmienić go, wywołując funkcję Marker.setZIndex().

Znaczniki są zawsze rysowane nad warstwami kafelków i innymi nakładkami, które nie są znacznikami (nakładkami naziemnymi, liniami łamanymi, wielokątami i innymi kształtami), niezależnie od indeksu Z innych nakładek. Znaczniki są traktowane jako należące do osobnej grupy indeksu Z w porównaniu z innymi nakładkami.

Poniżej znajdziesz informacje o wpływie indeksu Z na zdarzenia kliknięcia.

Obsługa zdarzeń znacznika

Interfejs API Map Google umożliwia nasłuchiwanie zdarzeń związanych ze znacznikami i reagowanie na nie. Aby nasłuchiwać tych zdarzeń, musisz ustawić odpowiedni detektor w obiekcie GoogleMap, do którego należą znaczniki. Gdy zdarzenie wystąpi na jednym ze znaczników na mapie, zostanie wywołane wywołanie zwrotne detektora z odpowiednim obiektem Marker przekazanym jako parametr. Aby porównać ten obiekt Marker z własnym odwołaniem do obiektu Marker, musisz użyć equals(), a nie ==.

Możesz nasłuchiwać tych zdarzeń:

• Zdarzenia kliknięcia znacznika
• Zdarzenia przeciągania znacznika
• Zdarzenia kliknięcia okna informacyjnego

Zdarzenia kliknięcia znacznika

Aby nasłuchiwać zdarzeń kliknięcia znacznika, możesz użyć OnMarkerClickListener. Aby ustawić ten detektor na mapie, wywołaj GoogleMap.setOnMarkerClickListener(OnMarkerClickListener). Gdy użytkownik kliknie znacznik, zostanie wywołana funkcja onMarkerClick(Marker), a znacznik zostanie przekazany jako argument. Ta metoda zwraca wartość logiczną, która wskazuje, czy zdarzenie zostało wykorzystane (czyli czy chcesz pominąć działanie domyślne). Jeśli zwraca wartość false, oprócz działania niestandardowego zostanie wykonane działanie domyślne. Domyślnym działaniem zdarzenia kliknięcia znacznika jest wyświetlenie okna informacyjnego (jeśli jest dostępne) i przesunięcie kamery tak, aby znacznik znajdował się na środku mapy.

Wpływ indeksu Z na zdarzenia kliknięcia:

• Gdy użytkownik kliknie klaster znaczników, zdarzenie kliknięcia zostanie wywołane dla znacznika o najwyższym indeksie Z.
• Na kliknięcie wywoływane jest maksymalnie 1 zdarzenie. Innymi słowy, kliknięcie nie jest przekazywane do znaczników ani innych nakładek o niższych wartościach indeksu Z.
• Kliknięcie grupy znaczników powoduje, że kolejne kliknięcia przechodzą przez grupę, wybierając po kolei każdy z nich. Kolejność cyklu najpierw uwzględnia indeks Z, a potem odległość od punktu kliknięcia.
• Jeśli użytkownik kliknie poza obszarem klastra, interfejs API ponownie obliczy klaster i zresetuje stan cyklu kliknięć, aby rozpocząć go od początku.
• Markery są traktowane jako należące do osobnej grupy indeksu Z w porównaniu z innymi nakładkami lub kształtami (poliliniami, wielokątami, okręgami lub nakładkami naziemnymi), niezależnie od indeksu Z innych nakładek. Jeśli kilka znaczników, nakładek lub kształtów nakłada się na siebie, zdarzenie kliknięcia jest najpierw przekazywane przez klaster znaczników.

Zdarzenia przeciągania znacznika

Możesz użyć OnMarkerDragListener, aby nasłuchiwać zdarzeń przeciągania znacznika. Aby ustawić ten detektor na mapie, wywołaj GoogleMap.setOnMarkerDragListener. Aby przeciągnąć znacznik, użytkownik musi go przytrzymać. Gdy użytkownik odsunie palec od ekranu, znacznik pozostanie w tym miejscu. Gdy znacznik jest przeciągany, najpierw wywoływana jest funkcja onMarkerDragStart(Marker). Podczas przeciągania znacznika stale wywoływana jest funkcja onMarkerDrag(Marker). Na końcu przeciągania wywoływana jest funkcja onMarkerDragEnd(Marker). Pozycję znacznika możesz uzyskać w dowolnym momencie, wywołując funkcję Marker.getPosition().