تراكبات الأرض هي تراكبات صور مرتبطة بتنسيقات خطوط الطول/العرض، لذلك تتحرك عند سحب الخريطة أو تكبيرها/تصغيرها.
عيّنات تعليمات برمجية
يتضمن مستودع ApiDemos على GitHub نموذجًا يوضح التراكبات الأرضية:
- GroundgroundDemoActivity - Java: مزايا تراكب الأرض والمستمعين في Java
- GroundLayerDemoActivity - Kotlin: يتضمّن ميزات تراكب الأرض والمستمعين في لغة Kotlin.
المقدّمة
التراكب الأرضي هو صورة ثابتة على خريطة. على عكس العلامات، يتم توجيه تراكبات الأرض على سطح الأرض بدلاً من الشاشة، لذا فإن تدوير الخريطة أو إمالتها أو تكبيرها/تصغيرها سيؤدي إلى تغيير اتجاه الصورة. تراكبات الأرض مفيدة عندما ترغب في إصلاح صورة واحدة في منطقة واحدة على الخريطة. إذا كنت ترغب في إضافة صور شاملة تغطي جزءًا كبيرًا من الخريطة، فيجب عليك التفكير في تراكب تجانب.
إضافة تراكب
لإضافة GroundOverlay
، أنشِئ كائن
GroundOverlayOptions
يحدّد الصورة والموضع. يمكنك اختياريًا تحديد إعدادات إضافية من شأنها
أن تؤثر على موضع الصورة على الخريطة. بعد تحديد الخيارات اللازمة، مرِّر الكائن إلى طريقة GoogleMap.addGroundOverlay()
لإضافة الصورة إلى الخريطة. تعرض الطريقة addGroundOverlay()
كائن GroundOverlay
، وعليك الاحتفاظ بمرجع إلى هذا الكائن إذا أردت تعديله لاحقًا.
الخطوات التفصيلية:
- إنشاء مثيل لعنصر
GroundOverlayOptions
جديد - عليك تحديد الصورة لتكون
BitmapDescriptor
. - يمكنك ضبط موضع الصورة باستخدام إحدى الطرق المتاحة:
position(LatLng location, float width, float height)
position(LatLng location, float width)
positionFromBounds(LatLngBounds bounds)
- اضبُط أي سمات اختيارية، مثل
transparency
، على النحو المطلوب. - اتصل بـ
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)
معاودة الاتصال.