قبل إعداد مشروع Flutter، تأكَّد من إكمال الشرط الأساسي. ضمن قبل البدء. بعد تفعيل الفوترة وإنشاء مفتاح واجهة برمجة تطبيقات، يمكنك إعداد مشروع Flutter الذي تستخدمه وتطوير تطبيقك.
الخطوة 1: تثبيت البرنامج المطلوب
لإنشاء مشروع باستخدام حزمة "خرائط Google" لبرنامج 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
. لتشغيل التطبيق، اكتب: يستهدف هذا التطبيق أنظمة التشغيل iOS وAndroid والويب. لا تتوافق حزمة تطوير البرامج (SDK) لخرائط Google مع تطبيقات سطح المكتب خارج المتصفح في الوقت الحالي.cd google_maps_in_flutter
flutter run
-
أضِف المكوّن الإضافي لحزمة "خرائط 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: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع
في قسم قبل البدء، أنشأت مفتاح واجهة برمجة تطبيقات لتطبيقك. إضافة الآن هذا المفتاح لمشروع Flutter بالنسبة إلى Flutter، يجب إضافة مفتاح واجهة برمجة التطبيقات هذا إلى جميع الأنظمة الأساسية المستهدفة: iOS، وAndroid، والويب.
في الأمثلة التالية، استبدِل YOUR_API_KEY
بمفتاح واجهة برمجة التطبيقات.
Android
لتبسيط هذه المهمة، نوصيك باستخدام المكوّن الإضافي السري لنظام Gradle المتوافق مع Android
لتثبيت مكوّن Secrets Gradle الإضافي لنظام التشغيل Android في مشروعك على "خرائط Google"، اتّبِع الخطوات التالية:
-
في "استوديو Android"، افتح
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
بمفتاح واجهة برمجة التطبيقات الخاص بك. تخزين مفتاحك في هذا الملف لأنّه تم استبعادsecrets.properties
من التحقق من عنصر تحكّم الإصدار .MAPS_API_KEY=YOUR_API_KEY
- احفظ الملف.
-
أنشئ الملف
local.defaults.properties
في دليل المستوى الأعلى بالطريقة نفسها كملفsecrets.properties
، ثم أضف الرمز التالي.MAPS_API_KEY=DEFAULT_API_KEY
الغرض من هذا الملف هو توفير موقع احتياطي لمفتاح واجهة برمجة التطبيقات إذا كان لم يتم العثور على ملف
secrets.properties
، لذا لا تفشل عمليات الإنشاء. يمكن أن يحدث هذا إذا استنساخ التطبيق من نظام تحكم في الإصدار يحذفsecrets.properties
لم تنشئ بعد ملفsecrets.properties
محليًا لتقديم مفتاح واجهة برمجة التطبيقات. - احفظ الملف.
-
في ملف
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
هو اسم البيانات الوصفية الموصى به لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على العديد واجهات برمجة التطبيقات القائمة على خرائط Google على نظام Android الأساسي، بما في ذلك حزمة تطوير البرامج (SDK) مع Flutter للتوافق مع الأنظمة القديمة، توفر واجهة برمجة التطبيقات أيضًا يتوافق مع الاسمcom.google.android.maps.v2.API_KEY
. هذا المحتوى القديم اسمها بالمصادقة على الإصدار الثاني من واجهة برمجة تطبيقات خرائط Android فقط. يمكن لتطبيق ما تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد الاثنين معًا، ستعرض واجهة برمجة التطبيقات يطرح استثناء. -
في "استوديو Android"، افتح
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
هو اسم البيانات الوصفية الموصى به
لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على العديد
واجهات برمجة التطبيقات القائمة على خرائط Google على نظام Android الأساسي، بما في ذلك
حزمة تطوير البرامج (SDK) مع Flutter للتوافق مع الأنظمة القديمة، توفر واجهة برمجة التطبيقات أيضًا
يتوافق مع الاسم com.google.android.maps.v2.API_KEY
. هذا المحتوى القديم
اسمها بالمصادقة على الإصدار الثاني من واجهة برمجة تطبيقات خرائط Android فقط. يمكن لتطبيق ما
تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد الاثنين معًا، ستعرض واجهة برمجة التطبيقات
يطرح استثناء.
iOS
أضِف مفتاح واجهة برمجة التطبيقات إلى ملف AppDelegate.swift
.
- افتح ملف
ios/Runner/AppDelegate.swift
في مشروع Flutter باستخدام بيئة تطوير البرامج (IDE) المفضّلة لديك. - أضِف عبارة الاستيراد التالية لإضافة حزمة "خرائط Google" لبرنامج Flutter إلى تطبيقك:
- أضِف واجهة برمجة التطبيقات إلى طريقة
application(_:didFinishLaunchingWithOptions:)
، واستبدِل مفتاح واجهة برمجة التطبيقات 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) } }
الويب
أضِف مفتاح واجهة برمجة التطبيقات إلى ملف تطبيق index.html
.
- افتح ملف
web/index.html
في مشروع Flutter باستخدام بيئة تطوير البرامج (IDE) المفضّلة لديك. - أضِف علامة النص البرمجي التالية داخل العلامة
<head>
، واستبدِل مفتاح واجهة برمجة التطبيقات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.يجب أن تعرض كل منصة خريطة موضوعة وسط مدينة سيدني بأستراليا. إذا لم تظهر لك الخريطة، تأكَّد من أنّك أضفت مفتاح واجهة برمجة التطبيقات إلى المشروع المستهدَف المناسب.
الخطوات التالية
بعد أن أصبح لديك مفتاح واجهة برمجة التطبيقات ومشروع Flutter، يمكنك إنشاء تطبيقات وتشغيلها. توفّر حزمة "خرائط Google" لبرنامج Flutter العديد من الأدلة التعليمية ونماذج تطبيقات يمكنه مساعدتك على البدء لمزيد من المعلومات، يمكنك الاطّلاع على المراجع التالية:
- برنامج تعليمي حول إضافة خريطة باستخدام محدّد
- دروس تطبيقية حول الترميز لبرنامج Flutter من خلال "منصة خرائط Google"
- عيّنات التعليمات البرمجية على GitHub