افزودن نقشه سه‌بعدی به برنامه

پلاتفرم را انتخاب کنید: Android iOS JavaScript

نقشه سه‌بعدی که شهر نیویورک را نشان می‌دهد

این صفحه نمونه‌ای از نحوه افزودن نقشه سه‌بعدی پایه به برنامه Android بااستفاده از «کیت توسعه نرم‌افزار سه‌بعدی نقشه برای Android» را نشان می‌دهد. دستورالعمل‌های این صفحه فرض می‌کنند که قبلاً مراحل صفحه راه‌اندازی را تکمیل کرده‌اید و موارد زیر را دارید:

  • پروژه Google Cloud با «کیت توسعه نرم‌افزار ۳ بعدی نقشه برای Android» فعال‌شده
  • کلید میانای برنامه‌سازی کاربردی پیکربندی‌شده برای استفاده با کیت توسعه نرم‌افزار سه‌بعدی Maps برای Android
  • پروژه «استودیو Android» برای استفاده با «کیت توسعه نرم‌افزار ۳ بعدی نقشه برای Android» راه‌اندازی شده است

برای اطلاعات بیشتر درباره این پیش‌نیازها، به راه‌اندازی مراجعه کنید.

بخش ۱: به‌روزرسانی فایل چیدمان (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> پیش‌فرض را که «سلام دنیا!» را نمایش می‌دهد حذف کنید.

  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>

بخش ۲: به‌روزرسانی MainActivity.kt

مراحل زیر مؤلفه Map3DView اضافه‌شده به فایل activity_main.xml در بخش ۱ را مقداردهی اولیه می‌کند و رویدادهای چرخه حیات مؤلفه را مدیریت می‌کند.

توجه داشته باشید که «کیت توسعه نرم‌افزار ۳ بعدی نقشه برای 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. واردات لازم برای کیت توسعه نرم‌افزار Maps 3D ویژه 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()
}

بخش ۳: همگام‌سازی Gradle و اجرا کردن

اکنون که چیدمان و فعالیت برنامه‌تان را به‌روز کرده‌اید، می‌توانید برنامه را بسازید و اجرا کنید تا نمای سه‌بعدی نقشه را ببینید.

  1. برای همگام‌سازی پروژه‌تان با Gradle، فایل > همگام‌سازی پروژه با فایل‌های Gradle را انتخاب کنید.

  2. برای ساختن و اجرای برنامه‌تان در شبیه‌ساز یا دستگاه فیزیکی، اجرا > اجرا را انتخاب کنید.

اگر همه‌چیز به‌درستی پیکربندی شده باشد، باید نقشه سه‌بعدی را در برنامه‌تان ببینید که در مرکز مختصات مشخص‌شده در activity_main.xml قرار دارد.

حالت‌های خطا و بارگیری نقشه

کیت توسعه نرم‌افزار ۳ بعدی نقشه برای Android به‌طور خودکار بازخورد دیداری داخلی را هنگام مدیریت وضعیت نقشه نمایش می‌دهد:

  • بار کردن هم‌پوشانی: وقتی نمای نقشه برای اولین‌بار مقداردهی اولیه می‌شود یا نمای اولیه آن بار می‌شود، یک نشانگر پیشرفت در مرکز نمایش داده می‌شود.
  • خطای هم‌پوشانی: اگر خطای بحرانی رخ دهد، مثل کلید API نامعتبر، خطای شبکه، یا هنگام اجرا در دستگاه پشتیبانی‌نشده، کارت خطای سبک‌دار نمایش داده می‌شود.

می‌توانید این خطاهای مقداردهی اولیه یا بار کردن را با لغو کردن 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
}

مراحل بعدی

اکنون که نقشه سه‌بعدی پایه را به برنامه‌تان اضافه کرده‌اید، می‌توانید ویژگی‌های پیشرفته‌تر «کیت توسعه نرم‌افزار سه‌بعدی Maps» برای Android را کاوش کنید، ازجمله پویانمایی‌های مسیر دوربین، نشانگرهای سه‌بعدی، یا چندضلعی‌ها.