Добавление иконок

При добавлении стилевого слоя часто возникает необходимость добавить к нему и новую иконку. Сделать это можно в редакторе стилей или через метод addIcon() у карты:

map.addIcon('newIconName', { url: '//path_to_icon/icon.svg' });

В качестве аргументов метод принимает имя иконки и ее конфигурацию StyleIconConfig. Эта конфигурация также позволяет задавать тянущуюся по тексту иконку, как у объекта Label.

На данный момент есть несколько ограничений по работе с этим методом:

в качестве URL может использоваться только абсолютный или шаблонный путь, например, //absolute_path_to_icon/icon.svg или //{appHost}/path_to_icon/icon.svg.

<!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="Adding user icon 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.26961558517149, 25.20161682758841],
                zoom: 16,
                key: 'Your API access key',
            });

            const data = {
                type: 'FeatureCollection',
                features: [
                    {
                        type: 'Feature',
                        properties: {},
                        geometry: {
                            type: 'Point',
                            coordinates: map.getCenter(),
                        },
                    },
                ],
            };


            const source = new mapgl.GeoJsonSource(map, {
                data,
                attributes: {
                    purpose: 'icon',
                },
            });

            const layer = {
                id: 'my-point-layer',
                filter: [
                    'match',
                    ['sourceAttr', 'purpose'],
                    ['icon'],
                    true,
                    false,
                ],
                type: 'point',
                style: {
                    iconImage: 'custom',
                    iconWidth: 30,
                    iconPriority: 1000
                },
            };

            map.on('styleload', () => {
                map.addIcon('custom', { url: 'https://docs.2gis.com/img/mapgl/point-red.svg'});
                map.addLayer(layer);
            });
        </script>
    </body>
</html>

Изменение ранее добавленной иконки

Чтобы обновить ранее добавленную иконку, сначала ее нужно удалить, а затем добавить новую:

map.removeIcon('newIconName');
map.addIcon('newIconName', { url: '//path_to_icon/new-icon.svg' });

<!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="Changing user icon 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.26961558517149, 25.20161682758841],
                zoom: 16,
                key: 'Your API access key',
            });

            const data = {
                type: 'FeatureCollection',
                features: [
                    {
                        type: 'Feature',
                        properties: {},
                        geometry: {
                            type: 'Point',
                            coordinates: map.getCenter(),
                        },
                    },
                ],
            };


            const source = new mapgl.GeoJsonSource(map, {
                data,
                attributes: {
                    purpose: 'icon',
                },
            });

            const layer = {
                id: 'my-point-layer',
                filter: [
                    'match',
                    ['sourceAttr', 'purpose'],
                    ['icon'],
                    true,
                    false,
                ],
                type: 'point',
                style: {
                    iconImage: 'custom',
                    iconWidth: 30,
                    iconPriority: 1000
                },
            };

            map.on('styleload', () => {
                map.addIcon('custom', { url: 'https://docs.2gis.com/img/mapgl/point-red.svg'});
                map.addLayer(layer);
                map.once('idle', () => {
                    map.removeIcon('custom');
                    map.addIcon('custom', { url: 'https://docs.2gis.com/img/mapgl/point-green.svg'});
                });
            });
        </script>
    </body>
</html>

Изменение иконки из стиля

Для изменения иконки из стиля необходимо знать ее имя. Сам процесс аналогичен тому, что описан выше:

map.removeIcon('metro_red_uae');
map.addIcon('metro_red_uae', { url: '//path_to_icon/new-metro_red_uae.svg' });

<!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="An example of changing icon in the current style" />
        <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.26961558517149, 25.20161682758841],
                zoom: 16,
                key: 'Your API access key',
            });

            map.once('idle', () => {
                map.removeIcon('metro_red_uae');
                map.addIcon('metro_red_uae', { url: 'https://docs.2gis.com/img/mapgl/point-red.svg'});
            });
        </script>
    </body>
</html>