ตัวทำเครื่องหมาย

เลือกแพลตฟอร์ม Android iOS JavaScript

เครื่องหมายระบุตำแหน่งเดียวบนแผนที่ คุณสามารถปรับแต่งเครื่องหมายได้โดยเปลี่ยนสีเริ่มต้น หรือแทนที่ไอคอนเครื่องหมายด้วยรูปภาพที่กําหนดเอง หน้าต่างข้อมูลสามารถให้บริบทเพิ่มเติมแก่เครื่องหมายได้

ตัวอย่างโค้ด

ที่เก็บ ApiDemos ใน GitHub มีตัวอย่างที่แสดงฟีเจอร์เครื่องหมายต่างๆ ดังนี้

Kotlin

• MapWithMarker: แผนที่แบบง่ายที่มีเครื่องหมาย ดูบทแนะนำเกี่ยวกับการเพิ่มแผนที่ด้วย marker-kt
• MarkerDemoActivity: การใช้เครื่องหมายบนแผนที่ รวมถึงตัวเลือกและ Listeners

Java

• MapWithMarker: แผนที่แบบง่ายที่มีเครื่องหมาย ดูบทแนะนำเกี่ยวกับการเพิ่มแผนที่ที่มีเครื่องหมาย
• MarkerDemoActivity: การใช้เครื่องหมายบนแผนที่ รวมถึงตัวเลือกและ Listeners

บทนำ

เครื่องหมายระบุตำแหน่งบนแผนที่ เครื่องหมายเริ่มต้นใช้ไอคอนมาตรฐานซึ่งมีลักษณะเดียวกับรูปลักษณ์ของ Google Maps คุณเปลี่ยนสี รูปภาพ หรือจุดยึดของไอคอนผ่าน API ได้ เครื่องหมายคือออบเจ็กต์ประเภท Marker และเพิ่มลงในแผนที่ด้วยเมธอด GoogleMap.addMarker(markerOptions)

เครื่องหมายออกแบบมาให้โต้ตอบได้ โดยจะได้รับเหตุการณ์ click โดยค่าเริ่มต้น และมักใช้ร่วมกับ Listener เหตุการณ์เพื่อเปิดหน้าต่างข้อมูล การตั้งค่าพร็อพเพอร์ตี้ draggable ของเครื่องหมายเป็น true ช่วยให้ผู้ใช้เปลี่ยนตำแหน่งของเครื่องหมายได้ กดค้างไว้เพื่อเปิดใช้งานความสามารถในการย้ายเครื่องหมาย

โดยค่าเริ่มต้น เมื่อผู้ใช้แตะเครื่องหมาย แถบเครื่องมือแผนที่จะปรากฏที่ด้านขวาล่างของแผนที่ ซึ่งช่วยให้ผู้ใช้เข้าถึงแอป Google Maps บนอุปกรณ์เคลื่อนที่ได้อย่างรวดเร็ว คุณปิดใช้แถบเครื่องมือได้ ดูข้อมูลเพิ่มเติมได้ที่คู่มือการควบคุม

เริ่มต้นใช้งานเครื่องหมาย

รายการ Maps Live นี้จะอธิบายพื้นฐานเกี่ยวกับการเพิ่มเครื่องหมายลงในแผนที่โดยใช้ Maps SDK สําหรับ Android

เพิ่มเครื่องหมาย

ตัวอย่างต่อไปนี้แสดงวิธีเพิ่มเครื่องหมายลงในแผนที่ ระบบจะสร้างเครื่องหมายที่พิกัด -33.852,151.211 (ซิดนีย์ ออสเตรเลีย) และแสดงสตริง "เครื่องหมายในซิดนีย์" ในหน้าต่างข้อมูลเมื่อคลิก

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

      

แสดงข้อมูลเพิ่มเติมเกี่ยวกับเครื่องหมาย

ข้อกำหนดทั่วไปคือต้องแสดงข้อมูลเพิ่มเติมเกี่ยวกับสถานที่หรือตำแหน่งเมื่อผู้ใช้แตะเครื่องหมายบนแผนที่ ดูคู่มือเกี่ยวกับหน้าต่างข้อมูล

เชื่อมโยงข้อมูลกับเครื่องหมาย

คุณสามารถจัดเก็บออบเจ็กต์ข้อมูลแบบกำหนดเองที่มีเครื่องหมายได้โดยใช้ Marker.setTag() และดึงข้อมูลออบเจ็กต์โดยใช้ Marker.getTag() ตัวอย่างด้านล่างแสดงวิธีนับจํานวนครั้งที่มีการคลิกเครื่องหมายโดยใช้แท็ก

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

      

ตัวอย่างสถานการณ์ที่ควรจัดเก็บและเรียกข้อมูลด้วยเครื่องหมายมีดังนี้

• แอปของคุณอาจรองรับเครื่องหมายประเภทต่างๆ และคุณต้องการจัดการเครื่องหมายเหล่านั้นแตกต่างกันเมื่อผู้ใช้คลิก คุณจัดเก็บ String ที่มีเครื่องหมายระบุประเภทเพื่อให้บรรลุเป้าหมายนี้ได้
• คุณอาจกำลังติดต่อกับระบบที่มีตัวระบุระเบียนที่ไม่ซ้ำกัน โดยเครื่องหมายแสดงถึงระเบียนเฉพาะในระบบนั้น
• ข้อมูลเครื่องหมายอาจระบุลําดับความสําคัญที่จะใช้เมื่อตัดสินใจเกี่ยวกับลําดับชั้น z ของเครื่องหมาย

ทําให้เครื่องหมายลากได้

คุณสามารถจัดตำแหน่งเครื่องหมายใหม่ได้เมื่อเพิ่มลงในแผนที่แล้ว ตราบใดที่การตั้งค่าพร็อพเพอร์ตี้ draggable เป็น true กดเครื่องหมายค้างไว้เพื่อเปิดใช้การลาก เมื่อคุณนำนิ้วออกจากหน้าจอ เครื่องหมายจะยังคงอยู่ในตำแหน่งนั้น

โดยค่าเริ่มต้น มาร์กเกอร์จะลากไม่ได้ คุณต้องตั้งค่าเครื่องหมายให้ลากได้อย่างชัดเจนด้วย MarkerOptions.draggable(boolean) ก่อนเพิ่มลงในแผนที่ หรือ Marker.setDraggable(boolean) เมื่อเพิ่มลงในแผนที่แล้ว คุณสามารถฟังเหตุการณ์การลากบนเครื่องหมายตามที่อธิบายไว้ในเหตุการณ์การลากเครื่องหมาย

ข้อมูลโค้ดด้านล่างจะเพิ่มเครื่องหมายที่ลากได้ที่เมืองเพิร์ธ ประเทศออสเตรเลีย

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

      

ปรับแต่งเครื่องหมาย

วิดีโอนี้แสดงวิธีใช้เครื่องหมายเพื่อแสดงตำแหน่งบนแผนที่

ตัวทำเครื่องหมายอาจกำหนดรูปภาพที่กำหนดเองให้แสดงแทนไอคอนเริ่มต้น การกําหนดไอคอนเกี่ยวข้องกับการตั้งค่าพร็อพเพอร์ตี้จํานวนหนึ่งซึ่งส่งผลต่อลักษณะที่ปรากฏของหมุด

เครื่องหมายรองรับการปรับแต่งผ่านพร็อพเพอร์ตี้ต่อไปนี้

ตำแหน่ง (ต้องระบุ)

ค่า LatLng สำหรับตำแหน่งของเครื่องหมายบนแผนที่ นี่เป็นพร็อพเพอร์ตี้เดียวที่จําเป็นสําหรับออบเจ็กต์ Marker

เชื่อมโยง

จุดบนรูปภาพที่จะวางไว้ที่ตำแหน่ง LatLng ของเครื่องหมาย โดยค่าเริ่มต้นจะเป็นตรงกลางด้านล่างของรูปภาพ

อัลฟ่า

ตั้งค่าความทึบแสงของเครื่องหมาย ค่าเริ่มต้นคือ 1.0

ชื่อ

สตริงที่แสดงในหน้าต่างข้อมูลเมื่อผู้ใช้แตะเครื่องหมาย

ตัวอย่างข้อมูล

ข้อความเพิ่มเติมที่แสดงใต้ชื่อ

Icon

บิตแมปที่แสดงแทนรูปภาพเครื่องหมายเริ่มต้น

ลากได้

ตั้งค่าเป็น true หากต้องการอนุญาตให้ผู้ใช้ย้ายเครื่องหมาย ค่าเริ่มต้นคือ false

แสดง

ตั้งค่าเป็น false เพื่อซ่อนเครื่องหมาย ค่าเริ่มต้นคือ true

การวางแนวแนวราบหรือบิลบอร์ด

โดยค่าเริ่มต้น เครื่องหมายจะใช้การวางแนวบิลบอร์ด ซึ่งหมายความว่าเครื่องหมายจะวาดขึ้นโดยวางแนวตามหน้าจอของอุปกรณ์แทนที่จะวางแนวตามพื้นผิวของแผนที่ การหมุน การเอียง หรือการซูมแผนที่จะไม่เปลี่ยนการวางแนวของเครื่องหมาย คุณตั้งค่าการวางแนวของเครื่องหมายให้วางราบกับพื้นโลกได้ เครื่องหมายแบบแบนจะหมุนเมื่อคุณหมุนแผนที่ และเปลี่ยนมุมมองเมื่อคุณเอียงแผนที่ เครื่องหมายแบนจะคงขนาดไว้เมื่อซูมแผนที่เข้าหรือออก เช่นเดียวกับเครื่องหมายบิลบอร์ด

การหมุน

การวางแนวของเครื่องหมายที่ระบุเป็นองศาตามเข็มนาฬิกา ตำแหน่งเริ่มต้นจะเปลี่ยนไปหากเครื่องหมายอยู่ในแนวราบ ตำแหน่งเริ่มต้นของเครื่องหมายบนพื้นผิวจะปรับแนวให้ทิศเหนือ เมื่อเครื่องหมายไม่วางราบ ตำแหน่งเริ่มต้นจะชี้ขึ้นและการหมุนจะทําให้เครื่องหมายหันหน้าเข้าหากล้องเสมอ

ข้อมูลโค้ดด้านล่างสร้างเครื่องหมายง่ายๆ ด้วยไอคอนเริ่มต้น

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

      

ปรับแต่งสีเครื่องหมาย

คุณสามารถปรับแต่งสีของรูปภาพเครื่องหมายเริ่มต้นได้โดยส่งออบเจ็กต์ BitmapDescriptor ไปยังเมธอด icon() คุณสามารถใช้ชุดสีที่กําหนดไว้ล่วงหน้าในออบเจ็กต์ BitmapDescriptorFactory หรือตั้งค่าสีเครื่องหมายที่กําหนดเองด้วยเมธอด BitmapDescriptorFactory.defaultMarker(float hue) เฉดสีคือค่าระหว่าง 0 ถึง 360 ซึ่งแสดงจุดบนวงล้อสี

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

      

ปรับแต่งความทึบแสงของเครื่องหมาย

คุณควบคุมระดับความทึบของหมุดได้ด้วยเมธอด MarkerOptions.alpha() คุณควรระบุค่าอัลฟ่าเป็นค่าลอยระหว่าง 0.0 ถึง 1.0 โดยที่ 0 คือโปร่งแสงทั้งหมดและ 1 คือทึบแสงทั้งหมด

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

      

ปรับแต่งรูปภาพเครื่องหมาย

คุณแทนที่รูปภาพเครื่องหมายเริ่มต้นด้วยรูปภาพเครื่องหมายที่กำหนดเองได้ ซึ่งมักเรียกว่าไอคอน ระบบจะตั้งค่าไอคอนที่กำหนดเองเป็น BitmapDescriptor เสมอ และกำหนดโดยใช้เมธอดใดเมธอดหนึ่งในคลาส BitmapDescriptorFactory

fromAsset(String assetName)

สร้างเครื่องหมายที่กำหนดเองโดยใช้ชื่อรูปภาพบิตแมปในไดเรกทอรีชิ้นงาน

fromBitmap(Bitmap image)

สร้างเครื่องหมายที่กำหนดเองจากรูปภาพบิตแมป

fromFile(String fileName)

สร้างไอคอนที่กำหนดเองโดยใช้ชื่อไฟล์รูปภาพบิตแมปที่อยู่ในพื้นที่เก็บข้อมูลภายใน

fromPath(String absolutePath)

สร้างเครื่องหมายที่กําหนดเองจากเส้นทางไฟล์สัมบูรณ์ของรูปภาพบิตแมป

fromResource(int resourceId)

สร้างเครื่องหมายที่กำหนดเองโดยใช้รหัสทรัพยากรของรูปภาพบิตแมป

ข้อมูลโค้ดด้านล่างจะสร้างเครื่องหมายที่มีไอคอนที่กำหนดเอง

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

      

ปรับเครื่องหมายให้แบน

โดยปกติแล้ว ไอคอนเครื่องหมายจะวาดตามหน้าจอ การหมุน การเอียง หรือการซูมแผนที่จะไม่เปลี่ยนการวางแนวของเครื่องหมาย คุณสามารถตั้งค่าการวางแนวของเครื่องหมายให้วางราบกับพื้นโลกได้ เครื่องหมายที่วางแนวในลักษณะนี้จะหมุนเมื่อแผนที่หมุน และเปลี่ยนมุมมองเมื่อแผนที่เอียง เครื่องหมายแบนจะคงขนาดเดิมเมื่อซูมแผนที่เข้าหรือออก

หากต้องการเปลี่ยนการวางแนวของเครื่องหมาย ให้ตั้งค่าพร็อพเพอร์ตี้ flat ของเครื่องหมายเป็น 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));

      

หมุนเครื่องหมาย

คุณหมุนเครื่องหมายรอบจุดยึดได้โดยใช้แป้น MarkersetRotation() การหมุนจะวัดเป็นองศาตามเข็มนาฬิกาจากตำแหน่งเริ่มต้น เมื่อเครื่องหมายวางราบบนแผนที่ ตำแหน่งเริ่มต้นคือทิศเหนือ เมื่อเครื่องหมายไม่วางราบ ตำแหน่งเริ่มต้นจะชี้ขึ้นและการหมุนจะทําให้เครื่องหมายหันหน้าเข้าหากล้องเสมอ

ตัวอย่างด้านล่างจะหมุนเครื่องหมาย 90° การตั้งค่าจุดยึดเป็น 0.5,0.5 จะทำให้เครื่องหมายหมุนรอบจุดศูนย์กลางแทนที่จะหมุนรอบฐาน

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

      

ดัชนีลำดับ Z ของเครื่องหมาย

ลำดับ z จะระบุลําดับกองของหมุดนี้เทียบกับหมุดอื่นๆ ในแผนที่ ระบบจะวาดเครื่องหมายที่มีดัชนีลำดับ Z สูงไว้บนเครื่องหมายที่มีดัชนีลำดับ Z ต่ำกว่า ค่า z-index เริ่มต้นคือ 0

ตั้งค่า z-index ในออบเจ็กต์ options ของเครื่องหมายโดยเรียกใช้ MarkerOptions.zIndex() ดังที่แสดงในข้อมูลโค้ดต่อไปนี้

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

      

คุณสามารถเข้าถึง z-index ของเครื่องหมายได้โดยเรียกใช้ Marker.getZIndex() และเปลี่ยนได้โดยเรียกใช้ Marker.setZIndex()

ระบบจะวาดเครื่องหมายเหนือเลเยอร์ไทล์และการวางซ้อนอื่นๆ ที่ไม่ใช่เครื่องหมายเสมอ (การซ้อนทับพื้นดิน เส้นประกอบ รูปหลายเหลี่ยม และรูปร่างอื่นๆ) โดยไม่คำนึงถึงดัชนีลำดับ Z ของการวางซ้อนอื่นๆ ระบบจะถือว่าเครื่องหมายอยู่ในกลุ่ม z-index แยกต่างหากเมื่อเทียบกับการวางซ้อนอื่นๆ

อ่านเกี่ยวกับผลของ z-index ต่อเหตุการณ์คลิกด้านล่าง

จัดการเหตุการณ์เครื่องหมาย

Maps API ช่วยให้คุณรับฟังและตอบสนองต่อเหตุการณ์เครื่องหมายได้ หากต้องการฟังเหตุการณ์เหล่านี้ คุณต้องตั้งค่า Listener ที่สอดคล้องกันในออบเจ็กต์ GoogleMap ที่เป็นเครื่องหมาย เมื่อเหตุการณ์เกิดขึ้นที่เครื่องหมายบนแผนที่ ระบบจะเรียกใช้ Callback ของ Listener พร้อมส่งออบเจ็กต์ Marker ที่เกี่ยวข้องผ่านพารามิเตอร์ หากต้องการเปรียบเทียบออบเจ็กต์ Marker นี้กับการอ้างอิงของคุณเองไปยังออบเจ็กต์ Marker คุณต้องใช้ equals() ไม่ใช่ ==

คุณสามารถฟังเหตุการณ์ต่อไปนี้

• เหตุการณ์การคลิกเครื่องหมาย
• เหตุการณ์การลากเครื่องหมาย
• เหตุการณ์การคลิกหน้าต่างข้อมูล

เหตุการณ์การคลิกเครื่องหมาย

คุณสามารถใช้ OnMarkerClickListener เพื่อฟังเหตุการณ์การคลิกบนเครื่องหมายได้ หากต้องการตั้งค่าโปรแกรมฟังเสียงนี้บนแผนที่ ให้เรียกใช้ GoogleMap.setOnMarkerClickListener(OnMarkerClickListener) เมื่อผู้ใช้คลิกเครื่องหมาย ระบบจะเรียก onMarkerClick(Marker) และส่งเครื่องหมายเป็นอาร์กิวเมนต์ เมธอดนี้จะแสดงผลบูลีนซึ่งระบุว่าคุณใช้เหตุการณ์หรือไม่ (กล่าวคือ คุณต้องการระงับลักษณะการทํางานเริ่มต้น) หากผลลัพธ์คือ false ลักษณะการทำงานเริ่มต้นจะเกิดขึ้นเพิ่มเติมจากลักษณะการทำงานที่กำหนดเอง ลักษณะการทำงานเริ่มต้นของเหตุการณ์การคลิกเครื่องหมายคือแสดงหน้าต่างข้อมูล (หากมี) และย้ายกล้องเพื่อให้เครื่องหมายอยู่ตรงกลางแผนที่

ผลของ z-index ต่อเหตุการณ์การคลิก

• เมื่อผู้ใช้คลิกกลุ่มเครื่องหมาย ระบบจะเรียกเหตุการณ์คลิกสําหรับเครื่องหมายที่มี z-index สูงสุด
• ระบบจะทริกเกอร์เหตุการณ์ได้สูงสุด 1 รายการต่อคลิก กล่าวคือ ระบบจะไม่ส่งการคลิกไปยังเครื่องหมายหรือการวางซ้อนอื่นๆ ที่มีค่าดัชนีลำดับ Z ต่ำกว่า
• การคลิกกลุ่มเครื่องหมายจะทำให้การคลิกครั้งต่อๆ ไปวนไปตามกลุ่ม โดยเลือกแต่ละรายการทีละรายการ ลําดับของรอบจะจัดลําดับความสําคัญเป็น z-index ก่อน จากนั้นจึงจัดลําดับตามความใกล้กับจุดคลิก
• หากผู้ใช้คลิกนอกบริเวณใกล้เคียงของคลัสเตอร์ API จะคํานวณคลัสเตอร์อีกครั้งและรีเซ็ตสถานะรอบการคลิกเพื่อให้เริ่มตั้งแต่ต้น
• เหตุการณ์การคลิกจะผ่านคลัสเตอร์เครื่องหมายไปยังรูปร่างและการวางซ้อนอื่นๆ ก่อนเริ่มรอบใหม่
• ระบบจะถือว่าเครื่องหมายอยู่ในกลุ่ม z-index แยกต่างหากเมื่อเทียบกับการวางซ้อนหรือรูปร่างอื่นๆ (เส้นประกอบ รูปหลายเหลี่ยม วงกลม และ/หรือการวางซ้อนพื้นดิน) โดยไม่คำนึงถึง z-index ของการวางซ้อนอื่นๆ หากวางเครื่องหมาย การวางซ้อน หรือรูปร่างหลายรายการซ้อนทับกัน เหตุการณ์การคลิกจะวนผ่านกลุ่มเครื่องหมายก่อน จากนั้นจึงเรียกให้แสดงการวางซ้อนหรือรูปร่างอื่นๆ ที่คลิกได้ โดยอิงตามค่า z-index

เหตุการณ์การลากเครื่องหมาย

คุณสามารถใช้ OnMarkerDragListener เพื่อรอเหตุการณ์การลากบนเครื่องหมายได้ หากต้องการตั้งค่าโปรแกรมฟังเสียงนี้บนแผนที่ ให้เรียกใช้ GoogleMap.setOnMarkerDragListener หากต้องการลากเครื่องหมาย ผู้ใช้ต้องกดเครื่องหมายนั้นค้างไว้ เมื่อผู้ใช้นำนิ้วออกจากหน้าจอ เครื่องหมายจะยังคงอยู่ในตำแหน่งนั้น เมื่อลากเครื่องหมาย ระบบจะเรียกใช้ onMarkerDragStart(Marker) ในตอนแรก ขณะที่ลากเครื่องหมาย onMarkerDrag(Marker) จะมีการเรียกใช้อย่างต่อเนื่อง เมื่อสิ้นสุดการลาก ระบบจะเรียกใช้ onMarkerDragEnd(Marker) คุณดูตำแหน่งของเครื่องหมายได้ทุกเมื่อโดยเรียกใช้ Marker.getPosition()

หมายเหตุ: โดยค่าเริ่มต้น คุณจะลากเครื่องหมายไม่ได้ คุณต้องตั้งค่าเครื่องหมายให้ลากได้อย่างชัดเจนก่อน ผู้ใช้จึงจะลากเครื่องหมายได้ ซึ่งทำได้ทั้งจาก MarkerOptions.draggable(boolean) ก่อนเพิ่มลงในแผนที่ หรือจาก Marker.setDraggable(boolean) เมื่อเพิ่มลงในแผนที่แล้ว