إعداد مشروع Flutter

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

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

لإنشاء مشروع باستخدام حزمة "خرائط Google لبرنامج Flutter"، يجب تثبيت حزمة Flutter SDK وإعداد بيئة التطوير للمنصّة المستهدَفة. يمكنك الاطّلاع على دليل تثبيت 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 في بيئة التطوير المتكاملة التي تفضّلها.
  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 في بيئة التطوير المتكاملة التي تفضّلها.
  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

لتبسيط هذه المهمة، ننصحك باستخدام المكوّن الإضافي Secret Gradle الإضافي لنظام Android.

لتثبيت المكوّن الإضافي Secret Gradle الإضافي لنظام التشغيل Android في مشروع "خرائط Google"، اتَّبِع الخطوات التالية:

  1. في "استوديو Android"، افتح ملف build.gradle أو build.gradle.kts ذي المستوى الأعلى وأضِف الرمز التالي إلى العنصر dependencies ضمن buildscript.

    رائع

    buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}

    Kotlin

    buildscript {
    dependencies {
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}
  2. افتح ملف build.gradle على مستوى الوحدة وأضِف الرمز التالي إلى العنصر plugins.

    رائع

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}

    Kotlin

    plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. في ملف 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}" />

    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 name com.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.

  10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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.*"
}

Kotlin

secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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 من واجهة برمجة تطبيقات "خرائط Google" فقط. ويمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. وإذا تم تحديد كليهما، تعرض واجهة برمجة التطبيقات استثناءً.

iOS

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

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