MapOptions

MapOptions = object

Объект параметров Map.

Свойства

anisotropicFilterPitch?

optional anisotropicFilterPitch?: number | null

Угол наклона, выше которого к растровым слоям карты применяется анизотропная фильтрация (0–180).

Значение по умолчанию

20

aroundCenter?

optional aroundCenter?: boolean

Определяет модель взаимодействия при вращении: - Если значение равно true: используется логика «орбитального» вращения, при которой вращение выполняется относительно центра поворота. Перетаскивание вправо в верхней части вращает карту по часовой стрелке, а в нижней — против часовой стрелки (как при вращении физического глобуса). - Если значение равно false: используется логика «линейного» вращения, при которой горизонтальное перемещение мыши напрямую изменяет азимут независимо от положения курсора.

attributionControl?

optional attributionControl?: false | AttributionControlOptions

Если задано значение, на карту будет добавлен AttributionControl с указанными параметрами. Чтобы отключить элемент управления атрибуцией, передайте false.

Значение по умолчанию

compact: true, customAttribution: "MapLibre ...".

bearing?

optional bearing?: number

Начальный азимут (вращение) карты в градусах против часовой стрелки от севера. Если bearing не указан в параметрах конструктора, MapLibre GL JS будет искать его в объекте стиля карты. Если он не указан и в стиле, по умолчанию используется 0.

Значение по умолчанию

0

bearingSnap?

optional bearingSnap?: number

Пороговое значение в градусах, определяющее, когда азимут карты будет зафиксирован на севере. Например, при значении bearingSnap, равном 7, если пользователь повернёт карту так, что её азимут будет отличаться от севера не более чем на 7 градусов, карта автоматически повернётся точно на север.

Значение по умолчанию

7

bounds?

optional bounds?: LngLatBoundsLike

Начальные границы карты. Если задано bounds, оно переопределяет параметры конструктора center и zoom.

boxZoom?

optional boxZoom?: boolean | BoxZoomHandlerOptions

Если задано true, включается взаимодействие «масштабирование выделенной области» (см. BoxZoomHandler). Значение Object задаёт параметры BoxZoomHandler. Если передано boxZoomEnd, вместо стандартного масштабирования до выделенной области запускается функция обратного вызова.

Значение по умолчанию

true

cancelPendingTileRequestsWhileZooming?

optional cancelPendingTileRequestsWhileZooming?: boolean

Определяет, следует ли отменять или сохранять загружающиеся тайлы из текущей области просмотра, относящиеся к более дальнему (меньшему) уровню масштабирования, чем текущий. * Если true, при увеличении масштаба отменяется загрузка тайлов, не успевших загрузиться для предыдущих уровней масштабирования. Это может сэкономить вычислительные ресурсы на менее производительных устройствах, но детали карты могут появляться более резко в конце масштабирования. * Если false, при увеличении масштаба тайлы предыдущих уровней будут постепенно появляться, обеспечивая более плавное отображение карты. Однако за короткий промежуток времени будет отрисовано больше тайлов.

Значение по умолчанию

true

canvasContextAttributes?

optional canvasContextAttributes?: WebGLContextAttributesWithType

Набор атрибутов WebGLContextAttributes, применяемых к контексту WebGL карты. Подробнее см. https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext. Для contextType допустимо только значение 'webgl2'. Этот параметр предусмотрен на перспективу для поддержки WebGPU.

Значение по умолчанию

antialias: false, powerPreference: 'high-performance', preserveDrawingBuffer: false, failIfMajorPerformanceCaveat: false, desynchronized: false, contextType: 'webgl2'

center?

optional center?: LngLatLike

Начальная географическая центральная точка карты. Если center не указан в параметрах конструктора, MapLibre GL JS будет искать его в объекте стиля карты. Если он не указан и в стиле, по умолчанию используется [0, 0]

Значение по умолчанию

[0, 0]

centerClampedToGround?

optional centerClampedToGround?: boolean

Если значение равно true, высота центральной точки автоматически устанавливается на высоту рельефа (или на ноль, если рельеф не включён). Если значение равно false, высота центральной точки по умолчанию соответствует уровню моря и не обновляется автоматически. По умолчанию установлено значение true. Чтобы камера оставалась над землёй при наклоне > 90 градусов, необходимо установить значение false.

clickTolerance?

optional clickTolerance?: number

Максимальное количество пикселей, на которое пользователь может переместить указатель мыши во время щелчка, чтобы он считался действительным щелчком, а не перетаскиванием.

Значение по умолчанию

3

collectResourceTiming?

optional collectResourceTiming?: boolean

Если true, для запросов, выполняемых веб-воркерами GeoJSON и векторных тайлов, будет собираться информация Resource Timing API (обычно эта информация недоступна из основного потока Javascript). Информация будет возвращаться в свойстве resourceTiming соответствующих событий data.

Значение по умолчанию

false

container

container: HTMLElement | string

HTML-элемент, в котором MapLibre GL JS будет отображать карту, или строковый id этого элемента. Указанный элемент не должен содержать дочерних элементов.

cooperativeGestures?

optional cooperativeGestures?: GestureOptions

Если задано значение true или объект параметров, на компьютере с картой можно взаимодействовать только при удерживании Command/Ctrl, а на мобильном устройстве — только двумя пальцами. Обычные жесты взаимодействия с картой вызывают информационное сообщение. При включённом параметре для наклона перетаскиванием требуется жест тремя пальцами. Совместное управление жестами отключается, когда карта переходит в полноэкранный режим с помощью FullscreenControl.

Значение по умолчанию

false

crossSourceCollisions?

optional crossSourceCollisions?: boolean

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

Значение по умолчанию

true

doubleClickZoom?

optional doubleClickZoom?: boolean

Если задано true, включается взаимодействие «двойной щелчок для масштабирования» (см. DoubleClickZoomHandler).

Значение по умолчанию

true

dragPan?

optional dragPan?: boolean | DragPanOptions

Если задано true, включается взаимодействие «перетаскивание для перемещения карты». Значение Object передаётся в качестве параметров для DragPanHandler.enable.

Значение по умолчанию

true

dragRotate?

optional dragRotate?: boolean

Если задано true, включается взаимодействие «перетаскивание для вращения» (см. DragRotateHandler).

Значение по умолчанию

true

elevation?

optional elevation?: number

Высота начальной географической центральной точки карты в метрах над уровнем моря. Если elevation не указан в параметрах конструктора, по умолчанию используется 0.

Значение по умолчанию

0

fadeDuration?

optional fadeDuration?: number

Задаёт длительность анимации появления и исчезновения меток при разрешении коллизий после первоначальной загрузки карты в миллисекундах. Этот параметр влияет на все символьные слои. Он не влияет на длительность переходов стилей во время выполнения или перекрёстного затухания растровых тайлов.

Значение по умолчанию

300

fitBoundsOptions?

optional fitBoundsOptions?: FitBoundsOptions

Объект параметров FitBoundsOptions, используемый только при подгонке начального значения bounds, указанного выше.

hash?

optional hash?: boolean | string

Если задано true, положение карты (масштаб, широта и долгота центра, азимут и наклон) будет синхронизировано с хеш-фрагментом URL страницы. Например, https://example.com#2.59/39.26/53.07/-24.1/60.

В качестве альтернативы можно указать дополнительную строку, обозначающую хеш в формате параметров. Например, передача hash: "foo" создаст хеш вида https://example.com#foo=2.59/39.26/53.07/-24.1/60. Это полезно для поддержки нескольких карт или другого состояния.

Значение по умолчанию

false

interactive?

optional interactive?: boolean

Если задано false, к карте не будут подключены обработчики событий мыши, сенсорного экрана или клавиатуры, поэтому она не будет реагировать на взаимодействие.

Значение по умолчанию

true

keyboard?

optional keyboard?: boolean

Если задано true, включаются сочетания клавиш (см. KeyboardHandler).

Значение по умолчанию

true

locale?

optional locale?: Record<string, string>

Переопределения для таблицы локализации строк интерфейса по умолчанию, например всплывающих подсказок элементов управления. Объект locale сопоставляет идентификаторы строк интерфейса с пространствами имён переведённым строкам на целевом языке; пример со всеми поддерживаемыми идентификаторами строк см. в src/ui/default_locale.js. В объекте можно указать все строки интерфейса (добавив поддержку нового перевода) или только часть строк (переопределив таблицу переводов по умолчанию). Пример см. на странице https://maplibre.org/maplibre-gl-js/docs/examples/locale-switching/. Также можно найти плагины для локализации на официальной странице плагинов.

Значение по умолчанию

null

localIdeographFontFamily?

optional localIdeographFontFamily?: string | false

Задаёт CSS-семейство шрифтов для локального формирования китайских, японских и корейских символов. Для этих символов настройки шрифта из стиля карты игнорируются, за исключением ключевых слов толщины шрифта (light/regular/medium/bold). Установите значение false, чтобы для этих диапазонов глифов применялись настройки шрифта из стиля карты. Этот параметр позволяет избежать ресурсоёмких запросов к серверу глифов.

См. также

Использование локально сформированных иероглифов

Значение по умолчанию

'sans-serif'

logoPosition?

optional logoPosition?: ControlPosition

Строка, задающая положение логотипа MapLibre на карте. Допустимые значения: top-left,top-right, bottom-left или bottom-right.

Значение по умолчанию

'bottom-left'

maplibreLogo?

optional maplibreLogo?: boolean

Если задано true, будет отображаться логотип MapLibre.

maxBounds?

optional maxBounds?: LngLatBoundsLike

Если задано, перемещение карты будет ограничено указанными границами.

maxCanvasSize?

optional maxCanvasSize?: [number, number]

Максимальные размеры width и height холста. Значения передаются в виде массива, где первый элемент задаёт максимальную ширину, а второй — максимальную высоту. Не следует задавать значение выше WebGl MAX_TEXTURE_SIZE. Холст большего размера не отклоняется: для подгонки уменьшается коэффициент плотности пикселей и один раз выводится предупреждение.

Значение по умолчанию

[4096, 4096].

maxPitch?

optional maxPitch?: number | null

Максимальный наклон карты (0–180).

Значение по умолчанию

60

maxTileCacheSize?

optional maxTileCacheSize?: number | null

Максимальное количество тайлов, хранящихся в кэше тайлов для заданного источника. Если параметр не указан, размер кэша будет динамически определяться на основе текущей области просмотра, которую можно задать с помощью параметров конструктора maxTileCacheZoomLevels.

Значение по умолчанию

null

maxTileCacheZoomLevels?

optional maxTileCacheZoomLevels?: number

Максимальное количество уровней масштабирования, для которых хранятся тайлы заданного источника. Динамический размер кэша тайлов рассчитывается путём умножения maxTileCacheZoomLevels на приблизительное количество тайлов заданного источника в области просмотра.

Значение по умолчанию

5

maxZoom?

optional maxZoom?: number | null

Максимальный уровень масштабирования карты. Пользователи не смогут увеличить масштаб выше этого уровня. (0–24)

Значение по умолчанию

22

minPitch?

optional minPitch?: number | null

Минимальный наклон карты (0–180).

Значение по умолчанию

0

minZoom?

optional minZoom?: number | null

Минимальный уровень масштабирования карты. Пользователи не смогут уменьшить масштаб ниже этого уровня. (0–24)

Значение по умолчанию

0

pitch?

optional pitch?: number

Начальный наклон карты в градусах относительно плоскости экрана (0–85). Если pitch не указан в параметрах конструктора, MapLibre GL JS будет искать его в объекте стиля карты. Если он не указан и в стиле, по умолчанию используется 0. Значения выше 60 градусов являются экспериментальными и могут вызывать проблемы при отображении. Если вы столкнётесь с такими проблемами, сообщите о них в проект MapLibre, подробно описав ситуацию.

Значение по умолчанию

0

pitchSpeed?

optional pitchSpeed?: number

Изменение наклона карты в градусах на каждый пиксель вертикального перетаскивания. Значение отрицательное, поэтому при перетаскивании вверх карта наклоняется к горизонту.

Значение по умолчанию

-0.5

pitchWithRotate?

optional pitchWithRotate?: boolean

Если задано false, управление наклоном карты с помощью взаимодействия «перетаскивание для вращения» будет отключено.

Значение по умолчанию

true

pixelRatio?

optional pixelRatio?: number

Коэффициент плотности пикселей. Атрибут width холста будет равен container.clientWidth * pixelRatio, а атрибут height — container.clientHeight * pixelRatio. Если параметр не указан, по умолчанию используется devicePixelRatio.

reduceMotion?

optional reduceMotion?: boolean

Если задано true, инерция жестов (например, перемещения карты) отключается. Если параметр не указан, инерция жестов определяется настройками устройства пользователя.

Значение по умолчанию

undefined

refreshExpiredTiles?

optional refreshExpiredTiles?: boolean

Если задано false, карта не будет повторно запрашивать тайлы после истечения срока их действия согласно HTTP-заголовкам cacheControl/expires.

Значение по умолчанию

true

renderWorldCopies?

optional renderWorldCopies?: boolean

Если задано true, несколько копий мира будут отображаться рядом друг с другом за пределами долгот 180 и −180 градусов. Если задано false:

• Если при уменьшении масштаба единственное изображение мира не заполняет всю область карты, за долготами 180 и −180 градусов останутся пустые области.
• Объекты, пересекающие долготы 180 и −180 градусов, будут разделяться на две части (одна часть будет у правого края карты, другая — у левого) на всех уровнях масштабирования.

Значение по умолчанию

true

roll?

optional roll?: number

Начальный угол крена карты в градусах против часовой стрелки вокруг оптической оси камеры. Если roll не указан в параметрах конструктора, MapLibre GL JS будет искать его в объекте стиля карты. Если он не указан и в стиле, по умолчанию используется 0.

Значение по умолчанию

0

rollEnabled?

optional rollEnabled?: boolean

Если задано false, управление креном карты с помощью взаимодействия «перетаскивание для вращения» будет отключено.

Значение по умолчанию

false

rotateSpeed?

optional rotateSpeed?: number

Изменение азимута карты в градусах на каждый пиксель горизонтального перетаскивания при вращении.

Значение по умолчанию

0.8

scrollZoom?

optional scrollZoom?: boolean | AroundCenterOptions

Если задано true, включается взаимодействие «прокрутка для масштабирования». Параметры AroundCenterOptions передаются в качестве параметров для ScrollZoomHandler.enable.

Значение по умолчанию

true

style?

optional style?: StyleSpecification | string

Стиль MapLibre для карты. Это должен быть объект JSON, соответствующий схеме из спецификации стилей MapLibre, или URL такого JSON-файла. Если стиль не указан, для отображения карты необходимо вызвать Map.setStyle.

terrainSkirtLength?

optional terrainSkirtLength?: "none" | "auto"

Задаёт длину вертикальных продолжений, добавляемых к краям тайлов рельефа.

Если юбки рельефа создают нежелательные вертикальные артефакты, старайтесь не использовать прозрачный или полупрозрачный фон. Например, можно сделать первым слоем фоновый слой с параметром background-color. Если это невозможно или не помогает, юбки можно полностью отключить, однако на границах тайлов с разными уровнями масштабирования в некоторых наборах данных рельефа могут появиться тонкие горизонтальные зазоры.

• "none" полностью отключает юбки.
• "auto" отображает юбки с автоматически выбранной длиной.

Значение по умолчанию

"auto"

touchPitch?

optional touchPitch?: boolean | AroundCenterOptions

Если задано true, включается взаимодействие «перетаскивание для наклона». Значение Object передаётся в качестве параметров для TwoFingersTouchPitchHandler.enable.

Значение по умолчанию

true

touchZoomRotate?

optional touchZoomRotate?: boolean | AroundCenterOptions

Если задано true, включается взаимодействие «сведение пальцев для вращения и масштабирования». Значение Object передаётся в качестве параметров для TwoFingersTouchZoomRotateHandler.enable.

Значение по умолчанию

true

trackResize?

optional trackResize?: boolean

Если задано true, размер карты будет автоматически изменяться при изменении размера окна браузера.

Значение по умолчанию

true

transformCameraUpdate?

optional transformCameraUpdate?: CameraUpdateTransformFunction | null

Функция обратного вызова, запускаемая перед перемещением камеры карты в результате действий пользователя или анимации. Она позволяет изменять новые значения центра, масштаба, наклона и азимута. Функция должна возвращать объект со значениями центра, масштаба, наклона или азимута, которые нужно переопределить.

Значение по умолчанию

null

transformConstrain?

optional transformConstrain?: TransformConstrainFunction | null

Функция обратного вызова, переопределяющая способ ограничения координат lnglat и масштаба области просмотра с учётом границ долготы и широты.

См. также

Настройка ограничений преобразования карты Функция должна возвращать объект, содержащий центр и масштаб.

Значение по умолчанию

null

transformRequest?

optional transformRequest?: RequestTransformFunction | null

Функция обратного вызова, запускаемая перед отправкой картой запроса к внешнему URL. Она позволяет изменить URL, задать заголовки или указать свойство credentials для междоменных запросов. Функция должна возвращать объект со свойством url и необязательными свойствами headers и credentials.

Значение по умолчанию

null

validateStyle?

optional validateStyle?: boolean

Если задано false, проверка стиля пропускается. Это полезно в производственных средах: в некоторых средах позволяет удалять код проверки при сборке и немного повышает производительность. Отключение этого параметра приводит к менее понятным сообщениям об ошибках.

Значение по умолчанию

true

zoom?

optional zoom?: number

Начальный уровень масштабирования карты. Если zoom не указан в параметрах конструктора, MapLibre GL JS будет искать его в объекте стиля карты. Если он не указан и в стиле, по умолчанию используется 0.

Значение по умолчанию

0

zoomLevelsToOverscale?

optional zoomLevelsToOverscale?: number

Задаёт количество уровней масштабирования, для которых будет применяться перемасштабирование вместо разбиения тайлов ниже (включительно) maxZoom карты. Если задано undefined, перемасштабирование применяется ко всем уровням масштабирования выше максимального уровня источника.

Это может уменьшить степень перемасштабирования и повысить производительность на больших уровнях масштабирования. Недостаток этого подхода в том, что он меняет отображение меток, расположенных в центре полигонов, и результаты запроса отображаемых объектов.

Например, если maxZoom карты равно 20, maxzoom источника равно 10 (тайлы доступны до уровня масштабирования 10), а zoomLevelsToOverscale установлено на 3: - На уровнях масштабирования 20, 19 и 18 будет применяться перемасштабирование. - На уровнях масштабирования с 11 по 17 тайлы будут разделяться.

Значение по умолчанию

4

zoomSnap?

optional zoomSnap?: number

Шаг, к которому будет привязываться уровень масштабирования. Например, если zoomSnap равно 1, при дискретном изменении масштаба карта будет привязываться к целым значениям. Если задать значение 0, масштабирование будет непрерывным.

Значение по умолчанию

0