Sekarang adalah hari jadi Google Maps Platform yang ke-15 - Lihat berita dan pengumuman terbaru

Penanda

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:

Pengantar

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

Penanda dirancang 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 tekan lama untuk mengaktifkan kemampuan untuk 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 untuk mengontrol.

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 10,10, dan menampilkan string 'Hello world' di jendela info saat diklik.

@Override
public void onMapReady(GoogleMap map) {
    map.addMarker(new MarkerOptions()
        .position(new LatLng(10, 10))
        .title("Hello world"));
}

Menampilkan informasi tambahan tentang penanda

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

Mengaitkan data dengan penanda

Anda dapat menyimpan objek data arbitrer dengan penanda menggunakan Marker.setTag(), dan mengambil objek data menggunakan Marker.getTag(), seperti yang ditunjukkan dalam contoh kode ini:

/**
 * A demo class that stores and retrieves data objects with each marker.
 */
public class MarkerDemoActivity extends FragmentActivity implements
        OnMarkerClickListener,
        OnMapReadyCallback {

    private static final LatLng PERTH = new LatLng(-31.952854, 115.857342);
    private static final LatLng SYDNEY = new LatLng(-33.87365, 151.20689);
    private static final LatLng BRISBANE = new LatLng(-27.47093, 153.0235);

    private Marker mPerth;
    private Marker mSydney;
    private Marker mBrisbane;

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.marker_demo);

        SupportMapFragment mapFragment =
                (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /** Called when the map is ready. */
    @Override
    public void onMapReady(GoogleMap map) {
        mMap = map;

        // Add some markers to the map, and add a data object to each marker.
        mPerth = mMap.addMarker(new MarkerOptions()
                .position(PERTH)
                .title("Perth"));
        mPerth.setTag(0);

        mSydney = mMap.addMarker(new MarkerOptions()
                .position(SYDNEY)
                .title("Sydney"));
        mSydney.setTag(0);

        mBrisbane = mMap.addMarker(new MarkerOptions()
                .position(BRISBANE)
                .title("Brisbane"));
        mBrisbane.setTag(0);

        // Set a listener for marker click.
        mMap.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, dan sebaiknya perlakukan penanda tersebut secara berbeda saat pengguna mengkliknya. 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. Saat melepaskan jari dari layar, penanda akan tetap berada di posisi tersebut.

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 Marker.setDraggable(boolean) setelah penanda ditambahkan ke peta. Anda dapat memantau peristiwa tarik pada penanda, seperti yang dijelaskan pada Peristiwa tarik penanda.

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

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .draggable(true));

Menyesuaikan penanda

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

Penanda dapat menentukan gambar kustom yang akan ditampilkan untuk menggantikan ikon default. Untuk menentukan ikon, sejumlah properti yang memengaruhi perilaku visual penanda harus ditetapkan.

Penanda mendukung penyesuaian melalui properti berikut:

Posisi (Wajib)
Nilai LatLng untuk posisi penanda pada peta. Ini adalah satu-satunya properti yang wajib ada untuk objek Marker.
Anchor
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.
Dapat ditarik
Tetapkan ke true jika Anda ingin mengizinkan pengguna memindahkan penanda. Default-nya adalah false.
Terlihat
Tetapkan ke false untuk membuat penanda tidak terlihat. Default-nya adalah true.
Orientasi Datar atau Billboard
Secara default, penanda berorientasi pada layar, dan tidak akan berputar atau miring bersama kamera. Penanda datar berorientasi pada permukaan bumi, serta akan berputar dan miring bersama kamera. Kedua jenis penanda ini tidak akan berubah ukurannya berdasarkan zoom. Gunakan GroundOverlays jika Anda menginginkan efek ini.
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.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE));

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 roda warna.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE)
                          .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.

static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
Marker melbourne = mMap.addMarker(new MarkerOptions()
                          .position(MELBOURNE)
                          .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 kelas 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 kustom.

  private static final LatLng MELBOURNE = new LatLng(-37.813, 144.962);
  private Marker melbourne = mMap.addMarker(new MarkerOptions()
                            .position(MELBOURNE)
                            .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. Penanda datar akan mempertahankan ukurannya saat peta diperbesar atau diperkecil.

Untuk mengubah orientasi penanda, tetapkan properti flat penanda ke true.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .flat(true));

Memutar penanda

Anda dapat memutar penanda di sekitar titik anchor-nya 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 anchor ke 0.5,0.5 menyebabkan penanda diputar di pusatnya, bukan di dasarnya.

static final LatLng PERTH = new LatLng(-31.90, 115.86);
Marker perth = mMap.addMarker(new MarkerOptions()
                          .position(PERTH)
                          .anchor(0.5,0.5)
                          .rotation(90.0));

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:

@Override
public void onMapReady(GoogleMap map) {
    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 memantau dan merespons peristiwa penanda. Untuk memantau 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 dengan referensi Anda sendiri ke objek Marker, Anda harus menggunakan equals(), bukan ==.

Anda dapat memantau peristiwa berikut:

Peristiwa klik penanda

Anda dapat menggunakan OnMarkerClickListener untuk memantau 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 atau tidak (yaitu 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 diturunkan 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 marker 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 memantau peristiwa tarik pada 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 posisi tersebut. Saat penanda ditarik, onMarkerDragStart(Marker) dipanggil terlebih dahulu. Saat penanda ditarik, onMarkerDrag(Marker) dipanggil secara konstan. Di akhir penarikan, onMarkerDragEnd(Marker) akan dipanggil. Posisi penanda dapat diperoleh kapan saja dengan memanggil Marker.getPosition().