Hướng dẫn nhanh về SDK Bản đồ dành cho Android

Tạo một ứng dụng Android hiển thị bản đồ bằng cách sử dụng mẫu Chế độ xem Google Maps cho Android Studio. Nếu bạn có một dự án Android Studio hiện có mà bạn muốn thiết lập, hãy xem bài viết Thiết lập dự án Android Studio.

Hướng dẫn bắt đầu nhanh này dành cho những nhà phát triển đã quen thuộc với việc phát triển ứng dụng Android cơ bản bằng Kotlin hoặc Java.

Giới thiệu về môi trường phát triển

Hướng dẫn bắt đầu nhanh này được phát triển bằng Android Studio Hedgehog và trình bổ trợ Android cho Gradle phiên bản 8.2.

Thiết lập thiết bị Android

Để chạy một ứng dụng sử dụng Maps SDK cho Android, bạn phải triển khai ứng dụng đó trên một thiết bị Android hoặc Trình mô phỏng Android dựa trên Android 5.0 trở lên và có chứa các API của Google.

• Để sử dụng thiết bị Android, hãy làm theo hướng dẫn tại Chạy ứng dụng trên thiết bị phần cứng.
• Để sử dụng Trình mô phỏng Android, bạn có thể tạo một thiết bị ảo và cài đặt trình mô phỏng bằng Trình quản lý thiết bị Android ảo (AVD) đi kèm với Android Studio.

Tạo dự án Google Maps trong Android Studio

Quy trình tạo dự án Google Maps trong Android Studio đã thay đổi trong Flamingo và các bản phát hành sau này của Android Studio.

1. Mở Android Studio rồi nhấp vào New Project (Dự án mới) trong cửa sổ Welcome to Android Studio (Chào mừng bạn đến với Android Studio).

2. Trong cửa sổ New Project (Dự án mới), trong danh mục Phone and Tablet (Điện thoại và máy tính bảng), hãy chọn No Activity (Không có hoạt động) rồi nhấp vào Next (Tiếp theo).

3. Hoàn tất biểu mẫu New Project (Dự án mới):

   • Đặt Language (Ngôn ngữ) thành Java hoặc Kotlin. Cả hai ngôn ngữ đều được Maps SDK cho Android hỗ trợ đầy đủ. Để tìm hiểu thêm về Kotlin, hãy xem bài viết Phát triển ứng dụng Android bằng Kotlin.

   • Đặt Minimum SDK (SDK tối thiểu) thành phiên bản SDK tương thích với thiết bị thử nghiệm của bạn. Bạn phải chọn một phiên bản lớn hơn phiên bản tối thiểu mà Maps SDK cho Android phiên bản 20.0.x yêu cầu, đó là Android API cấp độ 21 ("Lollipop"; Android 5.0) trở lên. Hãy xem Ghi chú phát hành để biết thông tin mới nhất về các yêu cầu về phiên bản SDK.

   • Đặt Build configuration language (Ngôn ngữ cấu hình bản dựng) thành Kotlin DSL hoặc Groovy DSL. Đoạn mã cho cả hai ngôn ngữ cấu hình bản dựng đều được trình bày trong các quy trình sau.

4. Nhấp vào Hoàn tất.

   Android Studio sẽ khởi động Gradle và tạo dự án. Quá trình này có thể mất chút thời gian.

5. Thêm Google Maps Views Activity (Hoạt động chế độ xem Google Maps):

   1. Nhấp chuột phải vào thư mục app trong dự án.

   2. Chọn New > Google > Google Maps Views Activity (Mới > Google > Hoạt động chế độ xem Google Maps).

      

   3. Trong hộp thoại New Android Activity (Hoạt động Android mới), hãy chọn hộp kiểm Launcher Activity (Hoạt động trình chạy).

   4. Chọn Hoàn tất.

      Để biết thêm thông tin, hãy xem bài viết Thêm mã từ một mẫu

6. Khi quá trình tạo bản dựng hoàn tất, Android Studio sẽ mở các tệp AndroidManifest.xml và MapsActivity. Hoạt động của bạn có thể có tên khác, nhưng đó là hoạt động mà bạn đã định cấu hình trong quá trình thiết lập.

Thiết lập dự án trên đám mây của bạn

Hoàn tất các bước thiết lập bắt buộc trên bảng điều khiển Cloud bằng cách nhấp vào các thẻ sau:

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Thêm khoá API vào ứng dụng

Phần này mô tả cách lưu trữ khoá API để ứng dụng của bạn có thể tham chiếu một cách an toàn. Bạn không nên kiểm tra khoá API vào hệ thống quản lý phiên bản. Vì vậy, bạn nên lưu trữ khoá API trong tệp secrets.properties nằm trong thư mục gốc của dự án. Để biết thêm thông tin về tệp secrets.properties, hãy xem bài viết Tệp thuộc tính Gradle.

Để đơn giản hoá tác vụ này, bạn nên sử dụng Trình bổ trợ Secrets Gradle cho Android.

Cách cài đặt Trình bổ trợ Secrets Gradle cho Android và lưu trữ khoá API:

1. Trong Android Studio, hãy mở tệp build.gradle ở cấp gốc rồi thêm đoạn mã sau vào phần tử dependencies trong buildscript.

   Groovy

   buildscript {
       dependencies {
           // ...
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           // ...
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

2. Mở tệp build.gradle ở cấp ứng dụng rồi thêm đoạn mã sau vào phần tử plugins.

   Groovy

   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

3. Nếu bạn sử dụng Android Studio, hãy đồng bộ hoá dự án với Gradle.
4. Mở local.properties trong thư mục cấp dự án, sau đó thêm đoạn mã sau. Thay thế YOUR_API_KEY bằng khoá API.

   MAPS_API_KEY=YOUR_API_KEY

5. Trong tệp AndroidManifest.xml, hãy chuyển đến com.google.android.geo.API_KEY rồi cập nhật thuộc tính android:value như sau:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
       

   Lưu ý: com.google.android.geo.API_KEY là tên siêu dữ liệu được đề xuất cho khoá API. Bạn có thể sử dụng khoá có tên này để xác thực cho nhiều API dựa trên Google Maps trên nền tảng Android, bao gồm cả Maps SDK cho Android. Để tương thích ngược, API này cũng hỗ trợ tên com.google.android.maps.v2.API_KEY. Tên cũ này chỉ cho phép xác thực cho Android Maps API phiên bản 2. Một ứng dụng chỉ có thể chỉ định một trong các tên siêu dữ liệu khoá API. Nếu cả hai đều được chỉ định, thì API sẽ gửi một ngoại lệ.

Xem mã

Kiểm tra mã do mẫu cung cấp. Cụ thể, hãy xem các tệp sau trong dự án Android Studio.

Tệp hoạt động trên Maps

Tệp hoạt động trên Maps là hoạt động chính activity của ứng dụng và chứa mã để quản lý và hiển thị bản đồ. Theo mặc định, tệp xác định hoạt động có tên là MapsActivity.java hoặc nếu bạn đặt Kotlin làm ngôn ngữ cho ứng dụng, thì tệp đó có tên là MapsActivity.kt.

Các phần tử chính của hoạt động trên Maps:

• Đối tượng SupportMapFragment quản lý vòng đời của bản đồ và là phần tử mẹ của giao diện người dùng của ứng dụng.

• Đối tượng GoogleMap cung cấp quyền truy cập vào dữ liệu và chế độ xem bản đồ. Đây là lớp chính của Maps SDK cho Android. Hướng dẫn Đối tượng bản đồ mô tả chi tiết hơn về các đối tượng SupportMapFragment và GoogleMap.

• Hàm moveCamera căn giữa bản đồ tại toạ độ LatLng cho Sydney, Úc. Các chế độ cài đặt đầu tiên cần định cấu hình khi thêm bản đồ thường là vị trí bản đồ và chế độ cài đặt máy ảnh; chẳng hạn như góc nhìn, hướng bản đồ và mức thu phóng. Hãy xem hướng dẫn Máy ảnh và chế độ xem để biết thông tin chi tiết.

• Hàm addMarker thêm một điểm đánh dấu vào toạ độ cho Sydney. Hãy xem hướng dẫn Điểm đánh dấu để biết thông tin chi tiết.

Tệp Gradle mô-đun

Tệp Mô-đun build.gradle.kts bao gồm phần phụ thuộc bản đồ sau đây, đây là phần phụ thuộc mà Maps SDK cho Android yêu cầu.

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

Để tìm hiểu thêm về cách quản lý phần phụ thuộc Maps, hãy xem bài viết Kiểm soát phiên bản.

Tệp bố cục XML

Tệp activity_maps.xml là tệp bố cục XML xác định cấu trúc của giao diện người dùng của ứng dụng. Tệp này nằm trong thư mục res/layout. Tệp activity_maps.xml khai báo một fragment bao gồm các phần tử sau:

• tools:context đặt hoạt động mặc định của fragment thành MapsActivity, được xác định trong tệp hoạt động trên Maps.
• android:name đặt tên lớp của fragment thành SupportMapFragment, đây là loại fragment được dùng trong tệp hoạt động trên Maps.

Tệp bố cục XML chứa đoạn mã sau:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

Triển khai và chạy ứng dụng

Khi bạn chạy ứng dụng thành công, ứng dụng sẽ hiển thị một bản đồ được căn giữa ở Sydney, Úc với một điểm đánh dấu trên thành phố như trong ảnh chụp màn hình sau.

Cách triển khai và chạy ứng dụng:

1. Trong Android Studio, hãy nhấp vào tuỳ chọn trình đơn Run (Chạy) (hoặc biểu tượng nút phát) để chạy ứng dụng.
2. Khi được nhắc chọn một thiết bị, hãy chọn một trong các lựa chọn sau:
   • Chọn thiết bị Android được kết nối với máy tính của bạn.
   • Ngoài ra, hãy chọn nút chọn Launch emulator (Khởi chạy trình mô phỏng) rồi chọn thiết bị ảo mà bạn đã thiết lập.
3. Nhấp vào OK. Android Studio sẽ khởi động Gradle để tạo ứng dụng của bạn, sau đó hiển thị kết quả trên thiết bị hoặc trình mô phỏng. Có thể mất vài phút trước khi ứng dụng khởi chạy.

Các bước tiếp theo

• Thiết lập bản đồ: Tài liệu này mô tả cách thiết lập các chế độ cài đặt ban đầu và thời gian chạy cho bản đồ, chẳng hạn như vị trí máy ảnh, loại bản đồ, thành phần giao diện người dùng và cử chỉ.

• Thêm bản đồ vào ứng dụng Android (Kotlin): Lớp học lập trình này hướng dẫn bạn cách sử dụng một ứng dụng minh hoạ một số tính năng bổ sung của Maps SDK cho Android.

• Sử dụng thư viện Maps Android KTX: Thư viện tiện ích Kotlin (KTX) này cho phép bạn tận dụng một số tính năng ngôn ngữ Kotlin trong khi sử dụng Maps SDK cho Android.