Penanda

Pilih platform: Android iOS JavaScript

Penanda menunjukkan satu lokasi pada peta. Anda dapat menyesuaikan penanda dengan mengubah warna default, atau mengganti ikon penanda dengan gambar kustom. Jendela info dapat memberikan konteks tambahan pada penanda.

Contoh kode

Repositori ApiDemos di GitHub mencakup contoh yang menunjukkan berbagai fitur penanda:

Kotlin

Java

Pengantar

Penanda mengidentifikasi lokasi pada peta. Penanda default menggunakan ikon standar, yang selaras dengan tampilan dan nuansa Google Maps. Anda dapat mengubah warna, gambar, atau titik tambatan ikon melalui API. Penanda adalah objek dengan jenis Marker, dan ditambahkan ke peta dengan metode GoogleMap.addMarker(markerOptions).

Penanda didesain agar interaktif. Penanda menerima peristiwa click secara default, dan sering digunakan dengan pemroses peristiwa untuk memunculkan jendela info. Menetapkan properti draggable penanda ke true memungkinkan pengguna mengubah posisi penanda. Gunakan gestur tekan lama untuk mengaktifkan kemampuan memindahkan penanda.

Secara default, saat pengguna mengetuk penanda, toolbar peta muncul di kanan bawah peta, yang memberi pengguna akses cepat ke aplikasi seluler Google Maps. Toolbar ini dapat dinonaktifkan. Untuk mendapatkan informasi lebih lanjut, lihat panduan kontrol.

Memulai penggunaan penanda

Episode Maps Live ini membahas dasar-dasar penambahan penanda pada peta Anda menggunakan Maps SDK for Android.

Menambahkan penanda

Contoh berikut menunjukkan cara menambahkan penanda ke peta. Penanda dibuat pada koordinat -33.852,151.211 (Sydney, Australia), dan menampilkan string 'Marker in Sydney' di jendela info saat diklik.

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

Menampilkan informasi tambahan tentang penanda

Persyaratan umumnya adalah menampilkan informasi tambahan tentang tempat atau lokasi saat pengguna mengetuk penanda pada peta. Lihat panduan jendela info.

Mengaitkan data dengan penanda

Anda dapat menyimpan objek data arbitrer dengan penanda menggunakan Marker.setTag(), dan mengambil objek data menggunakan Marker.getTag(). Contoh di bawah ini menunjukkan cara menghitung berapa kali penanda diklik menggunakan tag:

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

Berikut beberapa contoh skenario terkait saat yang tepat untuk menyimpan dan mengambil data dengan penanda:

  • Aplikasi Anda mungkin mengakomodasi berbagai jenis penanda, jadi Anda sebaiknya memperlakukan setiap penanda secara berbeda setiap kali diklik oleh pengguna. Caranya, Anda dapat menyimpan String dengan penanda yang menunjukkan jenis.
  • Anda mungkin berinteraksi dengan sistem yang memiliki ID catatan unik, dengan penanda yang merepresentasikan catatan khusus dalam sistem tersebut.
  • Data penanda dapat menunjukkan prioritas yang akan digunakan saat menentukan indeks z suatu penanda.

Membuat penanda dapat ditarik

Anda dapat mengubah posisi penanda setelah ditambahkan ke peta asalkan properti draggable ditetapkan ke true. Tekan lama penanda untuk mengaktifkan penarikan. Penanda akan tetap berada di posisinya, meskipun jari Anda diangkat dari layar.

Secara default, penanda tidak dapat ditarik. Anda harus menetapkan penanda secara eksplisit agar dapat ditarik baik dengan MarkerOptions.draggable(boolean) sebelum menambahkannya ke peta, maupun dengan Marker.setDraggable(boolean) setelah penanda ditambahkan ke peta. Anda dapat memproses peristiwa tarik pada penanda, seperti yang dijelaskan pada Peristiwa tarik penanda.

Cuplikan di bawah menambahkan penanda yang dapat ditarik di Perth, Australia.

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

Menyesuaikan penanda

Video ini menampilkan cara menggunakan penanda untuk memvisualisasikan lokasi pada peta.

Penanda dapat disesuaikan agar menampilkan gambar kustom sebagai ganti ikon default. Untuk menentukan ikon, sejumlah properti yang memengaruhi perilaku visual penanda harus ditetapkan.

Penanda mendukung penyesuaian untuk properti-properti berikut:

Posisi (Wajib)
Nilai LatLng untuk posisi penanda pada peta. Ini adalah satu-satunya properti yang wajib ada untuk objek Marker.
Titik Tambatan
Titik pada gambar yang akan ditempatkan pada posisi LatLng penanda. Default-nya adalah bagian tengah bawah gambar.
Alfa
Menetapkan opasitas penanda. Default-nya adalah 1.0.
Judul
String yang ditampilkan dalam jendela info saat pengguna mengetuk penanda.
Cuplikan
Teks tambahan yang ditampilkan di bawah judul.
Ikon
Bitmap yang ditampilkan untuk menggantikan gambar penanda default.
Kemampuan dapat ditarik
Tetapkan ke true untuk mengizinkan pengguna memindahkan penanda. Default-nya adalah false.
Visibilitas
Tetapkan ke false untuk membuat penanda tidak terlihat. Default-nya adalah true.
Orientasi Datar atau Baliho
Secara default, penanda menggunakan orientasi baliho, yang berarti penanda tersebut digambar dengan berorientasi pada layar perangkat, bukan permukaan peta. Memutar, memiringkan, atau melakukan zoom pada peta tidak akan mengubah orientasi penanda. Anda dapat menetapkan orientasi penanda agar datar terhadap bumi. Penanda datar akan berputar saat peta diputar, dan berubah perspektifnya saat peta dimiringkan. Seperti halnya penanda baliho, penanda datar akan tetap mempertahankan ukurannya saat peta diperbesar atau diperkecil.
Rotasi
Orientasi penanda, yang ditentukan dalam derajat, searah jarum jam. Posisi default berubah jika penanda datar. Posisi default untuk penanda datar adalah sejajar dengan utara. Jika penanda tidak datar, posisi default-nya adalah mengarah ke atas dan rotasi diatur sehingga penanda selalu menghadap kamera.

Cuplikan di bawah membuat penanda sederhana, dengan ikon default.

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

Menyesuaikan warna penanda

Warna gambar penanda default dapat disesuaikan dengan meneruskan objek BitmapDescriptor ke metode icon(). Anda dapat menggunakan kumpulan warna standar di objek BitmapDescriptorFactory, atau menetapkan warna penanda kustom dengan metode BitmapDescriptorFactory.defaultMarker(float hue). Hue adalah nilai antara 0 dan 360, yang merepresentasikan titik-titik pada lingkaran warna.

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

Menyesuaikan opasitas penanda

Anda dapat mengontrol opasitas penanda dengan metode MarkerOptions.alpha(). Alfa harus ditetapkan sebagai float antara 0,0 dan 1,0, dengan 0 sepenuhnya transparan dan 1 sepenuhnya tidak tembus pandang.

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

Menyesuaikan gambar penanda

Anda dapat mengganti gambar penanda default dengan gambar penanda kustom, yang sering disebut sebagai ikon. Ikon kustom selalu ditetapkan sebagai BitmapDescriptor, dan ditentukan menggunakan salah satu metode dalam class BitmapDescriptorFactory.

fromAsset(String assetName)
Membuat penanda kustom menggunakan nama gambar Bitmap di direktori aset.
fromBitmap(Bitmap image)
Membuat penanda kustom dari gambar Bitmap.
fromFile(String fileName)
Membuat ikon kustom menggunakan nama file gambar Bitmap yang terletak di penyimpanan internal.
fromPath(String absolutePath)
Membuat penanda kustom dari jalur file absolut gambar Bitmap.
fromResource(int resourceId)
Membuat penanda kustom menggunakan ID referensi gambar Bitmap.

Cuplikan di bawah membuat penanda dengan ikon khusus.

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

Mendatarkan penanda

Ikon penanda biasanya digambar dengan berorientasi pada layar. Memutar, memiringkan, atau melakukan zoom pada peta tidak akan mengubah orientasi penanda. Anda dapat menetapkan orientasi penanda agar datar terhadap bumi. Penanda yang berorientasi dengan cara ini akan berputar saat peta diputar, dan berubah perspektifnya saat peta dimiringkan. Ukuran penanda datar tidak akan berubah meski peta diperbesar atau diperkecil.

Untuk mengubah orientasi penanda, tetapkan properti flat penanda ke 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));

Memutar penanda

Anda dapat memutar penanda di sekitar titik tambatannya dengan Marker.Metode setRotation(). Rotasi diukur dalam derajat searah jarum jam dari posisi default. Jika penanda datar pada peta, posisi default-nya adalah Utara. Jika penanda tidak datar, posisi default-nya adalah mengarah ke atas dan rotasi diatur sehingga penanda selalu menghadap kamera.

Contoh di bawah memutar penanda 90°. Menetapkan titik link ke 0.5,0.5 menyebabkan penanda diputar di pusatnya, bukan di dasarnya.

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

Indeks z penanda

Indeks z menetapkan urutan tumpukan penanda ini secara relatif terhadap penanda lainnya pada peta. Penanda dengan indeks z yang tinggi digambar di atas penanda dengan indeks z yang lebih rendah. Nilai indeks z default adalah 0.

Tetapkan indeks z pada objek opsi penanda dengan memanggil MarkerOptions.zIndex(), seperti yang ditampilkan pada cuplikan kode berikut:

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

Anda dapat mengakses indeks z penanda dengan memanggil Marker.getZIndex(), dan dapat mengubahnya dengan memanggil Marker.setZIndex().

Penanda selalu digambar di atas lapisan ubin dan overlay non-penanda lainnya (overlay bumi, polyline, poligon, dan bentuk lainnya) terlepas dari indeks z overlay lainnya. Penanda pada dasarnya dianggap sebagai grup indeks z yang terpisah dibandingkan dengan overlay lainnya.

Baca tentang dampak indeks z pada peristiwa klik di bawah.

Menangani peristiwa penanda

Maps API memungkinkan Anda memproses dan merespons peristiwa penanda. Untuk memproses peristiwa ini, Anda harus menetapkan pemroses terkait pada objek GoogleMap yang memiliki penanda tersebut. Jika terjadi peristiwa pada salah satu penanda dalam peta, callback pemroses akan dipanggil dengan objek Marker terkait yang diteruskan sebagai parameter. Untuk membandingkan objek Marker ini menggunakan rujukan Anda sendiri dengan sebuah objek Marker, Anda harus menggunakan equals(), bukan ==.

Anda dapat memproses peristiwa berikut:

Peristiwa klik penanda

Anda dapat menggunakan OnMarkerClickListener untuk memproses peristiwa klik pada penanda. Untuk menetapkan pemroses ini pada peta, panggil GoogleMap.setOnMarkerClickListener(OnMarkerClickListener). Saat pengguna mengklik penanda, onMarkerClick(Marker) akan dipanggil dan penanda akan diteruskan sebagai argumen. Metode ini menampilkan boolean yang menunjukkan apakah Anda telah menggunakan peristiwa ini (artinya, Anda ingin menyembunyikan perilaku default). Jika metode tersebut menampilkan false, perilaku default akan terjadi selain perilaku kustom Anda. Perilaku default untuk peristiwa klik penanda adalah menampilkan jendela info (jika tersedia) dan menggerakkan kamera sehingga penanda berada di tengah peta.

Efek indeks z pada peristiwa klik:

  • Saat pengguna mengklik cluster penanda, peristiwa klik dipicu untuk penanda dengan indeks z yang tertinggi.
  • Maksimal satu peristiwa akan dipicu per klik. Dengan kata lain, klik tidak diteruskan ke penanda atau overlay lainnya dengan nilai indeks z yang lebih rendah.
  • Jika cluster penanda diklik, klik berikutnya akan disikluskan pada cluster tersebut, dengan memilih setiap penanda sesuai gilirannya. Urutan siklus terlebih dahulu memprioritaskan indeks z, lalu jarak ke titik klik.
  • Jika pengguna mengklik di luar jarak cluster, API menghitung ulang cluster dan mereset status siklus klik agar dimulai dari awal.
  • Peristiwa klik diteruskan melalui cluster penanda ke bentuk dan overlay lainnya sebelum memulai ulang siklus.
  • Penanda pada dasarnya dianggap sebagai grup indeks z terpisah dibandingkan dengan overlay atau bentuk (polyline, poligon, lingkaran, dan/atau overlay bumi) lainnya, terlepas dari indeks z overlay lainnya. Jika beberapa penanda, overlay, atau bentuk ditempatkan di atas satu sama lainnya, peristiwa klik akan disikluskan pada cluster penanda terlebih dulu, lalu dipicu untuk overlay atau bentuk yang dapat diklik lainnya berdasarkan nilai indeks z-nya.

Peristiwa tarik penanda

Anda dapat menggunakan OnMarkerDragListener untuk memproses peristiwa tarik di penanda. Untuk menetapkan pemroses ini pada peta, panggil GoogleMap.setOnMarkerDragListener. Untuk menarik penanda, pengguna harus menekan lama penanda. Saat pengguna mengangkat jarinya dari layar, penanda akan tetap berada di posisinya. Saat penanda ditarik, onMarkerDragStart(Marker) dipanggil terlebih dahulu. Saat penanda sedang ditarik, onMarkerDrag(Marker) dipanggil secara konstan. Di akhir penarikan, onMarkerDragEnd(Marker) akan dipanggil. Posisi penanda dapat diperoleh kapan saja dengan memanggil Marker.getPosition().