Pakiet SDK Map na Androida – krótkie wprowadzenie

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

Ten krótki przewodnik jest przeznaczony dla deweloperów, którzy znają podstawy programowania na Androidzie w języku Java lub Kotlin.

Skonfiguruj środowisko programistyczne

1. Wymagany jest Android Studio Arctic Fox lub nowszy. Pobierz i zainstaluj, jeśli jeszcze jej nie masz.
2. Upewnij się, że używasz wtyczki Android Gradle w wersji 7.0 lub nowszej w Android Studio.

• Aby korzystać z urządzenia z Androidem, wykonaj czynności opisane w artykule Uruchamianie aplikacji na urządzeniu sprzętowym.
• Aby użyć emulatora Androida, możesz utworzyć urządzenie wirtualne i zainstalować emulator za pomocą Menedżera urządzeń wirtualnych Android dostępnego w Android Studio.

Tworzenie projektu Map Google w Android Studio

1. Otwórz Android Studio i kliknij Utwórz nowy projekt w oknie Witamy w Android Studio.

2. W oknie Nowy projekt, w kategorii Telefon i tablet wybierz Aktywność w Mapach Google i kliknij Dalej.

3. Wypełnij formularz Aktywności w Mapach Google.

   • Ustaw Język na Java lub Kotlin. Pakiet SDK Map na Androida w pełni obsługuje oba języki. Aby dowiedzieć się więcej o Kotlinie, przeczytaj artykuł o tworzeniu aplikacji na Androida na platformie Kotlin.

   • Ustaw Minimalny pakiet SDK na wersję SDK zgodną z Twoim urządzeniem testowym. Musisz wybrać wersję wyższą niż minimalna wymagana przez pakiet SDK Map na Androida w wersji 18.0.x, która obecnie jest interfejsem API na poziomie 19 (Android 4.4, KitKat) lub nowszym. Najnowsze informacje o wymaganiach wersji pakietu SDK znajdziesz w informacjach o wersji.

4. Kliknij Zakończ.

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

5. Gdy kompilacja się zakończy, Android Studio otwiera pliki AndroidManifest.xml i MapsActivity. Twoja aktywność może mieć inną nazwę, ale będzie to ta, która została przez Ciebie skonfigurowana podczas konfiguracji.

6. Plik AndroidManifest.xml zawiera instrukcje, jak uzyskać klucz interfejsu API Map Google, a następnie dodać go do pliku local.property. Nie dodawaj klucza interfejsu API do pliku AndroidManifest.xml. W ten sposób Twój klucz API jest bezpieczniejszy. Zamiast tego wykonaj czynności opisane w kolejnych sekcjach, aby utworzyć projekt Cloud i skonfigurować klucz interfejsu API.

Konfigurowanie projektu Google Cloud

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

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"

Dodaj klucz interfejsu API do swojej aplikacji

W tej sekcji dowiesz się, jak przechowywać klucz interfejsu API, aby można było bezpiecznie odwoływać się do niego przez aplikację. Zalecamy niesprawdzanie klucza interfejsu API w systemie kontroli wersji, dlatego zalecamy przechowywanie go w pliku local.properties, który znajduje się w katalogu głównym projektu. Więcej informacji o pliku local.properties znajdziesz w artykule Pliki właściwości Gradle.

Aby uprościć to zadanie, zalecamy użycie wtyczki Gradle obiektów tajnych na Androida. Aby zainstalować wtyczkę i zapisać klucz interfejsu API:

1. W Android Studio otwórz plik build.gradle na poziomie projektu i dodaj ten kod do elementu dependencies w sekcji buildscript.

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

2. Następnie otwórz plik build.gradle na poziomie modułu i dodaj ten kod do elementu plugins.

   id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
       

3. Zapisz plik i zsynchronizuj projekt z Gradle.
4. Otwórz local.properties w katalogu na poziomie projektu i dodaj ten kod. Zastąp YOUR_API_KEY kluczem interfejsu API.

   MAPS_API_KEY=YOUR_API_KEY
       

5. Zapisz plik.
6. W pliku AndroidManifest.xml otwórz stronę com.google.android.geo.API_KEY i zaktualizuj android:value attribute w ten sposób:

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

Uwaga: jak pokazano powyżej, 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 również w pakiecie Maps SDK na Androida. Aby zapewnić zgodność wsteczną, interfejs API obsługuje też nazwę com.google.android.maps.v2.API_KEY. Ta nazwa starszego typu 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 podasz obie opcje, interfejs API zwróci wyjątek.

Zobacz kod

Sprawdź kod podany w szablonie. Zwróć szczególną uwagę na te pliki w projekcie Android Studio.

Plik aktywności Map Google

Plik aktywności z mapami jest główną aktywnością aplikacji i zawiera kod do zarządzania mapą i jej wyświetlania. Domyślnie plik definiujący aktywność ma nazwę MapsActivity.java lub jeśli dla Twojej aplikacji ustawiony jest język Kotlin (MapsActivity.kt).

Główne elementy działań na mapach:

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

• Obiekt GoogleMap zapewnia dostęp do danych mapy i widoku. To jest główna klasa pakietu SDK Map na Androida. Przewodnik Obiekty mapy zawiera szczegółowy opis obiektów SupportMapFragment i GoogleMap.

• Funkcja moveCamera wyśrodkowuje mapę na współrzędnych LatLng w Sydney Australia. Pierwszymi ustawieniami, które należy skonfigurować podczas dodawania mapy, są zwykle lokalizacja i ustawienia kamery, takie jak kąt patrzenia, orientacja mapy i poziom powiększenia. Szczegółowe informacje znajdziesz w przewodniku po aparacie i widoku.

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

Plik aktywności map zawiera ten kod:

import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     *
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        // Add a marker in Sydney and move the camera
        LatLng sydney = new LatLng(-34, 151);
        mMap.addMarker(new MarkerOptions()
                .position(sydney)
                .title("Marker in Sydney"));
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
    }
}

      

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

        // Add a marker in Sydney and move the camera
        val sydney = LatLng(-34.0, 151.0)
        mMap.addMarker(MarkerOptions()
            .position(sydney)
            .title("Marker in Sydney"))
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
    }
}

      

Plik Gradle modułu

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

dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.1.0'
    // ...
}

Aby dowiedzieć się więcej o zarządzaniu zależnościami w Mapach, przeczytaj Informacje o 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 następujące elementy:

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

Plik układu XML zawiera ten kod:

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

Wdrażanie i uruchamianie aplikacji

Po uruchomieniu aplikacji wyświetli się mapa wyśrodkowana na Sydney Australia ze znacznikiem miasta, tak jak na tym zrzucie ekranu.

Aby wdrożyć i uruchomić aplikację:

1. W Android Studio kliknij opcję 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 połączone z komputerem.
   • Możesz też zaznaczyć opcję Uruchom emulator i wybrać skonfigurowane urządzenie wirtualne.
3. Kliknij OK. Android Studio uruchomi Gradle w celu skompilowania aplikacji, a następnie wyświetli wyniki na urządzeniu lub w emulatorze. Może minąć kilka minut, zanim aplikacja zostanie uruchomiona.

Dalsze kroki

• Konfigurowanie mapy: w tym artykule dowiesz się, jak skonfigurować ustawienia początkowe i wykonawcze, takie jak pozycja kamery, typ mapy, komponenty interfejsu i gesty.

• Dodaj mapę do aplikacji na Androida (Kotlin): w ramach tych ćwiczeń z programowania poznasz niektóre funkcje pakietu SDK Map Google na Androida.

• Skorzystaj z biblioteki Map KTX Map na Androida: w bibliotece rozszerzeń Kotlin możesz korzystać z kilku funkcji językowych Kotlin, korzystając z pakietu SDK Map na Androida.