رونهادهای کاشی

پلاتفرم را انتخاب کنید: Android iOS JavaScript

رونهاد کاشی، که گاهی لایه کاشی نامیده می‌شود، مجموعه‌ای از تصاویر است که روی کاشی‌های نقشه مبنا نمایش داده می‌شود.

نمونه‌های کد

مخزن ApiDemos در GitHub شامل نمونه‌ای است که ویژگی رونهاد کاشی را نشان می‌دهد:

• TileOverlayDemoActivity - Java: ویژگی‌های رونهاد کاشی در جاوا
• TileCoordinateDemoActivity - Java: سیستم مختصات استفاده‌شده برای رونهادهای کاشی در جاوا
• TileOverlayDemoActivity - Kotlin: ویژگی‌های رونهاد کاشی در Kotlin
• TileCoordinateDemoActivity - Kotlin: سیستم مختصات استفاده‌شده برای رونهادهای کاشی در Kotlin

مقدمه

A TileOverlay مجموعه‌ای از تصاویر را تعریف می‌کند که در بالای کاشی‌های نقشه پایه اضافه می‌شوند.

باید کاشی‌ها را برای هر سطح بزرگ‌نمایی که می‌خواهید پشتیبانی شود ارائه دهید. اگر در سطوح بزرگ‌نمایی مختلف کاشی‌های کافی داشته باشید، می‌توانید داده‌های نقشه Google را برای کل نقشه تکمیل کنید.

رونهادهای کاشی زمانی مفید هستند که بخواهید تصاویر گسترده‌ای به نقشه اضافه کنید، که معمولاً مناطق جغرافیایی بزرگی را پوشش می‌دهند. درمقابل، پوشش‌های زمین زمانی مفید هستند که بخواهید یک تصویر واحد را در یک منطقه روی نقشه ثابت کنید.

همچنین می‌توانید از رونهادهای کاشی شفاف برای افزودن ویژگی‌های اضافی به نقشه استفاده کنید، با تنظیم عامل شفافیت روی رونهاد کاشی به‌صورت برنامه‌نویسی‌شده یا با ارائه تصاویر کاشی شفاف.

مختصات کاشی و سطوح بزرگ‌نمایی

‫Google Maps API تصاویر را در هر سطح بزرگ‌نمایی به مجموعه‌ای از کاشی‌های نقشه مربعی که در یک شبکه چیده شده‌اند تقسیم می‌کند. وقتی نقشه به مکان جدیدی منتقل می‌شود، یا به سطح بزرگ‌نمایی جدیدی می‌رود، Maps API تعیین می‌کند که به کدام کاشی‌ها نیاز است و این اطلاعات را به مجموعه‌ای از کاشی‌ها برای بازیابی ترجمه می‌کند.

کاشی با مختصات (۰،۰) همیشه در گوشه شمال‌غربی نقشه قرار دارد، با مقادیر x که از غرب به شرق افزایش می‌یابد و مقادیر y که از شمال به جنوب افزایش می‌یابد. کاشی‌ها بااستفاده از مختصات x و y از آن مبدأ نمایه‌سازی می‌شوند.

در سطح بزرگ‌نمایی ۰، کل جهان در یک کاشی واحد ارائه می‌شود. هر سطح بزرگ‌نمایی میزان بزرگ‌نمایی را دو برابر می‌کند. بنابراین، در سطح بزرگ‌نمایی ۱، نقشه به‌صورت شبکه‌ای ۲×۲ از کاشی‌ها ارائه می‌شود. در سطح بزرگ‌نمایی ۲، جدول ۴×۴ است. در سطح بزرگ‌نمایی ۳، شبکه ۸×۸ است و به همین ترتیب.

برای مثال، در سطح بزرگ‌نمایی ۲، زمین به ۱۶ کاشی تقسیم می‌شود. هر کاشی می‌تواند با ترکیب منحصربه‌فردی از x،‏ y، و بزرگ‌نمایی ارجاع داده شود:

هنگام ایجاد تصاویر برای لایه کاشی، باید برای هر کاشی در هر سطح بزرگ‌نمایی که می‌خواهید پشتیبانی کنید، یک تصویر ایجاد کنید. ‫Google Maps هنگام نمایش کاشی‌ها، ۲۵۶ پیکسل مستقل از دستگاه (dp) را هدف‌یابی می‌کند. برای دستگاه‌های با وضوح بالا، توصیه می‌شود کاشی‌های با dpi بالا (۵۱۲×۵۱۲ پیکسل) برگردانید. برای کسب اطلاعات درباره پشتیبانی از اندازه‌ها و تراکم‌های مختلف صفحه‌نمایش، به اسناد توسعه‌دهندگان Android مراجعه کنید.

توجه: سطوح بزرگ‌نمایی پشتیبانی‌شده توسط دوربین به عوامل مختلفی بستگی دارد و با سطوح بزرگ‌نمایی که کاشی‌هایتان پشتیبانی می‌کنند مرتبط نیست.

1. GoogleMap.getMaxZoomLevel() حداکثر سطح بزرگ‌نمایی در موقعیت کنونی دوربین را برمی‌گرداند. این گزینه نوع نقشه‌ای را که درحال‌حاضر استفاده می‌شود درنظر می‌گیرد. برای مثال، نقشه ماهواره‌ای یا زمین‌نمایی ممکن است سطح بزرگ‌نمایی بیشینه پایین‌تری نسبت‌به کاشی‌های نقشه پایه داشته باشد.
2. GoogleMap.getMinZoomLevel() حداقل سطح بزرگ‌نمایی را برمی‌گرداند، که برای همه مکان‌ها یکسان است (برخلاف حداکثر سطح بزرگ‌نمایی) اما ممکن است بین دستگاه‌ها و اندازه‌های نقشه متفاوت باشد.

افزودن رونهاد کاشی

ساده‌ترین و رایج‌ترین روش برای ایجاد رونهاد کاشی، ارائه نشانی وبی است که به تصویر کاشی مربوطه اشاره می‌کند. UrlTileProvider پیاده‌سازی جزئی از TileProvider است که کاشی‌های تصویر را براساس نشانی وب ارائه می‌دهد. این کلاس مستلزم این است که همه تصاویر ابعاد یکسانی داشته باشند.

باید UrlTileProvider.getTileUrl() را پیاده‌سازی کنید که مختصات کاشی (x،‏ y، بزرگ‌نمایی) را می‌پذیرد و نشانی وبی را برمی‌گرداند که به تصویری اشاره می‌کند که باید برای کاشی استفاده شود. اگر کاشی‌ای برای x،‏ y، و بزرگ‌نمایی داده‌شده وجود نداشته باشد، این روش باید مقدار تهی برگرداند. نشانی وب می‌تواند به منبع وب، دارایی Android، یا فایلی در دیسک محلی اشاره کند.

مجموعه تصاویر کاشی را در سروری راه‌اندازی کنید که برای همه مختصات x و y و سطوح بزرگ‌نمایی که قصد پشتیبانی از آن‌ها را دارید تعریف شده باشد. سپس رونهاد کاشی را اضافه کنید: رونهاد کاشی:

1. یک UrlTileProvider برای ارائه تصاویر کاشی تعریف کنید.
2. برای ساختن نشانی وب برای هر تصویر کاشی، getTileUrl() را لغو کنید.
3. یک شیء TileOverlayOptions با گزینه‌های مربوطه ارائه دهید:
• fadeIn: بولی. مشخص می‌کند که آیا کاشی‌ها باید به‌تدریج ظاهر شوند یا نه. مقدار پیش‌فرض true است. اگر می‌خواهید به‌سرعت بین رونهادهای کاشی جابه‌جا شوید، شاید بهتر باشد ظاهر شدن تدریجی را خاموش کنید. برای اطلاعات بیشتر درباره رابطه بین شفافیت و ظهور تدریجی، به بخش شفافیت در زیر مراجعه کنید.
• tileProvider: TileProvider برای استفاده در این رونهاد.
• ‫transparency: شناور. عامل شفافیت را برای تصاویر کاشی تنظیم می‌کند. مقدار باید در محدوده [0.0f, 1.0f] باشد که 0.0f به‌معنای کاملاً مات (پیش‌فرض) و 1.0f به‌معنای کاملاً شفاف است. برای دیدن نمونه کد و رابطه بین شفافیت و محو شدن تدریجی، به بخش شفافیت در زیر مراجعه کنید.
• ‫visible: بولی. رؤیت‌پذیری رونهاد کاشی را مشخص می‌کند. رونهاد کاشی نامرئی (مقدار false) روی نقشه ترسیم نمی‌شود، اما همه ویژگی‌های دیگرش را حفظ می‌کند. پیش‌فرض true است.
• zIndex: ترتیب ترسیم رونهاد کاشی را نسبت به رونهادهای دیگر، ازجمله رونهادهای زمین ، دایره‌ها، چندخطی‌ها، و چندضلعی‌ها تعیین می‌کند. رونهادهایی با شاخص z بالاتر روی رونهادهایی با شاخص z پایین‌تر رسم می‌شوند. ترتیب هم‌پوشانی‌ها با نمایه z یکسان اختیاری است. شاخص z پیش‌فرض ۰ است. توجه داشته باشید که نشانگرها همیشه بالای رونهادهای دیگر رسم می‌شوند، صرف‌نظر از شاخص z رونهادهای دیگر.
4. برای افزودن هم‌پوشانی به نقشه، GoogleMap.addTileOverlay() را فراخوانی کنید.

Kotlin

val 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)
)
tileOverlay?.let {
    val isVisible = it.isVisible
    val fadeIn = it.fadeIn
    val transparency = it.transparency
    val zIndex = it.zIndex
}

      

جاوا

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(java.util.Locale.US, "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 در کد نمونه که با کیت توسعه نرم‌افزار خدمات Google Play همراه است مراجعه کنید.

توجه: اگر به کنترل بیشتری نیاز دارید، می‌توانید با پیاده‌سازی میانای TileProvider، ارائه‌دهنده کاشی تعریف کنید.

تنظیم شفافیت برای رونهادهای کاشی

پوشاندن کاشی‌های شفاف روی نقشه می‌تواند مفید باشد، به‌طوری‌که کاربران بتوانند نقشه پایه را زیر کاشی‌های رونهادشده ببینند. می‌توانید این کار را با ارائه کاشی‌های شفاف خودتان یا با تنظیم عامل شفافیت در رونهاد کاشی به‌صورت برنامه‌نویسی‌شده انجام دهید.

نمونه کد زیر شفافیت رونهاد کاشی را بین 0.5f و 0.0f تغییر می‌دهد:

Kotlin

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

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

      

جاوا

TileOverlay tileOverlayTransparent = map.addTileOverlay(new TileOverlayOptions()
    .tileProvider(new UrlTileProvider(256, 256) {
        // ...
    })
    .transparency(0.5f));

// Switch between 0.0f and 0.5f transparency.
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()

      

جاوا

tileOverlay.remove();

      

پاک کردن کاشی‌های قدیمی

اگر کاشی‌های ارائه‌شده توسط رونهاد کاشی «قدیمی» شدند، می‌توانید clearTileCache() را برای اجبار کردن بازآوری فراخوانی کنید. این کار باعث می‌شود همه کاشی‌های این رونهاد دوباره بار شود. برای مثال، اگر کاشی‌های ارائه‌شده توسط TileProvider تغییر کند، باید بعداز آن clearTileCache() را فراخوانی کنید تا مطمئن شوید کاشی‌های قبلی دیگر پرداز نمی‌شوند.

Kotlin

tileOverlay?.clearTileCache()

      

جاوا

tileOverlay.clearTileCache();