إضافة خريطة ثلاثية الأبعاد إلى تطبيقك

اختيار النظام الأساسي: Android‏ iOS‏ JavaScript‏

توضّح هذه الصفحة مثالاً على كيفية إضافة خريطة ثلاثية الأبعاد أساسية إلى تطبيق iOS باستخدام حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة iOS. تفترض التعليمات الواردة في هذه الصفحة أنّك أكملت الخطوات في صفحة الإعداد وأنّك تستوفي الشروط التالية:

• مشروع على Google Cloud تم فيه تفعيل حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة iOS
• مفتاح واجهة برمجة التطبيقات لحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة iOS
• الإصدار 16.0 من Xcode أو إصدار أحدث مع إضافة حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة iOS.

لمزيد من المعلومات حول هذه المتطلبات الأساسية، يُرجى الاطّلاع على الإعداد.

اتّباع درس تطبيقي حول الترميز أكثر تقدّمًا

يمكنك الاطّلاع على المزيد من عيّنات التعليمات البرمجية على GitHub.

الجزء 1: إنشاء تطبيق SwiftUI أساسي

1. أنشئ تطبيقًا جديدًا في Xcode.
2. اضبط اسم المنتج على Hello3DWorld، مع ضبط معرّف المؤسسة على com.example. يجب أن يكون اسم الحزمة com.example.Hello3DWorld.
3. اختَر واجهة SwiftUI.
4. أضِف مكتبة Maps 3D إلى تطبيقك. اطّلِع على التعليمات في قسم الإعداد.

الجزء 2: إضافة خريطة

1. افتح الملف الذي يحمل الاسم ContentView.swift. هذه هي نقطة الدخول والتنقل الرئيسي لتطبيقك.

2. استورِد SwiftUI وحزمة GoogleMaps3D.

3. استبدِل كل الرموز البرمجية داخل بيان body بـ Map(mode: .hybrid).

   الحد الأدنى من الإعدادات الأولية التي يجب توفيرها لبدء Map هو MapMode:

   • .hybrid،
   • ‫.roadmap أو
   • .satellite

   يجب أن يظهر ملف ContentView.swift على النحو التالي:

   import SwiftUI
   import GoogleMaps3D
   
   struct ContentView: View {
     var body: some View {
       Map(mode: .hybrid)
     }
   }
   
   #Preview {
     ContentView()
   }
   

الجزء 3: ضبط مفتاح واجهة برمجة التطبيقات

1. يجب ضبط مفتاح واجهة برمجة التطبيقات قبل بدء الخريطة. يمكنك إجراء ذلك من خلال ضبط Map.apiKey في معالج الأحداث init() في View الذي يحتوي على الخريطة.

   تحذير: لا تُدخِل مفتاح واجهة برمجة التطبيقات في نظام التحكّم في الإصدارات الخارجي أو العام

   import SwiftUI
   import GoogleMaps3D
   
   struct ContentView: View {
     init () {
       Map.apiKey = "YOUR_API_KEY"
     }
   
     var body: some View {
       Map(mode: .hybrid)
     }
   }
   

الجزء 4: استخدام كاميرا للتحكّم في عرض الخريطة

يتم التحكّم في عروض الخرائط الثلاثية الأبعاد من خلال فئة Camera. في هذه الخطوة، ستتعلم كيفية تحديد الموقع الجغرافي والارتفاع والاتجاه والإمالة والتدوير والنطاق لتخصيص عرض الخريطة.

1. غيِّر استدعاء الدالة Map() لتضمين سمة initialCamera. ابدأ تشغيل initialCamera لعرض وسط مانهاتن.

   ملاحظة: ترتيب المَعلمات مهم. يتم إعداد الكاميرا من خلال توفير خط العرض أولاً، ثم خط الطول. تأكَّد من تحديد القيم الصحيحة لكلّ منهما، خاصةً عند اللصق من مصدر آخر، وإلا قد تعرض الكاميرا موقعًا جغرافيًا غير متوقّع.

   import SwiftUI
   import GoogleMaps3D
   
   struct ContentView: View {
     init () {
       Map.apiKey = "YOUR_API_KEY"
     }
     var body: some View {
       Map(initialCamera: .init(
         center: .init(latitude: 40.748339, longitude: -73.985912, altitude: 211.1),
         heading: 52,
         tilt: 68,
         roll: 0.0,
         range: 1039,
         fieldOfView: .degrees(50)
       ), mode: .hybrid)
     }
   }
   

يضبط الرمز أعلاه قيمًا للمَعلمات التالية:

• ‫center: يمثّل LatLngAltitude موقع الكاميرا
• ‫heading: الاتجاه بالدرجات من الشمال لتوجيه الكاميرا نحوه.
• ‫tilt: زاوية الإمالة بالدرجات، حيث تشير القيمة 0 إلى النظر للأعلى مباشرةً، بينما تشير القيمة 90 إلى النظر أفقيًا.
• ‫roll: زاوية الدوران حول المستوى العمودي للكاميرا، بالدرجات
• ‫range: المسافة بالأمتار بين الكاميرا والموقع الجغرافي المحدّد بخط العرض وخط الطول
• ‫fieldOfView: الزاوية التي تمثّل مجال رؤية الكاميرا

في حال عدم تقديم أي من هذه المَعلمات الإضافية، سيتم استخدام قيمة تلقائية.

ملاحظة: يمكنك أيضًا ضبط الارتفاع النسبي للكاميرا باستخدام الإمالة والنطاق.

لجعل عرض الكاميرا يعرض المزيد من البيانات ثلاثية الأبعاد، قم بتعيين المعلمات الأولية لإظهار عرض أقرب ومائل.

الجزء 5: معاينة تطبيقك وتشغيله

1. إضافة معاينة Xcode

   تُعد المعاينات ميزة قوية في XCode تتيح لك رؤية تطبيقك والتفاعل معه دون الحاجة إلى استخدام المحاكي أو جهاز خارجي.

   لإضافة معاينة، أضِف مجموعة رموز #Preview {} خارج البنية.

   #Preview {
     ContentView()
   }
   

2. تشغيل التطبيق

أنشئ التطبيق وشغِّله.

حالات تحميل الخريطة وحالات الخطأ

تعرض حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة iOS تلقائيًا ملاحظات مرئية مدمجة أثناء إدارة حالة Map:

• تراكب التحميل: يتم عرض مؤشر تقدّم في المنتصف عند بدء عرض الخريطة أو تحميلها لأول مرة.
• تراكب الخطأ: يتم عرض تراكب خطأ في حال تعذّر تحميل الخريطة.

إذا طبّقت نمط خريطة مستندًا إلى السحابة الإلكترونية باستخدام style(mapID:error:) على Map، يمكنك تمرير إغلاق error لمعالجة أخطاء تحميل النمط.

الاستماع إلى أحداث النقر على الخريطة

للاستماع إلى أحداث النقر على الخريطة، طبِّق المُعدِّل onTap(_:) على Map. عندما ينقر المستخدم على الخريطة، يتلقّى الإغلاق قيمة MapTapInfo التي توفّر location (LatLngAltitude) وcontent التي تم النقر عليها (MapTapInfo.Content.map أو MapTapInfo.Content.place(id:)). لمزيد من المعلومات عن التفاعلات مع نقاط الاهتمام، يُرجى الاطّلاع على التفاعل مع نقاط الاهتمام.

Map(mode: .hybrid)
  .onTap { tapInfo in
    print("Tapped at \(tapInfo.location), content: \(tapInfo.content)")
  }

تهانينا!

لقد أضفت خريطة ثلاثية الأبعاد إلى تطبيق بنجاح.

بعد ذلك، يمكنك استكشاف المزيد من الميزات المتقدّمة في حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة iOS، مثل الصور المتحركة لمسار الكاميرا أو العلامات الثلاثية الأبعاد أو المضلّعات.