Kiểu bản đồ mới sắp xuất hiện trên Nền tảng Google Maps. Bản cập nhật này để tạo kiểu bản đồ bao gồm một bảng màu mặc định mới và các cải tiến về trải nghiệm bản đồ cũng như khả năng hữu dụng. Tất cả kiểu bản đồ sẽ được cập nhật tự động vào tháng 3 năm 2025. Để biết thêm thông tin về phạm vi cung cấp và cách chọn tham gia sớm hơn, hãy xem bài viết Kiểu bản đồ mới cho Nền tảng Google Maps.

Trang này được dịch bởi Cloud Translation API.

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 Khung hiển thị Google Maps cho Android Studio. Nếu bạn đã có sẵn một dự án Android Studio cần thiết lập, 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 việc phát triển 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 SDK Maps dành cho Android, bạn phải triển khai SDK này cho thiết bị Android hoặc trình mô phỏng Android dựa trên Android 4.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 trong bài viết 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 cách sử dụng Trình quản lý thiết bị Android ảo (AVD) đi kèm với Android Studio.
Lưu ý: Nếu chọn sử dụng trình mô phỏng Android, hãy đảm bảo bạn chọn thiết bị có biểu tượng Play, , hiển thị trong cột Cửa hàng Play. Biểu tượng này cho biết rằng các hồ sơ này hoàn toàn tuân thủ CTS và có thể sử dụng hình ảnh hệ thống có chứa ứng dụng Cửa hàng Play:

Tạo một 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 Android Studio sau này.

Mở Android Studio rồi nhấp vào Create New Project (Tạo dự án mới) trong cửa sổ Welcome to Android Studio (Chào mừng bạn đến với Android Studio).
Trong cửa sổ New Project (Dự án mới), thuộc 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).
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. SDK Maps dành cho Android hỗ trợ đầy đủ cả hai ngôn ngữ. Để tìm hiểu thêm về Kotlin, hãy xem nội dung 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. Bạn phải chọn một phiên bản lớn hơn phiên bản tối thiểu theo yêu cầu của SDK Maps cho Android phiên bản 18.2.x, là API Android cấp 19 ("KitKat"; Android 4.4) 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 đối với phiên bản SDK.
  
  Lưu ý: Nếu bạn không chắc nên chọn phiên bản SDK nào, hãy chọn đường liên kết Giúp tôi chọn để hiển thị thông tin phân phối cho các SDK Android được hỗ trợ. Ví dụ: nếu bạn chọn Android API cấp 19 ("KitKat"; Android 4.4), ứng dụng của bạn phải chạy trên hơn 99% số thiết bị Android.
- Đặ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 quy trình sau.
Nhấp vào Hoàn tất.

Android Studio khởi động Gradle và tạo dự án. Quá trình này có thể mất chút thời gian.
Thêm Hoạt động trên Chế độ 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 > Google > Google Maps Views Activity (Mới > Google > Hoạt động trên 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 đánh dấu Launcher Activity (Hoạt động trình chạy).
4. Chọn Finish (Hoàn tất).
  
  Để biết thêm thông tin, hãy xem phần Thêm mã từ một mẫu
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à tên bạn đã định cấu hình trong quá trình thiết lập.

Thận trọng: Tệp AndroidManifest.xml có chứa hướng dẫn về cách tải khoá API của Google Maps rồi thêm khoá đó vào tệp local.properties của bạn. Đừng thêm khoá API vào tệp local.properties. Làm như vậy sẽ lưu trữ khoá API kém an toàn hơn. Thay vào đó, hãy làm theo hướng dẫn trong bài viết Thiết lập dự án Google Cloud để tạo một dự án Google Cloud và định cấu hình khoá API.

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

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

Bước 1

Giao diện dòng lệnh

Trong Google Cloud Console, trên trang bộ chọn dự án, hãy nhấp vào Create Project (Tạo dự án) để bắt đầu tạo dự án mới trên Google Cloud.

Chuyển đến trang bộ chọn dự án
Hãy nhớ bật tính năng thanh toán cho dự án trên Google Cloud của bạn. Xác nhận rằng tính năng thanh toán đã được bật cho dự án của bạn.

Google Cloud cung cấp gói dùng thử miễn phí. Thời gian dùng thử sẽ hết hạn sau 90 ngày hoặc sau khi tài khoản đã tích luỹ được khoản phí có giá trị 300 đô la, tuỳ theo điều kiện nào đến trước. Bạn có thể huỷ bất cứ lúc nào. Nền tảng Google Maps có khoản tín dụng định kỳ 200 USD định kỳ hằng tháng. Để biết thêm thông tin, hãy xem bài viết Tín dụng cho tài khoản thanh toán và Thanh toán.

SDK đám mây

gcloud projects create "PROJECT"

Hãy đọc thêm về Google Cloud SDK , cách cài đặt SDK Cloud và các lệnh sau:

gcloud projects create

Bước 2

Để sử dụng Nền tảng Google Maps, bạn phải bật API hoặc SDK mà bạn định sử dụng với dự án của mình.

Giao diện dòng lệnh

Bật SDK Maps dành cho Android

SDK đám mây

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

Hãy đọc thêm về Google Cloud SDK , cách cài đặt SDK Cloud và các lệnh sau:

Bước 3

Bước này chỉ trải qua quy trình tạo Khoá API. Nếu sử dụng Khoá API trong phiên bản chính thức, bạn nên hạn chế khoá API của mình. Bạn có thể tìm thêm thông tin trên trang Sử dụng khoá API cho sản phẩm cụ thể.

Khoá API là giá trị nhận dạng duy nhất dùng để xác thực các yêu cầu liên kết với dự án của bạn cho mục đích sử dụng và thanh toán. Bạn phải có ít nhất một khoá API liên kết với dự án của mình.

Cách tạo khoá API:

Giao diện dòng lệnh

Truy cập trang Nền tảng Google Maps > Thông tin xác thực.

Chuyển đến trang Thông tin xác thực
Trên trang Thông tin xác thực, hãy nhấp vào Tạo thông tin xác thực > Khoá API.
Hộp thoại API key created (Khoá API đã tạo) cho thấy khoá API mới tạo.
Nhấp vào Đóng.
Khoá API mới được liệt kê trên trang Thông tin xác thực trong phần Khoá API.
(Hãy nhớ hạn chế khoá API trước khi dùng khoá này trong phiên bản phát hành công khai.)

SDK đám mây

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

Hãy đọc thêm về Google Cloud SDK , cách cài đặt SDK Cloud và các lệnh sau:

gcloud alpha services api-keys create

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 trong 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 các 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ợ Bí mật cho Gradle cho Android.

Cách cài đặt Trình bổ trợ Secrets Gradle cho Android trong dự án Google Maps:

Trong Android Studio, hãy mở tệp build.gradle hoặc build.gradle.kts cấp cao nhất rồi thêm 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")
    }
}

Mở tệp build.gradle ở cấp mô-đun và thêm mã sau vào phần tử plugins.

Groovy

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

Kotlin

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

Trong tệp build.gradle ở cấp mô-đun, hãy đảm bảo rằng targetSdk và compileSdk được đặt thành 34.
Lưu tệp và đồng bộ hoá dự án của bạn với Gradle.
Mở tệp secrets.properties trong thư mục cấp cao nhất của bạn, 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 phép kiểm tra trong một hệ thống quản lý phiên bản.
Lưu ý: Nếu tệp secrets.properties không tồn tại, hãy tạo tệp này trong cùng thư mục với tệp local.properties.
```
MAPS_API_KEY=YOUR_API_KEY
```
Lưu tệp.
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.

Lưu ý: Hãy nhập mã như minh hoạ. Đừng thay thế DEFAULT_API_KEY bằng khoá API.
```
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 của mình.
Lưu tệp.
Trong tệp AndroidManifest.xml, hãy 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 làm thẻ con của thẻ <application>.
```
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />
```
Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

Groovy

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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.*"
}

Kotlin

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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.*"
}

Nhìn vào mã

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

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

Tệp hoạt động trên bản đồ là hoạt động chính 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 của mình, MapsActivity.kt.

Các thành phần 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ẹ trong 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 chế độ xem và dữ liệu bản đồ. Đâ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 đồ sẽ 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 của 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à các chế độ cài đặt máy ảnh; chẳng hạn như góc xem, hướng bản đồ và mức thu phóng. Xem hướng dẫn về 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. Xem hướng dẫn về Điểm đánh dấu để biết thêm chi tiết.

Tệp Gradle mô-đun

Tệp mô-đun build.gradle bao gồm phần phụ thuộc bản đồ sau đây theo yêu cầu của SDK Maps dành cho Android.

dependencies {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.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 Tạo 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 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 ánh xạ.
android:name đặt tên lớp của mảnh thành SupportMapFragment, là loại mảnh được dùng trong tệp hoạt động ánh xạ.

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

Ảnh chụp màn hình với bản đồ và điểm đánh dấu nằm ở giữa trên Syndney Australia.

Khi chạy thành công, ứng dụng sẽ hiển thị một bản đồ được căn giữa là Sydney Australia 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:

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.
Khi có lời nhắc chọn 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 (Chạy trình mô phỏng) rồi chọn thiết bị ảo mà bạn đã thiết lập.
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ủa bạn. 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 đồ của 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 sẽ 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 SDK Maps dành cho Android.
Sử dụng thư viện Android KTX của Maps: 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 SDK Maps dành cho Android.