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

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

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

توضّح هذه الصفحة مثالاً على كيفية إضافة خريطة ثلاثية الأبعاد أساسية إلى تطبيق 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> الذي يعرض "Hello World!‎".

  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 وتشغيله

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

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

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

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

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

بعد إضافة خريطة ثلاثية الأبعاد أساسية إلى تطبيقك، يمكنك استكشاف المزيد من الميزات المتقدّمة في &quot;حزمة تطوير البرامج بالاستناد إلى بيانات خرائط Google الثلاثية الأبعاد&quot; لنظام التشغيل Android، مثل الرسوم المتحركة لمسار الكاميرا أو العلامات الثلاثية الأبعاد أو المضلّعات.