Konfigurowanie projektu Flutter

Zanim skonfigurujesz projekt Flutter, musisz wykonać czynności wstępne opisane w sekcji Zanim zaczniesz. Po włączeniu płatności i utworzeniu klucza interfejsu API możesz skonfigurować projekt Flutter, którego używasz do tworzenia aplikacji.

Krok 1. Zainstaluj wymagane oprogramowanie

Aby utworzyć projekt, korzystając z pakietu Map Google dla Flutter, musisz zainstalować pakiet SDK Flutter i skonfigurować środowisko programistyczne pod kątem platformy docelowej. Szczegółowe informacje znajdziesz w przewodniku instalacji Flutter.

Krok 2. Zainstaluj pakiet Map Google dla Flutter w nowym projekcie

Flutter oferuje pakiet Map Google dla Flutter w postaci wtyczki Flutter.

Utwórz projekt Flutter i dodaj wtyczkę Maps.

  1. Utwórz nowy projekt Flutter za pomocą funkcji „flutter create”: 
      flutter create google_maps_in_flutter --platforms=android,ios,web
  
  Creating project google_maps_in_flutter...
  [Listing of created files elided]
  Wrote 127 files.

  All done!
    Kod Twojej aplikacji znajduje się w języku google_maps_in_flutter/lib/main.dart. Aby uruchomić swoją aplikację, wpisz: 
      cd google_maps_in_flutter
  flutter run
    Ta aplikacja jest kierowana na iOS, Androida i internet. Obecnie pakiet SDK Map Google nie obsługuje aplikacji komputerowych działających poza przeglądarką.
  2. Dodaj do tego projektu wtyczkę pakietu Mapy Google dla Flutter. 
    flutter pub add google_maps_flutter
  
  Resolving dependencies...
  [Listing of dependencies elided]

  Changed 14 dependencies!

Krok 3. Ustaw wersję platformy

Android

Ustaw minimalną wersję pakietu SDK na Androida.

  1. Otwórz plik konfiguracyjny android/app/build.gradle w preferowanym IDE.
  2. Zmień wartość z android.defaultConfig.minSdkVersion na 21: 
      android {
    //...
    defaultConfig {
        applicationId "com.example.google_maps_in_flutter"
        minSdkVersion 21     // Set to 21
        targetSdkVersion flutter.targetSdkVersion
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }
    //...
  }
  3. Podczas konfigurowania defaultConfig podaj własny unikalny identyfikator ApplicationID.
  4. Zapisz plik i zsynchronizuj zmiany w projekcie za pomocą Gradle.

iOS

Ustaw minimalną wersję platformy iOS.

  1. Otwórz plik konfiguracyjny ios/Podfile w preferowanym IDE.
  2. Dodaj następujące wiersze na początku tego pliku Podfile: 
      # Set platform to 14.0 to enable latest Google Maps SDK
  platform :ios, '14.0'

Krok 4. Dodaj do projektu klucz interfejsu API

W sekcji Zanim zaczniesz udało Ci się wygenerować klucz interfejsu API dla aplikacji. Teraz dodaj ten klucz do projektu Flutter. W przypadku Flutter dodaj ten klucz interfejsu API do wszystkich platform docelowych: iOS, Android i Web.

W poniższych przykładach zastąp YOUR_API_KEY swoim kluczem interfejsu API.

Android

Aby uprościć to zadanie, zalecamy korzystanie z wtyczki Gradle obiektów tajnych na Androida.

Aby zainstalować wtyczkę Secrets Gradle na Androida w projekcie Map Google:

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

    Zakręcony

    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 modułu i dodaj do elementu plugins poniższy kod.

    Zakręcony

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

    Kotlin

    plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. W pliku build.gradle na poziomie modułu sprawdź, czy targetSdk i compileSdk mają wartość 34.
  4. Zapisz plik i zsynchronizuj projekt z Gradle.
  5. Otwórz plik secrets.properties w katalogu najwyższego poziomu i dodaj ten kod. Zastąp YOUR_API_KEY swoim kluczem interfejsu API. Zapisz klucz w tym pliku, ponieważ adres secrets.properties nie jest rejestrowany w systemie kontroli wersji. 
    MAPS_API_KEY=YOUR_API_KEY
  6. Zapisz plik.

  7. Utwórz plik local.defaults.properties w katalogu najwyższego poziomu, w tym samym folderze co plik secrets.properties, a następnie dodaj poniższy kod.

    MAPS_API_KEY=DEFAULT_API_KEY

    Ten plik służy do podania lokalizacji kopii zapasowej klucza interfejsu API na wypadek, gdyby nie udało się znaleźć pliku secrets.properties, co pozwoli uniknąć błędów kompilacji. Może się tak zdarzyć, jeśli sklonujesz aplikację z systemu kontroli wersji, który pomija element secrets.properties, i nie utworzyłeś jeszcze lokalnie pliku secrets.properties zawierającego Twój klucz interfejsu API.

  8. Zapisz plik.
  9. W pliku AndroidManifest.xml przejdź do 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}" />

    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 Flutter SDK. 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.

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

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 Androida, m.in. w pakiecie Flutter SDK. Aby zapewnić 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ślić tylko jedną nazwę metadanych klucza interfejsu API. Jeśli podasz oba, interfejs API zgłosi wyjątek.

iOS

Dodaj klucz interfejsu API do pliku AppDelegate.swift.

  1. Otwórz plik ios/Runner/AppDelegate.swift w projekcie Flutter w preferowanym IDE.
  2. Dodaj poniższe polecenie importu, aby dodać pakiet Map Google dla Flutter do aplikacji:
    3. import GoogleMaps
  3. Dodaj interfejs API do metody application(_:didFinishLaunchingWithOptions:), zastępując klucz interfejsu API wartością YOUR_API_KEY: 
    GMSServices.provideAPIKey("YOUR_API_KEY")
  4. Zapisz i zamknij plik AppDelegate.swift.

Gotowy plik AppDelegate.swift powinien przypominać ten:

import UIKit
import Flutter
import GoogleMaps  // Add this import

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)

    // TODO: Add your Google Maps API key
    GMSServices.provideAPIKey("YOUR_API_KEY")

    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

Web

Dodaj klucz interfejsu API do pliku aplikacji index.html.

  1. Otwórz plik web/index.html w projekcie Flutter w preferowanym IDE.
  2. Dodaj podany niżej tag skryptu do tagu <head>, zastępując klucz interfejsu API wartością YOUR_API_KEY. 
    <script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>
  3. Zapisz i zamknij plik index.html.

    Pełna sekcja head dokumentu index.html powinna wyglądać mniej więcej tak:

        <head>
      <base href="/">
      
      <meta charset="UTF-8">
      <meta content="IE=Edge" http-equiv="X-UA-Compatible">
      <meta name="description" content="A new Flutter project.">
      
      <!-- iOS meta tags & icons -->
      <meta name="apple-mobile-web-app-capable" content="yes">
      <meta name="apple-mobile-web-app-status-bar-style" content="black">
      <meta name="apple-mobile-web-app-title" content="google_maps_in_flutter">
      <link rel="apple-touch-icon" href="icons/Icon-192.png">
      
      <script>
        (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
          key: "YOUR_API_KEY",
          v: "weekly",
          // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
          // Add other bootstrap parameters as needed, using camel case.
          });
      </script>
      
      <title>google_maps_in_flutter</title>
      <link rel="manifest" href="manifest.json">
    </head>

Krok 5. Dodaj mapę

Poniższy kod pokazuje, jak dodać prostą mapę do nowej aplikacji Flutter.

  1. Otwórz plik lib/main.dart w projekcie Flutter w preferowanym IDE.
  2. Dodaj lub zaktualizuj metody w domyślnej głównej metodzie aplikacji, aby utworzyć i zainicjować instancję mapController. 
          import 'package:flutter/material.dart';
      import 'package:google_maps_flutter/google_maps_flutter.dart';
      
      void main() => runApp(const MyApp());
      
      class MyApp extends StatefulWidget {
        const MyApp({super.key});
      
        @override
        State<MyApp> createState() => _MyAppState();
      }
      
      class _MyAppState extends State<MyApp> {
        late GoogleMapController mapController;
      
        final LatLng _center = const LatLng(-33.86, 151.20);
      
        void _onMapCreated(GoogleMapController controller) {
          mapController = controller;
        }
      
        @override
        Widget build(BuildContext context) {
          return MaterialApp(
            home: Scaffold(
              appBar: AppBar(
                title: const Text('Maps Sample App'),
                backgroundColor: Colors.green[700],
              ),
              body: GoogleMap(
                onMapCreated: _onMapCreated,
                initialCameraPosition: CameraPosition(
                  target: _center,
                  zoom: 11.0,
                ),
              ),
            ),
          );
        }
      }
  3. Uruchom emulatory lub urządzenia, na których chcesz uruchomić aplikację.
  4. Uruchom aplikację. Zostaną wyświetlone dane wyjściowe podobne do tych: 
      flutter run

   
    Multiple devices found:
    Android phone (mobile) • emulator-5554 • android-arm64  • Android 13 (API 33) (emulator)
    iPhone (mobile)  • ios • com.apple.CoreSimulator.SimRuntime.iOS-16-2 (simulator)
    Chrome (web) • chrome • web-javascript • Google Chrome 108.0.5359.124
    [1]: Android phone
    [2]: iPhone
    [3]: Chrome
    
    Please choose one (To quit, press "q/Q"):

    Wpisz numer platformy, na której chcesz działać. Przy każdym wywołaniu funkcji flutter run Flutter wyświetli te opcje. Jeśli w Twoim systemie programistycznym nie ma uruchomionego emulatora ani podłączonego urządzenia testowego, Flutter powinien uruchomić Chrome.

    Na każdej platformie powinna być wyświetlana mapa środkowana na Sydney w Australii. Jeśli nie widzisz mapy, sprawdź, czy klucz interfejsu API został dodany do odpowiedniego projektu docelowego.

Dalsze kroki

Gdy masz już klucz interfejsu API i projekt Flutter, możesz tworzyć i uruchamiać aplikacje. Pakiet Map Google dla Flutter zawiera wiele samouczków i przykładowych aplikacji, które pomogą Ci zacząć. Więcej informacji znajdziesz w tych materiałach: