Znaczniki

Wybierz platformę: Android iOS JavaScript

Znaczniki wskazują pojedyncze lokalizacje na mapie. Możesz dostosować znaczniki zmieniając kolor domyślny lub zastępując ikonę znacznika własną . Okna informacyjne mogą zapewnić dodatkowy kontekst dla znacznika.

Przykładowe fragmenty kodu

Repozytorium API Apigee na GitHubie zawiera przykład ilustrujący różne funkcje znaczników:

Kotlin

Java

Wprowadzenie

Znaczniki wskazują lokalizacje na mapie. W znaczniku domyślnym stosowany jest standardowy typową dla wyglądu i stylu Map Google. Możesz zmienić atrybut koloru ikony, obrazu lub punktu zakotwiczenia za pośrednictwem interfejsu API. Znaczniki są obiektami typu Marker i zostaną dodane do mapy z atrybutem GoogleMap.addMarker(markerOptions).

Znaczniki zostały zaprojektowane tak, aby były interaktywne. Otrzymują one click zdarzeń do jest domyślna i często jest używana z detektorami zdarzeń do wyświetlania informacji Windows. Ustawianie właściwości draggable znacznika na true umożliwia użytkownikowi zmianę pozycji znacznika. Przytrzymaj, aby aktywuj możliwość przeniesienia znacznika.

Domyślnie, gdy użytkownik kliknie znacznik, na dole wyświetli się pasek narzędzi mapy od prawej do mapy, dając użytkownikowi szybki dostęp do aplikacji mobilnej Mapy Google. Pasek narzędzi można wyłączyć. Więcej informacji: przewodnika po ustawieniach.

Wprowadzenie do znaczników

W tym odcinku Maps Live omówiliśmy podstawy dodawania znaczników do mapy. za pomocą pakietu Maps SDK na Androida.

Dodaj znacznik

Poniższy przykład pokazuje, jak dodać znacznik do mapy. Znacznik to utworzony pod współrzędnych -33.852,151.211 (Sydney, Australia) i wyświetla tekst „Marker w Sydney” w oknie informacyjnym.

Kotlin



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

Java


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

Wyświetl dodatkowe informacje o znaczniku

Typowym wymogiem jest wyświetlanie dodatkowych informacji o miejscu lub lokalizację, gdy użytkownik kliknie znacznik na mapie. Zobacz przewodnik okna informacyjne.

Powiąż dane ze znacznikiem

Możesz zapisać dowolny obiekt danych ze znacznikiem za pomocą funkcji Marker.setTag(), i pobierz obiekt danych za pomocą Marker.getTag(). Poniższy przykład pokazuje, możesz policzyć liczbę kliknięć znacznika za pomocą tagów:

Kotlin



/**
 * A demo class that stores and retrieves data objects with each marker.
 */
class MarkerDemoActivity : AppCompatActivity(),
    OnMarkerClickListener, OnMapReadyCallback {
    private val PERTH = LatLng(-31.952854, 115.857342)
    private val SYDNEY = LatLng(-33.87365, 151.20689)
    private val BRISBANE = LatLng(-27.47093, 153.0235)

    private var markerPerth: Marker? = null
    private var markerSydney: Marker? = null
    private var markerBrisbane: Marker? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_markers)
        val mapFragment =
            supportFragmentManager.findFragmentById(R.id.map) as SupportMapFragment?
        mapFragment!!.getMapAsync(this)
    }

    /** Called when the map is ready.  */
    override fun onMapReady(map: GoogleMap) {
        // Add some markers to the map, and add a data object to each marker.
        markerPerth = map.addMarker(
            MarkerOptions()
                .position(PERTH)
                .title("Perth")
        )
        markerPerth?.tag = 0
        markerSydney = map.addMarker(
            MarkerOptions()
                .position(SYDNEY)
                .title("Sydney")
        )
        markerSydney?.tag = 0
        markerBrisbane = map.addMarker(
            MarkerOptions()
                .position(BRISBANE)
                .title("Brisbane")
        )
        markerBrisbane?.tag = 0

        // Set a listener for marker click.
        map.setOnMarkerClickListener(this)
    }

    /** Called when the user clicks a marker.  */
    override fun onMarkerClick(marker: Marker): Boolean {

        // 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(
                this,
                "${marker.title} has been clicked $newClickCount times.",
                Toast.LENGTH_SHORT
            ).show()
        }

        // Return false to indicate that we have not consumed the event and that we wish
        // for the default behavior to occur (which is for the camera to move such that the
        // marker is centered and for the marker's info window to open, if it has one).
        return false
    }
}

Java


/**
 * A demo class that stores and retrieves data objects with each marker.
 */
public class MarkerDemoActivity extends AppCompatActivity implements
    GoogleMap.OnMarkerClickListener,
    OnMapReadyCallback {

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

    private Marker markerPerth;
    private Marker markerSydney;
    private Marker markerBrisbane;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_markers);
        SupportMapFragment mapFragment =
            (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /** Called when the map is ready. */
    @Override
    public void onMapReady(GoogleMap map) {
        // Add some markers to the map, and add a data object to each marker.
        markerPerth = map.addMarker(new MarkerOptions()
            .position(PERTH)
            .title("Perth"));
        markerPerth.setTag(0);

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

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

        // Set a listener for marker click.
        map.setOnMarkerClickListener(this);
    }

    /** Called when the user clicks a marker. */
    @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(this,
                marker.getTitle() +
                    " has been clicked " + clickCount + " times.",
                Toast.LENGTH_SHORT).show();
        }

        // Return false to indicate that we have not consumed the event and that we wish
        // for the default behavior to occur (which is for the camera to move such that the
        // marker is centered and for the marker's info window to open, if it has one).
        return false;
    }
}

Oto kilka przykładów sytuacji, w których przechowywanie i pobieranie danych może okazać się przydatne ze znacznikami:

  • Twoja aplikacja może obsługiwać różne typy znaczników i chcesz je traktować gdy użytkownik je kliknie. W tym celu możesz zapisać String ze znacznikiem wskazującym typ.
  • Być może korzystasz z systemu z unikalnymi identyfikatorami rekordów, gdzie znaczniki reprezentują określone rekordy w tym systemie.
  • Dane znacznika mogą wskazywać priorytet, który należy zastosować przy wyborze wartości z-index znacznik.

Ustawianie znacznika z możliwością przeciągania

Po dodaniu znacznika do mapy można zmienić jego położenie, 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 nie można przeciągać znaczników. Musisz wyraźnie ustawić znacznik jako można przeciągnąć za pomocą elementu MarkerOptions.draggable(boolean) przed dodaniem do lub Marker.setDraggable(boolean) po dodaniu jej do mapy. Możesz nasłuchiwać zdarzeń przeciągania na znaczniku, tak jak to opisano w sekcji Przeciąganie znacznika wydarzenia.

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

Kotlin



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

Java


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

Dostosowywanie znacznika

Ten film pokazuje sposoby użycia znaczników do wizualizacji lokalizacji na mapie.

Znaczniki mogą wskazywać niestandardowy obraz, który będzie wyświetlany zamiast domyślnej ikony. Definiowanie ikony obejmuje ustawienie szeregu właściwości, które mają wpływ wizualnego zachowania znacznika.

Znaczniki obsługują dostosowywanie za pomocą tych właściwości:

Pozycja (wymagana)
LatLng położenie znacznika na mapie. To jedyny wymagany element dla obiektu Marker.
Kotwica
Punkt na zdjęciu, który zostanie umieszczony w pozycji szerokości geograficznej znacznik. Domyślnie jest to środek dolnej części obrazu.
Alfa
Ustawia przezroczystość znacznika. Domyślna wartość to 1,0.
Tytuł
Ciąg znaków wyświetlany w oknie informacyjnym, gdy użytkownik kliknie ikonę znacznik.
Krótki opis
Dodatkowy tekst wyświetlany pod tytułem.
Ikona
Bitmapa wyświetlana w miejscu domyślnego obrazu znacznika.
Możliwość przeciągania
Ustaw na true, jeśli chcesz zezwolić użytkownikowi na przeniesienie znacznik. Domyślna wartość to false.
Widoczne
Ustaw na false, by znacznik był niewidoczny. Domyślna wartość to true
Orientacja płaska lub billboardowa
Domyślnie znaczniki mają orientację billboardu, co oznacza, że są rysowane. jest zorientowana na ekran urządzenia, a nie na powierzchnię mapy. Obracanie, przechylanie lub powiększanie mapy nie zmienia orientacji znacznik. Możesz ustawić płaską orientację znacznika względem ziemi. Płaskie znaczniki obracają się, gdy mapa jest obrócona, i zmieniają perspektywę, gdy mapa jest przechylona. Podobnie jak w przypadku znaczników billboardowych, płaskie znaczniki zachowują swój rozmiar, mapa jest powiększona lub pomniejszona.
Obrót
Orientacja znacznika, określona w stopniach w prawo. Domyślny położenie zmienia się, jeśli znacznik jest płaski. Domyślna pozycja reklamy płaskiej znacznik jest wyrównany do północy. Jeśli znacznik nie jest płaski, domyślna wartość położenie jest ustawione do góry, a obrót jest taki, że znacznik jest zawsze w stronę aparatu.

Poniższy fragment kodu pozwala utworzyć prosty znacznik z ikoną domyślną.

Kotlin



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

Java


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

Dostosowywanie koloru znacznika

Kolor domyślnego obrazu znacznika można dostosować, przekazując parametr BitmapDescriptor do metody icon(). Możesz użyć zestawu wstępnie zdefiniowane kolory w BitmapDescriptorFactory lub ustaw niestandardowy kolor znacznika za pomocą BitmapDescriptorFactory.defaultMarker(float hue). Odcień jest wartością od 0 do 360, co przedstawia punkty na kole kolorów.

Kotlin



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

Java


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

Dostosowywanie przezroczystości znacznika

Przezroczystość znacznika można kontrolować za pomocą metody MarkOptions.alpha(). Wartość alfa powinna być określona jako liczba zmiennoprzecinkowa z zakresu od 0,0 do 1,0, przy czym 0 to całkowita wartość przezroczysty, a 1 – pełny.

Kotlin



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

Java


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

Dostosuj obraz znacznika

Domyślny obraz znacznika można zastąpić niestandardowym obrazem znacznika. Często nazywa się ikoną. Ikony niestandardowe są zawsze ustawione jako BitmapDescriptor. zdefiniowane za pomocą jednej z metod Zajęcia: BitmapDescriptorFactory.

fromAsset(String assetName)
Tworzy znacznik niestandardowy na podstawie nazwy obrazu bitmapy w zasobach katalogu.
fromBitmap(Bitmap image)
Tworzy znacznik niestandardowy z obrazu bitmapy.
fromFile(String fileName)
Tworzy ikonę niestandardową na podstawie nazwy pliku obrazu bitmapy znajdującego się w sekcji pamięci wewnętrznej.
fromPath(String absolutePath)
Tworzy znacznik niestandardowy na podstawie bezwzględnej ścieżki pliku obrazu bitmapy.
fromResource(int resourceId)
Tworzy znacznik niestandardowy przy użyciu identyfikatora zasobu obrazu bitmapy.

Poniższy fragment kodu pozwala utworzyć znacznik z ikoną niestandardową.

Kotlin



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

Java


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łaszcz znacznik

Ikony znaczników są zwykle rysowane względem ekranu. obracanie, przechylanie lub powiększenie mapy nie zmieni orientacji znacznika. Możesz ustawić położenie znacznika na płaskim poziomie względem powierzchni Ziemi. Znaczniki, które są zorientowany w ten sposób będzie obrócony, gdy mapa jest obrócona, a perspektywa gdy mapa jest przechylona. Płaskie znaczniki zachowają swój rozmiar, jeśli mapa jest powiększony lub pomniejszony.

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

Kotlin



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

Java


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

Obracanie znacznika

Znacznik wokół punktu zakotwiczenia możesz obrócić za pomocą MarkerMetoda setRotation(). Obrót jest mierzony w stopniach w prawo od pozycji domyślnej. Jeśli znacznik jest płaski na mapie, domyślna wartość to to północ. Jeśli znacznik nie jest płaski, domyślną pozycją jest w górę, a znacznik jest zawsze skierowany w stronę aparatu.

Przykład poniżej obrócił znacznik o 90°. Ustawienie punktu zakotwiczenia na 0.5,0.5 powoduje obrót znacznika wokół jego środka, a nie wiele instalacji.

Kotlin



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

Java


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

Znacznik z-index

Kolejność nakładania elementów określa porządek stosu względem innych znaczników. na mapie. Znacznik o wysokim z-indeksie został narysowany nad znacznikami o niższych z-indexes. Domyślna wartość z-index to 0.

Ustaw kolejność nakładania elementów dla obiektu options znacznika, wywołując MarkerOptions.zIndex() na przykład w tym fragmencie kodu:

Kotlin



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

Java


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

Aby uzyskać dostęp do wartości z-index znacznika, wywołaj funkcję Marker.getZIndex() i możesz go zmień, dzwoniąc pod numer Marker.setZIndex().

Znaczniki są zawsze rysowane nad warstwami kafelków i innymi warstwami niebędącymi znacznikami (podłożem) nakładek, linii łamanych, wielokątów i innych kształtów) niezależnie od kolejności nakładania elementów dla pozostałych nakładek. Znaczniki są w praktyce uważane za odrębne w porównaniu z innymi nakładkami.

Więcej informacji o wpływie kolejności nakładania elementów na zdarzenia kliknięć znajdziesz poniżej.

Obsługa zdarzeń znaczników

Interfejs API Map Google umożliwia nasłuchiwanie zdarzeń związanych ze znacznikami i odpowiadanie na nie. Do słuchania tych zdarzeń, musisz ustawić odpowiedni detektor w: GoogleMap obiekt, do którego należą znaczniki. Gdy zdarzenie nastąpi na jednym z znaczniki na mapie, wywołanie zwrotne detektora jest wywoływane z użyciem odpowiedni obiekt Marker przekazany jako parametr. Aby porównać 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

Do słuchania możesz użyć: OnMarkerClickListener dla zdarzeń kliknięcia znacznika. Aby ustawić tego odbiornika na mapie, wywołaj GoogleMap.setOnMarkerClickListener(OnMarkerClickListener) Gdy użytkownik kliknie znacznik, nastąpi wywołanie funkcji onMarkerClick(Marker), a znacznik mogą być przekazywane jako argument. Ta metoda zwraca wartość logiczną, która wskazuje, czy brałaś to zdarzenie (tj. chcesz pominąć wartość domyślną zachowanie użytkownika). Jeśli zwróci wartość false, domyślne działanie będzie miało miejsce w w uzupełnieniu niestandardowego zachowania. Domyślne zachowanie po kliknięciu znacznika jest wyświetlenie swojego okna informacyjnego (jeśli jest dostępne) i przeniesienie kamery, tak aby znacznik był wyśrodkowany na mapie.

Wpływ kolejności nakładania elementów na zdarzenia kliknięcia:

  • Gdy użytkownik kliknie klaster znaczników, zdarzenie kliknięcia jest wywoływane przez znacznik o najwyższym wskaźniku z-index.
  • Na każde kliknięcie wyzwalane jest maksymalnie 1 zdarzenie. Innymi słowy, kliknięcie do znaczników lub innych nakładek o niższych wartościach z-index.
  • Kliknięcie grupy znaczników powoduje cykliczne kliknięcia wybierając po kolei każdy z nich. Kolejność cyklu ma najwyższy priorytet z-index, a następnie odległość do punktu kliknięcia.
  • Jeśli użytkownik kliknie reklamę poza obszarem klastra, interfejs API ponownie obliczy klastra i resetuje stan cyklu kliknięcia, tak aby rozpoczynał się od od początku.
  • Zdarzenie kliknięcia przechodzi przez grupy znaczników na inne kształty i nakładki. przed ponownym uruchomieniem.
  • Znaczniki są w praktyce uważane za należące do oddzielnej grupy z-index w porównaniu do innych nakładek lub kształtów (linii łamanych, wielokątów, okręgów i/lub powierzchni); nakładki), niezależnie od kolejności nakładania pozostałych warstw. Jeśli kilka nałożone na siebie znaczniki, nakładki lub kształty, jest najpierw zmieniana przez klaster znaczników, a potem wywoływany dla pozostałych klikalne nakładki lub kształty, zależnie od ich wartości z-index.

Zdarzenia przeciągania znacznika

Możesz użyć usługi OnMarkerDragListener, aby nasłuchiwać przeciągać zdarzenia na znacznik. Aby ustawić tego odbiornika na mapie, wywołaj GoogleMap.setOnMarkerDragListener Aby przeciągnąć znacznik, użytkownik musi przytrzymać na znaczniku. Gdy użytkownik zdejmuje palec z ekranu, znacznik pozostanie w tym położeniu. Po przeciągnięciu znacznika onMarkerDragStart(Marker) jest wywoływane początkowo. W czasie, gdy znacznik jest aktywny przeciągnięty, funkcja onMarkerDrag(Marker) jest wywoływana stale. Na końcu przeciągania Funkcja onMarkerDragEnd(Marker) jest wywoływana. Położenie znacznika można znaleźć tutaj: w dowolnym momencie, dzwoniąc pod numer Marker.getPosition().