Растровые тайлы

Для показа растровых тайлов на карте нужно:

подключить их источник в карту;
добавить слой в стиль карты, который объяснит, как рисовать эти тайлы.

Подключение источника тайлов

Для подключения источника тайлов в карту нужно использовать класс RasterTileSource:

const source = new mapgl.RasterTileSource(map, {
    url: (x, y, zoom) => `https://tile.openstreetmap.org/${zoom}/${x}/${y}.png`,
    attribution:
        '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors',
    attributes: { bar: 'asd' },
});

Чтобы источник отличался от других, нужно добавить ему уникальное свойство через поле attributes — теперь его можно связать с новым слоем стиля карты, а значит и отобразить.

Помните, что большинство тайл-серверов требуют указывать копирайт. Сделать это можно через поле attribution.

Добавление слоя в стиль карты

Стиль карты — это конфиг, который описывает как рисовать данные карты. Стиль состоит из слоев. Каждый слой содержит:

в поле filter — логику фильтрации данных карты для определения, какие именно данные будут рисоваться этим слоем;
в поле style — описание внешнего вида объектов отрисовки (цвет, ширина, шрифт и пр.).

Подробнее про стиль карты можно узнать в Спецификации стиля.

Добавление через API

Для начала создадим новый слой:

const layer = {
    id: 'raster-tile-layer', // ID каждого слоя должен быть уникальным

    // Логика фильтрации или выбора данных для этого слоя
    filter: [
        'match',
        ['sourceAttr', 'bar'],
        ['asd'],
        true, // Значение при совпадении атрибута bar источника cо значением "asd"
        false, // Значение при несовпадении
    ],

    // Тип объекта отрисовки
    type: 'raster',

    // Стиль объекта отрисовки
    style: {
        opacity: 1,
    },
};

И добавим слой после загрузки стиля:

map.on('styleload', () => {
    map.addLayer(layer);
});

Здесь в filter используются:

SourceAttrExpression — для получения значений из свойства bar источника данных;
MatchExpression — для сопоставления полученного свойства из атрибута bar со строковым значением "asd".

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Map API</title>
        <meta name="description" content="Raster source example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.425, 25.355],
                zoom: 13,
                key: 'Your API access key',
            });

            const source = new mapgl.RasterTileSource(map, {
                url: (x, y, zoom) => `https://tile.openstreetmap.org/${zoom}/${x}/${y}.png`,

                // Source attribute for data filtering logic
                attributes: { bar: 'asd' },
            })

            const layer = {
                // Drawing object type
                type: 'raster',

                // Each layer ID must be unique
                id: 'raster-tile-layer',

                // Data filtering logic
                filter: [
                    'match',
                    ['sourceAttr', 'bar'], // Match with attribute from data source
                    ['asd'],
                    true, // Result if value of bar source attribute equals "asd"
                    false // Result if not
                ],
                // Style of drawing object
                style: {
                    opacity: 1,
                },
            };

            map.on('styleload', () => {
                map.addLayer(layer);
            });
        </script>
    </body>
</html>