İşaretçiler

Platform seçin: Android iOS JavaScript

İşaretçiler haritada tek bir konumu 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, bir 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:

Kotlin

Java

Giriş

İşaretçiler haritada konumları tanımlar. Varsayılan işaretçi, Google Haritalar'ın görünüm ve izleniminde genel olarak kullanılan standart bir simge kullanır. Simgenin rengini, resmini veya sabitleme noktasını API aracılığıyla değiştirmek mümkündür. İşaretçiler Marker türündeki nesnelerdir ve haritaya GoogleMap.addMarker(markerOptions) yöntemi ile eklenir.

İşaretçiler etkileşimli olacak şekilde tasarlanmıştır. click etkinliklerini varsayılan olarak alırlar ve genellikle bilgi pencereleri açmak için etkinlik işleyicilerle birlikte kullanılırlar. Bir iş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 taşıma özelliğini etkinleştirmek için uzun basmayı kullanın.

Varsayılan olarak, kullanıcı bir işaretçiye dokunduğunda, haritanın sağ alt köşesinde harita araç çubuğu görünür ve kullanıcının Google Haritalar mobil uygulamasına hızlı bir şekilde erişmesine olanak tanır. 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 eklemeyle ilgili temel bilgiler ele alınmaktadır.

İşaretçi ekleyin

Aşağıdaki örnekte, haritaya işaretçinin nasıl ekleneceği gösterilmektedir. İşaretçi -33.852,151.211 (Sidney, Avustralya) koordinatlarında oluşturulur ve tıklandığında "Sidney'deki İşaretçi" dizesini bir bilgi penceresinde 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çi hakkında ek bilgiler görüntüleme

Kullanıcılar haritadaki bir işaretçiye dokunduğunda bir yer veya 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

Marker.setTag() kullanarak bir işaretçiyle rastgele veri nesnesini 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



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

Aşağıda, işaretçilerle verileri depolamanın ve almanın yararlı olduğu durumlarla ilgili bazı örnekler verilmiştir:

  • Uygulamanız farklı türde işaretçiler sunuyor olabilir ve kullanıcı bunları tıkladığında bunlara farklı bir şekilde davranmak istiyorsunuz. Bunun için, türü belirten bir işaretçiyle String depolayabilirsiniz.
  • Benzersiz kayıt tanımlayıcılarına sahip bir sistemle etkileşim kuruyor olabilirsiniz. Bu tanımlayıcılarda 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 hale getirme

Haritaya eklendikten sonra, 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 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) ile veya haritaya eklendikten sonra Marker.setDraggable(boolean) ile sürüklenebilir olacak şekilde açıkça ayarlamanız gerekir. İşaretçi sürükleme etkinlikleri konusunda açıklandığı gibi, işaretçideki sürükleme etkinliklerini dinleyebilirsiniz.

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

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çiyi özelleştirme

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

İşaretçiler, varsayılan simgenin yerine gösterilecek özel bir resim tanımlayabilir. Bir simgenin tanımlanması, işaretçinin görsel davranışını etkileyen bir dizi özellik ayarlamayı içerir.

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

Konum (Zorunlu)
İşaretçinin haritadaki konumu için LatLng değeri. Bir Marker nesnesi için gerekli tek özellik budur.
Çapa
Resimde, işaretçinin EnlBoy konumuna yerleştirilecek nokta. Bu değer, 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österilen ek metin.
Simge
Varsayılan işaretçi resminin yerine görüntülenen 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ü
Varsayılan olarak, işaretçiler ilan tahtası yönünü kullanır. Yani, harita yüzeyine göre değil, cihazın ekranına göre ç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ünya üzerinde düz olacak şekilde ayarlayabilirsiniz. Düz işaretçiler, harita döndürüldüğünde döner ve harita eğik olduğunda perspektif değişir. İlan tahtası 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 yönü (saat yönünde derece cinsinden belirtilir). İşaretçi düzse varsayılan konum değişir. Düz bir işaretçi için varsayılan konum kuzeye hizalanır. İşaretçi düz olmadığında varsayılan konum yukarı bakar ve döndürme yönü işaretçi her zaman kameraya bakacak şekilde yapılır.

Aşağıdaki snippet, varsayılan simgeyi içeren 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ştirin

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

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ştirin

Bir işaretçinin opaklığını MarkerOptions.alpha() yöntemiyle kontrol edebilirsiniz. Alfa, 0,0 ile 1,0 arasında bir hareketli değer 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ş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 dizinindeki bir bit eşlem resminin adını kullanarak özel bir 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 Bit eşlem resim dosyasının adını kullanarak özel bir simge oluşturur.
fromPath(String absolutePath)
Bir bit eşlemi görüntüsünün mutlak dosya yolundan özel işaretçi oluşturur.
fromResource(int resourceId)
Bir bit eşlemi 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şturuyor.

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üzeltme

İşaretçi simgeleri normalde ekrana göre çizilir; haritayı döndürmek, yatırmak veya yakınlaştırmak işaretçinin yönünü değiştirmez. Bir işaretçinin yönünü dünya üzerinde düz olacak şekilde ayarlayabilirsiniz. Bu şekilde yönlenen işaretçiler, harita döndürüldüğünde de döner ve harita eğik olduğunda perspektif değişir. 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 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ının etrafında 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 haritada düz olduğunda, varsayılan konum Kuzey'dir. İşaretçi düz olmadığında varsayılan konum yukarıyı gösterir ve döndürme yönü 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 değerine ayarlanması, işaretçinin tabanı yerine merkezinin çevresinde 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ş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, düşük Z-endeksine sahip işaretçilerin üzerine çizilir. Varsayılan Z-endeksi değeri 0 şeklindedir.

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:

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

İşaretçinin Z-endeksine erişmek için Marker.getZIndex() kodunu çağırın. Ayrıca Marker.setZIndex() öğesini çağırarak bunu değiştirebilirsiniz.

İşaretçiler, diğer bindirmelerin Z-endeksinden bağımsız olarak her zaman karo katmanlarının ve işaretsiz diğer bindirmelerin (zemin örtüşmeleri, çoklu çizgiler, poligonlar ve diğer şekiller) üzerine çizilir. İşaretçiler, diğer yer paylaşımlarına kıyasla ayrı bir Z-endeksi grubunda etkili bir şekilde kabul edilir.

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

Herkese açık kullanıcı adı etkinlikleri

Haritalar API'si, işaretçi etkinliklerini dinlemenize ve yanıtlamanıza olanak tanır. Bu etkinlikleri dinlemek için ilgili işleyiciyi, işaretçilerin ait olduğu GoogleMap nesnesine ayarlamanız gerekir. Etkinlik haritadaki işaretçilerden birinde gerçekleştiğinde, karşılık gelen Marker nesnesi parametre olarak iletilerek dinleyicinin geri çağırması çağrılır. Bu Marker nesnesini bir Marker nesnesiyle 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 OnMarkerClickListener kullanabilirsiniz. Bu işleyiciyi haritaya 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 iletilir. Bu yöntem, etkinliği kullanıp kullanmadığınızı (yani, varsayılan davranışı önlemek isteyip istemediğinizi) belirten bir boole döndürür. false değerini döndürürse özel davranışınıza ek olarak varsayılan davranış da uygulanır. İş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ümesini tıkladığınızda, sonraki tıklamaların kümede döngü şeklinde tekrar gösterilmesine ve her bir işaretçinin sırayla seçilmesine 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ümeye yakın konumun dışına tıklarsa API kümeyi yeniden hesaplar ve tıklama döngüsünün durumunu sıfırlar. Böylece döngü baştan başlar.
  • Tıklama etkinliği, döngü yeniden başlatılmadan önce işaretçi kümelerinden diğer şekillere ve yer paylaşımlarına denk gelir.
  • İşaretçiler, diğer bindirmelerin Z-endeksinden bağımsız olarak, diğer bindirmelere veya şekillere (çoklu çizgiler, poligonlar, daireler ve/veya yer örtüleri) kıyasla ayrı bir z-endeksi grubunda etkili bir şekilde kabul edilir. Birden fazla işaretçi, yer paylaşımı veya şekil birbirlerinin üzerine yerleştiriliyorsa tıklama etkinliği önce işaretçiler kümesinde döngü şeklinde döndürülür, ardından 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 haritaya ayarlamak için GoogleMap.setOnMarkerDragListener numaralı telefonu arayın. Kullanıcı, işaretçiyi sürüklemek için işaretçiye uzun basmalıdır. Kullanıcı parmağını ekrandan çektiğinde, işaretçi bu konumda kalır. Bir işaretçi sürüklendiğinde baş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() numaralı telefonu arayarak işaretçinin konumunu istediğiniz zaman öğrenebilirsiniz.