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 muốn thiết lập một dự án Android Studio hiện có, hãy xem phần Thiết lập dự án Android Studio.

Hướng dẫn bắt đầu nhanh này dành cho các nhà phát triển đã quen với các Phát triển Android 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à Android Trình bổ trợ 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 SDK Maps 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à bao gồm 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 thiết bị ảo và cài đặt trình mô phỏng bằng cách sử dụ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 đã được thay đổi trong Flamingo và các bản phát hành Android Studio sau này.

1. Mở Android Studio rồi nhấp vào New Project (Dự án mới) trong Cửa sổ 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), 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 hỗ trợ đầy đủ bởi SDK bản đồ dành cho Android. Để tìm hiểu thêm về Kotlin, hãy xem Phát triển ứng dụng Android bằng Kotlin.

   • Đặt Minimum SDK (SDK tối thiểu) thành một 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à SDK Bản đồ dành cho Android phiên bản 19.0.x, là API Android cấp 21 ("Lollipop"; Android 5.0) trở lên. Hãy xem phần Ghi chú phát hành để thông tin mới nhất về yêu cầu đối với 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 được hiển thị 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 Hoạt động xem trên Google Maps:

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

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

      

   3. Trong hộp thoại New Android Activity (Hoạt động Android mới), chọn Hộp đánh dấu launcher Activity (Hoạt động của trình chạy).

   4. Chọn Finish (Hoàn tất).

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

6. Khi 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à thẻ mà bạn đã định cấu hình trong quá trình thiết lập.

Thiết lập dự án Google Cloud

Hoàn thành các bước thiết lập Cloud Console bắt buộc bằng cách nhấp vào thông qua các thẻ sau:

gcloud projects create "PROJECT"

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

gcloud alpha 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 khoá đó 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á đó 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 phần 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 trong dự án Google Maps:

1. Trong Android Studio, hãy mở tệp build.gradle.kts hoặc build.gradle cấp cao nhất và thêm mã sau vào phần tử dependencies trong buildscript.

   Kotlin

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

   Groovy

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

2. Mở tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun rồi thêm mã sau đây vào phần tử plugins.

   Kotlin

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

   Groovy

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

3. Trong tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun, hãy đảm bảo rằng bạn đặt targetSdk và compileSdk thành 34.
4. Lưu tệp và đồng bộ hoá dự án với Gradle.
5. Mở tệp secrets.properties trong thư mục cấp cao nhất, sau đó thêm mã sau. Thay thế YOUR_API_KEY bằng khoá API. Lưu trữ khoá của bạn trong tệp này vì secrets.properties không được đưa vào hệ thống quản lý phiên bản.

   MAPS_API_KEY=YOUR_API_KEY

6. Lưu tệp.

7. Tạo tệp local.defaults.properties trong thư mục cấp cao nhất, cùng thư mục với tệp secrets.properties, sau đó thêm mã sau.

   MAPS_API_KEY=DEFAULT_API_KEY

   Mục đích của tệp này là cung cấp vị trí sao lưu cho khoá API nếu không tìm thấy tệp secrets.properties để các bản dựng không bị lỗi. Điều này có thể xảy ra nếu bạn sao chép ứng dụng từ một hệ thống quản lý phiên bản, trong đó bỏ qua secrets.properties và bạn chưa tạo tệp secrets.properties cục bộ để cung cấp Khoá API.

8. Lưu tệp.
9. Trong tệp AndroidManifest.xml, chuyển đến com.google.android.geo.API_KEY rồi cập nhật android:value attribute. Nếu thẻ <meta-data> không tồn tại, hãy tạo thẻ này dưới dạng thẻ con của thẻ <application>.

   <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ể dùng khoá có tên này để xác thực với nhiều API dựa trên Google Maps trên nền tảng Android, bao gồm cả SDK Maps cho Android. Để có khả năng tương thích ngược, API cũng hỗ trợ tên com.google.android.maps.v2.API_KEY. Kiểu cũ này tên chỉ cho phép xác thực API Android Maps v2. Một ứng dụng có thể chỉ định một trong các tên siêu dữ liệu khoá API. Nếu bạn chỉ định cả hai, API sẽ gửi một ngoại lệ.

10. Trong Android Studio, hãy mở tệp build.gradle.kts hoặc build.gradle ở cấp mô-đun và chỉnh sửa thuộc tính secrets. Nếu thuộc tính secrets không tồn tại, hãy thêm thuộc tính này.

    Chỉnh sửa các thuộc tính của trình bổ trợ để đặt propertiesFileName thành secrets.properties, đặt defaultPropertiesFileName thành local.defaults.properties và đặt bất kỳ thuộc tính nào khác.

    Kotlin

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Groovy

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

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 bản đồ là hoạt động chính của ứng dụng và chứa mã để quản lý cũng như 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 MapsActivity.kt nếu bạn đặt Kotlin làm ngôn ngữ cho ứng dụng.

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 bản đồ và chế độ xem. Đây là lớp chính của SDK Bản đồ dành cho Android. Hướng dẫn về Đối tượng bản đồ mô tả chi tiết hơn về đối tượng SupportMapFragment và GoogleMap.

• Hàm moveCamera căn giữa bản đồ ở LatLng toạ độ cho Sydney, Úc. Chế độ cài đặt đầu tiên để định cấu hình khi thêm bản đồ thường là cài đặt vị trí bản đồ và máy ảnh; như góc nhìn, hướng bản đồ và mức thu phóng. Xem Hướng dẫn về Camera 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. Xem hướng dẫn về Đ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 ánh xạ sau, đó là là yêu cầu của SDK bản đồ dành cho Android.

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

Để tìm hiểu thêm về cách quản lý phần phụ thuộc Maps, hãy xem nội dung Versioning (Lập 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 mảnh bao gồm các phần tử sau:

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

Tệp bố cục XML chứa 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 thành công ứng dụ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 đây.

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 của bạn.
2. Khi được nhắc chọn thiết bị, hãy chọn một trong các tuỳ chọn sau:
   • Chọn thiết bị Android đã 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 (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 đó cho thấy kết quả trên thiết bị hoặc trình mô phỏng. Có thể mất vài phút thì ứng dụng mới 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ài đặt ban đầu và thời gian chạy cho bản đồ của bạn, chẳng hạn như 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 qua một ứng dụng minh hoạ một số tính năng bổ sung của SDK Bản đồ dành cho Android.

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