تراكبات الأرض هي تراكبات صور مرتبطة بتنسيقات خطوط الطول/العرض، لذا تتحرك عند سحب الخريطة أو تكبيرها/تصغيرها.
عيّنات تعليمات برمجية
يتضمن مستودع ApiDemos على GitHub نموذجًا يوضح التراكبات الأرضية:
- GroundOverlayDemoActivity - Java: ميزات تراكب الأرض والمُستمعين في Java
- GroundOverlayDemoActivity - Kotlin: ميزات تراكب Ground والمستمعين في 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)
.