İşaretçiler

Platform seçin: Android iOS JavaScript

İşaretçiler, haritada tek bir konumu gösterir. Varsayılan rengi değiştirerek veya işaretçi simgesini özel bir resimle değiştirerek işaretçilerinizi özelleştirebilirsiniz. Bilgi pencereleri, işaretçilerle ilgili ek bağlam bilgisi sağlayabilir.

Kod örnekleri

GitHub'daki ApiDemos deposu, çeşitli işaretçi özelliklerini gösteren bir örnek içerir:

Kotlin

Java

Giriş

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

İşaretler etkileşimli olacak şekilde tasarlanmıştır. Varsayılan olarak click etkinlikleri alırlar ve genellikle bilgi pencerelerini açmak için etkinlik işleyicilerle birlikte kullanılırlar. Bir işaretçinin draggable mülkünü 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 basılı tutun.

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

İşaretçileri kullanmaya başlama

Haritalar Canlı'nın bu bölümünde, Android için Haritalar SDK'sını kullanarak haritanıza işaretçi eklemeyle ilgili temel bilgiler ele alınmaktadır.

İşaretçi ekleyin

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

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

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

Kullanıcı haritadaki bir işaretçiye dokunduğunda bir yer veya konumla ilgili ek bilgilerin gösterilmesi yaygın bir şarttır. Bilgi pencereleri kılavuzuna bakın.

Verileri bir işaretçiyle ilişkilendirme

Marker.setTag() kullanarak rastgele bir veri nesnesini işaretçiyle saklayabilir 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ğinizi görebilirsiniz:

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

İşaretçilerle veri depolamak ve almak 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ı bunları tıkladığında farklı şekilde işlemek istiyorsunuzdur. Bunu yapmak için türünü belirten işaretleyiciyle bir String saklayabilirsiniz.
  • İşaretçilerin, söz konusu sistemdeki belirli kayıtları temsil ettiği, benzersiz kayıt tanımlayıcılarına sahip bir sistemle arayüz oluşturabilirsiniz.
  • İşaretçi verileri, bir işaretçinin z-dizinine karar verirken kullanılacak önceliği belirtebilir.

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

draggable mülkü true olarak ayarlandığı sürece, haritaya eklenen bir 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çileri varsayılan olarak sürükleyemezsiniz. İşaretçiyi, haritaya eklemeden önce MarkerOptions.draggable(boolean) ile veya haritaya eklendikten sonra Marker.setDraggable(boolean) ile sürüklenebilir olarak açıkça ayarlamanız gerekir. İşaretçi sürükleme etkinlikleri bölümünde açıklandığı gibi, işaretçide sürükleme etkinliklerini dinleyebilirsiniz.

Aşağıdaki snippet, Avustralya'nın Perth kentine 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)
)

Java

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

İşaretçileri özelleştirme

Bu videoda, haritadaki konumları görselleştirmek için işaretçilerin kullanım şekilleri gösterilmektedir.

İşaretçilerde, varsayılan simgenin yerine gösterilecek özel bir resim tanımlanabilir. Simge tanımlamak, işaretçinin görsel davranışını etkileyen bir dizi özelliği ayarlamayı içerir.

İşaretçilerde aşağıdaki özellikler aracılığıyla özelleştirme desteklenir:

Konum (zorunlu)
İşaretçinin haritada konumu için LatLng değeri. Bu, Marker nesnesi için gereken tek özelliktir.
Bağlayıcı
Resimdeki, işaretçinin LatLng konumuna yerleştirilecek nokta. Bu, varsayılan olarak resmin alt kısmının ortasına ayarlanır.
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örüntülenen dize.
Snippet
Başlığın altında gösterilen ek metin.
Simge
Varsayılan işaretçi resminin yerine gösterilen bir bitmap.
Sürüklenebilir
Kullanıcının işaretçiyi hareket ettirmesine izin vermek istiyorsanız true olarak ayarlayın. Varsayılan olarak false değerine ayarlanır.
Gösteriliyor
İşaretçiyi görünmez yapmak için false olarak ayarlayın. Varsayılan olarak true değerine ayarlanır.
Yatay veya dikey yön
İşaretçilerde varsayılan olarak billboard yönü kullanılır. Yani işaretçiler, haritanın yüzeyine göre değil, cihazın ekranına göre çizilir. Haritayı döndürmek, eğmek veya yakınlaştırmak, işaretçinin yönünü değiştirmez. Bir işaretçiyi, dünya üzerinde düz olacak şekilde yönlendirebilirsiniz. Düz işaretçiler, harita döndürüldüğünde döner ve harita eğildiğinde perspektifi değiştirir. Reklam panoları işaretçileri 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 yönü. Saat yönünde derece cinsinden belirtilir. İşaretçi düzse varsayılan konum değişir. Düz bir işaretleyicinin varsayılan konumu kuzeye hizalıdır. İşaretçi düz değilse varsayılan konum yukarı dönüktür ve işaretçi her zaman kameraya bakacak şekilde döndürülür.

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 renk grubu kullanabilir veya BitmapDescriptorFactory.defaultMarker(float hue) yöntemiyle özel bir işaretçi rengi ayarlayabilirsiniz. Ton, renk tekerleğindeki 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 bir işaretçinin opaklığını kontrol edebilirsiniz. Alfa, 0,0 ile 1,0 arasında bir kayan nokta olarak belirtilmelidir. 0 değeri tamamen şeffaf, 1 değeri 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)
assets dizininde bir bitmap resminin adını kullanarak özel bir işaretçi oluşturur.
fromBitmap(Bitmap image)
Bir bitmap görüntüsünden özel işaretçi oluşturur.
fromFile(String fileName)
Dahili depolama alanındaki bir bitmap resim dosyasının adını kullanarak özel bir simge oluşturur.
fromPath(String absolutePath)
Bir bitmap resminin mutlak dosya yolundan özel işaretçi oluşturur.
fromResource(int resourceId)
Bir bitmap resminin kaynak kimliğini kullanarak özel 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 genellikle 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ü, dünya üzerinde düz olacak şekilde ayarlayabilirsiniz. Bu şekilde yönlendirilen işaretçiler, harita döndürüldüğünde döner ve harita eğildiğinde perspektifi 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 mülkünü 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 ankraj noktası etrafında döndürebilirsiniz.setRotation() yöntemini kullanın. Dönüş, varsayılan konumdan saat yönünde derece cinsinden ölçülür. İşaretçi haritanın düz bir yerindeyken varsayılan konum kuzeydir. İşaretçi düz değilse varsayılan konum yukarı dönüktür ve işaretçi her zaman kameraya bakacak şekilde döndürülür.

Aşağıdaki örnekte işaretçi 90° döndürülmektedir. Sabitleme noktasını 0.5,0.5 olarak ayarlamak, işaretçinin tabanı yerine ortasının 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-endeksi, bu işaretleyicinin haritadaki diğer işaretleyicilere göre grup sırasını belirtir. Yüksek Z-endeksi olan bir işaretçi, daha düşük Z-endeksi olan işaretçilerin üzerine çizilir. Varsayılan z-index değeri 0'tür.

Aşağıdaki kod snippet'inde gösterildiği gibi MarkerOptions.zIndex()'ü çağırarak işaretçinin seçenekler nesnesinde z-dizinini 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-dizinini görebilir ve Marker.setZIndex() işlevini çağırarak değiştirebilirsiniz.

İşaretler, diğer yer paylaşımlarının z-endeksine bakılmaksızın her zaman karo katmanlarının ve işaret olmayan diğer yer paylaşımlarının (zemin yer paylaşımları, çoklu çizgiler, poligonlar ve diğer şekiller) üzerinde çizilir. İşaretçilerin, diğer yer paylaşımlarına kıyasla ayrı bir z-dizini grubunda olduğu kabul edilir.

z-dizininin tıklama etkinlikleri üzerindeki etkisi hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.

İşaretçi etkinliklerini işleme

Maps API, 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, ilgili Marker nesnesi parametre olarak iletilerek çağrılır. Bu Marker nesnesini, Marker nesnesine ait kendi 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 bir OnMarkerClickListener kullanabilirsiniz. Bu dinleyiciyi haritada ayarlamak için GoogleMap.setOnMarkerClickListener(OnMarkerClickListener) numaralı telefonu arayı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ı (yani varsayılan davranışı bastırmak isteyip istemediğinizi) belirten bir boole değeri döndürür. false döndürülürse özel davranışınıza ek olarak varsayılan davranış da gerçekleşir. İşaretçi tıklama etkinliğinin varsayılan davranışı, bilgi penceresini (varsa) göstermek ve kamerayı işaretçi haritanın ortasına gelecek şekilde hareket ettirmektir.

Z-endeksi'nin tıklama etkinlikleri üzerindeki etkisi:

  • Kullanıcı bir işaretçi kümesini tıkladığında, en yüksek z-dizini değerine sahip işaretçi için tıklama etkinliği tetiklenir.
  • Tıklama başına en fazla bir etkinlik tetiklenir. Diğer bir deyişle, tıklama, işaretçilere veya daha düşük z-endeksi değerlerine sahip diğer yer paylaşımlarına iletilmez.
  • Bir işaretçi kümesini tıkladığınızda, sonraki tıklamalar küme içinde dönerek her işaretçiyi sırayla seçer. Döngünün sırası önce z-dizinine, ardından tıklama noktasına olan yakınlığa öncelik verir.
  • Kullanıcı kümenin yakınlığının dışında 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.
  • Tıklama etkinliği, döngüyü yeniden başlatmadan önce işaretçi kümelerinden diğer şekillere ve yer paylaşımlarına geçer.
  • İşaretçilerin, diğer yer paylaşımlarının z-dizininden bağımsız olarak diğer yer paylaşımları veya şekillere (çoklu çizgiler, poligonlar, daireler ve/veya yer yer paylaşımları) kıyasla ayrı bir z-dizini grubunda olduğu kabul edilir. Birden fazla işaretçi, yer paylaşımı veya şekil birbirinin üzerine yerleştirilmişse tıklama etkinliği önce işaretçi kümesi arasında dolaştırılır, ardından z-dizini değerlerine göre diğer tıklanabilir yer paylaşımları veya şekiller için tetiklenir.

İşaretçi sürükleme etkinlikleri

İşaretçideki sürükleme etkinliklerini dinlemek için OnMarkerDragListener kullanabilirsiniz. Bu dinleyiciyi haritada ayarlamak için GoogleMap.setOnMarkerDragListener numaralı telefonu arayın. İş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 başlangıçta onMarkerDragStart(Marker) çağrılır. İşaretçi sürüklenirken onMarkerDrag(Marker) sürekli olarak çağrılır. Sürecin sonunda onMarkerDragEnd(Marker) çağrılır. Marker.getPosition() işlevini çağırarak işaretçinin konumunu istediğiniz zaman alabilirsiniz.