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

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

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

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

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

• ‫GroundOverlayDemoActivity - Java: ميزات تراكب الأرض وأدوات الاستماع في Java
• GroundOverlayDemoActivity - Kotlin: ميزات تراكب الأرض وأدوات الاستماع في Kotlin

مقدمة

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

إضافة تراكب

لإضافة GroundOverlay، أنشئ عنصر GroundOverlayOptions يحدّد كلاً من الصورة والموضع. يمكنك اختياريًا تحديد إعدادات إضافية تؤثّر في موضع الصورة على الخريطة. بعد تحديد الخيارات اللازمة، مرِّر العنصر إلى طريقة GoogleMap.addGroundOverlay() لإضافة الصورة إلى الخريطة. يعرض الإجراء addGroundOverlay() عنصر GroundOverlay، وعليك الاحتفاظ بمرجع لهذا العنصر إذا أردت تعديله لاحقًا.

ملاحظة: عند إضافة الصورة إلى الخريطة، سيتم تحويلها إلى صورة ذات جوانب من مضاعفات الرقم اثنين. يمكنك تجنُّب هذا التحويل باستخدام صورة أصلية بأبعاد من مضاعفات الرقم اثنين، على سبيل المثال، 128×512 أو 1024×1024.

الخطوات بالتفصيل:

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)

      

جافا

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)

      

جافا

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

      

إزالة تراكب

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

Kotlin

imageOverlay?.remove()

      

جافا

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

      

جافا

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

      

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

تحديد موضع "طبقة الأرض"

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

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

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

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

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

      

جافا

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)

      

جافا

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"

      

جافا

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

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