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

إعداد مشروع Flutter

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

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

لإنشاء مشروع باستخدام حزمة "خرائط Google" لـ Flutter، يجب تثبيت حزمة تطوير البرامج (SDK) الخاصة بـ Flutter وإعداد بيئة التطوير للنظام الأساسي المستهدف. يمكنك الاطّلاع على دليل تثبيت Flutter للحصول على التفاصيل.

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

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

أنشئ مشروع Flutter وأضِف مكوّن Maps الإضافي.

أنشئ مشروع 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 Maps for 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")
    }
}

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 مستبعد من إمكانية التحقّق من نظام التحكّم في الإصدار.
ملاحظة: إذا لم يكن ملف 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، بما في ذلك حزمة تطوير البرامج (SDK) الخاصة بـ Flutter. للتوافق مع الإصدارات السابقة، تتيح واجهة برمجة التطبيقات أيضًا الاسم com.google.android.maps.v2.API_KEY. يتيح هذا الاسم القديم المصادقة على الإصدار 2 من واجهة برمجة التطبيقات "خرائط Google" لنظام التشغيل Android فقط. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

في 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"
}

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"
}

ملاحظة: كما هو موضّح أعلاه، com.google.android.geo.API_KEY هو اسم البيانات الوصفية المقترَح لمفتاح واجهة برمجة التطبيقات. يمكن استخدام مفتاح بهذا الاسم للمصادقة على واجهات برمجة تطبيقات متعددة مستندة إلى "خرائط Google" على نظام التشغيل Android، بما في ذلك حزمة تطوير البرامج (SDK) الخاصة بـ Flutter. للتوافق مع الإصدارات السابقة، تتيح واجهة برمجة التطبيقات أيضًا استخدام الاسم com.google.android.maps.v2.API_KEY. يتيح هذا الاسم القديم المصادقة على الإصدار 2 من واجهة برمجة التطبيقات Android Maps API فقط. يمكن للتطبيق تحديد اسم واحد فقط من أسماء البيانات الوصفية لمفتاح واجهة برمجة التطبيقات. إذا تم تحديد كليهما، ستعرض واجهة برمجة التطبيقات استثناءً.

iOS

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

افتح الملف ios/Runner/AppDelegate.swift في مشروع Flutter باستخدام بيئة التطوير المتكاملة المفضّلة لديك.
أضِف عبارة الاستيراد التالية لإضافة حزمة "خرائط 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

إعداد مشروع Flutter تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

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

Android

iOS

الخطوة 4: إضافة مفتاح واجهة برمجة التطبيقات إلى المشروع

Android

Kotlin

Groovy

Kotlin

Groovy

Kotlin

Groovy

iOS

الويب

الخطوة 5: إضافة خريطة

الخطوات التالية

إعداد مشروع Flutter