تراكبات الأرض هي تراكبات صور مرتبطة بإحداثيات خطوط الطول/العرض، وبذلك تتحرك عند سحب الخريطة أو تكبيرها/تصغيرها.
عيّنات تعليمات برمجية
يتضمّن مستودع ApiDemos على GitHub عيّنة توضّح التراكبات الأساسية:
- GroundOverlayDemoActivity - لغة جافا: ميزات ومستمعي التراكبات الأرضية في جافا
- GroundoverlayDemoActivity - 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
حالي.
لغة 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);
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)
إذا كنت ترغب في تغيير تراكب الأرض أو إزالته بعد إضافته إلى الخريطة، تأكد من الاحتفاظ بالكائن GroundOverlay
. يمكنك تعديل التراكب في وقت لاحق عن طريق إجراء تغييرات على هذا الكائن.
لغة Java
// Add an overlay to the map, retaining a handle to the GroundOverlay object. GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);
Kotlin
// Add an overlay to the map, retaining a handle to the GroundOverlay object. val imageOverlay = map.addGroundOverlay(newarkMap)
إزالة تركيب
يمكنك إزالة التراكب الأرضي باستخدام طريقة GroundOverlay.remove()
.
لغة Java
imageOverlay.remove();
Kotlin
imageOverlay?.remove()
تغيير تراكب
يمكنك تغيير صورة التراكب الأرضي بعد إضافتها إلى الخريطة باستخدام طريقة GroundOverlay.setImage(BitmapDescriptor)
.
لغة Java
// Update the GroundOverlay with a new image of the same dimension imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));
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))
ستستبدل طريقة setImage()
الصورة الحالية بصورة أخرى
بالأبعاد نفسها.
وضع تراكب الأرض
هناك طريقتان لتحديد موضع تراكب الأرض:
- استخدام
LatLng
لتركيب التراكب والأبعاد بالأمتار لتحديد حجم الصورة. - يمكنك استخدام
LatLngBounds
لتحديد الزوايا الشمالية الشرقية والجنوبية الغربية للصورة.
يجب تحديد موضع تراكب الأرض قبل إضافته إلى الخريطة.
استخدام الموقع لتحديد موضع الصورة
عند إضافة الصورة، يمكنك تحديد خط الطول والعرض الذي سيتم تثبيت المرساة عليه
وعرض التراكب (بالأمتار). ويتم ضبط
anchor
تلقائيًا على مركز
الصورة. ويمكنك اختياريًا تحديد ارتفاع التراكب (بالأمتار). إذا لم تقدم ارتفاع التراكب، فسيتم حسابه تلقائيًا للحفاظ على نسب الصورة.
يعمل الرمز التالي على وضع الصورة في الموضع 40.714086, -74.228697
بعرض 8.6 كم وارتفاع 6.5 كم. يتم تثبيت الصورة في أسفل يمين الشاشة.
لغة 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);
Kotlin
val newarkMap = GroundOverlayOptions() .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922)) .anchor(0f, 1f) .position(LatLng(40.714086, -74.228697), 8600f, 6500f)
استخدم LatLngBounds لتحديد موضع إحدى الصور
يمكنك تقديم LatLngBounds
يحتوي على الصورة. يعيِّن LatLngBounds
الزوايا الشمالية الشرقية والجنوبية الغربية للصورة. عندما يتم رسم الصورة على الخريطة، سيتم تدويرها لتتناسب مع الحدود. إذا لم تتطابق الحدود مع نسبة العرض إلى الارتفاع الأصلية، فسيتم انحراف الصورة.
يعمل الرمز أدناه على وضع صورة على الخريطة مع توجّه زاويتها من الجنوب الغربي إلى
40.712216,-74.22655
، والركن الشمالي الشرقي المرتبط بها
40.773941, -74.12544
.
لغة 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);
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)
ربط البيانات بتراكب أرضي
يمكنك استدعاء GroundOverlay.setTag()
لتخزين كائن بيانات عشوائي مع تراكب أرضي، واسترداد كائن البيانات باستخدام GroundOverlay.getTag()
.
يخزّن نموذج الرمز التالي وصف سلسلة مع تراكب على سطح الأرض:
لغة 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");
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"
في ما يلي بعض الأمثلة على سيناريوهات عندما يكون من المفيد تخزين البيانات واستردادها باستخدام تراكبات الأرضية:
- قد يلبي تطبيقك تراكبات الأرض المختلفة، وتريد أن تتعامل معها بشكل مختلف عند نقر المستخدم عليها.
- قد تواجه نظامًا له معرّفات سجل فريدة، حيث تمثل التراكبات سجلات معينة في هذا النظام.
- قد تشير بيانات التراكب إلى الأولوية لتحديد مؤشر z للتراكب.
التعامل مع أحداث تراكب الأرضية
افتراضيًا، لا تكون تراكبات الأرض قابلة للنقر. يمكنك تفعيل إمكانية النقر وإيقافها من خلال الاتصال على
GroundOverlay.setClickable(boolean)
.
استخدِم OnGroundOverlayClickListener
للاستماع إلى أحداث النقر على سطح مركّب قابل للنقر. لضبط أداة معالجة البيانات هذه على
الخريطة، اتصل برقم
GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener)
.
عندما ينقر المستخدم على تراكب الأرضية، ستتلقى معاودة اتصال من onGroundOverlayClick(GroundOverlay)
.