تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

يتضمن مستودع 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 حالي.

لغة 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) معاودة الاتصال.

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