Điểm đánh dấu

Điểm đánh dấu xác định vị trí trên bản đồ. Điểm đánh dấu mặc định sử dụng một biểu tượng tiêu chuẩn, thường thấy trong giao diện của Google Maps. Bạn có thể thay đổi màu, hình ảnh hoặc điểm neo của biểu tượng thông qua API. Điểm đánh dấu là các đối tượng thuộc loại Marker và được thêm vào bản đồ bằng phương thức GoogleMap.addMarker(markerOptions).

Điểm đánh dấu được thiết kế để có tính tương tác. Theo mặc định, điểm đánh dấu nhận các sự kiện click và thường được dùng với trình nghe sự kiện để hiển thị cửa sổ thông tin. Việc đặt thuộc tính draggable của điểm đánh dấu thành true cho phép người dùng thay đổi vị trí của điểm đánh dấu. Nhấn và giữ để kích hoạt khả năng di chuyển điểm đánh dấu.

Theo mặc định, khi người dùng nhấn vào một điểm đánh dấu, thanh công cụ bản đồ sẽ xuất hiện ở dưới cùng bên phải của bản đồ, giúp người dùng nhanh chóng truy cập vào ứng dụng di động Google Maps. Bạn có thể tắt thanh công cụ này. Để biết thêm thông tin, hãy xem hướng dẫn về các chế độ điều khiển.

Thêm một điểm đánh dấu

Ví dụ sau đây minh hoạ cách thêm một điểm đánh dấu vào bản đồ. Điểm đánh dấu được tạo tại toạ độ -33.852,151.211 (Sydney, Úc) và hiển thị chuỗi "Marker in Sydney" (Điểm đánh dấu ở Sydney) trong một cửa sổ thông tin khi được nhấp vào.

// Add a marker in Sydney, Australia,
// and move the map's camera to the same location.
val sydney = LatLng(-33.852, 151.211)
val marker = map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney")
)
marker?.let {
    val position = it.position
    val title = it.title
    val snippet = it.snippet
    val isDraggable = it.isDraggable
    val isFlat = it.isFlat
    val isVisible = it.isVisible
    val alpha = it.alpha
    val rotation = it.rotation
    val zIndex = it.zIndex
}
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

      

// Add a marker in Sydney, Australia,
// and move the map's camera to the same location.
LatLng sydney = new LatLng(-33.852, 151.211);
Marker marker = map.addMarker(new MarkerOptions()
    .position(sydney)
    .title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

      

Hiển thị thông tin bổ sung về một điểm đánh dấu

Một yêu cầu thường gặp là hiển thị thông tin bổ sung về một địa điểm khi người dùng nhấn vào một điểm đánh dấu trên bản đồ. Hãy xem hướng dẫn về cửa sổ thông tin.

Liên kết dữ liệu với một điểm đánh dấu

Bạn có thể lưu trữ một đối tượng dữ liệu tuỳ ý với một điểm đánh dấu bằng cách sử dụng Marker.setTag() và truy xuất đối tượng dữ liệu bằng cách sử dụng Marker.getTag(). Mẫu dưới đây cho biết cách bạn có thể đếm số lần một điểm đánh dấu được nhấp vào bằng cách sử dụng thẻ:

val PERTH = LatLng(-31.952854, 115.857342)
val SYDNEY = LatLng(-33.87365, 151.20689)
val BRISBANE = LatLng(-27.47093, 153.0235)

val markerPerth = map.addMarker(
    MarkerOptions()
        .position(PERTH)
        .title("Perth")
)
markerPerth?.tag = 0

val markerSydney = map.addMarker(
    MarkerOptions()
        .position(SYDNEY)
        .title("Sydney")
)
markerSydney?.tag = 0

val markerBrisbane = map.addMarker(
    MarkerOptions()
        .position(BRISBANE)
        .title("Brisbane")
)
markerBrisbane?.tag = 0

// Set a listener for marker click.
map.setOnMarkerClickListener { marker ->
    // 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(
            context,
            "${marker.title} has been clicked $newClickCount times.",
            Toast.LENGTH_SHORT
        ).show()
    }

    // Return false to indicate default behavior.
    false
}

      

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

Marker markerPerth = map.addMarker(new MarkerOptions()
    .position(PERTH)
    .title("Perth"));
markerPerth.setTag(0);

Marker markerSydney = map.addMarker(new MarkerOptions()
    .position(SYDNEY)
    .title("Sydney"));
markerSydney.setTag(0);

Marker markerBrisbane = map.addMarker(new MarkerOptions()
    .position(BRISBANE)
    .title("Brisbane"));
markerBrisbane.setTag(0);

// Set a listener for marker click.
map.setOnMarkerClickListener(new GoogleMap.OnMarkerClickListener() {
    @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(context,
                marker.getTitle() + " has been clicked " + clickCount + " times.",
                Toast.LENGTH_SHORT).show();
        }

        // Return false to indicate default behavior should occur.
        return false;
    }
});

      

Dưới đây là một số ví dụ về các trường hợp hữu ích khi lưu trữ và truy xuất dữ liệu bằng điểm đánh dấu:

• Ứng dụng của bạn có thể phục vụ nhiều loại điểm đánh dấu và bạn muốn xử lý các điểm đánh dấu đó theo cách khác nhau khi người dùng nhấp vào chúng. Để thực hiện việc này, bạn có thể lưu trữ một String với điểm đánh dấu cho biết loại.
• Bạn có thể đang tương tác với một hệ thống có mã nhận dạng bản ghi riêng biệt, trong đó các điểm đánh dấu đại diện cho các bản ghi cụ thể trong hệ thống đó.
• Dữ liệu điểm đánh dấu có thể cho biết mức độ ưu tiên cần sử dụng khi quyết định chỉ mục z của một điểm đánh dấu.

Cho phép kéo điểm đánh dấu

Bạn có thể đổi vị trí một điểm đánh dấu sau khi thêm điểm đánh dấu đó vào bản đồ, miễn là thuộc tính draggable của điểm đánh dấu được đặt thành true. Nhấn và giữ điểm đánh dấu để cho phép kéo. Khi bạn nhấc ngón tay khỏi màn hình, điểm đánh dấu sẽ vẫn ở vị trí đó.

Theo mặc định, bạn không thể kéo điểm đánh dấu. Bạn phải đặt điểm đánh dấu một cách rõ ràng để có thể kéo được bằng MarkerOptions.draggable(boolean) trước khi thêm điểm đánh dấu đó vào bản đồ hoặc Marker.setDraggable(boolean) sau khi đã thêm điểm đánh dấu đó vào bản đồ. Bạn có thể theo dõi các sự kiện kéo trên điểm đánh dấu, như mô tả trong phần Sự kiện kéo điểm đánh dấu.

Đoạn mã dưới đây thêm một điểm đánh dấu có thể kéo được ở Perth, Úc.

val perthLocation = LatLng(-31.90, 115.86)
val perth = map.addMarker(
    MarkerOptions()
        .position(perthLocation)
        .draggable(true)
)
map.moveCamera(com.google.android.gms.maps.CameraUpdateFactory.newLatLngZoom(perthLocation, 10f))

      

final LatLng perthLocation = new LatLng(-31.90, 115.86);
Marker perth = map.addMarker(
    new MarkerOptions()
        .position(perthLocation)
        .draggable(true));
map.moveCamera(com.google.android.gms.maps.CameraUpdateFactory.newLatLngZoom(perthLocation, 10f));

      

Tuỳ chỉnh điểm đánh dấu

Video này cho thấy các cách sử dụng điểm đánh dấu để hình dung vị trí trên bản đồ.

Điểm đánh dấu có thể xác định một hình ảnh tuỳ chỉnh để hiển thị thay cho biểu tượng mặc định. Việc xác định một biểu tượng liên quan đến việc thiết lập một số thuộc tính ảnh hưởng đến hành vi trực quan của điểm đánh dấu.

Điểm đánh dấu hỗ trợ tuỳ chỉnh thông qua các thuộc tính sau:

Vị trí (Bắt buộc)

Giá trị LatLng cho vị trí của điểm đánh dấu trên bản đồ. Đây là thuộc tính bắt buộc duy nhất cho đối tượng Marker.

Neo

Điểm trên hình ảnh sẽ được đặt ở vị trí LatLng của điểm đánh dấu. Giá trị mặc định là giữa phần dưới cùng của hình ảnh.

Alpha

Đặt độ mờ của điểm đánh dấu. Giá trị mặc định là 1.0.

Tiêu đề

Một chuỗi được hiển thị trong cửa sổ thông tin khi người dùng nhấn vào điểm đánh dấu.

Đoạn trích

Văn bản bổ sung được hiển thị bên dưới tiêu đề.

Biểu tượng

Một bitmap được hiển thị thay cho hình ảnh điểm đánh dấu mặc định.

Kéo được

Đặt thành true nếu bạn muốn cho phép người dùng di chuyển điểm đánh dấu. Giá trị mặc định là false.

Hiển thị

Đặt thành false để ẩn điểm đánh dấu. Giá trị mặc định là true.

Hướng phẳng hoặc hướng bảng quảng cáo

Theo mặc định, điểm đánh dấu sử dụng hướng bảng quảng cáo, nghĩa là điểm đánh dấu được vẽ theo hướng màn hình của thiết bị thay vì theo hướng bề mặt của bản đồ. Việc xoay, nghiêng hoặc thu phóng bản đồ sẽ không thay đổi hướng của điểm đánh dấu. Bạn có thể đặt hướng của một điểm đánh dấu sao cho phẳng so với trái đất. Điểm đánh dấu phẳng sẽ xoay khi bản đồ được xoay và thay đổi góc nhìn khi bản đồ được nghiêng. Giống như điểm đánh dấu bảng quảng cáo, điểm đánh dấu phẳng vẫn giữ nguyên kích thước khi bản đồ được thu phóng.

Xoay

Hướng của điểm đánh dấu, được chỉ định theo độ theo chiều kim đồng hồ. Vị trí mặc định sẽ thay đổi nếu điểm đánh dấu phẳng. Vị trí mặc định cho điểm đánh dấu phẳng là căn chỉnh theo hướng bắc. Khi điểm đánh dấu không phẳng, vị trí mặc định vị trí hướng lên và chế độ xoay là sao cho điểm đánh dấu luôn hướng về phía máy ảnh.

Đoạn mã dưới đây tạo một điểm đánh dấu đơn giản, có biểu tượng mặc định.

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

      

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

      

Tuỳ chỉnh màu điểm đánh dấu

Bạn có thể tuỳ chỉnh màu của hình ảnh điểm đánh dấu mặc định bằng cách truyền đối tượng BitmapDescriptor vào phương thức icon(). Bạn có thể sử dụng một tập hợp màu được xác định trước trong đối tượng BitmapDescriptorFactory hoặc đặt màu điểm đánh dấu tuỳ chỉnh bằng phương thức BitmapDescriptorFactory.defaultMarker(float hue). Hue là một giá trị từ 0 đến 360, đại diện cho các điểm trên bánh xe màu.

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

      

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

      

Tuỳ chỉnh độ mờ của điểm đánh dấu

Bạn có thể kiểm soát độ mờ của một điểm đánh dấu bằng phương thức MarkerOptions.alpha(). Alpha phải được chỉ định dưới dạng số thực từ 0.0 đến 1.0, trong đó 0 là hoàn toàn trong suốt và 1 là hoàn toàn không trong suốt.

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

      

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

      

Tuỳ chỉnh hình ảnh điểm đánh dấu

Bạn có thể thay thế hình ảnh điểm đánh dấu mặc định bằng một hình ảnh điểm đánh dấu tuỳ chỉnh, thường được gọi là biểu tượng. Biểu tượng tuỳ chỉnh luôn được đặt làm BitmapDescriptor và được xác định bằng một trong các phương thức trong lớp BitmapDescriptorFactory.

fromAsset(String assetName)

Tạo một điểm đánh dấu tuỳ chỉnh bằng tên của hình ảnh Bitmap trong thư mục thành phần.

fromBitmap(Bitmap image)

Tạo một điểm đánh dấu tuỳ chỉnh từ hình ảnh Bitmap.

fromFile(String fileName)

Tạo một biểu tượng tuỳ chỉnh bằng tên của tệp hình ảnh Bitmap nằm trong bộ nhớ trong.

fromPath(String absolutePath)

Tạo một điểm đánh dấu tuỳ chỉnh từ đường dẫn tệp tuyệt đối của hình ảnh Bitmap.

fromResource(int resourceId)

Tạo một điểm đánh dấu tuỳ chỉnh bằng mã tài nguyên của hình ảnh Bitmap.

Đoạn mã dưới đây tạo một điểm đánh dấu có biểu tượng tuỳ chỉnh.

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

      

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

      

Làm phẳng điểm đánh dấu

Biểu tượng điểm đánh dấu thường được vẽ theo màn hình; việc xoay, nghiêng hoặc thu phóng bản đồ sẽ không thay đổi hướng của điểm đánh dấu. Bạn có thể đặt hướng của một điểm đánh dấu sao cho phẳng so với trái đất. Các điểm đánh dấu được định hướng theo cách này sẽ xoay khi bản đồ được xoay và thay đổi góc nhìn khi bản đồ được nghiêng. Điểm đánh dấu phẳng sẽ giữ nguyên kích thước khi bản đồ được thu phóng.

Để thay đổi hướng của điểm đánh dấu, hãy đặt thuộc tính flat của điểm đánh dấu thành true.

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

      

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

      

Xoay điểm đánh dấu

Bạn có thể xoay một điểm đánh dấu quanh điểm neo bằng Marker.Phương thức setRotation(). Chế độ xoay được đo bằng độ theo chiều kim đồng hồ từ vị trí mặc định. Khi điểm đánh dấu phẳng trên bản đồ, vị trí mặc định là hướng bắc. Khi điểm đánh dấu không phẳng, vị trí mặc định là hướng lên và chế độ xoay là sao cho điểm đánh dấu luôn hướng về phía máy ảnh.

Ví dụ dưới đây xoay điểm đánh dấu 90°. Việc đặt điểm neo thành 0.5,0.5 sẽ khiến điểm đánh dấu được xoay quanh tâm của điểm đánh dấu đó, thay vì quanh chân của điểm đánh dấu.

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

      

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

      

Chỉ mục z của điểm đánh dấu

Chỉ mục z chỉ định thứ tự ngăn xếp của điểm đánh dấu này, so với các điểm đánh dấu khác trên bản đồ. Một điểm đánh dấu có chỉ mục z cao sẽ được vẽ trên các điểm đánh dấu có chỉ mục z thấp hơn. Giá trị chỉ mục z mặc định là 0.

Đặt chỉ mục z trên đối tượng tuỳ chọn của điểm đánh dấu bằng cách gọi MarkerOptions.zIndex(), như trong đoạn mã sau:

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

      

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

      

Bạn có thể truy cập vào chỉ mục z của điểm đánh dấu bằng cách gọi Marker.getZIndex() và bạn có thể thay đổi chỉ mục z đó bằng cách gọi Marker.setZIndex().

Điểm đánh dấu luôn được vẽ phía trên các lớp ô và các lớp phủ không phải điểm đánh dấu khác (lớp phủ mặt đất, đường nhiều đoạn, đa giác và các hình dạng khác) bất kể chỉ mục z của các lớp phủ khác. Điểm đánh dấu được coi là nằm trong một nhóm chỉ mục z riêng biệt so với các lớp phủ khác.

Đọc về ảnh hưởng của chỉ mục z đối với các sự kiện nhấp chuột bên dưới.

Xử lý sự kiện điểm đánh dấu

API Maps cho phép bạn theo dõi và phản hồi các sự kiện điểm đánh dấu. Để theo dõi các sự kiện này, bạn phải đặt trình nghe tương ứng trên đối tượng GoogleMap mà các điểm đánh dấu thuộc về. Khi sự kiện xảy ra trên một trong các điểm đánh dấu trên bản đồ, lệnh gọi lại của trình nghe sẽ được gọi với đối tượng Marker tương ứng được truyền qua dưới dạng tham số. Để so sánh đối tượng Marker này với tệp đối chiếu của riêng bạn đến đối tượng Marker, bạn phải sử dụng equals() chứ không phải ==.

Bạn có thể theo dõi các sự kiện sau:

• Sự kiện nhấp chuột vào điểm đánh dấu
• Sự kiện kéo điểm đánh dấu
• Sự kiện nhấp chuột vào cửa sổ thông tin

Sự kiện nhấp chuột vào điểm đánh dấu

Bạn có thể sử dụng OnMarkerClickListener để lắng nghe các sự kiện nhấp chuột vào điểm đánh dấu. Để đặt trình nghe này trên bản đồ, hãy gọi GoogleMap.setOnMarkerClickListener(OnMarkerClickListener). Khi người dùng nhấp vào một điểm đánh dấu, onMarkerClick(Marker) sẽ được gọi và điểm đánh dấu sẽ được truyền qua dưới dạng đối số. Phương thức này trả về một giá trị boolean cho biết liệu bạn đã sử dụng sự kiện hay chưa (tức là bạn muốn ngăn chặn hành vi mặc định). Nếu phương thức này trả về false, thì hành vi mặc định sẽ xảy ra ngoài hành vi tuỳ chỉnh của bạn. Hành vi mặc định cho sự kiện nhấp vào điểm đánh dấu là hiển thị cửa sổ thông tin của điểm đánh dấu đó (nếu có) và di chuyển máy ảnh sao cho điểm đánh dấu nằm ở giữa bản đồ.

Ảnh hưởng của chỉ mục z đối với các sự kiện nhấp chuột:

• Khi người dùng nhấp vào một cụm điểm đánh dấu, sự kiện nhấp chuột sẽ được kích hoạt cho điểm đánh dấu có chỉ mục z cao nhất.
• Tối đa một sự kiện được kích hoạt cho mỗi lượt nhấp. Nói cách khác, lượt nhấp không được truyền xuống các điểm đánh dấu hoặc lớp phủ khác có giá trị chỉ mục z thấp hơn.
• Việc nhấp vào một cụm điểm đánh dấu sẽ khiến các lượt nhấp tiếp theo chuyển qua cụm đó, lần lượt chọn từng điểm đánh dấu. Thứ tự của chu kỳ này ưu tiên Chỉ mục Z trước, sau đó là tương cận đến điểm nhấp.
• Nếu người dùng nhấp vào bên ngoài phạm vi lân cận của cụm, API sẽ tính toán lại cụm và đặt lại trạng thái của chu kỳ nhấp để chu kỳ đó bắt đầu từ đầu.
• Điểm đánh dấu được coi là nằm trong một nhóm chỉ mục z riêng biệt so với các lớp phủ hoặc hình dạng khác (đường nhiều đoạn, đa giác, hình tròn và/hoặc lớp phủ mặt đất), bất kể chỉ mục z của các lớp phủ khác. Nếu nhiều điểm đánh dấu, lớp phủ hoặc hình dạng được phủ lên nhau, thì sự kiện nhấp chuột sẽ được chuyển qua cụm điểm đánh dấu trước.

Sự kiện kéo điểm đánh dấu

Bạn có thể sử dụng OnMarkerDragListener để theo dõi các sự kiện kéo trên một điểm đánh dấu. Để đặt trình nghe này trên bản đồ, hãy gọi GoogleMap.setOnMarkerDragListener. Để kéo một điểm đánh dấu, người dùng phải nhấn và giữ điểm đánh dấu đó. Khi người dùng nhấc ngón tay khỏi màn hình, điểm đánh dấu sẽ vẫn ở vị trí đó. Khi một điểm đánh dấu được kéo, onMarkerDragStart(Marker) sẽ được gọi ban đầu. Trong khi điểm đánh dấu đang được kéo, onMarkerDrag(Marker) sẽ được gọi liên tục. Khi kết thúc thao tác kéo, onMarkerDragEnd(Marker) sẽ được gọi. Bạn có thể lấy vị trí của điểm đánh dấu bất cứ lúc nào bằng cách gọi Marker.getPosition().