پوشش های زمینی

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

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

نمونه کد

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

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

معرفی

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

یک پوشش اضافه کنید

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

توجه: هنگامی که تصویر به نقشه اضافه می شود به تصویری با اضلاع با توان دو تبدیل می شود. می‌توانید با استفاده از یک تصویر اصلی با ابعادی که توان دو را دارند از این تبدیل جلوگیری کنید - به عنوان مثال، 128x512 یا 1024x1024.

گام به گام:

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 موجود اضافه کرد.

کاتلین

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 را نگه دارید. می‌توانید بعداً با ایجاد تغییراتی در این شی، همپوشانی را تغییر دهید.

کاتلین

// 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() می توانید یک همپوشانی زمین را حذف کنید.

کاتلین

imageOverlay?.remove()

      

جاوا

imageOverlay.remove();

      

یک پوشش را تغییر دهید

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

کاتلین

// Update the GroundOverlay with a new image of the same dimension

// 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 قرار می دهد که عرض آن 8.6 کیلومتر و ارتفاع 6.5 کیلومتر است. تصویر در پایین سمت چپ لنگر انداخته است.

کاتلین

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 محدود شده است.

کاتلین

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() بازیابی کنید.

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

کاتلین

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-index و رویدادهای کلیک بیشتر بخوانید.