İşaretçiler

Platform seçin: Android iOS JavaScript

İşaretçiler, haritada tek konumları belirtir. 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çiye ek bağlam sağlayabilir.

Kod örnekleri

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

Java

Kotlin

Giriş

İşaretçiler, haritada konumları tanımlar. Varsayılan işaretçi, Google Haritalar görünümü ve tarzında benzer olan standart bir simge kullanır. Simgenin rengini, resmini veya sabitleme noktasını API üzerinden değiştirmek mümkündür. İşaretçiler Marker türündeki nesnelerdir ve haritaya GoogleMap.addMarker(markerOptions) yöntemiyle eklenir.

İşaretçiler etkileşimli olacak şekilde tasarlanmıştır. Varsayılan olarak click etkinliklerini alırlar ve genellikle bilgi pencerelerini görüntülemek için etkinlik işleyicilerle birlikte kullanılırlar. İşaretçinin draggable özelliğinin true değerine ayarlanması, 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 altında görünür ve kullanıcının Google Haritalar mobil uygulamasına hızlı bir şekilde erişmesini sağlar. Araç çubuğunu devre dışı bırakabilirsiniz. Daha fazla bilgi için kontrol 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 ekleme ile 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 koordinatlarında (Sidney, Avustralya) oluşturulur ve tıklandığında bir bilgi penceresinde "Marker in Sydney" dizesini görüntüler.

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

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

Bir işaretçi hakkında ek bilgileri görüntüleme

Kullanıcılar haritadaki bir işaretçiye dokunduğunda bir yer ya da konum hakkında ek bilgi göstermek yaygın bir gereksinimdir. Bilgi pencereleri ile ilgili kılavuzu inceleyin.

Verileri bir işaretçiyle ilişkilendirme

Rastgele bir veri nesnesini Marker.setTag() ile bir işaretçiyle depolayabilir ve Marker.getTag() ile bu veri nesnesini alabilirsiniz. Aşağıdaki örnekte, etiketleri kullanarak bir işaretçinin tıklanma sayısını nasıl sayabileceğiniz gösterilmektedir:

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

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

Aşağıda, işaretçilerle veri depolamanın ve almanın yararlı olduğu durumlara ilişkin bazı örnekler verilmiştir:

  • Uygulamanız farklı işaretçi türlerini sağlayabilir ve kullanıcı bunları tıkladığında farklı bir şekilde ele almak istersiniz. Bunu yapmak için, işaretçiyle türü gösteren bir String depolayabilirsiniz.
  • Benzersiz kayıt tanımlayıcıları olan bir sistemle karşılaşıyor olabilirsiniz. Bu sistemde işaretçiler, söz konusu sistemdeki belirli kayıtları temsil eder.
  • İşaretçi verileri, bir işaretçinin Z-endeksine karar verilirken kullanılacak bir önceliği gösterebilir.

İşaretçiyi sürüklenebilir yap

Bir işaretçiyi, draggable özelliği true olarak ayarlandığı sürece, haritaya eklendikten sonra yeniden konumlandırabilirsiniz. Sürüklemeyi etkinleştirmek için işaretçiye uzun basın. Parmağınızı ekrandan kaldırdığınızda, işaretçi bu konumda kalır.

İşaretçiler varsayılan olarak sürüklenemez. İşaretçiyi, haritaya eklemeden önce MarkerOptions.draggable(boolean) veya haritaya eklendikten sonra Marker.setDraggable(boolean) ile sürüklenebilir olacak şekilde açık bir şekilde ayarlamanız gerekir. İşaretçi sürükleme etkinlikleri konusunda açıklandığı gibi işaretçide sürükleme etkinliklerini dinleyebilirsiniz.

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

Java


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

Kotlin


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

İşaretçiyi özelleştirme

Bu videoda, haritada konumları görselleştirmek için işaretçilerin nasıl kullanılacağı gösterilmektedir.

İşaretçiler, varsayılan simge yerine gösterilecek özel bir resim tanımlayabilir. Bir simge tanımlamak, işaretçinin görsel davranışını etkileyen çeşitli özelliklerin 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. Bir Marker nesnesi için gerekli tek özelliktir.
Çapa
Resimde, işaretçinin EnlBoy konumuna yerleştirilecek nokta. Bu parametre, 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österilen bir dize.
Snippet
Başlığın altında görüntülenen ek metin.
Simge
Varsayılan işaretçi resminin yerine gösterilen bir bit eşlem.
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.
Düz veya İlan Tahtası yönü
İşaretçiler varsayılan olarak ilan tahtası yönünü kullanır. Diğer bir ifadeyle, işaretçiler haritanın yüzeyine değil, cihazın ekranına bakacak şekilde çizilir. Haritayı döndürmek, yatırmak veya yakınlaştırmak işaretçinin yönünü değiştirmez. İşaretçinin yönünü dünyaya göre düz olacak şekilde ayarlayabilirsiniz. Düz işaretçiler, harita döndürüldüğünde döner ve harita yatırıldığında perspektifi değiştirir. İlan tahtası işaretçilerinde olduğu gibi, harita yakınlaştırıldığında veya uzaklaştırıldığında düz işaretçilerin 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 işaretçi için varsayılan konum kuzeye hizalıdır. İşaretçi düz değilse varsayılan konum yukarıyı gösterir ve döndürme, işaretçi her zaman kameraya bakacak şekilde yapılır.

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

Java


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

Kotlin


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

İşaretçi rengini özelleştirme

icon() yöntemine bir BitmapDescriptor nesnesi ileterek varsayılan işaretçi resminin rengini özelleştirmek mümkündür. BitmapDescriptorFactory nesnesinde önceden tanımlanmış bir renk grubu kullanabilir veya BitmapDescriptorFactory.defaultMarker(float hue) yöntemiyle özel bir işaretçi rengi ayarlayabilirsiniz. Ton, 0 ile 360 arasında bir değerdir ve renk çemberindeki noktaları temsil eder.

Java


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

Kotlin


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

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

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

Java


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

Kotlin


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

İşaretçi resmini özelleştirin

Varsayılan işaretçi resmini, genellikle simge adı verilen ö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)
Öğe dizininde bir Bitmap resminin adını kullanarak özel işaretçi oluşturur.
fromBitmap(Bitmap image)
Bit Eşlem görüntüsünden özel işaretçi oluşturur.
fromFile(String fileName)
Dahili depolama alanındaki bir Bit eşlem görüntü dosyasının adını kullanarak özel bir simge oluşturur.
fromPath(String absolutePath)
Bit eşlem görüntüsünün mutlak dosya yolundan özel işaretçi oluşturur.
fromResource(int resourceId)
Bit eşlem görüntüsünün kaynak kimliğini kullanarak özel işaretçi oluşturur.

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

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

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

İş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ü dünyaya göre düz olacak şekilde ayarlayabilirsiniz. Bu şekilde yönlü işaretçiler, harita döndürüldüğünde döner ve harita yatırıldığında perspektifi değiştirir. Düz işaretçilerin, harita yakınlaştırıldığında veya uzaklaştırıldığında boyutu korunur.

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

Java


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

Kotlin


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

İşaretçiyi döndürme

Marker kullanarak işaretçiyi sabitleme noktasının çevresinde döndürebilirsiniz.setRotation() yöntemini çağırı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 Kuzey'dir. İşaretçi düz değilse varsayılan konum yukarıyı gösterir ve döndürme, işaretçi her zaman kameraya bakacak şekilde olur.

Aşağıdaki örnek, işaretçiyi 90° döndürür. Sabitleme noktasını 0.5,0.5 olarak ayarlamak, işaretçinin tabanı yerine kendi merkezi çevresinde döndürülmesine neden olur.

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

Kotlin


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

İşaretçi z-endeksi

Z-endeksi, haritadaki diğer işaretçilere göre bu işaretçinin yığın sırasını belirtir. Düşük Z-endeklerine sahip işaretçilerin üzerine yüksek Z-endeksine sahip bir işaretçi ç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 nesnesindeki Z-endeksini ayarlayın:

Java


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

Kotlin


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

İşaretçinin Z-endeksine Marker.getZIndex() yöntemini çağırarak erişebilir, Marker.setZIndex() yöntemini çağırarak da değiştirebilirsiniz.

İşaretleyiciler, diğer bindirmelerin Z-endeksinden bağımsız olarak her zaman karo 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) üzerine çizilir. İşaretçiler, diğer yer paylaşımlarına kıyasla etkin bir şekilde ayrı bir Z-endeksi grubunda kabul edilir.

Aşağıdaki Z-endeksinin tıklama etkinlikleri üzerindeki etkisi hakkında bilgi edinin.

İşaretçi etkinliklerini işleme

Maps API, işaretçi etkinliklerini dinlemenize ve bunlara yanıt vermenize olanak tanır. Bu etkinlikleri dinlemek için işaretçilerin ait olduğu GoogleMap nesnesinde karşılık gelen işleyiciyi ayarlamanız gerekir. Etkinlik, haritadaki işaretçilerden birinde gerçekleştiğinde, parametre olarak geçirilen karşılık gelen Marker nesnesiyle birlikte işleyicinin geri çağırması çağrılır. Bu Marker nesnesini bir Marker nesnesine kendi referansınızla karşılaştırmak için == değil 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 işleyiciyi 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, bağımsız değişken olarak aktarılır. Bu yöntem, etkinliği tüketip tüketmediğinizi (yani varsayılan davranışı bastırmak istediğinizi) belirten bir boole döndürür. false sonucunu döndürürse özel davranışınıza ek olarak varsayılan davranış da uygulanır. Bir işaretçi tıklama etkinliği için varsayılan davranış, bilgi penceresini (varsa) göstermek ve kamerayı, işaretçi haritanın ortasına gelecek ş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-endeksine 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, işaretçilere veya daha düşük Z-endeksi değerlerine sahip diğer yer paylaşımlarına iletilmez.
  • Bir işaretçi kümesinin tıklanması, sonraki tıklamaların kümede döngüye girmesine ve her birini sırayla seçmesine neden olur. Döngünün sırası önce Z-endeksine, ardından tıklama noktasına yakınlığa öncelik verir.
  • Kullanıcı, kümenin yakınının dışına tıklama yaparsa API, kümeyi yeniden hesaplar ve tıklama döngüsünün durumunu sıfırlayarak en baştan başlar.
  • Tıklama etkinliği, döngüyü yeniden başlatmadan önce işaretçi kümelerinden diğer şekillere ve yer paylaşımlarına düşer.
  • İşaretçiler, diğer bindirmelerin z-endeksinden bağımsız olarak, diğer bindirmelere veya şekillere (çoklu çizgiler, poligonlar, daireler ve/veya zemin yer paylaşımları) kıyasla ayrı bir Z-endeksi grubunda yer alırlar. Birden fazla işaretçi, yer paylaşımı veya şekil birbirinin üzerine yerleştirilirse tıklama etkinliği önce işaretçi kümesi boyunca döner. Daha sonra, Z-endeksi değerlerine göre diğer tıklanabilir yer paylaşımları veya şekiller için tetiklenir.

İşaretçi sürükleme etkinlikleri

İşaretçi üzerindeki sürükleme etkinliklerini dinlemek için OnMarkerDragListener kullanabilirsiniz. Bu işleyiciyi haritada ayarlamak için GoogleMap.setOnMarkerDragListener numaralı telefonu arayın. Kullanıcının, bir işaretçiyi sürüklemek için işaretçiye uzun basması gerekir. Kullanıcı parmağını ekrandan çektiğinde, işaretçi bu 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ürüklemenin sonunda onMarkerDragEnd(Marker) çağrılır. Marker.getPosition() yöntemini çağırarak işaretçinin konumunu istediğiniz zaman öğrenebilirsiniz.