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

اختيار النظام الأساسي: 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 (أو عنصر التنسيق الجذر)، أضِف مساحة اسم XML التالية: map3d

    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:mapMode="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 وإدارة أحداث يتم في مراحل النشاط للمكوّن.

يُرجى العِلم أنّ حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" الثلاثية الأبعاد لأجهزة Android لا تتيح سوى مثيل واحد نشط من Map3DView في كل مرة. لا يمكن عرض نُسخ متعددة من Map3DView في الوقت نفسه (على سبيل المثال، في التنسيق نفسه أو في أنشطة أو أجزاء مختلفة مرئية)، وقد يؤدي ذلك إلى حدوث مشاكل في العرض، مثل ظهور شاشات سوداء في طرق العرض الثانوية.

علاوةً على ذلك، ستشارك جميع Map3DView حالة الخريطة نفسها وتعكسها (مثل موضع الكاميرا والعلامات المضافة والمضلّعات وما إلى ذلك)، والتي ستستمر حتى إذا تم تدمير Map3DView واحدة (باستخدام onDestroy) وتم إنشاء أخرى، ما لم يتم محوها يدويًا. على سبيل المثال، إذا أضفت علامات إلى Map3DView1، ثم دمرتها وأنشأت Map3DView2، فستظل هذه العلامات نفسها موجودة على Map3DView2.

مسؤوليات المطوّر:

  • عرض واحد في كل مرة: تأكَّد من أنّ Map3DView واحد فقط يظهر في جزء نشط من هيكلية طرق العرض في أي لحظة.
  • التنظيف اليدوي: عند التبديل من Map3DView (مثل Map3DView1) إلى آخر (مثل Map3DView2)، عليك استدعاء onDestroy() على المثيل القديم (Map3DView1). وبما أنّ حالة الخريطة الأساسية مشترَكة، لضمان بدء Map3DView2 بحالة جديدة أو محدّدة، عليك تنظيف أي حالة تم ضبطها بواسطة Map3DView1 يدويًا. ويشمل ذلك إزالة العلامات والتراكبات وما إلى ذلك، وإعادة ضبط موضع الكاميرا باستخدام عنصر GoogleMap3D الذي تم الحصول عليه في OnMap3DViewReadyCallback.

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

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

    import android.util.Log
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 وonError. يتم تشغيل عمليات الاستدعاء هذه عندما تكون الخريطة جاهزة للاستخدام، أو عند حدوث خطأ أثناء الإعداد:

    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.flyTo(camera { ... })
}

override fun onError(error: Exception) {
    // Handle the error gracefully here (for example, show an error dialog or log the error).
    Log.e("MainActivity", "Error loading 3D map", error)
}

  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.

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

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

  • تراكب التحميل: يتم عرض مؤشر تقدّم في المنتصف عند بدء عرض الخريطة لأول مرة أو تحميل إطار العرض الأولي.
  • تراكب الخطأ: يتم عرض بطاقة خطأ منسَّقة في حال حدوث عطل فادح، مثل مفتاح واجهة برمجة تطبيقات غير صالح أو خطأ في الشبكة أو عند التشغيل على جهاز غير متوافق.

يمكنك تسجيل أخطاء الإعداد أو التحميل هذه آليًا من خلال إلغاء onError(error: Exception) ضمن تنفيذ OnMap3DViewReadyCallback.

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

للاستماع إلى أحداث النقر على الخريطة، استدعِ الدالة setMap3DClickListener على GoogleMap3D. عندما ينقر مستخدم على الخريطة، تتلقّى دالة الاستدعاء onMap3DClick عنصر Map3DClickEvent يوفّر location و placeId للنقطة التي تم النقر عليها، ويعرض Boolean (true لإيقاف عنصر واجهة المستخدم التلقائي في واجهة مستخدم "الأماكن"، أو false لعرضه). لمزيد من المعلومات، يُرجى الاطّلاع على مقالة التفاعل مع نقاط الاهتمام.

يوضّح المثال التالي كيفية ضبط متتبِّع نقرات الخريطة:

googleMap3D.setMap3DClickListener { event: Map3DClickEvent ->
    Log.d(
        "MainActivity",
        "Clicked at ${event.location}, placeId: ${event.placeId}"
    )
    false
}

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

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