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

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

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

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

يتضمّن مستودع ApiDemos على GitHub مثالاً يوضّح العناصر التي تظهر على سطح الأرض:

• ‫GroundOverlayDemoActivity - Java: ميزات طبقة الأرض و المستمعون في Java
• ‫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 حالي.

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)

      

Java

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)

      

Java

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

      

إزالة تراكب

يمكنك إزالة تراكب سطح الأرض باستخدام الطريقة GroundOverlay.remove().

Kotlin

imageOverlay?.remove()

      

Java

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

      

Java

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

      

ستؤدي الطريقة setImage() إلى استبدال الصورة الحالية بصورة أخرى بالأبعاد نفسها.

تحديد موضع "طبقة الأرض"

هناك طريقتان لتحديد موضع تراكب السطح:

• استخدام LatLng لمحاذاة التراكب، والأبعاد بالمتر لتحديد حجم الصورة
• استخدام LatLngBounds لتحديد الزاويتَين الشمالية الشرقية والجنوبية الغربية للصورة

يجب تحديد موضع تراكب السطح قبل إضافته إلى الخريطة.

استخدام الموقع الجغرافي لتحديد موضع صورة

عند إضافة الصورة، يمكنك تحديد إحداثيات خط الطول والعرض التي سيتم تثبيت العنصر الأساسي عليها وعرض الصورة المتراكبة (بالمتر). يتم ضبط 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)

      

Java

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)

      

Java

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"

      

Java

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. يتمّ بدء حدث واحد كحدّ أقصى لكلّ نقرة. بعبارة أخرى، لا يتم تمرير النقرة إلى الصور المتراكبة أو الأشكال التي لها قيم أقل من z-index. يمكنك الاطّلاع على مزيد من المعلومات عن فهرس z للعلامة وأحداث النقرات.