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

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

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

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

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

שלב 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.kts או build.gradle ברמה העליונה ומוסיפים את הקוד הבא לאלמנט dependencies בקטע buildscript.

Kotlin

buildscript {
    dependencies {
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}

Groovy

buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}

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

Kotlin

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

Groovy

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

בקובץ build.gradle.kts או 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, כדי שה-builds לא יכשלו אם הקובץ secrets.properties לא נמצא. מצב כזה יכול לקרות אם משכפלים את האפליקציה ממערכת בקרת גרסאות שמשמיטה את 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}" />
```
הערה: com.google.android.geo.API_KEY הוא שם המטא-נתונים המומלץ למפתח ה-API. אפשר להשתמש במפתח עם השם הזה כדי לבצע אימות במספר ממשקי API שמבוססים על מפות Google בפלטפורמת Android, כולל Flutter SDK. מטעמי תאימות לאחור, ה-API תומך גם בשם com.google.android.maps.v2.API_KEY. השם הקודם מאפשר אימות רק ל-Android Maps API v2. אפליקציה יכולה לציין רק אחד משמות המטא-נתונים של מפתח ה-API. אם מציינים את שניהם, ה-API יוצר חריגה.

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

עורכים את המאפיינים של הפלאגין כדי להגדיר את propertiesFileName לערך secrets.properties, את defaultPropertiesFileName לערך local.defaults.properties ומגדירים את כל המאפיינים האחרים.

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

Groovy

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

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

iOS

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

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

import GoogleMaps

מוסיפים את ה-API לשיטה 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>, ומחליפים את YOUR_API_KEY במפתח ה-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>

שומרים את קובץ ה-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