إعداد مشروع Flutter

قبل إعداد مشروع Flutter، تأكَّد من إكمال الخطوات التمهيدية ضمن قبل البدء. بعد تفعيل الفوترة وإنشاء مفتاح واجهة برمجة التطبيقات، يمكنك إعداد مشروع Flutter الذي تستخدمه ل تطوير تطبيقك.

الخطوة 1: تثبيت البرنامج المطلوب

لإنشاء مشروع باستخدام حزمة "خرائط Google" لتطبيق Flutter، عليك تثبيت IDE لتطبيق Flutter وإعداد بيئة التطوير للنظام الأساسي المستهدَف. اطّلِع على دليل تثبيت Flutter للاطّلاع على التفاصيل.

الخطوة 2: تثبيت حزمة "خرائط Google" لتطبيق Flutter في مشروع جديد

يوفّر Flutter حزمة "خرائط Google" لنظام Flutter كمكوّن إضافي لنظام Flutter.

أنشئ مشروع Flutter وأضِف المكوّن الإضافي "خرائط Google".

  1. أنشئ مشروع 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" مع تطبيقات الكمبيوتر المكتبي خارج المتصفّح في الوقت الحالي.
  2. أضِف المكوّن الإضافي لحزمة "خرائط Google" لتطبيق Flutter إلى هذا المشروع.
    flutter pub add google_maps_flutter
      
      Resolving dependencies...
      [Listing of dependencies elided]
    
      Changed 14 dependencies!

الخطوة 3: ضبط إصدار النظام الأساسي

Android

اضبط الحد الأدنى لإصدار حزمة تطوير البرامج (SDK) لنظام التشغيل Android.

  1. افتح ملف الإعدادات android/app/build.gradle في بيئة تطوير البرامج المتكاملة (IDE) المفضّلة لديك.
  2. غيِّر قيمة 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
        }
        //...
      }
  3. عند ضبط defaultConfig، حدِّد ApplicationID الفريد الخاص بك.
  4. احفظ الملف وامزِن تغييرات مشروعك مع Gradle.

iOS

اضبط الحد الأدنى لإصدار نظام التشغيل iOS.

  1. افتح ملف الإعدادات ios/Podfile في بيئة تطوير البرامج المتكاملة (IDE) المفضّلة لديك.
  2. أضِف الأسطر التالية إلى بداية ملف 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"، اتّبِع الخطوات التالية:

  1. في 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"
        }
    }
  2. افتح ملف 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'
    }
  3. في ملف build.gradle.kts أو build.gradle على مستوى الوحدة، تأكَّد من ضبط targetSdk وcompileSdk على 34.
  4. احفظ الملف و امزِن مشروعك مع Gradle.
  5. افتح ملف secrets.properties في الدليل من المستوى الأعلى، ثم أضِف الرمز التالي: استبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات. عليك تخزين مفتاحك في هذا الملف لأنّه تم استبعاد secrets.properties من التحقّق من الملفات في نظام التحكّم في الإصدارات
    MAPS_API_KEY=YOUR_API_KEY
  6. احفظ الملف.
  7. أنشئ ملف local.defaults.properties في الدليل على المستوى الأعلى، وهو المجلد نفسه الذي يتضمّن ملف secrets.properties، ثم أضِف الرمز التالي.

    MAPS_API_KEY=DEFAULT_API_KEY

    الغرض من هذا الملف هو توفير موقع احتياطي لمفتاح واجهة برمجة التطبيقات في حال عدم العثور على ملف secrets.properties حتى لا تفشل عمليات الإنشاء. يمكن أن يحدث ذلك في حال استنساخ التطبيق من نظام تحكّم في الإصدارات يتجاهل secrets.properties ولم تنشئ بعد ملف secrets.properties على الجهاز لتوفير مفتاح واجهة برمجة التطبيقات.

  8. احفظ الملف.
  9. في ملف 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. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. في حال تحديد كليهما، يُعرِض واجهة برمجة التطبيقات استثناءً.

  10. في 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.

  1. افتح ملف ios/Runner/AppDelegate.swift في مشروع Flutter باستخدام بيئة تطوير البرامج المفضّلة لديك.
  2. أضِف عبارة الاستيراد التالية لإضافة حزمة "خرائط Google" لنظام التشغيل Flutter إلى تطبيقك:
  3. import GoogleMaps
  4. أضِف واجهة برمجة التطبيقات إلى طريقة application(_:didFinishLaunchingWithOptions:)، واستبدِل YOUR_API_KEY بمفتاح واجهة برمجة التطبيقات:
    GMSServices.provideAPIKey("YOUR_API_KEY")
  5. احفظ ملف 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)
  }
}

الويب

أضِف مفتاح واجهة برمجة التطبيقات إلى ملف تطبيق index.html.

  1. افتح ملف web/index.html في مشروع Flutter باستخدام بيئة تطوير البرامج المفضّلة لديك.
  2. أضِف علامة النص البرمجي التالية داخل علامة <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>
  3. احفظ ملف 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 جديد.

  1. افتح ملف lib/main.dart في مشروع Flutter باستخدام بيئة تطوير البرامج المفضّلة لديك.
  2. أضِف طُرقًا أو عدِّلها في الطريقة الرئيسية التلقائية لتطبيقك لإنشاء مثيل من 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,
                    ),
                  ),
                ),
              );
            }
          }
  3. ابدأ أي محاكيات أو أجهزة تريد تشغيل تطبيقك عليها.
  4. شغِّل تطبيقك. من المفترض أن يظهر لك ناتج يشبه ما يلي:
      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 العديد من الأدلة التعليمية ونماذج التطبيقات التي يمكن أن تساعدك في البدء. لمزيد من المعلومات، اطّلِع على المراجع التالية: