İşaretçiler

Platform seçin: Android iOS JavaScript

Birkaç işaretçi içeren bir harita

İşaretçiler, haritadaki konumları tanımlar. Varsayılan işaretçi, Google Haritalar'ın görünüm ve tarzına uygun standart bir simge kullanır. API aracılığıyla simgenin rengini, resmini veya tutturma noktasını değiştirebilirsiniz. İşaretçiler, Marker türündeki nesnelerdir ve GoogleMap.addMarker(markerOptions) yöntemiyle haritaya eklenir.

İşaretçiler etkileşimli olacak şekilde tasarlanmıştır. Varsayılan olarak click etkinliklerini alırlar ve genellikle bilgi pencerelerini açmak için etkinlik işleyicilerle birlikte kullanılırlar. Bir işaretçinin draggable özelliğini true olarak ayarlamak, kullanıcının işaretçinin konumunu değiştirmesine olanak tanır. İşaretçiyi hareket ettirme özelliğini etkinleştirmek için uzun basın.

Varsayılan olarak, kullanıcı bir işaretçiye dokunduğunda harita araç çubuğu haritanın sağ alt kısmında görünür ve kullanıcıya Google Haritalar mobil uygulamasına hızlı erişim imkanı sunar. Araç çubuğunu devre dışı bırakabilirsiniz. Daha fazla bilgi için denetimler kılavuzuna bakın.

İşaretçi ekleyin

Aşağıdaki örnekte, haritaya nasıl işaretçi ekleneceği gösterilmektedir. İşaretçi, -33.852,151.211 koordinatlarında (Sidney, Avustralya) oluşturulur ve tıklandığında bir bilgi penceresinde "Sidney'deki İşaretçi" dizesini gösterir.

Kotlin

// Add a marker in Sydney, Australia,
// and move the map's camera to the same location.
val sydney = LatLng(-33.852, 151.211)
val marker = map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney")
)
marker?.let {
    val position = it.position
    val title = it.title
    val snippet = it.snippet
    val isDraggable = it.isDraggable
    val isFlat = it.isFlat
    val isVisible = it.isVisible
    val alpha = it.alpha
    val rotation = it.rotation
    val zIndex = it.zIndex
}
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

Java

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

İşaretçiyle ilgili ek bilgileri görüntüleme

Kullanıcı haritadaki bir işaretçiye dokunduğunda bir yer veya konum hakkında ek bilgi göstermek yaygın bir gereksinimdir. Bilgi pencereleri kılavuzuna bakın.

Verileri bir işaretçiyle ilişkilendirme

Marker.setTag() kullanarak bir işaretçiyle rastgele bir veri nesnesi depolayabilir ve Marker.getTag() kullanarak veri nesnesini alabilirsiniz. Aşağıdaki örnekte, etiketleri kullanarak bir işaretçinin kaç kez tıklandığını nasıl sayabileceğiniz gösterilmektedir:

Kotlin

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
}

Java

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

Verileri işaretçilerle depolamanın ve almanın yararlı olduğu senaryolara dair bazı örnekleri aşağıda bulabilirsiniz:

  • Uygulamanız farklı işaretçi türlerine hitap ediyor olabilir ve kullanıcı işaretçileri tıkladığında bunları farklı şekilde ele almak isteyebilirsiniz. Bunu yapmak için türü belirten işaretçiyle birlikte bir String saklayabilirsiniz.
  • Benzersiz kayıt tanımlayıcıları olan bir sistemle etkileşim kuruyor olabilirsiniz. Bu durumda işaretçiler, ilgili sistemdeki belirli kayıtları temsil eder.
  • İşaretçi verileri, bir işaretçinin z-indeksine karar verirken kullanılacak bir önceliği gösterebilir.

İşaretçiyi sürüklenebilir hale getirme

Haritaya eklenen bir işaretçinin draggable özelliği true olarak ayarlandığı sürece işaretçiyi yeniden konumlandırabilirsiniz. Sürüklemeyi etkinleştirmek için işaretçiye uzun basın. Parmağınızı ekrandan çektiğinizde işaretçi o konumda kalır.

İşaretçiler varsayılan olarak sürüklenebilir değildir. İşaretçiyi haritaya eklemeden önce MarkerOptions.draggable(boolean) ile veya haritaya eklendikten sonra Marker.setDraggable(boolean) ile sürüklenir olarak açıkça ayarlamanız gerekir. İşaretçi sürükleme etkinlikleri bölümünde açıklandığı gibi, işaretçideki sürükleme etkinliklerini dinleyebilirsiniz.

Aşağıdaki snippet, Avustralya'nın Perth şehrine sürüklenebilir bir işaretçi ekler.

Kotlin

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .draggable(true)
)
map.moveCamera(com.google.android.gms.maps.CameraUpdateFactory.newLatLngZoom(perthLocation, 10f))

Java

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(
    new MarkerOptions()
        .position(perthLocation)
        .draggable(true));
map.moveCamera(com.google.android.gms.maps.CameraUpdateFactory.newLatLngZoom(perthLocation, 10f));

İşaretçileri özelleştirme

Bu videoda, haritadaki konumları görselleştirmek için işaretçileri kullanmanın yolları gösterilmektedir.

İşaretçiler, varsayılan simge yerine gösterilecek özel bir resim tanımlayabilir. Simge tanımlama, işaretçinin görsel davranışını etkileyen bir dizi özelliğin ayarlanmasını içerir.

İşaretçiler, aşağıdaki özellikler aracılığıyla özelleştirmeyi destekler:

Pozisyon (Zorunlu)
İşaretçinin haritadaki konumu için LatLng değeri. Bu, Marker nesnesi için gerekli olan tek özelliktir.
Bağlayıcı
İşaretçinin LatLng konumuna yerleştirilecek olan resimdeki nokta. Bu, varsayılan olarak resmin alt kısmının ortasına yerleştirilir.
Alfa
İşaretçinin opaklığını ayarlar. Varsayılan olarak 1,0 değerine ayarlanır.
Başlık
Kullanıcı işaretçiye dokunduğunda bilgi penceresinde gösterilen dize.
Snippet
Başlığın altında gösterilen ek metin.
Simge
Varsayılan işaretçi resmi yerine gösterilen bit eşlem.
Sürüklenebilir
Kullanıcının işaretçiyi taşımasına izin vermek istiyorsanız true olarak ayarlayın. Varsayılan değer false'dır.
Visible
İşaretçiyi görünmez yapmak için false olarak ayarlayın. Varsayılan olarak true değerine ayarlanır.
Düz veya billboard yönü
Varsayılan olarak işaretçiler, billboard yönünü kullanır. Yani haritanın yüzeyine göre değil, cihazın ekranına göre çizilirler. Haritayı döndürme, eğme veya yakınlaştırma, işaretçinin yönünü değiştirmez. Bir işaretçinin yönünü yere paralel olacak şekilde ayarlayabilirsiniz. Düz işaretçiler, harita döndürüldüğünde döner ve harita eğildiğinde perspektifi değiştirir. Reklam panosu işaretçilerinde olduğu gibi, düz işaretçiler de harita yakınlaştırıldığında veya uzaklaştırıldığında boyutlarını korur.
Döndürme
İşaretçinin saat yönünde derece cinsinden belirtilen yönü. İşaretleyici düzse varsayılan konum değişir. Düz işaretçinin varsayılan konumu kuzeye hizalıdır. İşaretçi düz olmadığında varsayılan konum yukarıyı gösterir ve dönüş, işaretçi her zaman kameraya bakacak şekilde olur.

Aşağıdaki snippet, varsayılan simgeyle basit bir işaretçi oluşturur.

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

İşaretçi rengini özelleştirme

icon() yöntemine bir BitmapDescriptor nesnesi ileterek varsayılan işaretçi resminin rengini özelleştirebilirsiniz. BitmapDescriptorFactory nesnesinde önceden tanımlanmış bir dizi renk kullanabilir veya BitmapDescriptorFactory.defaultMarker(float hue) yöntemiyle özel bir işaretçi rengi ayarlayabilirsiniz. Ton, renk çarkındaki noktaları temsil eden 0 ile 360 arasında bir değerdir.

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

İşaretçi opaklığını özelleştirme

MarkerOptions.alpha() yöntemiyle işaretçinin opaklığını kontrol edebilirsiniz. Alfa, 0,0 ile 1,0 arasında bir kayan nokta değeri olarak belirtilmelidir. Burada 0 tamamen şeffaf, 1 ise tamamen opaktır.

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

İşaretçi resmini özelleştirme

Varsayılan işaretçi resmini, genellikle simge olarak adlandırılan özel bir işaretçi resmiyle değiştirebilirsiniz. Özel simgeler her zaman BitmapDescriptor olarak ayarlanır ve BitmapDescriptorFactory sınıfındaki yöntemlerden biri kullanılarak tanımlanır.

fromAsset(String assetName)
Öğeler dizinindeki bir bit eşlem resminin adını kullanarak özel bir işaretçi oluşturur.
fromBitmap(Bitmap image)
Bitmap resimden özel işaretçi oluşturur.
fromFile(String fileName)
Dahili depolama alanında bulunan bir bit eşlem resim dosyasının adını kullanarak özel bir simge oluşturur.
fromPath(String absolutePath)
Bitmap resmin mutlak dosya yolundan özel bir işaretçi oluşturur.
fromResource(int resourceId)
Bitmap resmin kaynak kimliğini kullanarak özel bir işaretçi oluşturur.

Aşağıdaki snippet, özel simge içeren bir işaretçi oluşturur.

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

İşaretçiyi düzleştirme

İşaretçi simgeleri normalde ekrana göre çizilir. Haritayı döndürmek, eğmek veya yakınlaştırmak işaretçinin yönünü değiştirmez. İşaretçinin yönünü yere paralel olacak şekilde ayarlayabilirsiniz. Bu şekilde yönlendirilen işaretçiler, harita döndürüldüğünde döner ve harita eğildiğinde perspektif değiştirir. Düz işaretçiler, harita yakınlaştırıldığında veya uzaklaştırıldığında boyutlarını korur.

İşaretçinin yönünü değiştirmek için işaretçinin flat özelliğini true olarak ayarlayın.

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

İşaretçiyi döndürme

Marker ile bir işaretçiyi sabitleme noktası etrafında döndürebilirsiniz.setRotation() yöntemini kullanın. Döndürme, varsayılan konumdan saat yönünde derece cinsinden ölçülür. İşaretçi harita üzerinde düz olduğunda varsayılan konum kuzeydir. İşaretçi düz olmadığında varsayılan konum yukarıyı gösterir ve döndürme işlemi, işaretçi her zaman kameraya bakacak şekilde yapılır.

Aşağıdaki örnekte işaretçi 90° döndürülür. Sabitleme noktasının 0.5,0.5 olarak ayarlanması, işaretçinin tabanı yerine merkezi etrafında döndürülmesine neden olur.

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

İşaretçi z-endeksi

z-index, bu işaretçinin haritadaki diğer işaretçilere göre yığın sırasını belirtir. Yüksek z-endeksine sahip bir işaretçi, daha düşük z-endeksine sahip işaretçilerin üzerine çizilir. Varsayılan z-endeksi değeri 0'dir.

Aşağıdaki kod snippet'inde gösterildiği gibi, MarkerOptions.zIndex() yöntemini çağırarak işaretçinin seçenekler nesnesinde z-index değerini ayarlayın:

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

Marker.getZIndex() işlevini çağırarak işaretçinin z-index değerine erişebilir ve Marker.setZIndex() işlevini çağırarak bu değeri değiştirebilirsiniz.

İşaretçiler, diğer yer paylaşımlarının z-indeksinden bağımsız olarak her zaman döşeme katmanlarının ve işaretçi olmayan diğer yer paylaşımlarının (zemin yer paylaşımları, çoklu çizgiler, poligonlar ve diğer şekiller) üzerinde çizilir. İşaretçiler, diğer yer paylaşımlarına kıyasla ayrı bir z-index grubunda kabul edilir.

Z-index'in tıklama etkinlikleri üzerindeki etkisi hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.

İşaretçi etkinliklerini yönetme

Haritalar API'si, işaretçi etkinliklerini dinlemenize ve yanıtlamanıza olanak tanır. Bu etkinlikleri dinlemek için işaretçilerin ait olduğu GoogleMap nesnesinde ilgili dinleyiciyi ayarlamanız gerekir. Etkinlik, haritadaki işaretçilerden birinde gerçekleştiğinde dinleyicinin geri çağırma işlevi, parametre olarak iletilen ilgili Marker nesnesiyle çağrılır. Bu Marker nesnesini kendi Marker nesnesi referansınızla karşılaştırmak için == yerine equals() kullanmanız gerekir.

Aşağıdaki etkinlikleri dinleyebilirsiniz:

İşaretçi tıklama etkinlikleri

İşaretçideki tıklama etkinliklerini dinlemek için OnMarkerClickListener kullanabilirsiniz. Bu dinleyiciyi haritada ayarlamak için GoogleMap.setOnMarkerClickListener(OnMarkerClickListener) yöntemini çağırın. Kullanıcı bir işaretçiyi tıkladığında onMarkerClick(Marker) çağrılır ve işaretçi bir bağımsız değişken olarak iletilir. Bu yöntem, etkinliği kullanıp kullanmadığınızı (ör. varsayılan davranışı bastırmak istiyorsanız) belirten bir boole değeri döndürür. false döndürürse özel davranışınıza ek olarak varsayılan davranış da gerçekleşir. Bir işaretçi tıklama etkinliğinin varsayılan davranışı, işaretçinin bilgi penceresini (varsa) göstermek ve kamerayı işaretçi haritanın ortasında olacak şekilde hareket ettirmektir.

Z-endeksinin tıklama etkinlikleri üzerindeki etkisi:

  • Kullanıcı bir işaretçi kümesini tıkladığında, en yüksek z-index değerine sahip işaretçi için tıklama etkinliği tetiklenir.
  • Tıklama başına en fazla bir etkinlik tetiklenir. Başka bir deyişle, tıklama, daha düşük z-index değerlerine sahip işaretçilere veya diğer yer paylaşımlarına aktarılmaz.
  • Bir işaretçi kümesini tıkladığınızda, sonraki tıklamalar küme içinde döngü oluşturarak her birini sırayla seçer. Döngü sırası önce z-index'e, ardından tıklama noktasına yakınlığa öncelik verir.
  • Kullanıcı, kümenin yakınında olmayan bir yeri tıklarsa API, kümeyi yeniden hesaplar ve tıklama döngüsünün durumunu baştan başlayacak şekilde sıfırlar.
  • İşaretçiler, diğer yer paylaşımlarının z-dizininden bağımsız olarak diğer yer paylaşımlarına veya şekillere (çoklu çizgiler, çokgenler, daireler ve/veya yer yer paylaşımları) kıyasla ayrı bir z-dizini grubunda kabul edilir. Birden fazla işaretçi, yer paylaşımı veya şekil üst üste yerleştirilirse tıklama etkinliği önce işaretçi kümesinde sırayla uygulanır.

İşaretçi sürükleme etkinlikleri

Bir işaretçideki sürükleme etkinliklerini dinlemek için OnMarkerDragListener kullanabilirsiniz. Bu dinleyiciyi haritada ayarlamak için GoogleMap.setOnMarkerDragListener işlevini çağırın. Bir işaretçiyi sürüklemek için kullanıcının işaretçiye uzun basması gerekir. Kullanıcı parmağını ekrandan çektiğinde işaretçi o konumda kalır. Bir işaretçi sürüklendiğinde ilk olarak onMarkerDragStart(Marker) çağrılır. İşaretçi sürüklenirken onMarkerDrag(Marker) sürekli olarak çağrılır. Sürükleme işleminin sonunda onMarkerDragEnd(Marker) çağrılır. Marker.getPosition() işlevini çağırarak işaretçinin konumunu istediğiniz zaman öğrenebilirsiniz.