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

اختيار النظام الأساسي: 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

// 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 لتحديد الزاوية الشمالية الشرقية والجنوبية الغربية للصورة.

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

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

عند إضافة الصورة، تحدد خط 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)

      

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 المنخفضة. يمكنك الاطّلاع على مزيد من المعلومات عن علامة z-index وأحداث النقر.