تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إعداد مشروع Flutter

قبل إعداد مشروع 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. لتشغيل تطبيقك، اكتب:
```
  cd google_maps_in_flutter
  flutter run
```
يستهدف هذا التطبيق أنظمة التشغيل iOS وAndroid والويب. لا تتوافق حزمة تطوير البرامج (SDK) لخرائط Google مع تطبيقات سطح المكتب خارج المتصفح في الوقت الحالي.

أضِف المكوّن الإضافي لحزمة "خرائط 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.

لتثبيت مكوّن Secret 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")
    }
}

رائع

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 من التحقق من الوصول إلى نظام التحكم في الإصدار.
ملاحظة: إذا لم يكن ملف secrets.properties موجودًا، أنشِئه في المجلد نفسه الذي يتضمّن ملف local.properties.
```
MAPS_API_KEY=YOUR_API_KEY
```
احفظ الملف.
أنشئ ملف local.defaults.properties في الدليل على المستوى الأعلى، وهو المجلد نفسه الذي يتضمّن ملف secrets.properties، ثم أضِف الرمز التالي.

ملاحظة: أدخِل الرمز كما هو معروض. لا تستبدِل DEFAULT_API_KEY بمفتاح واجهة برمجة التطبيقات.
```
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. ويسمح هذا الاسم القديم بالمصادقة على الإصدار الثاني من واجهة برمجة تطبيقات 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". يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. في حال تحديد الاثنين، تطرح واجهة برمجة التطبيقات استثناءً.

iOS

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

افتح ملف ios/Runner/AppDelegate.swift في مشروع Flutter باستخدام بيئة تطوير البرامج (IDE) المفضّلة لديك.
أضِف عبارة الاستيراد التالية لإضافة حزمة "خرائط Google" لبرنامج Flutter إلى تطبيقك:

import GoogleMaps

أضِف واجهة برمجة التطبيقات إلى طريقة application(_:didFinishLaunchingWithOptions:)، واستبدِل مفتاح واجهة برمجة التطبيقات YOUR_API_KEY بما يلي:
```
GMSServices.provideAPIKey("YOUR_API_KEY")
```
احفظ ملف 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.

افتح ملف 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