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

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

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

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

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

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

      

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. يمكنك تعديل التراكب في وقت لاحق عن طريق إجراء تغييرات على هذا الكائن.

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

      

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
val 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

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

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

      

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.

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

      

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

يخزّن نموذج الرمز التالي وصف سلسلة مع تراكب على سطح الأرض:

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

      

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