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

اختيار النظام الأساسي: 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. أضِف مكتبة "خرائط Google" الثلاثية الأبعاد إلى تطبيقك. اطّلِع على التعليمات في قسم الإعداد.

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

خريطة ثلاثية الأبعاد بسيطة لكرة أرضية

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

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

  3. استبدِل كل الرمز البرمجي داخل تعريف النص الأساسي بـ Map(mode: .hybrid).

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

    • .hybrid، أو
    • ‎.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(
      latitude: 40.748339,
      longitude: -73.985912,
      altitude: 211.1,
      heading: 52,
      tilt: 68,
      range: 1039
    ), mode: .hybrid)
  }
}

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

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

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

لعرض المزيد من البيانات الثلاثية الأبعاد في طريقة عرض الكاميرا، اضبط المَعلمات الأولية لعرض منظر أقرب ومائل.

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

خريطة ثلاثية الأبعاد أساسية لمدينة نيويورك

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

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

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

    #Preview {
  CameraDemo()
}

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

إنشاء التطبيق وتشغيله

تهانينا!

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

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