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

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

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 ו-Web.

בדוגמאות הבאות, מחליפים את הערך 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 אם הקובץ 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}" />
```
הערה: 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 עם סביבת הפיתוח המשולבת המועדפת עליכם.
יש להוסיף את הצהרת הייבוא הבאה כדי להוסיף לאפליקציה את חבילת מפות Google עבור 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