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

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

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

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

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

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

لغة 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);

      

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)

      

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

لغة Java

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

      

Kotlin

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

      

إزالة طبقة مركّبة

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

لغة Java

imageOverlay.remove();

      

Kotlin

imageOverlay?.remove()

      

تغيير تراكب

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

لغة Java

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

      

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

      

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

وضع تراكب على الأرض

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

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

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

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

عندما تضيف الصورة التي تحدّد خط الطول اللاتيني الذي سيتم تثبيت المرسى عليه وعرض التراكب (بالمتر). يتم ضبط anchor تلقائيًا على منتصف الصورة. يمكنك اختياريًا توفير ارتفاع التراكب (بالمتر). إذا لم يتم توفير ارتفاع التراكب، سيتم احتسابه تلقائيًا للحفاظ على نسب الصورة.

يضع الرمز التالي صورة في الموضع 40.714086, -74.228697 ارتفاعًا و8.6 كيلومترًا في ارتفاع 6.5 كيلومتر. يتم تثبيت الصورة في أسفل يمين الشاشة.

لغة 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);

      

Kotlin

val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0f, 1f)
    .position(LatLng(40.714086, -74.228697), 8600f, 6500f)

      

استخدام LatLNGBounds لتحديد موضع صورة

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

يضع الرمز التالي صورة على الخريطة مرتبطة بركن جنوب غربها 40.712216,-74.22655 يحدّها زاوية الشمال الشرقي بـ 40.773941, -74.12544.

لغة 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);

      

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)

      

ربط البيانات بتراكب أساسي

يمكنك استدعاء GroundOverlay.setTag() لتخزين كائن بيانات عشوائي بتراكب على شكل عنصر، واسترداد كائن البيانات باستخدام GroundOverlay.getTag().

يخزّن نموذج الرمز التالي وصفًا لسلسلة مع طبقة مركّبة:

لغة 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");

      

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"

      

في ما يلي بعض الأمثلة على السيناريوهات التي يكون فيها تخزين البيانات واستردادها باستخدام طبقات أساسية:

• قد يلبي تطبيقك عناصر مركّبة مختلفة، وتريد التعامل معها بشكل مختلف عندما ينقر عليها المستخدم.
• من الممكن أنك تواجه نظامًا له معرّفات سجلّات فريدة، حيث تمثل التراكبات سجلات محددة في هذا النظام.
• قد تشير بيانات التراكب إلى أولوية لتحديد فهرس z للتراكب.

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

حسب الإعدادات التلقائية، لا يمكن النقر على العناصر المركّبة. ويمكنك تفعيل إمكانية النقر وإيقافها من خلال الاتصال بـ GroundOverlay.setClickable(boolean).

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

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