Krótkie wprowadzenie do Maps SDK na Androida

Utwórz aplikację na Androida, która wyświetla mapę, korzystając z szablonu widoków Map Google w Android Studio. Jeśli masz już projekt w Android Studio, który chcesz skonfigurować, przeczytaj artykuł Konfigurowanie projektu w Android Studio.

Ten dokument jest przeznaczony dla deweloperów, którzy znają podstawy tworzenia aplikacji na Androida w Kotlinie lub Javie.

Informacje o środowisku programistycznym

Ten dokument został opracowany przy użyciu Android Studio Hedgehog i wtyczki Androida do obsługi Gradle w wersji 8.2.

Konfigurowanie urządzenia z Androidem

Aby uruchomić aplikację korzystającą z pakietu Maps SDK na Androida, musisz wdrożyć ją na urządzeniu z Androidem lub emulatorze Androida , który jest oparty na Androidzie 6.0 lub nowszym i zawiera interfejsy API Google.

• Aby używać urządzenia z Androidem, postępuj zgodnie z instrukcjami w artykule Uruchamianie aplikacji na urządzeniu fizycznym.
• Aby używać emulatora Androida, możesz utworzyć urządzenie wirtualne i zainstalować emulator za pomocą menedżera urządzenia wirtualnego z Androidem (AVD) który jest częścią Android Studio.

Tworzenie projektu Map Google w Android Studio

Procedura tworzenia projektu Map Google w Android Studio została zmieniona w wersji Flamingo i nowszych.

1. Otwórz Android Studio i w oknie Welcome to Android Studio (Witamy w Android Studio) kliknij New Project (Nowy projekt).

2. W oknie New Project w kategorii Phone and Tablet wybierz No Activity, a następnie kliknij Next.

3. Wypełnij formularz New Project (Nowy projekt):

   • Ustaw Language (Język) na Java lub Kotlin. Oba języki są w pełni obsługiwane przez pakiet Maps SDK na Androida. Więcej informacji o Kotlinie znajdziesz w artykule Tworzenie aplikacji na Androida w Kotlinie.

   • Ustaw Minimum SDK (Minimalny pakiet SDK) na wersję pakietu SDK zgodną z urządzeniem testowym. Musisz wybrać wersję nowszą niż minimalna wersja wymagana przez pakiet Maps SDK na Androida w wersji 20.0.x, czyli poziom interfejsu API Androida 23 („Marshmallow”; Android 6.0) lub nowszy. Najnowsze informacje o wymaganiach dotyczących wersji pakietu SDK znajdziesz w informacjach o wersji.

   • Ustaw Build configuration language (Język konfiguracji kompilacji) na Kotlin DSL lub Groovy DSL. W kolejnych procedurach znajdziesz fragmenty kodu w obu językach konfiguracji kompilacji.

4. Kliknij Zakończ.

   Android Studio uruchomi Gradle i utworzy projekt. Może to chwilę potrwać.

5. Dodaj Google Maps Views Activity (Aktywność widoków Map Google):

   1. Kliknij prawym przyciskiem myszy folder app w projekcie.

   2. Wybierz New > Google > Google Maps Views Activity (Nowy > Google > Aktywność widoków Map Google).

      

   3. W oknie New Android Activity (Nowa aktywność Androida) zaznacz pole wyboru Launcher Activity (Aktywność uruchamiająca).

   4. Kliknij Zakończ.

      Więcej informacji znajdziesz w artykule Dodawanie kodu z szablonu.

6. Po zakończeniu kompilacji Android Studio otworzy pliki AndroidManifest.xml i MapsActivity. Twoja aktywność może mieć inną nazwę, ale jest to ta, którą skonfigurowano podczas instalacji.

Konfigurowanie projektu Google Cloud

Wykonaj wymagane czynności konfiguracyjne w konsoli Cloud, klikając te karty:

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"

Dodawanie klucza interfejsu API do aplikacji

W tej sekcji opisujemy, jak przechowywać klucz interfejsu API, aby aplikacja mogła się do niego bezpiecznie odwoływać. Nie należy dodawać klucza interfejsu API do systemu kontroli wersji, dlatego zalecamy przechowywanie go w pliku secrets.properties, który znajduje się w katalogu głównym projektu. Więcej informacji o pliku secrets.properties znajdziesz w Pliki właściwości Gradle.

Aby uprościć to zadanie, zalecamy używanie wtyczki Gradle obiektów tajnych na Androida .

Aby zainstalować wtyczkę Gradle obiektów tajnych na Androida i zapisać klucz interfejsu API:

1. W Android Studio otwórz plik build.gradle na poziomie głównym i dodaj ten kod do elementu dependencies w sekcji 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. Otwórz plik build.gradle na poziomie aplikacji i dodaj ten kod do elementu 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. Jeśli używasz Android Studio, zsynchronizuj projekt z Gradle.
4. Otwórz plik local.properties w katalogu na poziomie projektu, a następnie dodaj ten kod. Zastąp YOUR_API_KEY swoim kluczem interfejsu API.

   MAPS_API_KEY=YOUR_API_KEY

5. W pliku AndroidManifest.xml przejdź do com.google.android.geo.API_KEY i zaktualizuj atrybut android:value w ten sposób:

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

   Uwaga: com.google.android.geo.API_KEY to zalecana nazwa metadanych klucza interfejsu API. Klucz o tej nazwie może służyć do uwierzytelniania w wielu interfejsach API opartych na Mapach Google na platformie Android, w tym w pakiecie Maps SDK na Androida. Aby zachować zgodność wsteczną, interfejs API obsługuje też nazwę com.google.android.maps.v2.API_KEY. Ta starsza nazwa umożliwia uwierzytelnianie tylko w interfejsie Android Maps API w wersji 2. Aplikacja może określać tylko jedną z nazw metadanych klucza interfejsu API. Jeśli określono obie nazwy, interfejs API zgłosi wyjątek.

Sprawdzanie kodu

Sprawdź kod dostarczony przez szablon. W szczególności przyjrzyj się tym plikom w projekcie Android Studio.

Plik aktywności w Mapach

Plik aktywności w Mapach to główna aktywność aplikacji, która zawiera kod do zarządzania mapą i jej wyświetlania. Domyślnie plik definiujący aktywność ma nazwę MapsActivity.java lub MapsActivity.kt, jeśli jako język aplikacji ustawisz Kotlin.

Główne elementy aktywności w Mapach:

• Obiekt SupportMapFragment zarządza cyklem życia mapy i jest elementem nadrzędnym interfejsu aplikacji.

• Obiekt GoogleMap zapewnia dostęp do danych mapy i widoku. Jest to główna klasa pakietu Maps SDK na Androida. Więcej informacji o obiektach SupportMapFragment i GoogleMap znajdziesz w przewodniku Obiekty mapy.

• Funkcja moveCamera wyśrodkowuje mapę na współrzędnych LatLng dla Sydney w Australii. Pierwsze ustawienia, które należy skonfigurować podczas dodawania mapy, to zwykle lokalizacja mapy i ustawienia kamery, takie jak kąt widzenia, orientacja mapy i poziom powiększenia. Więcej informacji znajdziesz w przewodniku Kamera i widok.

• Funkcja addMarker dodaje znacznik do współrzędnych dla Sydney. Więcej informacji znajdziesz w przewodniku Znaczniki.

Plik Gradle modułu

Plik build.gradle.kts modułu zawiera tę zależność map, która jest wymagana przez pakiet Maps SDK na Androida.

dependencies {

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

Więcej informacji o zarządzaniu zależnością Map znajdziesz w artykule Obsługa wersji.

Plik układu XML

Plik activity_maps.xml to plik układu XML, który definiuje strukturę interfejsu aplikacji. Plik znajduje się w katalogu res/layout. Plik activity_maps.xml deklaruje fragment, który zawiera te elementy:

• tools:context ustawia domyślną aktywność fragmentu na MapsActivity, która jest zdefiniowana w pliku aktywności w Mapach.
• android:name ustawia nazwę klasy fragmentu na SupportMapFragment, czyli typ fragmentu używany w pliku aktywności w Mapach.

Plik układu XML zawiera ten kod:

<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" />

Wdrażanie i uruchamianie aplikacji

Po pomyślnym uruchomieniu aplikacja wyświetli mapę wyśrodkowaną na Sydney w Australii ze znacznikiem w tym mieście, jak widać na tym zrzucie ekranu.

Aby wdrożyć i uruchomić aplikację:

1. W Android Studio kliknij opcję menu Run (Uruchom) (lub ikonę przycisku odtwarzania), aby uruchomić aplikację.
2. Gdy pojawi się prośba o wybranie urządzenia, wybierz jedną z tych opcji:
   • Wybierz urządzenie z Androidem podłączone do komputera.
   • Możesz też kliknąć opcję Launch emulator (Uruchom emulator) i wybrać skonfigurowane urządzenie wirtualne.
3. Kliknij OK. Android Studio uruchomi Gradle, aby utworzyć aplikację, a następnie wyświetli wyniki na urządzeniu lub emulatorze. Uruchomienie aplikacji może potrwać kilka minut.

Dalsze kroki

• Konfigurowanie mapy: w tym dokumencie opisujemy, jak skonfigurować ustawienia początkowe i środowiska wykonawczego mapy, takie jak pozycja kamery, typ mapy, komponenty interfejsu i gesty.

• Dodawanie mapy do aplikacji na Androida (Kotlin): w tym ćwiczeniu w Codelabs dowiesz się, jak korzystać z aplikacji, która demonstruje niektóre dodatkowe funkcje pakietu Maps SDK na Androida.

• Korzystanie z biblioteki Maps Android KTX: ta biblioteka rozszerzeń Kotlin (KTX) umożliwia korzystanie z kilku funkcji języka Kotlin podczas używania pakietu Maps SDK na Androida.