Графические режимы

Функциональность доступна для MapGL JS API версии 1.55.0 и выше.

Иммерсивные возможности MapGL JS API требуют высокой производительности устройств пользователей. Чтобы управлять уровнем графики и иммерсивности на карте, настройте графические режимы карты в Редакторе стилей. Вы можете установить активный режим для всех пользователей или позволить пользователям выбирать режим, чтобы они могли отключать неактуальные возможности.

Для графических режимов вы можете указать настройки графики — набор флагов, которые включают или выключают иммерсивные возможности карты: иммерсивные дороги, тени, туман и небо. Карта использует настройки графики, которые соответствуют текущему значению глобальной переменной стиля graphicsPreset (это одно из полей объекта StyleState). Доступны три значения: light, normal и immersive.

Пример использования:

<!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="Graphics Preset Example" />
        <style>
            html,
            body,
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            }
            select {
                position: absolute;
                z-index: 1;
                top: 16px;
                left: 16px;
            }
        </style>
    </head>
    <body>
        <select>
            <option value="light">light</option>
            <option value="normal">normal</option>
            <option value="immersive">immersive</option>
        </select>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.31878, 25.23584],
                zoom: 18.5,
                pitch: 35,
                key: 'Your API access key',
                graphicsPreset: 'immersive',
                style: '8780eed4-0428-4982-b615-aa6cf04d8f5f',
                styleState: {
                    immersiveRoadsOn: true,
                },
            });
            const select = document.querySelector('select');
            select.value = 'immersive';
            select.addEventListener('change', () => {
                map.patchStyleState({ graphicsPreset: select.value });
            });
        </script>
    </body>
</html>

Настройка режимов

Откройте Редактор стилей.
Откройте нужный стиль.
На вкладке Другое выберите пункт Графические режимы:
Чтобы установить значение graphicsPreset, откройте раздел Настройки и в поле Графический режим выберите режим:
Укажите настройки графики для каждого режима. Например, выключите тени для режима normal:

В этом случае при выборе значения graphicsPreset = immersive тени будут включены:

При выборе graphicsPreset = normal тени будут выключены:

Включение и переключение режима

Чтобы установить для карты графический режим и применить его настройки из стиля, при инициализации карты установите глобальную переменную стиля graphicsPreset:

const map = new mapgl.Map('map-container', {
    graphicsPreset: 'immersive', // 'light', 'normal' или 'immersive'
});

Чтобы пользователи могли менять активный режим во время работы с картой, используйте метод map.patchStyleState():

const map = new mapgl.Map('map-container', {
    graphicsPreset: 'immersive',
});

// ...

// Переключение режима
map.patchStyleState({ graphicsPreset: 'normal' });