設定 Flutter 專案

請確認您已完成「事前準備」一文所述的前置步驟，再設定 Flutter 專案。啟用計費功能並建立 API 金鑰後，即可設定要用來開發應用程式的 Flutter 專案。

步驟 1：安裝必要軟體

如要使用 Google Maps for Flutter 套件建立專案，請安裝 Flutter SDK，並設定目標平台的開發環境。詳情請參閱 Flutter 安裝指南。

步驟 2：在新專案中安裝 Google Maps for Flutter 套件

Flutter 提供 Google Maps for Flutter 套件做為外掛程式。

請建立 Flutter 專案並新增 Google 地圖外掛程式。

  1. 使用「flutter create」建立新的 Flutter 專案： 
      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!
    您的應用程式程式碼位於 google_maps_in_flutter/lib/main.dart。 如要執行應用程式，請輸入： 
      cd google_maps_in_flutter
  flutter run
    這個應用程式適用於 iOS、Android 和網頁。Google Maps SDK 目前不支援瀏覽器之外的電腦版應用程式。
  2. 將 Google Maps for Flutter 套件外掛程式加進這個專案。 
    flutter pub add google_maps_flutter
  
  Resolving dependencies...
  [Listing of dependencies elided]

  Changed 14 dependencies!

步驟 3：設定平台版本

Android

設定 Android SDK 的最低版本。

  1. 在想用的 IDE 中開啟 android/app/build.gradle 設定檔。
  2. 將 android.defaultConfig.minSdkVersion 的值變更為 21： 
      android {
    //...
    defaultConfig {
        applicationId "com.example.google_maps_in_flutter"
        minSdkVersion 21     // Set to 21
        targetSdkVersion flutter.targetSdkVersion
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }
    //...
  }
  3. 設定 defaultConfig 時，請指定您的專屬 ApplicationID。
  4. 儲存檔案，然後使用 Gradle 同步處理專案變更。

iOS

設定 iOS 平台的最低版本。

  1. 在想用的 IDE 中開啟 ios/Podfile 設定檔。
  2. 在這個 Podfile 的開頭加入以下幾行內容： 
      # Set platform to 14.0 to enable latest Google Maps SDK
  platform :ios, '14.0'

步驟 4：將 API 金鑰加進專案

您先前已按照「事前準備」的說明，為應用程式產生了 API 金鑰，現在請將金鑰加進 Flutter 專案。使用 Flutter 時，應把這個 API 金鑰加入所有目標平台：iOS、Android 和網頁。

請將以下範例中的 YOUR_API_KEY 替換成您的 API 金鑰。

Android

建議您使用 Secrets Gradle Plugin for Android 來簡化這項工作。

如要在 Google 地圖專案中安裝 Secrets Gradle Plugin for Android，請按照下列步驟操作：

  1. 在 Android Studio 中開啟頂層的 build.gradle 或 build.gradle.kts 檔案， 然後將下列程式碼加進 buildscript 下方的 dependencies 元素。

    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. 開啟模組層級的 build.gradle 檔案，然後將下列程式碼加進 plugins 元素。

    Groovy

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

    Kotlin

    plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. 在模組層級的 build.gradle 檔案中，確認 targetSdk 和 compileSdk 已設為 34。
  4. 儲存檔案，然後使用 Gradle 同步處理專案。
  5. 開啟頂層目錄中的 secrets.properties 檔案，並加入下列程式碼，然後將 YOUR_API_KEY 替換成您的 API 金鑰。 
    MAPS_API_KEY=YOUR_API_KEY
  6. 儲存檔案。
  7. 找到 AndroidManifest.xml 檔案中的 com.google.android.geo.API_KEY，並更新 android:value attribute。如果沒有 <meta-data> 標記，請以 <application> 標記子項的形式建立該標記。 
    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

  8. 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 the name of your local properties file (either local.properties or local.defaults.properties depending on how you created the project), 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.*"
}

注意事項：如上所示，API 金鑰的建議中繼資料名稱為 com.google.android.geo.API_KEY。在 Android 平台上，具有此名稱的金鑰可用來驗證多個 Google 地圖 API，包括 Flutter SDK。為了兼顧回溯相容性，API 也支援 com.google.android.maps.v2.API_KEY 這個名稱。此舊版名稱僅允許對 Android Maps API 第 2 版進行驗證。應用程式只能指定這兩種 API 金鑰中繼資料名稱的其中一個；如果同時指定兩者，API 會擲回例外狀況。

iOS

將 API 金鑰加進 AppDelegate.swift 檔案。

  1. 透過想用的 IDE，在 Flutter 專案中開啟 ios/Runner/AppDelegate.swift 檔案。
  2. 新增下列匯入陳述式，將 Google Maps for Flutter 套件加進應用程式：
    3. import GoogleMaps
  3. 在 application(_:didFinishLaunchingWithOptions:) 方法中加入 API，將 YOUR_API_KEY 換成您的 API 金鑰： 
    GMSServices.provideAPIKey("YOUR_API_KEY")
  4. 儲存並關閉 AppDelegate.swift 檔案。

完成的 AppDelegate.swift 檔案應類似下列內容：

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

網頁

將 API 金鑰加進 index.html 應用程式檔案。

  1. 透過想用的 IDE，在 Flutter 專案中開啟 web/index.html 檔案。
  2. 在 <head> 標記內加入下列指令碼標記，將 YOUR_API_KEY 換成您的 API 金鑰。 
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. 儲存並關閉 index.html 檔案。

    index.html 的整個 head 部分應類似下列內容：

        <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 src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY">
      </script>
      
      <title>google_maps_in_flutter</title>
      <link rel="manifest" href="manifest.json">
    </head>

步驟 5：新增地圖

下列程式碼示範如何在新的 Flutter 應用程式中加入簡易地圖。

  1. 透過想用的 IDE，在 Flutter 專案中開啟 lib/main.dart 檔案。
  2. 在應用程式預設的主要方法中加入或更新方法，建立及初始化 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 createState() => _MyAppState();
      }
      
      class _MyAppState extends State {
        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. 啟動要用來執行應用程式的所有模擬器或裝置。
  4. 執行您的應用程式。結果看起來應該會像這樣： 
      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"):

    請輸入您要執行的平台所對應的編號。每次叫用 flutter run 時，Flutter 都會顯示這些選項。如果您的開發系統中，沒有正在執行的模擬器或已連結的測試裝置，Flutter 應該會選擇開啟 Chrome。

    每個平台應該都會顯示以澳洲雪梨為中心的地圖。如果沒有看到地圖，請確認您是否已在正確的目標專案中加入 API 金鑰。

後續步驟

您已取得 API 金鑰並設定 Flutter 專案，接下來可以建立並執行應用程式。Google Maps for Flutter 套件提供許多教學課程和範例應用程式，可協助您快速上手。詳情請參考下列資源：