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

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

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

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

الجزء 1: تعديل ملف التنسيق (activity_main.xml) لإضافة المكوّن Map3DView

عنصر Map3DView هو العرض الذي يعرض الخريطة الثلاثية الأبعاد داخل التطبيق. تضيف الخطوات التالية المكوّن وتعدّل الحالة الأولية للملف الشخصي ، بما في ذلك موضع الكاميرا والسمات ذات الصلة:

1. افتح ملف تنسيق نشاطك الرئيسي، والذي يقع عادةً في ‎ app/src/main/res/layout/activity_main.xml.

2. في العنصر الجذر ConstraintLayout (أو عنصر التنسيق الجذر)، أضِف مساحة الاسم map3d XML:

   xmlns:map3d="http://schemas.android.com/apk/res-auto"
   

3. حذف العنصر التلقائي <TextView> الذي يعرض "مرحبًا بالجميع"

4. أضِف المكوّن Map3DView إلى التنسيق. يمكنك تخصيص موقع الكاميرا وسمات أخرى:

   <?xml version="1.0" encoding="utf-8"?>
   <androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:app="http://schemas.android.com/apk/res-auto"
     xmlns:map3d="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools"
     android:id="@+id/main"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     tools:context=".MainActivity">
   
     <com.google.android.gms.maps3d.Map3DView
       android:id="@+id/map3dView"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       map3d:mode="hybrid"
       map3d:centerLat="38.544012"
       map3d:centerLng="-107.670428"
       map3d:centerAlt="2427.6"
       map3d:heading="310"
       map3d:tilt="63"
       map3d:range="8266"
       map3d:roll="0"
       map3d:minAltitude="0"
       map3d:maxAltitude="1000000"
       map3d:minHeading="0"
       map3d:maxHeading="360"
       map3d:minTilt="0"
       map3d:maxTilt="90"
       app:layout_constraintBottom_toBottomOf="parent"
       app:layout_constraintEnd_toEndOf="parent"
       app:layout_constraintStart_toStartOf="parent"
       app:layout_constraintTop_toTopOf="parent" />
   </androidx.constraintlayout.widget.ConstraintLayout>
   

الجزء 2: تعديل MainActivity.kt

تعمل الخطوات التالية على بدء عنصر Map3DView الذي تمت إضافته إلى ملف activity_main.xml في الجزء 1 وإدارة أحداث دورة حياة المكوّن:

1. افتح ملف MainActivity.kt الذي يقع عادةً في ‎ app/src/main/java/com/example/yourpackagename/MainActivity.kt.

2. أضِف عمليات الاستيراد اللازمة لحزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android:

   import com.google.android.gms.maps3d.GoogleMap3D
   import com.google.android.gms.maps3d.Map3DView
   import com.google.android.gms.maps3d.OnMap3DViewReadyCallback
   

3. عدِّل فئة MainActivity لتنفيذ OnMap3DViewReadyCallback:

   class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {
   

4. يمكنك تحديد متغيّرات لكلّ من Map3DView وGoogleMap3D:

   private lateinit var map3DView: Map3DView
   private var googleMap3D: GoogleMap3D? = null
   

5. في طريقة onCreate، بعد setContentView(...) ومحاولة ViewCompat.setOnApplyWindowInsetsListener، يمكنك بدء map3DView، وطلب طريقة onCreate لدورة الحياة، وطلب الخريطة بشكل غير متزامن:

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       enableEdgeToEdge()
       setContentView(R.layout.activity_main)
       ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
           val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
           v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
           insets
       }
   
       map3DView = findViewById(R.id.map3dView)
       map3DView.onCreate(savedInstanceState)
       map3DView.getMap3DViewAsync(this)
   }
   

6. إلغاء طريقة onMap3DViewReady يتم تشغيل هذا المرجع المرجعي عندما تكون الخريطة جاهزة للاستخدام:

   override fun onMap3DViewReady(googleMap3D: GoogleMap3D) {
       // Interact with the googleMap3D object here
       this.googleMap3D = googleMap3D
       // You can now make calls to the googleMap3D object, e.g.,
       // googleMap3D.cameraController.flyTo(camera { ... })
   }
   

7. يمكنك إعادة توجيه أحداث خطوات المستخدِم من "نشاطك" إلى Map3DView من خلال إضافة عمليات الاستبدال التالية إلى MainActivity:

   override fun onStart() {
       super.onStart()
       map3DView.onStart()
   }
   
   override fun onResume() {
       super.onResume()
       map3DView.onResume()
   }
   
   override fun onPause() {
       map3DView.onPause()
       super.onPause()
   }
   
   override fun onStop() {
       map3DView.onStop()
       super.onStop()
   }
   
   override fun onDestroy() {
       map3DView.onDestroy()
       super.onDestroy()
   }
   
   override fun onSaveInstanceState(outState: Bundle) {
       super.onSaveInstanceState(outState)
       map3DView.onSaveInstanceState(outState)
   }
   
   override fun onLowMemory() {
       super.onLowMemory()
       map3DView.onLowMemory()
   }
   

الجزء 3: مزامنة Gradle وRun

بعد أن عدّلت تنسيق تطبيقك ونشاطه، يمكنك إنشاء التطبيق وتشغيله لعرض طريقة عرض الخريطة الثلاثية الأبعاد.

1. لمزامنة مشروعك مع Gradle، اختَر ملف > مزامنة المشروع مع ملفات Gradle.

2. لإنشاء تطبيقك وتشغيله على جهاز محاكاة أو جهاز فعلي، اختَر تشغيل > تشغيل.

إذا تم ضبط كل الإعدادات بشكل صحيح، من المفترض أن تظهر لك خريطة ثلاثية الأبعاد في تطبيقك، تكون مركزها بالقرب من الإحداثيات المحدّدة في activity_main.xml.

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

بعد إضافة خريطة ثلاثية الأبعاد أساسية إلى تطبيقك، يمكنك استكشاف ميزات أكثر تقدمًا لحزمة تطوير البرامج (SDK) لميزة "الخرائط الثلاثية الأبعاد" على نظام التشغيل Android، مثل الرسوم المتحرّكة لمسار الكاميرا أو العلامات الثلاثية الأبعاد أو الأشكال المضلّعة.