Konfigurowanie projektu Flutter

Zanim skonfigurujesz projekt Flutter, wykonaj 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 przy użyciu pakietu Google Maps for Flutter, musisz zainstalować pakiet SDK Fluttera i skonfigurować środowisko programistyczne pod kątem platformy docelowej. Szczegółowe informacje znajdziesz w przewodniku instalacji Fluttera.

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

Flutter udostępnia pakiet Map Google dla Fluttera jako wtyczkę Fluttera.

Utwórz projekt Fluttera i dodaj w nim wtyczkę Map.

  1. Utwórz nowy projekt Fluttera za pomocą polecenia `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!
     Twój kod aplikacji znajduje się w google_maps_in_flutter/lib/main.dart. Aby uruchomić aplikację, wpisz: 
      cd google_maps_in_flutter
  flutter run
     Ta aplikacja jest kierowana na iOS, Androida i internet. Pakiet SDK Map Google nie obsługuje obecnie aplikacji na komputery poza przeglądarką.
  2. Dodaj do tego projektu wtyczkę pakietu Mapy Google dla Fluttera. 
    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 konfiguracji android/app/build.gradle w wybranym środowisku IDE.
  2. Zmień wartość 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 swój własny unikalny ApplicationID.
  4. Zapisz plik i zsynchronizuj zmiany w projekcie z Gradle.

iOS

Ustaw minimalną wersję platformy iOS.

  1. Otwórz plik konfiguracji ios/Podfile w ulubionym środowisku IDE.
  2. Dodaj te wiersze na początku pliku Podfile: 
      # Set platform to 14.0 to enable latest Google Maps SDK
  platform :ios, '14.0'

Krok 4. Dodaj klucz interfejsu API do projektu

W sekcji Przed rozpoczęciem wygenerowałeś klucz API dla swojej aplikacji. Teraz dodaj ten klucz do projektu Flutter. W przypadku Fluttera należy dodać ten klucz interfejsu API do wszystkich platform docelowych: iOS, Android i internet.

W podanych niżej przykładach zastąp YOUR_API_KEY swoim kluczem API.

Android

Aby usprawnić to zadanie, zalecamy użycie wtyczki Gradle obiektów tajnych na Androida.

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

  1. W Android Studio otwórz najwyższy poziom pliku build.gradle.kts lub build.gradle i dodaj pod elementem buildscript kod:dependencies

    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 do elementu plugins ten kod:

    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ź, czy wartości targetSdk i compileSdk są ustawione na 34.
  4. Zapisz plik i zsynchronizuj projekt z Gradle.
  5. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a potem dodaj ten kod: Zastąp YOUR_API_KEY swoim kluczem API. Przechowuj klucz w tym pliku, ponieważ secrets.properties nie jest uwzględniany 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, czyli w tym samym folderze co plik secrets.properties, a potem dodaj podany niżej kod.

    MAPS_API_KEY=DEFAULT_API_KEY

    Ten plik stanowi kopię zapasową klucza interfejsu API na wypadek, gdyby nie udało się znaleźć plikusecrets.properties, dzięki czemu kompilacje nie będą się załamywać. Może się tak zdarzyć, jeśli skopiujesz aplikację z systemu kontroli wersji, który pomija plik secrets.properties, a na komputerze lokalnym nie masz jeszcze utworzonego pliku secrets.properties, aby podać 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: com.google.android.geo.API_KEY to zalecane nazwa metadanych klucza interfejsu API. Klucza o tej nazwie można używać do uwierzytelniania w wielu interfejsach API opartych na Mapach Google na platformie Androida, w tym w pakiecie Flutter SDK. Ze względu na zgodność wsteczną interfejs API obsługuje też nazwę com.google.android.maps.v2.API_KEY. Ten starszy identyfikator umożliwia uwierzytelnianie tylko w ramach interfejsu Mapy Google na Androida w wersji 2. Aplikacja może podać tylko jedną z nazwy metadanych klucza interfejsu API. Jeśli podasz obie wartości, interfejs API zwróci wyjątek.

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

    Zmień właściwości wtyczki, aby ustawić wartość propertiesFileName na secrets.properties, wartość defaultPropertiesFileName na local.defaults.properties i ustawić inne 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.*"
}

Uwaga: jak widać powyżej,com.google.android.geo.API_KEY to zalecana nazwa metadanych dla klucza API. Klucza o tej nazwie można używać do uwierzytelniania w wielu interfejsach API opartych na Mapach Google na platformie Androida, w tym w pakiecie Flutter SDK. Ze względu na zgodność wsteczną interfejs API obsługuje też nazwę com.google.android.maps.v2.API_KEY. Ta starsza nazwa umożliwia uwierzytelnianie tylko w ramach interfejsu Mapy Google na Androida w wersji 2. Aplikacja może podać tylko jedną nazwę metadanych klucza interfejsu API. Jeśli podasz obie wartości, interfejs API zwróci wyjątek.

iOS

Dodaj klucz interfejsu API do pliku AppDelegate.swift.

  1. Otwórz plik ios/Runner/AppDelegate.swift w projekcie Fluttera za pomocą ulubionego środowiska IDE.
  2. Aby dodać do aplikacji pakiet Google Maps for Flutter, dodaj tę instrukcję importu:
    3. import GoogleMaps
  3. Dodaj interfejs API do metody application(_:didFinishLaunchingWithOptions:), zastępując YOUR_API_KEY kluczem interfejsu API: 
    GMSServices.provideAPIKey("YOUR_API_KEY")
  4. Zapisz i zamknij plik AppDelegate.swift.

Wypełniony plik AppDelegate.swift powinien wyglądać tak:

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)
  }
}

Sieć

Dodaj klucz interfejsu API do pliku aplikacji index.html.

  1. Otwórz plik web/index.html w projekcie Fluttera w wybranym środowisku IDE.
  2. Dodaj ten tag skryptu w tagu <head>, zastępując YOUR_API_KEY swoim kluczem interfejsu API. 
    <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.

    Cała sekcja head w pliku 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 Fluttera w wybranym środowisku IDE.
  2. Dodaj lub zaktualizuj metody w domyślnej metodzie głównej aplikacji, aby utworzyć i inicjializować wystąpienie klasy 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 wszystkie emulatory lub urządzenia, na których chcesz uruchomić aplikację.
  4. Uruchom aplikację. Powinny się wyświetlić 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 uruchomić test. Za każdym razem, gdy wywołasz flutter run, Flutter wyświetla te opcje. Jeśli na Twoim systemie deweloperskim nie ma uruchomionego emulatora ani podłączonego urządzenia testowego, Flutter powinien otworzyć Chrome.

    Każda platforma powinna wyświetlać mapę wyśrodkowaną na Sydney w Australii. Jeśli nie widzisz mapy, sprawdź, czy klucz API został dodany do odpowiedniego projektu docelowego.

Dalsze kroki

Teraz, gdy masz klucz interfejsu API i projekt Fluttera, możesz tworzyć i uruchamiać aplikacje. Pakiet Map Google dla Fluttera zawiera wiele samouczków i przykładowych aplikacji, które pomogą Ci zacząć. Aby dowiedzieć się więcej, zapoznaj się z tymi materiałami: