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

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

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

نمونه‌های کد

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

مقدمه

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

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

برای افزودن 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)

جاوا

// 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) دریافت خواهید کرد.