قبل إعداد مشروع Flutter، تأكَّد من إكمال الخطوات التمهيدية ضمن قبل البدء. بعد تفعيل الفوترة وإنشاء مفتاح واجهة برمجة التطبيقات، يمكنك إعداد مشروع Flutter الذي تستخدمه ل تطوير تطبيقك.
الخطوة 1: تثبيت البرنامج المطلوب
لإنشاء مشروع باستخدام حزمة "خرائط Google" لتطبيق Flutter، عليك تثبيت IDE لتطبيق Flutter وإعداد بيئة التطوير للنظام الأساسي المستهدَف. اطّلِع على دليل تثبيت 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
لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي 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") } }
رائع
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") }
رائع
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، بما في ذلك حزمة تطوير البرامج Flutter SDK. للتوافق مع الإصدارات السابقة، تتيح واجهة برمجة التطبيقات أيضًا استخدام الاسمcom.google.android.maps.v2.API_KEY
. لا يسمح هذا الاسم القديم بالمصادقة إلا على الإصدار 2 من واجهة برمجة التطبيقات Android Maps 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.*" }
رائع
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، بما في ذلك
حزمة تطوير البرامج Flutter SDK. للتوافق مع الإصدارات السابقة، تتيح واجهة برمجة التطبيقات أيضًا
استخدام الاسم com.google.android.maps.v2.API_KEY
. لا يسمح هذا الاسم القديم
بالمصادقة إلا على الإصدار 2 من واجهة برمجة التطبيقات Android Maps API. يمكن للتطبيق تحديد
اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. في حال تحديد كليهما، يُعرِض واجهة برمجة التطبيقات
استثناءً.
iOS
أضِف مفتاح واجهة برمجة التطبيقات إلى ملف AppDelegate.swift
.
- افتح ملف
ios/Runner/AppDelegate.swift
في مشروع Flutter باستخدام بيئة تطوير البرامج المفضّلة لديك. - أضِف عبارة الاستيراد التالية لإضافة حزمة "خرائط 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 باستخدام بيئة تطوير البرامج المفضّلة لديك. - أضِف علامة النص البرمجي التالية داخل علامة
<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 باستخدام بيئة تطوير البرامج المفضّلة لديك. - أضِف طُرقًا أو عدِّلها في الطريقة الرئيسية التلقائية لتطبيقك لإنشاء مثيل من
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 العديد من الأدلة التعليمية ونماذج التطبيقات التي يمكن أن تساعدك في البدء. لمزيد من المعلومات، اطّلِع على المراجع التالية:
- الدليل التعليمي لإضافة خريطة تتضمّن علامة
- Codelabs لنظام Flutter باستخدام "منصة خرائط Google"
- عيّنات الرموز البرمجية على GitHub