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 các hình ảnh được hiển thị ở đầu các ô bản đồ cơ sở.

Mẫu mã

Kho lưu trữ Apidemos trên GitHub bao gồm một mẫu minh hoạ tính năng lớp phủ thẻ thông tin:

Giới thiệu

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

Bạn cần cung cấp các ô cho mỗi 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ủ xếp kề sẽ hữu ích khi bạn muốn thêm hình ảnh bao quát 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 rất hữu ích khi bạn muốn chỉnh sửa một hình ảnh tại một khu vực trên bản đồ.

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

Toạ độ xếp kề và mức thu phóng

API Google Maps chia nhỏ 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 trong một lưới. Khi bản đồ di chuyển đến một vị trí mới hoặc sang một mức thu phóng mới, API Maps sẽ xác định thẻ thông tin nào cần thiết và chuyển thông tin đó thành một tập hợp các thẻ thông tin để truy xuất.

Ô 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 từ Tây sang Đông và giá trị y tăng từ Bắc xuống Nam. Thẻ thông tin được lập chỉ mục theo toạ độ x,y từ nguồn đó.

Ở mức thu phóng 0, toàn bộ thế giới được hiển thị trong một ô duy nhất. Mỗi mức thu phóng sẽ tăng độ phóng to thêm hai hệ số. 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à 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 ô. Mỗi thẻ thông tin có thể được tham chiếu bằng tổ hợp x, y và mức thu phóng riêng biệt:

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

Khi tạo hình ảnh cho một lớp thẻ thông tin, bạn sẽ cần tạo một hình ảnh cho mỗi thẻ thông tin ở 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 thẻ thông tin. Đối với các thiết bị có độ phân giải cao, bạn nên trả về các thẻ thông tin có dpi cao (512 x 512 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ó sẵn ở vị trí hiện tại của máy ảnh. Điều này có tính đến loại bản đồ đang được sử dụng. Ví dụ: bản đồ vệ tinh hoặc địa hình có thể có mức thu phóng tối đa thấp hơn so với ô bản đồ cơ sở.
  2. GoogleMap.getMinZoomLevel() trả về mức thu phóng tối thiểu, 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ủ xếp kề

Cách đơn giản và phổ biến nhất để tạo một lớp phủ thẻ thông tin là cung cấp URL trỏ đến hình ảnh thẻ thông tin có liên quan. UrlTileProvider là cách triển khai một phần của TileProvider cung cấp các ô hình ảnh dựa trên URL. Lớp này yêu cầu tất cả cá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 các toạ độ thẻ thông tin (x, y, thu phóng) và trả về một URL trỏ đến hình ảnh sẽ được dùng cho thẻ thông tin. Phương thức này sẽ trả về giá trị rỗng nếu không có thẻ thông tin nào cho x, y và mức thu phóng đã cho. URL có thể trỏ đến tài nguyên web, tài sản Android hoặc tệp trên ổ đĩa cục bộ.

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

  1. Xác định UrlTileProvider để cung cấp hình ảnh thẻ thông tin.
  2. Ghi đè getTileUrl() để tạo URL cho từng hình ảnh thẻ thông tin.
  3. Cung cấp một đối tượng TileOverlayOptions kèm theo các tuỳ chọn liên quan:
    • fadeIn: Boolean. Chỉ định xem thẻ thông tin có mờ dần hay không. Giá trị mặc định là true. Bạn nên tắt hiệu ứng mờ dần khi chuyển đổi nhanh giữa các lớp phủ thẻ thông tin. Để biết thông tin về mối quan hệ giữa độ trong suốt và độ mờ, hãy xem phần về độ trong suốt bên dưới.
    • tileProvider: TileProvider để sử dụng cho lớp phủ này.
    • transparency: Số thực. Đặt hệ số trong suốt cho hình ảnh thẻ thông tin. 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ờ (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 dưới đây để biết một mã mẫu cũng như mối quan hệ giữa độ trong suốt và độ mờ.
    • visible: Boolean. Chỉ định chế độ hiển thị của lớp phủ thẻ thông tin. Một lớp phủ xếp kề ẩn (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ự vẽ lớp phủ ô so với các lớp phủ khác, bao gồm lớp phủ mặt đất , hình tròn, hình nhiều đường và đa giác. Lớp phủ có chỉ mục z cao hơn sẽ được vẽ lên trên các 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. Lưu ý rằng đ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 là gì.
  4. Gọi GoogleMap.addTileOverlay() để thêm lớp phủ vào bản đồ.

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

      

Để xem ví dụ về một UrlTileProvider trong thực tế, hãy tham khảo TileOverlayDemoActivity trong mã mẫu đi kèm với SDK của Dịch vụ Google Play.

Đặt độ trong suốt cho lớp phủ thẻ thông tin

Bạn nên phủ các ô trong suốt lên bản đồ để người dùng có thể nhìn thấy 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 thẻ thông tin trong suốt của riêng mình hoặc bằng cách lập trình đặt hệ số trong suốt trên lớp phủ thẻ thông tin.

Mã mẫu sau đây chuyển đổi độ trong suốt của lớp phủ thẻ thông tin giữa 0.5f0.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());
    }
}

      

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

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

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

Không có ảnh động khi độ trong suốt thay đổi. Tuỳ chọn trong suốt hoạt động cùng với tuỳ chọn fadeIn.

Tính năng mờ dần mang lại ảnh động về độ trong suốt khi tải thẻ thông tin. Nếu bạn đặt một giá trị độ trong suốt, các thẻ thông tin sẽ mờ dần từ hoàn toàn trong suốt sang giá trị độ trong suốt đã xác định. Nếu bạn thay đổi độ trong suốt trong khi chuyển dần, ảnh động sẽ tiếp tục hướng tới độ trong suốt mục tiêu mới.

Xoá lớp phủ xếp kề

Bạn có thể xoá lớp phủ thẻ thông tin bằng phương thức TileOverlay.remove().

Kotlin



tileOverlay?.remove()

      

Java


tileOverlay.remove();

      

Xoá thẻ thông tin cũ

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

Kotlin



tileOverlay?.clearTileCache()

      

Java


tileOverlay.clearTileCache();