לפני ההגדרה של פרויקט Flutter, צריך לוודא שהשלמת את הדרישות המוקדמות בקטע לפני שמתחילים. אחרי הפעלה חיוב וליצור מפתח API, אפשר להגדיר את פרויקט Flutter שבו משתמשים לפתח את האפליקציה.
שלב 1: מתקינים את התוכנה הנדרשת
כדי לבנות פרויקט באמצעות חבילת מפות Google ל-Flutter, צריך להתקין את Flutter SDK והגדרה של סביבת הפיתוח לפלטפורמת היעד. כדאי לנסות את התקנת Flutter מדריך לפרטים.
שלב 2: מתקינים את החבילה של מפות Google ל-Flutter בפרויקט חדש
Flutter מציעה את חבילת מפות Google for 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
-
הוספת הפלאגין של חבילת 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 ואינטרנט.
בדוגמאות הבאות, מחליפים את 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
לא נכלל בבדיקה לניהול גרסאות המערכת.MAPS_API_KEY=YOUR_API_KEY
- שומרים את הקובץ.
-
יוצרים את הקובץ
local.defaults.properties
בספרייה שברמה העליונה, אותה לתיקייה בתור הקובץsecrets.properties
, ואז מוסיפים את הקוד הבא.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 namecom.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.kts
orbuild.gradle
file and edit thesecrets
property. If thesecrets
property does not exist, add it.Edit the properties of the plugin to set
propertiesFileName
tosecrets.properties
, setdefaultPropertiesFileName
tolocal.defaults.properties
, and set any other 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 גרסה 2. האפליקציה יכולה לציין רק אחד משמות המטא-נתונים של מפתח ה-API. אם מציינים את שניהם, ה-API ויוצרת חריגה.iOS
מוסיפים את מפתח ה-API לקובץ
AppDelegate.swift
.- פותחים את הקובץ
ios/Runner/AppDelegate.swift
בפרויקט Flutter עם סביבת הפיתוח המשולבת המועדפת עליכם. - יש להוסיף את הצהרת הייבוא הבאה כדי להוסיף לאפליקציה את חבילת מפות Google עבור Flutter:
- מוסיפים את ה-API ל-method
application(_:didFinishLaunchingWithOptions:)
, תוך החלפת מפתח ה-API ב-YOUR_API_KEY:GMSServices.provideAPIKey("YOUR_API_KEY")
- שומרים וסוגרים את הקובץ
AppDelegate.swift
.
import GoogleMaps
הקובץ
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 עם סביבת הפיתוח המשולבת המועדפת עליכם. - מוסיפים את תג הסקריפט הבא בתוך התג
<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 עם סביבת הפיתוח המשולבת המועדפת עליכם. - כדי ליצור ולהפעיל מופע של
mapController
, צריך להוסיף או לעדכן methods בשיטה הראשית של האפליקציה שמוגדרת כברירת מחדל.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 with Google Maps Platform
- דוגמאות קוד ב-GitHub
- פותחים את הקובץ
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2024-09-05 (שעון UTC).