Krótkie wprowadzenie do Maps SDK na Androida

Stwórz aplikację dla Androida wyświetlającą mapę, korzystając ze Zdjęć w Mapach Google dla Android Studio. Jeśli masz już projekt w Android Studio, które chcesz skonfigurować, przeczytaj artykuł Konfigurowanie projektu Android Studio.

To krótkie wprowadzenie jest przeznaczone dla programistów znających Programowanie na Androida w języku Kotlin lub Java.

Informacje o środowisku programistycznym

To krótkie wprowadzenie zostało opracowane w Android Studio Jeż i Android Wtyczka Gradle wersji 8.2.

Konfigurowanie urządzenia z Androidem

Aby uruchomić aplikację, która korzysta z pakietu Maps SDK na Androida, musisz ją wdrożyć na urządzeniu z Androidem lub na urządzeniu z Androidem emulator oparty na Androidzie 5.0 lub nowszym i obejmuje interfejsów API Google.

• Aby użyć urządzenia z Androidem, postępuj zgodnie z instrukcjami na stronie Uruchamianie aplikacji na urządzeniu
• Aby użyć emulatora Androida, możesz utworzyć urządzenie wirtualne i zainstalować emulator za pomocą: Menedżer urządzeń wirtualnych z Androidem (AVD), dostępne w Android Studio.

Tworzenie projektu Map Google w Android Studio

Procedura tworzenia projektu Map Google w Android Studio została zmieniona w Flamingo i nowsze wersje Android Studio.

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

2. W oknie New Project (Nowy projekt) w kategorii Phone and Tablet (Telefon i tablet) wybierz Brak aktywności i kliknij Dalej.

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

   • Ustaw Język na Java lub Kotlin. Oba języki są w pełni obsługiwane przez SDK Maps na Androida. Więcej informacji o Kotlin znajdziesz na stronie Tworzenie aplikacji na Androida za pomocą Kotlin

   • Ustaw Minimalny pakiet SDK na wersję pakietu SDK zgodną z urządzeniem testowym. Musisz wybrać wersję wyższą niż minimalna wersja wymagana przez Maps SDK na Androida w wersji 19.0.x, – Android API poziomu 21 („Lollipop”; Android 5.0) lub nowszy. Zapoznaj się z informacjami o wersji Najnowsze informacje o wymaganiach dotyczących wersji pakietu SDK.

   • Jako Język konfiguracji kompilacji ustaw Kotlin DSL lub Groovy DSL. Fragmenty obu języków konfiguracji kompilacji są wyświetlane poniżej procedur.

4. Kliknij Zakończ.

   Android Studio uruchamia Gradle i kompiluje projekt. Może to chwilę potrwać.

5. Dodaj Aktywność związaną z zdjęciami w Mapach Google:

   1. Kliknij prawym przyciskiem myszy folder app w projekcie.

   2. Wybierz Nowy > Google > Aktywność związana z Zdjęciami w Mapach Google.

      

   3. W oknie Nowa aktywność na Androidzie wybierz Aktywność programu uruchamiającego.

   4. Wybierz Zakończ.

      Więcej informacji: Dodawanie kodu z szablonu

6. Po zakończeniu kompilacji Android Studio otwiera okno AndroidManifest.xml i MapsActivity plików. Aktywność może mieć inną nazwę, ale to adres skonfigurowany podczas konfiguracji.

Skonfiguruj projekt Google Cloud

Zakończ wymagane czynności konfiguracyjne Cloud Console, klikając na tych kartach:

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"

Dodawanie klucza interfejsu API do aplikacji

W tej sekcji opisano, jak zapisać klucz interfejsu API, aby umożliwić bezpieczne korzystanie z niego do aplikacji. Nie sprawdzaj klucza interfejsu API w systemie kontroli wersji, dlatego zalecamy i przechowywanie go w pliku secrets.properties, który znajduje się w katalogu głównym instancji w projektach AI. Więcej informacji o pliku secrets.properties znajdziesz tutaj: Pliki właściwości Gradle.

Aby usprawnić to zadanie, zalecamy skorzystanie z Wtyczka Gradle obiektów tajnych na Androida.

Aby zainstalować wtyczkę Gradle obiektów tajnych na Androida w projekcie Map Google:

1. W Android Studio otwórz build.gradle.kts lub build.gradle najwyższego poziomu. i dodaj ten kod do elementu dependencies pod buildscript

   Kotlin

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

   Zakręcony

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

2. Otwórz plik build.gradle.kts lub build.gradle na poziomie modułu i dodaj ten kod do elementu plugins.

   Kotlin

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

   Zakręcony

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

3. W pliku build.gradle.kts lub build.gradle na poziomie modułu sprawdź, że wartości targetSdk i compileSdk są ustawione do 34.
4. Zapisz plik i zsynchronizować projekt z Gradle.
5. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a następnie dodaj atrybut tego kodu. Zastąp YOUR_API_KEY swoim kluczem interfejsu API. Przechowuj klucz w tym pliku ponieważ secrets.properties nie jest sprawdzany w kontroli wersji systemu.

   MAPS_API_KEY=YOUR_API_KEY

6. Zapisz plik.

7. Utwórz plik local.defaults.properties w katalogu najwyższego poziomu, tak samo jako plik secrets.properties, a potem dodaj podany niżej kod.

   MAPS_API_KEY=DEFAULT_API_KEY

   Ten plik ma na celu udostępnienie zapasowej lokalizacji klucza interfejsu API, jeśli plik Nie znaleziono pliku secrets.properties, więc kompilacje nie zawierają błędów. Może się tak zdarzyć, jeśli: sklonujesz aplikację z systemu kontroli wersji, który pomija secrets.properties oraz nie utworzyłeś jeszcze lokalnie pliku secrets.properties, który umożliwi przesyłanie klucz interfejsu API.

8. Zapisz plik.
9. W pliku AndroidManifest.xml otwórz com.google.android.geo.API_KEY i zaktualizuj android:value attribute. Jeśli tag <meta-data> nie istnieje, utwórz go jako element podrzędny tagu <application>.

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

   Uwaga: Zalecana nazwa metadanych to com.google.android.geo.API_KEY dla klucza interfejsu API. Klucz o tej nazwie może być używany do uwierzytelniania w wielu Interfejsy API oparte na Mapach Google na platformie Android, w tym Maps SDK na Androida. Aby zapewnić zgodność wsteczną, interfejs API obsługuje nazwę com.google.android.maps.v2.API_KEY. To dziedzictwo name umożliwia uwierzytelnianie tylko dla interfejsu Android Maps API v2. Aplikacja może określać tylko jedną z nazw metadanych klucza interfejsu API. Jeśli określono oba te parametry, zgłasza wyjątek.

10. W Android Studio otwórz build.gradle.kts na poziomie modułu lub build.gradle i edytuj właściwość secrets. Jeśli Właściwość secrets nie istnieje. Dodaj ją.

    Edytuj właściwości wtyczki, aby ustawić propertiesFileName na secrets.properties, ustaw defaultPropertiesFileName na local.defaults.properties i ustaw pozostałe właściwości.

    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.*"
    }
            

    Zakręcony

    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.*"
    }
            

Spójrz na kod

Sprawdź kod w szablonie. W szczególności zwróć uwagę na te kwestie: w projekcie Android Studio.

Plik aktywności w Mapach

Plik aktywności w Mapach jest główną aktywnością w aplikacji. który zawiera kod służący do zarządzania mapą i jej wyświetlania. Domyślnie plik zdefiniowane jest działanie o nazwie MapsActivity.java lub jeśli ustawisz Kotlin jako język Twojej aplikacji: MapsActivity.kt.

Główne elementy aktywności związanej z mapami:

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

• Obiekt GoogleMap zapewnia dostęp do danych mapy i widok. To jest główna klasa pakietu SDK Maps na Androida. Obiekty mapy Przewodnik opisuje obiekty SupportMapFragment i GoogleMap w bardziej szczegóły.

• Funkcja moveCamera wyśrodkowuje mapę na Współrzędne LatLng dla Sydney Australia. Pierwsze ustawienia skonfigurować podczas dodawania mapy to zwykle lokalizacja na mapie i ustawienia aparatu; takie jak kąt patrzenia, orientacja mapy i poziom powiększenia. Zobacz Przewodnik po aparacie i widoku zawiera szczegółowe informacje.

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

Plik Gradle modułu

Plik modułu build.gradle.kts zawiera następującą zależność map, która: jest wymagany przez pakiet Maps SDK na Androida.

dependencies {

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

Aby dowiedzieć się więcej o zarządzaniu zależnością Map, przeczytaj artykuł na temat obsługi wersji.

Plik układu XML

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

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

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

Wdróż i uruchom aplikację

Po uruchomieniu aplikacji wyświetli się mapa wyśrodkowana na Sydney Australia ze znacznikiem na mieście, jak widać na poniższym zrzucie ekranu.

Aby wdrożyć i uruchomić aplikację:

1. W Android Studio kliknij w menu opcję Uruchom (lub ikonę przycisku odtwarzania), aby uruchom 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ż zaznaczyć opcję Uruchom emulator, a potem kliknąć skonfigurowanego przez Ciebie urządzenia wirtualnego.
3. Kliknij OK. Android Studio uruchomi Gradle, aby utworzyć aplikację, a następnie i wyświetlaj wyniki na urządzeniu lub w emulatorze. Aplikacja może uruchomić się po kilku minutach nowych funkcji.

Dalsze kroki

• Skonfiguruj mapę: ten dokument opisuje sposób konfigurowania początkowych i czasowych ustawień mapy, takich jak takie jak pozycja kamery, typ mapy, komponenty interfejsu i gesty.

• Dodawanie mapy do aplikacji na Androida (Kotlin): to ćwiczenie z programowania opisuje aplikację prezentującą dodatkowe funkcje Maps SDK na Androida.

• Użyj biblioteki Map KTX na Androida: Ta biblioteka rozszerzeń Kotlin (KTX) pozwala korzystać z funkcje językowe Kotlin podczas korzystania z pakietu Maps SDK na Androida.