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

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

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