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

هذا المنتج أو الميزة يتوفران في النسخة التجريبية (ما قبل التوفر للجمهور العام). قد يكون الدعم المقدّم للمنتجات والميزات في مرحلة ما قبل التوفّر للجمهور العام محدودًا، وقد لا تكون التغييرات التي يتم إجراؤها على المنتجات والميزات هنا متوافقة مع الإصدارات الأخرى من هذه المرحلة. تخضع عروض مرحلة ما قبل التوفّر للجمهور العام لبنود الخدمة المحدّدة في منصة خرائط Google. لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق.

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

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

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

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

يمكنك اتّباع درس تعليمي أكثر تقدّمًا عبر Codelabs.

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

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

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

الجزء 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),
         altitudeMode: .relativeToGround
       ), mode: .hybrid)
     }
   }
   

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

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

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

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

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

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

1. أضِف معاينة في Xcode

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

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

   #Preview {
     CameraDemo()
   }
   

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

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

تهانينا!

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

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