تراكبات البلاط

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

تراكب الصور، الذي يُطلق عليه أحيانًا اسم طبقة المربّعات، هو مجموعة من الصور التي يتم عرضها أعلى مربعات الخرائط الأساسية.

تعليمات برمجية نموذجية

يشمل مستودع ApiDemos على GitHub نموذجًا يوضح ميزة تراكب الصور:

مقدمة

تحدّد السمة TileOverlay مجموعة من الصور التي تتم إضافتها فوق مربّعات الخرائط الأساسية.

تحتاج إلى توفير الفئات لكل مستوى تكبير/تصغير تريد توفيره. إذا كان لديك ما يكفي من المربّعات بمستويات تكبير/تصغير متعددة، يمكنك استكمال بيانات الخريطة من Google للخريطة بأكملها.

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

يمكنك أيضًا استخدام تراكبات المربعات الشفافة لإضافة ميزات إضافية إلى الخريطة، عن طريق ضبط عامل شفافية على تراكب الصور بشكل آلي أو من خلال توفير صور مربّعات شفافة.

إحداثيات المربّعات ومستويات التكبير أو التصغير

في Google Maps API، تقسّم الصور في كل مستوى من مستويات التكبير أو التصغير إلى مجموعة من مربّعات الخرائط المربّعة والمرتّبة على شكل شبكة. عندما تتحرك خريطة إلى موقع جديد أو إلى مستوى تكبير/تصغير جديد، تحدّد Maps API الفئات المطلوبة وتترجم تلك المعلومات إلى مجموعة من المربّعات لاستردادها.

يقع المربّع الذي يتضمّن إحداثيات (0,0) دائمًا في الزاوية الشمالية الغربية من الخريطة، مع زيادة قيم المحور "س" من الغرب إلى الشرق وقيم "ص" من الشمال إلى الجنوب. تتم فهرسة المربعات باستخدام الإحداثيات x,y من هذا الأصل.

عند مستوى التكبير/التصغير 0، يتم عرض العالم بالكامل في مربّع واحد. ويؤدي كل مستوى من مستويات التكبير أو التصغير إلى زيادة التكبير بمقدار معامل اثنين. لذلك، عند مستوى التكبير أو التصغير 1، سيتم عرض الخريطة على شكل شبكة مربّعات بحجم 2×2. في مستوى التكبير/التصغير 2، تكون عبارة عن شبكة 4×4. في مستوى التكبير/التصغير 3، تكون عبارة عن شبكة 8×8، وهكذا.

على سبيل المثال، عند مستوى التكبير أو التصغير 2، يتم تقسيم الأرض إلى 16 مربّعًا. يمكن الإشارة إلى كل مربّع من خلال مجموعة فريدة تضم x وy وzoom:

خريطة للعالم مقسّمة إلى أربعة صفوف وأربعة أعمدة من المربّعات.

عند إنشاء صور لطبقة أحد مربّعات الاختيار، يجب إنشاء صورة لكل مربّع في كل مستوى تكبير تريد إتاحة عرضه. تستهدف "خرائط Google" 256 بكسل مستقل الكثافة (بكسل مستقلة عن الجهاز) عند عرض المربّعات. بالنسبة إلى الأجهزة العالية الدقة، يُنصَح بعرض مربّعات نقاط لكل بوصة (DPI) عالية (512×512 بكسل). يُرجى الرجوع إلى مستندات مطوّري برامج Android للحصول على معلومات حول التوافق مع أحجام الشاشات وكثافاتها المختلفة.

ملاحظة: تعتمد مستويات التكبير أو التصغير التي توفّرها الكاميرا على عوامل مختلفة، ولا ترتبط بمستويات التكبير أو التصغير التي تتوافق معها مربّعاتك.

  1. تعرض العلامة GoogleMap.getMaxZoomLevel() الحد الأقصى لمستوى التكبير المتاح في موضع الكاميرا الحالي. ويأخذ ذلك في الاعتبار نوع الخريطة المستخدَم حاليًا. على سبيل المثال، قد يكون الحد الأقصى لمستوى تكبير/تصغير خريطة القمر الصناعي أو خريطة التضاريس أقل من مربّعات الخريطة الأساسية.
  2. يعرض GoogleMap.getMinZoomLevel() الحد الأدنى لمستوى التكبير/التصغير، وهو نفسه لكل موقع جغرافي (على عكس الحد الأقصى لمستوى التكبير/التصغير)، ولكنه قد يختلف باختلاف الأجهزة وأحجام الخرائط.

إضافة تراكب مربّعات

إنّ الطريقة الأبسط والأكثر شيوعًا لإنشاء تراكب مربّعات هي تقديم عنوان URL يشير إلى صورة المربّع ذي الصلة. UrlTileProvider هو تنفيذ جزئي لواجهة TileProvider التي توفّر أقسام صور تستند إلى عنوان URL. تتطلّب هذه الفئة أن يكون لجميع الصور الأبعاد نفسها.

ستحتاج إلى تطبيق العلامة UrlTileProvider.getTileUrl() التي تقبل إحداثيات المربّعات (س، ص، تكبير/تصغير)، وتعرض عنوان URL يشير إلى الصورة لاستخدامها في المربّع. من المفترض أن تعرض الطريقة قيمة فارغة في حال عدم توفُّر مربّع للإطارات x وy والتكبير/التصغير المذكورة. ويمكن أن يشير عنوان URL إلى مورد ويب أو مادة عرض Android أو ملف على قرص محلي.

يمكنك إعداد مخزونك من صور المربّعات على خادم، مع تحديد جميع إحداثيات x وy ومستويات التكبير/التصغير التي تريد إتاحة عرضها. بعد ذلك، أضِف تراكب الصور:

  1. حدِّد UrlTileProvider لتوفير صور المربّعات.
  2. يمكنك تجاوز getTileUrl() لإنشاء عنوان URL لكل صورة مقسّمة إلى أجزاء.
  3. قدِّم عنصر TileOverlayOptions مع الخيارات ذات الصلة:
    • fadeIn: منطقي. لتحديد ما إذا كان يجب أن تتلاشى المربّعات أم لا. القيمة التلقائية هي true. وقد يكون من المفيد إيقاف تلاشي عند التبديل بين تراكبات المربّعات بسرعة. لمزيد من المعلومات عن العلاقة بين الشفافية والتلاشي، يمكنك مراجعة القسم حول الشفافية أدناه.
    • tileProvider: السمة TileProvider المطلوب استخدامها لهذا التراكب.
    • transparency: بيانات عائمة تحدِّد عامل شفافية للصور المقسّمة. يجب أن تكون القيمة ضمن النطاق [0.0f, 1.0f] حيث يعني 0.0f معتمًا بالكامل (تلقائيًا) ويعني 1.0f شفافًا تمامًا. يمكنك الاطّلاع على القسم حول الشفافية أدناه للاطّلاع على عيّنة من الرمز والعلاقة بين الشفافية والتلاشي.
    • visible: منطقي. تحدد هذه السمة مستوى رؤية تراكب الصور. لا يتم رسم تراكب مربّعات غير مرئية (القيمة false) على الخريطة، ولكن يحتفظ بجميع خصائصه الأخرى. والقيمة التلقائية هي true.
    • zIndex: لتحديد ترتيب رسم تراكب الصور بالنسبة إلى التركيبات الأخرى، بما في ذلك تراكبات الأرض والدوائر والخطوط المتعددة والمضلعات. يتم رسم التراكبات ذات المؤشر z الأعلى فوق تلك التي تحتوي على فهارس z منخفضة. ويكون ترتيب التراكبات التي لها مؤشر z نفسه أمرًا عشوائيًا. مؤشر z التلقائي هو 0. يُرجى العِلم أنّ العلامات يتم رسمها دائمًا فوق تراكبات أخرى، بغض النظر عن الفهرس z للتراكبات الأخرى.
  4. اطلب GoogleMap.addTileOverlay() لإضافة العنصر إلى الخريطة.

Kotlin



private lateinit var map: GoogleMap

var tileProvider: TileProvider = object : UrlTileProvider(256, 256) {
    override fun getTileUrl(x: Int, y: Int, zoom: Int): URL? {

        /* Define the URL pattern for the tile images */
        val url = "http://my.image.server/images/$zoom/$x/$y.png"
        return if (!checkTileExists(x, y, zoom)) {
            null
        } else try {
            URL(url)
        } catch (e: MalformedURLException) {
            throw AssertionError(e)
        }
    }

    /*
     * Check that the tile server supports the requested x, y and zoom.
     * Complete this stub according to the tile range you support.
     * If you support a limited range of tiles at different zoom levels, then you
     * need to define the supported x, y range at each zoom level.
     */
    private fun checkTileExists(x: Int, y: Int, zoom: Int): Boolean {
        val minZoom = 12
        val maxZoom = 16
        return zoom in minZoom..maxZoom
    }
}

val tileOverlay = map.addTileOverlay(
    TileOverlayOptions()
        .tileProvider(tileProvider)
)

Java


private GoogleMap map;

TileProvider tileProvider = new UrlTileProvider(256, 256) {

    @Override
    public URL getTileUrl(int x, int y, int zoom) {

        /* Define the URL pattern for the tile images */
        String s = String.format("http://my.image.server/images/%d/%d/%d.png", zoom, x, y);

        if (!checkTileExists(x, y, zoom)) {
            return null;
        }

        try {
            return new URL(s);
        } catch (MalformedURLException e) {
            throw new AssertionError(e);
        }
    }

    /*
     * Check that the tile server supports the requested x, y and zoom.
     * Complete this stub according to the tile range you support.
     * If you support a limited range of tiles at different zoom levels, then you
     * need to define the supported x, y range at each zoom level.
     */
    private boolean checkTileExists(int x, int y, int zoom) {
        int minZoom = 12;
        int maxZoom = 16;

        return (zoom >= minZoom && zoom <= maxZoom);
    }
};

TileOverlay tileOverlay = map.addTileOverlay(new TileOverlayOptions()
    .tileProvider(tileProvider));

للاطّلاع على مثال عملي على UrlTileProvider، يمكنك الرجوع إلى TileOverlayDemoActivity في نموذج الرمز المضمّن في حزمة تطوير البرامج (SDK) لخدمات Google Play.

ضبط شفافية تراكبات الصور

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

يعمل الرمز النموذجي التالي على تبديل شفافية تراكب المربّعات بين 0.5f و0.0f:

Kotlin



private var tileOverlayTransparent: TileOverlay? = null

override fun onMapReady(map: GoogleMap) {
    tileOverlayTransparent = map.addTileOverlay(
        TileOverlayOptions()
            .tileProvider(object : UrlTileProvider(256, 256) {
                // ...
            })
            .transparency(0.5f)
    )
}

// Switch between 0.0f and 0.5f transparency.
fun toggleTileOverlayTransparency() {
    tileOverlayTransparent?.let {
        it.transparency = 0.5f - it.transparency
    }
}

Java


private TileOverlay tileOverlayTransparent;

@Override
public void onMapReady(GoogleMap map) {
    tileOverlayTransparent = map.addTileOverlay(new TileOverlayOptions()
        .tileProvider(new UrlTileProvider(256, 256) {
            // ...
        })
        .transparency(0.5f));
}

// Switch between 0.0f and 0.5f transparency.
public void toggleTileOverlayTransparency() {
    if (tileOverlayTransparent != null) {
        tileOverlayTransparent.setTransparency(0.5f - tileOverlayTransparent.getTransparency());
    }
}

يتم تطبيق الشفافية كمُضاعِف قناة ألفا لصور المربّعات. لضبط شفافية تراكب مربّعات، قدِّم عنصر TileOverlayOptions يحتوي على transparency في النطاق [0.0f, 1.0f] كما هو موضّح في العيّنة أعلاه. أما القيمة 0.0f، فتعني أنّ تراكب الصور غير شفاف تمامًا، بينما تشير القيمة 1.0f إلى أنه شفاف بالكامل. وتكون القيمة التلقائية 0.0f (قيمة مبهمة).

يمكنك الوصول إلى شفافية تراكب الصور من خلال طلب TileOverlay.getTransparency()، ويمكنك تغييرها من خلال طلب TileOverlay.setTransparency().

الشفافية والرسوم المتحركة والتلاشي

لا توجد رسوم متحركة عند تغيير الشفافية. يعمل خيار الشفافية جنبًا إلى جنب مع الخيار fadeIn.

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

إزالة تراكب مربّعات

يمكنك إزالة مربّع مركّب باستخدام طريقة TileOverlay.remove().

Kotlin



tileOverlay?.remove()

Java


tileOverlay.remove();

محو المربّعات القديمة

إذا أصبحت المربّعات المتوفّرة من خلال تراكب المربّعات "قديمة"، يمكنك استدعاء clearTileCache() لفرض إعادة التحميل. سيؤدي ذلك إلى إعادة تحميل كل المربّعات الظاهرة على هذا التراكب. على سبيل المثال، إذا تغيّرت المربّعات التي يوفّرها تغيير TileProvider، يجب طلب clearTileCache() بعد ذلك لضمان عدم عرض المربّعات السابقة.

Kotlin



tileOverlay?.clearTileCache()

Java


tileOverlay.clearTileCache();