Lớp phủ xếp kề

Chọn nền tảng: Android iOS JavaScript

Lớp phủ ô (đôi khi được gọi là lớp ô) là một tập hợp hình ảnh xuất hiện ở trên cùng của các ô bản đồ cơ sở.

Mã mẫu

Kho lưu trữ ApiDemos trên GitHub có một mẫu minh hoạ tính năng lớp phủ xếp kề:

Giới thiệu

TileOverlay xác định một tập hợp hình ảnh được thêm vào phía trên các ô bản đồ cơ sở.

Bạn cần cung cấp các ô cho từng mức thu phóng mà bạn muốn hỗ trợ. Nếu có đủ ô ở nhiều mức thu phóng, bạn có thể bổ sung dữ liệu bản đồ của Google cho toàn bộ bản đồ.

Lớp phủ ô rất hữu ích khi bạn muốn thêm nhiều hình ảnh vào bản đồ, thường bao phủ các khu vực địa lý rộng lớn. Ngược lại, lớp phủ mặt đất sẽ hữu ích khi bạn muốn cố định một hình ảnh tại một khu vực trên bản đồ.

Bạn cũng có thể sử dụng lớp phủ ô trong suốt để thêm các tính năng khác vào bản đồ bằng cách đặt hệ số trong suốt cho lớp phủ ô theo phương thức lập trình hoặc bằng cách cung cấp hình ảnh ô trong suốt.

Tọa độ ô vuông và mức thu phóng

API Google Maps chia hình ảnh ở mỗi mức thu phóng thành một tập hợp các ô bản đồ hình vuông được sắp xếp theo dạng lưới. Khi bản đồ di chuyển đến một vị trí mới hoặc đến một mức thu phóng mới, API Maps sẽ xác định những ô cần thiết và chuyển thông tin đó thành một tập hợp các ô cần truy xuất.

Mảnh có toạ độ (0,0) luôn nằm ở góc tây bắc của bản đồ, với giá trị x tăng dần từ tây sang đông và giá trị y tăng dần từ bắc xuống nam. Các ô được lập chỉ mục bằng toạ độ x,y từ gốc đó.

Ở mức thu phóng 0, toàn bộ thế giới được kết xuất trong một ô duy nhất. Mỗi mức thu phóng sẽ tăng độ phóng đại lên gấp đôi. Vì vậy, ở mức thu phóng 1, bản đồ sẽ được kết xuất dưới dạng lưới ô 2x2. Ở mức thu phóng 2, đó là một lưới 4x4. Ở mức thu phóng 3, đó là lưới 8x8, v.v.

Ví dụ: ở mức thu phóng 2, trái đất được chia thành 16 ô. Bạn có thể tham chiếu từng ô bằng một tổ hợp duy nhất gồm x, y và mức thu phóng:

Bản đồ thế giới được chia thành 4 hàng và 4 cột ô.

Khi tạo hình ảnh cho một lớp ô, bạn cần tạo một hình ảnh cho mỗi ô ở mỗi mức thu phóng mà bạn muốn hỗ trợ. Google Maps nhắm đến 256 dp (pixel không phụ thuộc vào thiết bị) khi hiển thị các ô. Đối với các thiết bị có độ phân giải cao, bạn nên trả về các ô có dpi cao (512x512 px). Hãy tham khảo tài liệu dành cho nhà phát triển Android để biết thông tin về cách hỗ trợ nhiều kích thước và mật độ màn hình.

Lưu ý: Mức thu phóng mà máy ảnh hỗ trợ phụ thuộc vào nhiều yếu tố và không liên quan đến mức thu phóng mà thẻ thông tin của bạn sẽ hỗ trợ.

  1. GoogleMap.getMaxZoomLevel() trả về mức thu phóng tối đa có thể sử dụng ở vị trí hiện tại của camera. Thao tác này sẽ tính đến loại bản đồ hiện đang được sử dụng. Ví dụ: bản đồ vệ tinh hoặc bản đồ địa hình có thể có mức thu phóng tối đa thấp hơn so với các ô bản đồ cơ sở.
  2. GoogleMap.getMinZoomLevel() trả về mức thu phóng tối thiểu, mức này giống nhau cho mọi vị trí (không giống như mức thu phóng tối đa) nhưng có thể khác nhau giữa các thiết bị và kích thước bản đồ.

Thêm lớp phủ ô

Cách đơn giản và phổ biến nhất để tạo lớp phủ ô là cung cấp một URL trỏ đến hình ảnh ô có liên quan. UrlTileProvider là một phần của quá trình triển khai TileProvider. Phần này cung cấp các ô hình ảnh dựa trên một URL. Lớp này yêu cầu tất cả hình ảnh phải có cùng kích thước.

Bạn sẽ cần triển khai UrlTileProvider.getTileUrl(), chấp nhận tọa độ ô vuông (x, y, mức thu phóng) và trả về một URL trỏ đến hình ảnh sẽ được dùng cho ô. Phương thức này sẽ trả về giá trị rỗng nếu không có mảnh bản đồ cho x, y và mức thu phóng đã cho. URL có thể trỏ đến một tài nguyên web, một thành phần Android hoặc một tệp trên ổ đĩa cục bộ.

Thiết lập kho hình ảnh ô trên một máy chủ, được xác định cho tất cả toạ độ x,y và mức thu phóng mà bạn dự định hỗ trợ. Sau đó, hãy thêm lớp phủ ô:

  1. Xác định một UrlTileProvider để cung cấp hình ảnh cho thẻ thông tin.
  2. Ghi đè getTileUrl() để tạo URL cho mỗi hình ảnh ô.
  3. Cung cấp đối tượng TileOverlayOptions có các tuỳ chọn liên quan:
    • fadeIn: Boolean. Chỉ định xem các ô có nên mờ dần hay không. Giá trị mặc định là true. Bạn có thể thấy hữu ích khi tắt hiệu ứng mờ dần khi chuyển đổi nhanh giữa các lớp phủ ô. Để biết thông tin về mối quan hệ giữa độ trong suốt và hiệu ứng mờ dần, hãy xem phần về độ trong suốt bên dưới.
    • tileProvider: TileProvider để dùng cho lớp phủ này.
    • transparency: Số thực có độ chính xác đơn. Đặt hệ số độ trong suốt cho hình ảnh của ô. Giá trị phải nằm trong phạm vi [0.0f, 1.0f], trong đó 0.0f có nghĩa là hoàn toàn mờ đục (mặc định) và 1.0f có nghĩa là hoàn toàn trong suốt. Hãy xem phần về độ trong suốt bên dưới để biết mã mẫu và mối quan hệ giữa độ trong suốt và hiệu ứng mờ dần.
    • visible: Boolean. Chỉ định chế độ hiển thị của lớp phủ ô. Lớp phủ ô không hiển thị (giá trị false) không được vẽ trên bản đồ, nhưng vẫn giữ lại tất cả các thuộc tính khác. Giá trị mặc định là true.
    • zIndex: Xác định thứ tự mà lớp phủ ô sẽ được vẽ so với các lớp phủ khác, bao gồm cả lớp phủ mặt đất , hình tròn, đường nhiều đoạn và đa giác. Lớp phủ có chỉ mục z cao hơn sẽ được vẽ lên trên lớp phủ có chỉ mục z thấp hơn. Thứ tự của các lớp phủ có cùng chỉ mục z là tuỳ ý. Chỉ mục z mặc định là 0. Xin lưu ý rằng các điểm đánh dấu luôn được vẽ phía trên các lớp phủ khác, bất kể chỉ mục z của các lớp phủ khác.
  4. Gọi GoogleMap.addTileOverlay() để thêm lớp phủ vào bản đồ.

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
}

Java

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));

Để xem ví dụ về UrlTileProvider đang hoạt động, hãy tham khảo TileOverlayDemoActivity trong mã mẫu đi kèm với SDK Dịch vụ Google Play.

Đặt độ trong suốt cho lớp phủ ô

Bạn nên phủ các ô trong suốt lên bản đồ để người dùng có thể xem bản đồ cơ sở bên dưới các ô được phủ. Bạn có thể thực hiện việc này bằng cách cung cấp các ô trong suốt của riêng bạn hoặc bằng cách đặt hệ số trong suốt trên lớp phủ ô theo phương thức lập trình.

Mã mẫu sau đây chuyển đổi độ trong suốt của lớp phủ ô giữa 0.5f và 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
}

Java

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());
}

Độ trong suốt được triển khai dưới dạng hệ số nhân kênh alpha cho hình ảnh ô. Để đặt độ trong suốt của lớp phủ xếp kề, hãy cung cấp một đối tượng TileOverlayOptions có transparency trong phạm vi [0.0f, 1.0f] như trong mẫu ở trên. Giá trị 0.0f có nghĩa là lớp phủ xếp kề hoàn toàn mờ đục và 1.0f có nghĩa là lớp phủ xếp kề hoàn toàn trong suốt. Giá trị mặc định là 0.0f (không trong suốt).

Bạn có thể truy cập vào độ trong suốt của lớp phủ ô bằng cách gọi TileOverlay.getTransparency() và thay đổi độ trong suốt đó bằng cách gọi TileOverlay.setTransparency().

Độ trong suốt, ảnh động và hiệu ứng rõ dần

Không có ảnh động khi độ trong suốt thay đổi. Lựa chọn về độ trong suốt hoạt động cùng với lựa chọn fadeIn.

Hiệu ứng mờ dần cung cấp ảnh động về độ trong suốt khi tải thẻ thông tin. Nếu bạn đặt giá trị độ trong suốt, các ô sẽ mờ dần từ hoàn toàn trong suốt đến giá trị độ trong suốt đã xác định. Nếu bạn thay đổi độ trong suốt trong quá trình tăng dần, thì ảnh động sẽ tiếp tục hướng đến độ trong suốt mới của mục tiêu.

Xoá lớp phủ ô

Bạn có thể xoá lớp phủ xếp kề bằng phương thức TileOverlay.remove().

Kotlin

tileOverlay?.remove()

Java

tileOverlay.remove();

Xoá các ô cũ

Nếu các ô do lớp phủ ô cung cấp trở nên "cũ", bạn có thể gọi clearTileCache() để buộc làm mới. Thao tác này sẽ khiến tất cả các ô trên lớp phủ này được tải lại. Ví dụ: nếu các ô do TileProvider cung cấp thay đổi, bạn phải gọi clearTileCache() sau đó để đảm bảo các ô trước đó không còn được kết xuất nữa.

Kotlin

tileOverlay?.clearTileCache()

Java

tileOverlay.clearTileCache();