Стилевой уровень масштабирования (Style zoom)

Рассмотрим небольшой фрагмент объекта стиля:

{
    type: 'polygon',
    id: 'background',
    filter: ['match', ['get', 'sublayer'], ['s_region'], true, false],
    style: {
        color: [
            'interpolate', ['linear'], ['zoom'],
            9, 'hsl(50, 61%, 90%)',
            12, 'hsl(51, 37%, 90%)',
            14, 'hsl(49, 48%, 91%)',
            16, 'hsl(51, 51%, 92%)',
        ],
    },
},

Объект описывает цвет фона для данных с полем "sublayer", равным s_region. Обратите внимание на фрагмент кода ниже:

color: [
    'interpolate', ['linear'], ['zoom'],
    9, 'hsl(50, 61%, 90%)',
    12, 'hsl(51, 37%, 90%)',
    14, 'hsl(49, 48%, 91%)',
    16, 'hsl(51, 51%, 92%)',
],

Этот массив описывает, как цвет фона зависит от масштаба. Но это не обычный уровень масштабирования, который можно установить в настройках карты, а styleZoom. Параметры styleZoom и zoom задают один и тот же масштаб карты, но в разных проекциях. А значение styleZoom используется в стилях.

Вы можете задать styleZoom в настройках карты, если хотите установить тот же масштаб, что и в настройках стиля. Если заданы обе опции (zoom и styleZoom), то styleZoom имеет более высокий приоритет, чем zoom. Если вам нужно установить/получить styleZoom in runtime, вы можете использовать setStyleZoom и getStyleZoom.

Пример, где вы можете увидеть разницу между zoom и styleZoom:

<!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="Style zoom example" />
        <style>
            html,
            body {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
                font-family: Helvetica, Arial, sans-serif;
            }
            #container_1, #container_2 {
                height: 250px;
                width: 100%;
                overflow: hidden;
            }
        </style>
    </head>
    <body>
        <h2>Map with zoom option equal to 16</h2>
        <div id="container_1"></div>
        <h2>Map with styleZoom option equal to 16</h2>
        <div id="container_2"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script>
            let key = 'Your API access key';
            const map_1 = new mapgl.Map('container_1', {
                center: [55.190803, 25.141451],
                zoom: 16,
                pitch: 40,
                rotation: -90,
                key,
            });
            const map_2 = new mapgl.Map('container_2', {
                center: [55.190803, 25.141451],
                styleZoom: 16,
                pitch: 40,
                rotation: -90,
                key,
            });
        </script>
    </body>
</html>

Когда нужен zoom, а когда - styleZoom

styleZoom введён для компенсации искажений проекции Меркатора. Благодаря этому объекты карты отображаются в одном и том же масштабе на разных широтах.

Используйте zoom, если хотите работать с масштабом карты. Он будет одинаковым вблизи полярного круга и на экваторе.

Используйте styleZoom, если вы хотите работать именно с границами масштабирования в стилях. Обычно это тот случай, когда вы разрабатываете стиль карты с помощью Редактора стилей и вам необходимо убедиться, что определенные объекты, ограниченные масштабом, будут видны.

По умолчанию используется опция zoom.