Thêm bản đồ 3D vào ứng dụng

Chọn nền tảng: Android iOS JavaScript

Bản đồ 3D cho thấy Thành phố New York

Trang này trình bày ví dụ về cách thêm bản đồ 3D cơ bản vào một ứng dụng Android bằng SDK Maps 3D dành cho Android. Hướng dẫn trên trang này giả định rằng bạn đã hoàn tất các bước trên trang Thiết lập và có những thông tin sau:

  • Một dự án trên đám mây của Google Cloud đã bật SDK Maps 3D dành cho Android
  • Khoá API được định cấu hình để sử dụng với SDK Maps 3D dành cho Android
  • Một dự án Android Studio được thiết lập để sử dụng với SDK Maps 3D dành cho Android

Để biết thêm thông tin về các điều kiện tiên quyết này, hãy xem phần Thiết lập.

Phần 1: Cập nhật tệp bố cục (activity_main.xml) để thêm thành phần Map3DView

Thành phần Map3DView là khung hiển thị kết xuất bản đồ 3D trong ứng dụng. Các bước sau đây sẽ thêm thành phần và định cấu hình trạng thái ban đầu của bản đồ, bao gồm cả vị trí camera và các thuộc tính liên quan:

  1. Mở tệp bố cục của hoạt động chính, thường nằm tại app/src/main/res/layout/activity_main.xml.

  2. Trong ConstraintLayout gốc (hoặc phần tử bố cục gốc), hãy thêm không gian tên XML map3d:

    xmlns:map3d="http://schemas.android.com/apk/res-auto"

  3. Xoá <TextView> mặc định hiển thị "Hello World!".

  4. Thêm thành phần Map3DView vào bố cục. Bạn có thể tuỳ chỉnh vị trí camera và các thuộc tính khác:

    <?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  xmlns:map3d="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools"
  android:id="@+id/main"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  tools:context=".MainActivity">

  <com.google.android.gms.maps3d.Map3DView
    android:id="@+id/map3dView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    map3d:mapMode="hybrid"
    map3d:centerLat="38.544012"
    map3d:centerLng="-107.670428"
    map3d:centerAlt="2427.6"
    map3d:heading="310"
    map3d:tilt="63"
    map3d:range="8266"
    map3d:roll="0"
    map3d:minAltitude="0"
    map3d:maxAltitude="1000000"
    map3d:minHeading="0"
    map3d:maxHeading="360"
    map3d:minTilt="0"
    map3d:maxTilt="90"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent" />
</androidx.constraintlayout.widget.ConstraintLayout>

Phần 2: Cập nhật MainActivity.kt

Các bước sau đây sẽ khởi chạy thành phần Map3DView được thêm vào tệp activity_main.xml trong Phần 1 và quản lý các sự kiện trong vòng đời của thành phần.

Xin lưu ý rằng SDK Maps 3D dành cho Android chỉ hỗ trợ một phiên bản Map3DView đang hoạt động tại một thời điểm. Việc hiển thị nhiều phiên bản Map3DView cùng lúc (ví dụ: trong cùng một bố cục hoặc các Hoạt động hoặc Mảnh hiển thị khác nhau) không được hỗ trợ và có thể dẫn đến các vấn đề về kết xuất, chẳng hạn như màn hình đen trên các khung hiển thị phụ.

Hơn nữa, tất cả Map3DView sẽ chia sẻ và phản ánh cùng một trạng thái bản đồ (ví dụ: vị trí camera, điểm đánh dấu đã thêm, đa giác, v.v.). Trạng thái này sẽ vẫn tồn tại ngay cả khi một Map3DView bị huỷ (bằng cách sử dụng onDestroy) và một khác được tạo, trừ phi bị xoá theo cách thủ công. Ví dụ: nếu bạn thêm điểm đánh dấu vào Map3DView1, sau đó huỷ điểm đánh dấu đó và tạo Map3DView2, thì các điểm đánh dấu đó vẫn sẽ xuất hiện trên Map3DView2.

Trách nhiệm của nhà phát triển:

  • Mỗi lần một khung hiển thị: Đảm bảo chỉ có một Map3DView nằm trong phần đang hoạt động của hệ phân cấp view tại bất kỳ thời điểm nào.
  • Dọn dẹp theo cách thủ công: Khi chuyển từ một Map3DView (ví dụ: Map3DView1) sang một khác (ví dụ: Map3DView2), bạn phải gọi onDestroy() trên phiên bản cũ (Map3DView1). Vì trạng thái bản đồ cơ bản được chia sẻ, để đảm bảo Map3DView2 bắt đầu bằng một trạng thái mới hoặc cụ thể, bạn phải tự chịu trách nhiệm xoá mọi trạng thái do Map3DView1 đặt. Việc này bao gồm xoá điểm đánh dấu, lớp phủ, v.v. và đặt lại vị trí camera bằng đối tượng GoogleMap3D thu được trong OnMap3DViewReadyCallback.

  1. Mở tệp MainActivity.kt, thường nằm ở app/src/main/java/com/example/yourpackagename/MainActivity.kt.

  2. Thêm các lệnh nhập cần thiết cho SDK Maps 3D dành cho Android:

    import android.util.Log
import com.google.android.gms.maps3d.GoogleMap3D
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.OnMap3DViewReadyCallback

  3. Sửa đổi lớp MainActivity để triển khai OnMap3DViewReadyCallback:

    class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {

  4. Khai báo các biến cho Map3DView và GoogleMap3D:

    private lateinit var map3DView: Map3DView
private var googleMap3D: GoogleMap3D? = null

  5. Trong phương thức onCreate, sau setContentView(...) và khối ViewCompat.setOnApplyWindowInsetsListener, hãy khởi chạy map3DView, gọi phương thức vòng đời onCreate và yêu cầu bản đồ không đồng bộ:

    override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    setContentView(R.layout.activity_main)
    ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
        val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
        v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
        insets
    }

    map3DView = findViewById(R.id.map3dView)
    map3DView.onCreate(savedInstanceState)
    map3DView.getMap3DViewAsync(this)
}

  6. Ghi đè các phương thức onMap3DViewReady và onError. Các lệnh gọi lại này được kích hoạt khi bản đồ đã sẵn sàng để sử dụng hoặc khi xảy ra lỗi trong quá trình khởi chạy:

    override fun onMap3DViewReady(googleMap3D: GoogleMap3D) {
    // Interact with the googleMap3D object here
    this.googleMap3D = googleMap3D
    // You can now make calls to the googleMap3D object, e.g.,
    // googleMap3D.flyTo(camera { ... })
}

override fun onError(error: Exception) {
    // Handle the error gracefully here (for example, show an error dialog or log the error).
    Log.e("MainActivity", "Error loading 3D map", error)
}

  7. Chuyển tiếp các sự kiện trong vòng đời từ Hoạt động của bạn đến Map3DView bằng cách thêm các phương thức ghi đè sau vào MainActivity:

    override fun onStart() {
    super.onStart()
    map3DView.onStart()
}

override fun onResume() {
    super.onResume()
    map3DView.onResume()
}

override fun onPause() {
    map3DView.onPause()
    super.onPause()
}

override fun onStop() {
    map3DView.onStop()
    super.onStop()
}

override fun onDestroy() {
    map3DView.onDestroy()
    super.onDestroy()
}

override fun onSaveInstanceState(outState: Bundle) {
    super.onSaveInstanceState(outState)
    map3DView.onSaveInstanceState(outState)
}

override fun onLowMemory() {
    super.onLowMemory()
    map3DView.onLowMemory()
}

Phần 3: Đồng bộ hoá Gradle và chạy

Giờ đây, khi đã cập nhật bố cục và hoạt động của ứng dụng, bạn có thể tạo và chạy ứng dụng để xem chế độ xem bản đồ 3D.

  1. Để đồng bộ hoá dự án với Gradle, hãy chọn File > Sync Project with Gradle Files (Tệp > Đồng bộ hoá dự án với các tệp Gradle).

  2. Để tạo và chạy ứng dụng trên trình mô phỏng hoặc thiết bị thực, hãy chọn Run > Run (Chạy > Chạy).

Nếu mọi thứ được định cấu hình chính xác, bạn sẽ thấy một bản đồ 3D xuất hiện trong ứng dụng của mình, được đặt ở gần toạ độ mà bạn chỉ định trong activity_main.xml.

Trạng thái lỗi và trạng thái tải bản đồ

SDK Maps 3D dành cho Android tự động hiển thị phản hồi trực quan tích hợp sẵn trong khi quản lý trạng thái của bản đồ:

  • Lớp phủ đang tải: Chỉ báo tiến trình ở giữa sẽ xuất hiện khi chế độ xem bản đồ được khởi chạy lần đầu hoặc đang tải khung nhìn ban đầu.
  • Lớp phủ lỗi: Thẻ lỗi được tạo kiểu sẽ xuất hiện nếu xảy ra lỗi nghiêm trọng, chẳng hạn như khoá API không hợp lệ, lỗi mạng hoặc khi chạy trên thiết bị không được hỗ trợ.

Bạn có thể nắm bắt những lỗi khởi chạy hoặc tải này theo cách lập trình bằng cách ghi đè onError(error: Exception) trong quá trình triển khai OnMap3DViewReadyCallback.

Lắng nghe sự kiện nhấp chuột vào bản đồ

Để theo dõi các sự kiện nhấp chuột trên bản đồ, hãy gọi setMap3DClickListener trên GoogleMap3D. Khi người dùng nhấp vào bản đồ, lệnh gọi lại onMap3DClick sẽ nhận được một đối tượng Map3DClickEvent cung cấp location và placeId của điểm đã nhấp, đồng thời trả về một Boolean (true để ẩn tiện ích mặc định trong giao diện người dùng Places hoặc false để hiện tiện ích đó). Để biết thêm thông tin, hãy xem bài viết Tương tác với địa điểm yêu thích.

Ví dụ sau đây cho thấy cách thiết lập trình theo dõi lượt nhấp trên bản đồ:

googleMap3D.setMap3DClickListener { event: Map3DClickEvent ->
    Log.d(
        "MainActivity",
        "Clicked at ${event.location}, placeId: ${event.placeId}"
    )
    false
}

Các bước tiếp theo

Giờ đây, khi đã thêm bản đồ 3D cơ bản vào ứng dụng, bạn có thể khám phá thêm các tính năng nâng cao của Maps 3D SDK cho Android, chẳng hạn như ảnh động đường đi của camera, điểm đánh dấu 3D hoặc đa giác.