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

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

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

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

مقدمة

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

إضافة تراكب

لإضافة GroundOverlay، أنشئ عنصر GroundOverlayOptions يحدّد كلاً من الصورة والموقع. يمكنك اختياريًا تحديد إعدادات إضافية تؤثر في موضع الصورة على الخريطة. بعد تحديد options الضرورية، مرِّر العنصر إلى GoogleMap.addGroundOverlay()method لإضافة الصورة إلى الخريطة. تُعرِض طريقة 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)

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

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

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

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

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

بشكلٍ تلقائي، لا يمكن النقر على العناصر التي تظهر على سطح الأرض. يمكنك تفعيل إمكانية النقر وإيقافها من خلال الاتصال بالرقم GroundOverlay.setClickable(boolean).

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