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

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

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

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

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

مقدمة

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

إضافة تراكب

لإضافة 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 حالي.

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