رونهادهای زمین

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

رونهادهای زمین رونهادهای تصویری هستند که به مختصات طول/عرض جغرافیایی گره خورده‌اند، بنابراین وقتی نقشه را می‌کشید یا بزرگ‌نمایی می‌کنید، آن‌ها نیز حرکت می‌کنند.

نمونه‌های کد

مخزن ApiDemos در GitHub شامل نمونه‌ای است که پوشش‌های زمین را نشان می‌دهد:

• GroundOverlayDemoActivity - Java: ویژگی‌های رونهاد زمینی و شنوندگان در جاوا
• GroundOverlayDemoActivity - Kotlin: ویژگی‌های رونهاد زمینی و شنوندگان در Kotlin

مقدمه

رونهاد زمین تصویری است که روی نقشه ثابت شده است. برخلاف نشانگرها، هم‌پوشانی‌های زمینی به‌جای صفحه‌نمایش، نسبت به سطح زمین جهت‌گیری می‌شوند، بنابراین چرخاندن، کج کردن، یا بزرگ‌نمایی نقشه جهت تصویر را تغییر می‌دهد. زمانی‌که می‌خواهید یک تصویر را در یک منطقه روی نقشه ثابت کنید، هم‌پوشانی‌های زمینی مفید هستند. اگر می‌خواهید تصاویر گسترده‌ای اضافه کنید که بخش بزرگی از نقشه را پوشش دهد، باید پوشش کاشی را درنظر بگیرید.

افزودن رونهاد

برای افزودن GroundOverlay، شیء GroundOverlayOptions ایجاد کنید که هم تصویر و هم موقعیت را تعریف می‌کند. می‌توانید به‌صورت اختیاری تنظیمات اضافی را مشخص کنید که بر موقعیت تصویر در نقشه تأثیر می‌گذارد. پس‌از تعریف گزینه‌های لازم، شیء را به روش GoogleMap.addGroundOverlay() منتقل کنید تا تصویر به نقشه اضافه شود. روش addGroundOverlay() یک شیء GroundOverlay را برمی‌گرداند؛ اگر می‌خواهید بعداً این شیء را اصلاح کنید، باید مرجع آن را حفظ کنید.

توجه: وقتی تصویر به نقشه اضافه می‌شود، به تصویری تبدیل می‌شود که اضلاع آن توان‌هایی از دو هستند. بااستفاده از تصویر اصلی با ابعادی که توان دو هستند (مثلاً ۱۲۸×۵۱۲ یا ۱۰۲۴×۱۰۲۴) می‌توانید از این تبدیل جلوگیری کنید.

گام‌به‌گام:

1. نمونه‌سازی شیء GroundOverlayOptions جدید
2. تصویر را به‌عنوان BitmapDescriptor مشخص کنید.
3. موقعیت تصویر را بااستفاده از یکی از روش‌های موجود تنظیم کنید:
   • position(LatLng location, float width, float height)
   • position(LatLng location, float width)
   • positionFromBounds(LatLngBounds bounds)
4. هر ویژگی اختیاری‌ای را که می‌خواهید، مثل transparency، تنظیم کنید.
5. برای افزودن تصویر به نقشه، با GoogleMap.addGroundOverlay() تماس بگیرید.

مثال زیر نحوه افزودن رونهاد زمین به شیء GoogleMap موجود را نشان می‌دهد.

Kotlin

val newarkLatLng = LatLng(40.714086, -74.228697)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f)
map.addGroundOverlay(newarkMap)

      

جاوا

LatLng newarkLatLng = new LatLng(40.714086, -74.228697);

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f);
map.addGroundOverlay(newarkMap);

      

اگر می‌خواهید پس‌از افزودن هم‌پوشانی زمین به نقشه آن را تغییر دهید یا بردارید، مطمئن شوید که شیء GroundOverlay را نگه داشته‌اید. می‌توانید بعداً با ایجاد تغییرات در این شیء، این هم‌پوشانی را اصلاح کنید.

Kotlin

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
val imageOverlay = map.addGroundOverlay(newarkMap)
imageOverlay?.let {
    val isClickable = it.isClickable
    val isVisible = it.isVisible
    val bearing = it.bearing
    val transparency = it.transparency
    val zIndex = it.zIndex
    val position = it.position
    val width = it.width
    val height = it.height
}

      

جاوا

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);

      

برداشتن رونهاد

می‌توانید با روش GroundOverlay.remove()، پوشش زمین را بردارید.

Kotlin

imageOverlay?.remove()

      

جاوا

imageOverlay.remove();

      

تغییر رونهاد

پس‌از اینکه تصویر رونهاد زمین با روش GroundOverlay.setImage(BitmapDescriptor) به نقشه اضافه شد، می‌توانید آن را تغییر دهید.

Kotlin

// Update the GroundOverlay with a new image of the same dimension
imageOverlay?.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))

      

جاوا

// Update the GroundOverlay with a new image of the same dimension
imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));

      

روش setImage() تصویر موجود را با تصویر دیگری با همان ابعاد جایگزین می‌کند.

موقعیت رونهاد زمینی

دو روش برای مشخص کردن موقعیت رونهاد زمین وجود دارد:

• استفاده از LatLng برای قرار دادن هم‌پوشانی در مرکز، و ابعاد به متر برای مشخص کردن اندازه تصویر.
• استفاده از LatLngBounds برای مشخص کردن گوشه‌های شمال شرقی و جنوب غربی تصویر.

باید موقعیت هم‌پوشانی زمین را قبل‌از اضافه شدن به نقشه مشخص کنید.

استفاده از مکان برای قرار دادن تصویر

وقتی تصویر را اضافه می‌کنید، LatLng را که لنگر به آن ثابت می‌شود و پهنای رونهاد (به متر) را مشخص می‌کنید. anchor به‌طور پیش‌فرض در مرکز تصویر قرار می‌گیرد. می‌توانید به‌صورت اختیاری ارتفاع رونهاد را (به متر) ارائه دهید. اگر ارتفاع هم‌پوشانی را ارائه نکنید، به‌طور خودکار محاسبه می‌شود تا نسبت‌های تصویر حفظ شود.

کد زیر تصویری را در موقعیت 40.714086, -74.228697 قرار می‌دهد که ۸٫۶ کیلومتر عرض و ۶٫۵ کیلومتر ارتفاع دارد. تصویر در پایین سمت راست ثابت شده است.

Kotlin

val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0f, 1f)
    .position(LatLng(40.714086, -74.228697), 8600f, 6500f)

      

جاوا

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0, 1)
    .position(new LatLng(40.714086, -74.228697), 8600f, 6500f);

      

استفاده از LatLngBounds برای تعیین موقعیت تصویر

LatLngBounds را که حاوی تصویر است ارائه دهید. ‫LatLngBounds گوشه‌های شمال شرقی و جنوب غربی تصویر را تنظیم می‌کند. وقتی تصویر روی نقشه کشیده می‌شود، چرخانده می‌شود تا در محدوده جا بگیرد. اگر محدوده‌ها با نسبت ابعادی اصلی مطابقت نداشته باشند، تصویر کج خواهد شد.

کد زیر تصویری را روی نقشه قرار می‌دهد که گوشه جنوب غربی آن به 40.712216,-74.22655 و گوشه شمال شرقی آن به 40.773941, -74.12544 محدود شده است.

Kotlin

val newarkBounds = LatLngBounds(
    LatLng(40.712216, -74.22655),  // South west corner
    LatLng(40.773941, -74.12544)   // North east corner
)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds)

      

جاوا

LatLngBounds newarkBounds = new LatLngBounds(
    new LatLng(40.712216, -74.22655),       // South west corner
    new LatLng(40.773941, -74.12544));      // North east corner
GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds);

      

مرتبط کردن داده‌ها با رونهاد زمین

می‌توانید GroundOverlay.setTag() را فراخوانی کنید تا یک شیء داده دلخواه را با یک پوشش زمینی ذخیره کنید و شیء داده را بااستفاده از GroundOverlay.getTag() بازیابی کنید.

نمونه کد زیر شرح رشته‌ای را با پوشش زمین ذخیره می‌کند:

Kotlin

val sydneyGroundOverlay = map.addGroundOverlay(
    GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
        .position(LatLng(-33.873, 151.206), 100f)
        .clickable(true)
)
sydneyGroundOverlay?.tag = "Sydney"

      

جاوا

GroundOverlay sydneyGroundOverlay = map.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206), 100)
    .clickable(true));

sydneyGroundOverlay.setTag("Sydney");

      

در اینجا چند نمونه از سناریوهایی آورده شده است که در آن‌ها ذخیره و بازیابی داده‌ها بااستفاده از هم‌پوشانی‌های زمینی مفید است:

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

پرداختن به رویدادهای رونهاد زمین

به‌طور پیش‌فرض، رونهادهای زمینی کلیک‌کردنی نیستند. با فراخوانی GroundOverlay.setClickable(boolean) می‌توانید قابلیت کلیک کردن را فعال و غیرفعال کنید.

از OnGroundOverlayClickListener برای گوش دادن به رویدادهای کلیک در یک هم‌پوشانی زمین کلیک‌کردنی استفاده کنید. برای تنظیم این شنونده در نقشه، با GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener) تماس بگیرید. وقتی کاربر روی هم‌پوشانی زمین کلیک می‌کند، برگشت تماس onGroundOverlayClick(GroundOverlay) دریافت خواهید کرد.

توجه: اگر چند هم‌پوشانی یا شکل (نشانگر، چندخطی، چندضلعی، دایره، و/یا هم‌پوشانی زمین) روی هم قرار گرفته باشند، رویداد کلیک ابتدا در خوشه نشانگرها می‌چرخد، سپس برای دیگر هم‌پوشانی‌ها یا شکل‌های قابل‌کلیک براساس مقادیر z-index آن‌ها راه‌اندازی می‌شود. با هر کلیک حداکثر یک رویداد راه‌اندازی می‌شود. به‌عبارت دیگر، کلیک به رونهادها یا شکل‌هایی با مقادیر z-index پایین‌تر منتقل نمی‌شود. درباره شاخص z و رویدادهای کلیک بیشتر بخوانید.