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

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

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

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

• GroundOverlayDemoActivity - Java: ميزات تراكب الأرض و مستمعو الأحداث في 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 حالي.

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)
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().

imageOverlay?.remove()

      

imageOverlay.remove();

      

تغيير تراكب

يمكنك تغيير صورة تراكب الأرض بعد إضافتها إلى الخريطة باستخدام طريقة GroundOverlay.setImage(BitmapDescriptor).

// 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-index للتراكب.

التعامل مع أحداث تراكب الأرض

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

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