דף זה תורגם על ידי Cloud Translation API.

הגדרה של פרויקט Flutter

לפני שמגדירים פרויקט של Flutter, חשוב לוודא שהשלמתם את השלבים הנדרשים בקטע לפני שמתחילים. אחרי שמפעילים את החיוב ויוצרים מפתח API, אפשר להגדיר את הפרויקט Flutter שבו משתמשים כדי לפתח את האפליקציה.

שלב 1: מתקינים את התוכנה הנדרשת

כדי ליצור פרויקט באמצעות חבילת מפות Google ל-Flutter, צריך להתקין אתFlutter SDK ולהגדיר את סביבת הפיתוח לפלטפורמת היעד. לפרטים, קראו את מדריך ההתקנה של Fllutter.

שלב 2: התקנת החבילה של מפות Google ל-Flutter בפרויקט חדש

Flutter מציע את החבילה של מפות Google ל-Flutter כפלאגין של Flutter.

יוצרים את פרויקט Flutter ומוסיפים את הפלאגין של מפות Google.

יוצרים פרויקט חדש ב-Flutter באמצעות '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!
```
קוד האפליקציה נמצא ב-google_maps_in_flutter/lib/main.dart. כדי להפעיל את האפליקציה, מקלידים:
```
  cd google_maps_in_flutter
  flutter run
```
האפליקציה הזו מיועדת ל-iOS, ל-Android ולאינטרנט. בשלב זה, ה-SDK של מפות Google לא תומך באפליקציות למחשב מחוץ לדפדפן.

הוספת הפלאגין של חבילת מפות Google ל-Flutter לפרויקט הזה.

flutter pub add google_maps_flutter
  
  Resolving dependencies...
  [Listing of dependencies elided]

  Changed 14 dependencies!

שלב 3: מגדירים את גרסת הפלטפורמה

Android

צריך להגדיר את גרסת ה-SDK המינימלית ל-Android.

פותחים את קובץ התצורה android/app/build.gradle בסביבת הפיתוח המשולבת (IDE) הרצויה.

משנים את הערך של 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
    }
    //...
  }

במהלך ההגדרה של defaultConfig, יש לציין ApplicationID ייחודי משלך.
שומרים את הקובץ ומסנכרנים את השינויים בפרויקט עם Gradle.

iOS

להגדיר את הגרסה המינימלית של פלטפורמת iOS.

פותחים את קובץ התצורה ios/Podfile בסביבת הפיתוח המשולבת (IDE) הרצויה.

מוסיפים את השורות הבאות בתחילת ה-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 ל-Android.

כדי להתקין את הפלאגין Secrets Gradle ל-Android בפרויקט של מפות Google:

ב-Android Studio, פותחים את הקובץ build.gradle או build.gradle.kts ברמה העליונה ומוסיפים את הקוד הבא לרכיב dependencies בקטע buildscript.

מגניב

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

פותחים את הקובץ build.gradle ברמת המודול ומוסיפים את הקוד הבא לרכיב plugins.

מגניב

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

Kotlin

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

בקובץ build.gradle ברמת המודול, מוודאים ש-targetSdk ו-compileSdk מוגדרים ל-34.
שומרים את הקובץ ומסנכרנים את הפרויקט עם Gradle.
פותחים את הקובץ secrets.properties בספרייה ברמה העליונה ומוסיפים את הקוד הבא. מחליפים את YOUR_API_KEY במפתח ה-API. אפשר לאחסן את המפתח בקובץ הזה כי אין אפשרות לבדוק את secrets.properties במערכת לניהול גרסאות.
הערה: אם הקובץ secrets.properties לא קיים, צריך ליצור אותו באותה תיקייה שבה נמצא הקובץ local.properties.
```
MAPS_API_KEY=YOUR_API_KEY
```
שומרים את הקובץ.
יוצרים את הקובץ local.defaults.properties בספרייה ברמה העליונה, באותה תיקייה שבה נמצא הקובץ secrets.properties, ולאחר מכן מוסיפים את הקוד הבא.

הערה: יש להזין את הקוד כפי שמוצג. אין להחליף את DEFAULT_API_KEY במפתח ה-API.
```
MAPS_API_KEY=DEFAULT_API_KEY
```
מטרת הקובץ הזה היא לספק מיקום גיבוי למפתח ה-API אם הקובץ secrets.properties לא נמצא כדי שגרסאות build לא ייכשלו. מצב כזה יכול לקרות אם משכפלים את האפליקציה ממערכת לניהול גרסאות, ללא secrets.properties ועדיין לא יצרת קובץ secrets.properties באופן מקומי כדי לספק את מפתח ה-API.
שומרים את הקובץ.
בקובץ 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}" />
```
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.

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

הערה: כפי שצוין למעלה, com.google.android.geo.API_KEY הוא השם המומלץ של המטא-נתונים למפתח ה-API. מפתח עם השם הזה יכול לשמש לאימות במספר ממשקי API המבוססים על מפות Google בפלטפורמת Android, כולל ה-Flutter SDK. לצורך תאימות לאחור, ה-API תומך גם בשם com.google.android.maps.v2.API_KEY. השם הקודם מאפשר אימות של Android Maps API בגרסה 2 בלבד. אפליקציה יכולה לציין רק אחד משמות המטא-נתונים של מפתח ה-API. אם ציינתם את שניהם, ה-API יגרום לחריגה.

iOS

מוסיפים את מפתח ה-API לקובץ AppDelegate.swift.

פותחים את הקובץ ios/Runner/AppDelegate.swift בפרויקט Flutter עם סביבת הפיתוח המשולבת (IDE) המועדפת.
יש להוסיף את הצהרת הייבוא הבאה כדי להוסיף את חבילת Google Maps for Flutter לאפליקציה שלך:

import GoogleMaps

מוסיפים את ה-API ל-method application(_:didFinishLaunchingWithOptions:) ומחליפים את מפתח ה-API של YOUR_API_KEY:
```
GMSServices.provideAPIKey("YOUR_API_KEY")
```
שומרים וסוגרים את הקובץ 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.

פותחים את הקובץ web/index.html בפרויקט Flutter עם סביבת הפיתוח המשולבת (IDE) המועדפת.

מוסיפים את תג הסקריפט הבא בתוך התג <head>, ומחליפים את מפתח ה-API ב-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>

שומרים וסוגרים את הקובץ index.html.

קטע הhead השלם של index.html אמור להיראות כך:

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

שלב 5: הוספת מפה

הקוד הבא מדגים איך להוסיף מפה פשוטה לאפליקציה חדשה של Flutter.

פותחים את הקובץ lib/main.dart בפרויקט Flutter עם סביבת הפיתוח המשולבת (IDE) המועדפת.

כדי ליצור ולהפעיל מכונה של 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,
                ),
              ),
            ),
          );
        }
      }

הפעל אמולטורים או מכשירים שבהם ברצונך להריץ את האפליקציה.
מפעילים את האפליקציה. הפלט אמור להיראות כך:
```
  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 ל-Flutter כוללת מדריכים רבים ואפליקציות לדוגמה, שיוכלו לעזור לך להתחיל. מידע נוסף זמין במקורות המידע הבאים:

מדריך בנושא הוספת מפה באמצעות סמן
Codelabs ל-Flutter עם הפלטפורמה של מפות Google
דוגמאות קוד ב-GitHub