تراكبات الأرض

اختيار النظام الأساسي: Android iOS JavaScript

طبقات الأرض هي طبقات صور مرتبطة بإحداثيات خطوط الطول والعرض، لذا تتحرّك عند سحب الخريطة أو تكبيرها أو تصغيرها.

عيّنات تعليمات برمجية

يتضمّن مستودع ApiDemos على GitHub عيّنة توضّح طبقات الأرض:

• GroundOverlayDemoActivity - Java: ميزات طبقة الأرض و مستمعو الأحداث في Java
• GroundOverlayDemoActivity - Kotlin: ميزات طبقة الأرض و مستمعو الأحداث في Kotlin

مقدمة

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

إضافة طبقة

لإضافة GroundOverlay، أنشئ كائن GroundOverlayOptions يحدّد صورة وموضعًا. يمكنك اختياريًا تحديد إعدادات إضافية تؤثر في موضع الصورة على الخريطة. بعد تحديد الخيارات اللازمة، مرِّر الكائن إلى طريقة GoogleMap.addGroundOverlay() لإضافة الصورة إلى الخريطة. تعرض طريقة addGroundOverlay() كائن GroundOverlay، ويجب الاحتفاظ بمرجع لـ هذا الكائن إذا أردت تعديله لاحقًا.

**ملاحظة:** عند إضافة الصورة إلى الخريطة، سيتم تحويلها إلى صورة تكون أضلاعها قوى للعدد اثنين. يمكنك تجنُّب هذا التحويل باستخدام صورة أصلية بأبعاد تكون قوى للعدد اثنين، مثل 128×512 أو 1024×1024.

الخطوات بالتفصيل:

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 بعرض 8.6 كم وارتفاع 6.5 كم. تم تثبيت الصورة في أسفل يسار الشاشة.

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-index للطبقة.

التعامل مع أحداث طبقة الأرض

لا يمكن النقر على طبقات الأرض تلقائيًا. يمكنك تفعيل إمكانية النقر وإيقافها عن طريق استدعاء GroundOverlay.setClickable(boolean).

استخدِم OnGroundOverlayClickListener للاستماع إلى أحداث النقر على طبقة أرض قابلة للنقر. لضبط هذا المستمع على الخريطة، استدعِ GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener). عندما ينقر مستخدم على طبقة أرض، ستتلقّى رد الاتصال onGroundOverlayClick(GroundOverlay).

ملاحظة: إذا تم تراكب طبقات أو أشكال متعدّدة (علامات أو خطوط متعددة أو مضلّعات أو دوائر أو طبقات أرض) فوق بعضها البعض، يتم تصفّح حدث ناتج عن النقر أولاً من خلال مجموعة العلامات ، ثم يتم تفعيله للطبقات أو الأشكال الأخرى القابلة للنقر استنادًا إلى قيم z-index الخاصة بها. يتم تفعيل حدث واحد على الأكثر لكل نقرة. بعبارة أخرى، لا يتم تمرير النقرة إلى الطبقات أو الأشكال ذات قيم z-index المنخفضة. مزيد من المعلومات عن قيمة z-index للعلامة وأحداث النقر.