ol/Map~Map

import Map from 'ol/Map.js';

Карта — это основной компонент OpenLayers. Для отображения карты необходимы представление, один или несколько слоёв и целевой контейнер:

import Map from 'ol/Map.js';
import View from 'ol/View.js';
import TileLayer from 'ol/layer/Tile.js';
import OSM from 'ol/source/OSM.js';

const map = new Map({
  view: new View({
    center: [0, 0],
    zoom: 1,
  }),
  layers: [
    new TileLayer({
      source: new OSM(),
    }),
  ],
  target: 'map',
});

Приведённый выше фрагмент создаёт карту с помощью TileLayer для отображения данных OSM из OSM и выводит её в элемент DOM с идентификатором map.

Конструктор размещает контейнер области просмотра (с именем CSS-класса ol-viewport) в целевом элементе (см. getViewport()), а затем добавляет в область просмотра ещё два элемента: один с именем CSS-класса ol-overlaycontainer-stopevent для элементов управления и некоторых наложений, другой с именем CSS-класса ol-overlaycontainer для остальных наложений (см. параметр stopEvent у Overlay, чтобы узнать, в чём разница). Сама карта размещается в дополнительном элементе внутри области просмотра.

Слои хранятся в виде Collection в группах слоёв. Библиотека предоставляет группу верхнего уровня. К ней обращаются с помощью getLayerGroup и setLayerGroup. Слои, указанные в параметрах, добавляются в эту группу, а addLayer и removeLayer изменяют коллекцию слоёв в группе. getLayers — это вспомогательная функция для getLayerGroup().getLayers(). Обратите внимание, что LayerGroup является подклассом BaseLayer, поэтому слои, указанные в параметрах или добавленные с помощью addLayer, могут быть группами, содержащими другие группы, и так далее.

new Map(options) Map.js, строка 250

Имя	Тип	Описание
`controls`	Collection<Control> \| Array<Control> \| undefined	Элементы управления, изначально добавляемые на карту. Если параметр не указан, используется `defaults`. В веб-воркере элементы управления по умолчанию не добавляются.
`pixelRatio`	number (по умолчанию window.devicePixelRatio)	Соотношение физических пикселей и независимых от устройства пикселей (DIP) на устройстве.
`interactions`	Collection<Interaction> \| Array<Interaction> \| undefined	Взаимодействия, изначально добавляемые на карту. Если параметр не указан, используется `defaults`. В веб-воркере взаимодействия по умолчанию не добавляются.
`keyboardEventTarget`	HTMLElement \| Document \| string \| undefined	Элемент, на котором отслеживаются события клавиатуры. Он определяет, когда срабатывают взаимодействия `KeyboardPan` и `KeyboardZoom`. Например, если для этого параметра задано значение `document`, взаимодействия с клавиатурой будут срабатывать всегда. Если параметр не указан, библиотека отслеживает события клавиатуры на целевом элементе карты (то есть на предоставленном пользователем div для карты). Если это значение не равно `document`, целевой элемент необходимо сфокусировать, чтобы генерировались события клавиатуры; для этого у целевого элемента должен быть атрибут `tabindex`.
`layers`	Array<BaseLayer> \| Collection<BaseLayer> \| LayerGroup \| undefined	Слои. Если параметр не задан, будет отображена карта без слоёв. Обратите внимание, что слои отображаются в указанном порядке. Например, чтобы векторный слой отображался поверх растрового, его нужно указать после растрового слоя.
`maxTilesLoading`	number (по умолчанию 16)	Максимальное количество одновременно загружаемых тайлов.
`moveTolerance`	number (по умолчанию 1)	Минимальное расстояние в пикселях, на которое должен переместиться курсор, чтобы это было распознано как событие перемещения карты, а не как щелчок. Увеличение этого значения может облегчить щелчки по карте.
`overlays`	Collection<Overlay> \| Array<Overlay> \| undefined	Наложения, изначально добавляемые на карту. По умолчанию наложения не добавляются.
`target`	HTMLElement \| string \| HTMLCanvasElement \| OffscreenCanvas \| undefined	Контейнер карты: сам элемент или `id` элемента. Если параметр не указан при создании, для отображения карты необходимо вызвать `setTarget`. Если в качестве параметра передан элемент, контейнер может находиться во вторичном документе. Для использования в веб-воркерах или при экспорте карты задайте в качестве целевого объекта `OffscreenCanvas` или `HTMLCanvasElement` с шириной и высотой в физических пикселях; при необходимости умножьте их на масштабный коэффициент, соответствующий соотношению пикселей карты. Для обеспечения доступности (фокусировки и обработки событий клавиатуры при навигации по карте) для элемента `target` необходимо правильно настроить атрибут `tabindex`. Если элемент `target` находится внутри Shadow DOM, атрибут `tabindex` необходимо задать для хост-элемента пользовательского элемента. Примечание: поддержка CSS `transform` для целевого элемента ограничена значением `scale`.
`view`	View \| Promise<ViewOptions> \| undefined	Представление карты. Источники слоёв не будут загружаться, если этот параметр не задан при создании или с помощью `setView`.

Генерируемые события:

change (BaseEvent) — общее событие изменения. Срабатывает при увеличении счётчика ревизий.
change:layerGroup (ObjectEvent)
change:size (ObjectEvent)
change:target (ObjectEvent)
change:view (ObjectEvent)
click (MapBrowserEvent) — щелчок без перетаскивания. Двойной щелчок вызовет это событие дважды.
dblclick (MapBrowserEvent) — двойной щелчок без перетаскивания.
error (BaseEvent) — общее событие ошибки. Срабатывает при возникновении ошибки.
loadend (MapEvent) — срабатывает после завершения загрузки дополнительных данных карты.
loadstart (MapEvent) — срабатывает при начале загрузки дополнительных данных карты (тайлов, изображений, объектов).
moveend (MapEvent) — срабатывает после перемещения карты.
movestart (MapEvent) — срабатывает при начале перемещения карты.
pointerdrag (MapBrowserEvent) — срабатывает при перетаскивании указателя.
pointermove (MapBrowserEvent) — срабатывает при перемещении указателя. Обратите внимание, что на сенсорных устройствах это событие срабатывает при перемещении карты, поэтому оно не совпадает с событием mousemove.
postcompose (RenderEvent) — срабатывает после объединения слоёв. Если событие отправлено картой, у объекта события не будет задан контекст. Если событие отправлено слоем, у объекта события будет задан контекст. В настоящее время это событие отправляют только слои WebGL.
postrender (MapEvent) — срабатывает после отображения кадра карты.
precompose (RenderEvent) — срабатывает перед объединением слоёв. Если событие отправлено картой, у объекта события не будет задан контекст. Если событие отправлено слоем, у объекта события будет задан контекст. В настоящее время это событие отправляют только слои WebGL.
propertychange (ObjectEvent) — срабатывает при изменении свойства.
rendercomplete (RenderEvent) — срабатывает по завершении отрисовки, то есть когда загрузка всех источников и тайлов для текущей области просмотра завершена и все тайлы проявились. У объекта события не будет задан контекст.
singleclick (MapBrowserEvent) — одиночный щелчок без перетаскивания и двойного щелчка. Обратите внимание, что это событие задерживается на 250 мс, чтобы убедиться, что это не двойной щелчок.

Наследует

BaseObject

Наблюдаемые свойства

Имя	Тип	Можно задать	Тип ObjectEvent	Описание
`layerGroup`	LayerGroup	да	`change:layergroup`	Группа слоёв, содержащая слои этой карты.
`size`	Size \| undefined	да	`change:size`	Размер карты в пикселях в DOM.
`target`	HTMLElement \| string \| undefined	да	`change:target`	Элемент или идентификатор элемента, в котором отображается карта.
`view`	View	да	`change:view`	Представление, управляющее этой картой.

Методы

addControl(control) Map.js, строка 615

Добавляет указанную панель управления на карту.

Имя	Тип	Описание
`control`	Control	Панель управления.

addInteraction(interaction) Map.js, строка 628

Добавляет указанное взаимодействие на карту. Чтобы добавить взаимодействие в другое место коллекции, используйте getInteractions() и доступные методы Collection. Это можно использовать, чтобы остановить распространение события из функции handleEvent. Взаимодействия обрабатывают события в порядке, обратном порядку элементов этой коллекции.

Имя	Тип	Описание
`interaction`	Interaction	Добавляемое взаимодействие.

addLayer(layer) Map.js, строка 639

Добавляет указанный слой в верхнюю часть стека слоёв этой карты. Чтобы добавить слой в другое место стека, используйте getLayers() и доступные методы Collection.

Имя	Тип	Описание
`layer`	BaseLayer	Слой.

addOverlay(overlay) Map.js, строка 657

Добавляет указанное наложение на карту.

Имя	Тип	Описание
`overlay`	Overlay	Наложение.

changed() унаследовано Observable.js, строка 68

Увеличивает счётчик версий и отправляет событие 'change'.

dispatchEvent(event){boolean | undefined} унаследовано events/Target.js, строка 85

Отправляет событие и вызывает все обработчики, подписанные на события этого типа. Параметр event может быть строкой или объектом со свойством type.

Имя	Тип	Описание
`event`	BaseEvent \| string	Объект события.

Возвращает:

false, если кто-либо вызвал preventDefault для объекта события или если любой из обработчиков вернул false.

forEachFeatureAtPixel(pixel, callback, options){T | undefined} Map.js, строка 709

Обнаруживает объекты, пересекающие пиксель в области просмотра, и вызывает функцию обратного вызова для каждого пересекающегося объекта. Слои, участвующие в обнаружении, можно настроить с помощью параметра layerFilter в options. Для полигонов без заливки при проверке попадания используется только обводка. Чтобы обнаруживались пиксели внутри полигона, необходимо применить к нему стиль заливки. Заливка может быть прозрачной.

Имя Тип Описание

pixel

Pixel

Пиксель.

callback

function

Функция обратного вызова для объектов. Она будет вызвана с двумя аргументами. Первый аргумент — объект feature или render feature в указанном пикселе, второй — layer этого объекта; для неуправляемых слоёв он будет равен null. Чтобы остановить обнаружение, функция обратного вызова может вернуть истинное значение.

options

Необязательные параметры.

Имя	Тип	Описание
`layerFilter`	undefined \| function	Функция фильтрации слоёв. Функция фильтрации получает один аргумент — `layer-candidate` — и должна возвращать логическое значение. Объекты будут проверяться только на тех слоях, которые видимы и для которых эта функция возвращает `true`. По умолчанию проверяются все видимые слои.
`hitTolerance`	number (по умолчанию 0)	Допуск проверки попадания в CSS-пикселях. Объекты проверяются в пикселях внутри радиуса вокруг указанной позиции.
`checkWrapped`	boolean (по умолчанию true)	Проверка обёрнутых геометрий: проверяет наличие обёрнутых геометрий в диапазоне +/- 1 ширины мира. Работает только в проекции, допускающей обёртывание.

Возвращает:

Результат функции обратного вызова: значение, возвращённое при последнем её вызове, либо первое истинное возвращённое значение.

get(key){*} унаследовано Object.js, строка 136

Получает значение.

Имя	Тип	Описание
`key`	string	Имя ключа.

Возвращает:

Значение.

getAllLayers(){Array<Layer>} Map.js, строка 760

Получает все слои из всех групп слоёв.

Возвращает:

Слои.

getControls(){Collection<Control>} Map.js, строка 910

Получает панели управления карты. Изменение этой коллекции изменяет набор панелей управления, связанных с картой.

Возвращает:

Панели управления.

getCoordinateFromPixel(pixel){Coordinate} Map.js, строка 883

Получает координату для указанного пикселя. Возвращает координату в пользовательской проекции.

Имя	Тип	Описание
`pixel`	Pixel	Положение пикселя в области просмотра карты.

Возвращает:

Координату для положения пикселя.

getEventCoordinate(event){Coordinate} Map.js, строка 813

Возвращает координату в пользовательской проекции для события браузера.

Имя	Тип	Описание
`event`	MouseEvent	Событие.

Возвращает:

Координату.

getEventPixel(event){Pixel} Map.js, строка 832

Возвращает положение пикселя карты для события браузера относительно области просмотра.

Имя	Тип	Описание
`event`	UIEvent \| Object	Событие.

Возвращает:

Пиксель.

getFeaturesAtPixel(pixel, options){Array<FeatureLike>} Map.js, строка 743

Получает все объекты, пересекающие пиксель в области просмотра. Для полигонов без заливки при проверке попадания используется только обводка. Чтобы обнаруживались пиксели внутри полигона, необходимо применить к нему стиль заливки. Заливка может быть прозрачной.

Имя Тип Описание

pixel

Pixel

Пиксель.

options

Необязательные параметры.

Имя	Тип	Описание
`layerFilter`	undefined \| function	Функция фильтрации слоёв. Функция фильтрации получает один аргумент — `layer-candidate` — и должна возвращать логическое значение. Объекты будут проверяться только на тех слоях, которые видимы и для которых эта функция возвращает `true`. По умолчанию проверяются все видимые слои.
`hitTolerance`	number (по умолчанию 0)	Допуск проверки попадания в CSS-пикселях. Объекты проверяются в пикселях внутри радиуса вокруг указанной позиции.
`checkWrapped`	boolean (по умолчанию true)	Проверка обёрнутых геометрий: проверяет наличие обёрнутых геометрий в диапазоне +/- 1 ширины мира. Работает только в проекции, допускающей обёртывание.

Возвращает:

Обнаруженные объекты или пустой массив, если ничего не найдено.

getInteractions(){Collection<Interaction>} Map.js, строка 945

Получает взаимодействия карты. Изменение этой коллекции изменяет набор взаимодействий, связанных с картой.

Взаимодействия используются, например, для панорамирования, масштабирования и поворота.

Возвращает:

Взаимодействия.

getKeys(){Array.<string>} унаследовано Object.js, строка 149

Получает список имён свойств объекта.

Возвращает:

Список имён свойств.

getLayerGroup(){LayerGroup} Map.js, строка 955

Получает группу слоёв, связанную с этой картой.

Возвращает:

Группу слоёв, содержащую слои этой карты.

getLayers(){Collection<BaseLayer>} Map.js, строка 981

Получает коллекцию слоёв, связанных с этой картой.

Возвращает:

Слои.

getOverlayById(id){Overlay | null} Map.js, строка 932

Получает наложение по его идентификатору (значению, возвращаемому overlay.getId()). Обратите внимание, что индекс считает строковые и числовые идентификаторы одинаковыми. Поэтому map.getOverlayById(2) вернёт наложение с идентификатором '2' или 2.

Имя	Тип	Описание
`id`	string \| number	Идентификатор наложения.

Возвращает:

Наложение.

getOverlays(){Collection<Overlay>} Map.js, строка 920

Получает наложения карты. Изменение этой коллекции изменяет набор наложений, связанных с картой.

Возвращает:

Наложения.

getPixelFromCoordinate(coordinate){Pixel} Map.js, строка 1015

Получает пиксель для координаты. Метод принимает координату в пользовательской проекции и возвращает соответствующий пиксель.

Имя	Тип	Описание
`coordinate`	Coordinate	Координата карты.

Возвращает:

Положение пикселя в области просмотра карты.

getPixelRatio(){number} Map.js, строка 1045

Получает коэффициент пикселей отрисованной карты.

Возвращает:

Коэффициент пикселей.

getProperties(){NoInfer.<Properties>} унаследовано Object.js, строка 158

Получает объект со всеми именами свойств и их значениями.

Возвращает:

Объект.

getRevision(){number} унаследовано Observable.js, строка 79

Получает номер версии этого объекта. При каждом изменении объекта его номер версии увеличивается.

Возвращает:

Номер версии.

getSize(){Size | undefined} Map.js, строка 1076

Получает размер этой карты.

Возвращает:

Размер карты в пикселях в DOM.

getTarget(){HTMLElement | string | undefined} Map.js, строка 859

Получает целевой элемент, в котором отрисовывается эта карта. Обратите внимание: метод возвращает значение, заданное в параметре или переданное в setTarget: если это был элемент, возвращается элемент; если строка — возвращается эта строка.

Возвращает:

Элемент или идентификатор элемента, в котором отрисовывается карта.

getTargetElement(){HTMLElement} Map.js, строка 872

Получает элемент DOM, в котором отрисовывается эта карта. В отличие от getTarget этот метод всегда возвращает Element или null, если для карты не задан целевой элемент.

Возвращает:

Элемент, в котором отрисовывается карта.

getView(){View} Map.js, строка 1089

Получает представление, связанное с этой картой. Представление управляет такими свойствами, как центр и разрешение.

Возвращает:

Представление, управляющее этой картой.

getViewport(){HTMLElement} Map.js, строка 1098

Получает элемент, служащий областью просмотра карты.

Возвращает:

Область просмотра.

hasFeatureAtPixel(pixel, options){boolean} Map.js, строка 786

Определяет, пересекаются ли объекты с пикселем в области просмотра. Слои, участвующие в обнаружении, можно настроить с помощью параметра layerFilter. Для полигонов без заливки при проверке попадания используется только обводка. Чтобы обнаруживались пиксели внутри полигона, необходимо применить к нему стиль заливки. Заливка может быть прозрачной.

Имя Тип Описание

pixel

Pixel

Пиксель.

options

Необязательные параметры.

Имя	Тип	Описание
`layerFilter`	undefined \| function	Функция фильтрации слоёв. Функция фильтрации получает один аргумент — `layer-candidate` — и должна возвращать логическое значение. Объекты будут проверяться только на тех слоях, которые видимы и для которых эта функция возвращает `true`. По умолчанию проверяются все видимые слои.
`hitTolerance`	number (по умолчанию 0)	Допуск проверки попадания в CSS-пикселях. Объекты проверяются в пикселях внутри радиуса вокруг указанной позиции.
`checkWrapped`	boolean (по умолчанию true)	Проверка обёрнутых геометрий: проверяет наличие обёрнутых геометрий в диапазоне +/- 1 ширины мира. Работает только в проекции, допускающей обёртывание.

Возвращает:

Есть ли объект в указанном пикселе?

on(type, listener){EventsKey | Array<EventsKey>} унаследовано Observable.js, строка 152

Прослушивает события заданного типа.

Имя	Тип	Описание
`type`	string \| Array.<string>	Тип события или массив типов событий.
`listener`	function	Функция-обработчик.

Возвращает:

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

once(type, listener){EventsKey | Array<EventsKey>} унаследовано Observable.js, строка 164

Однократно прослушивает события заданного типа.

Имя	Тип	Описание
`type`	string \| Array.<string>	Тип события или массив типов событий.
`listener`	function	Функция-обработчик.

Возвращает:

removeControl(control){Control | undefined} Map.js, строка 1550

Удаляет указанный элемент управления с карты.

Имя	Тип	Описание
`control`	Control	Элемент управления.

Возвращает:

Удаленный элемент управления (или undefined, если элемент управления не найден).

removeInteraction(interaction){Interaction | undefined} Map.js, строка 1561

Удаляет указанное взаимодействие с карты.

Имя	Тип	Описание
`interaction`	Interaction	Взаимодействие для удаления.

Возвращает:

Удаленное взаимодействие (или undefined, если взаимодействие не найдено).

removeLayer(layer){BaseLayer | undefined} Map.js, строка 1572

Удаляет указанный слой с карты.

Имя	Тип	Описание
`layer`	BaseLayer	Слой.

Возвращает:

Удаленный слой (или undefined, если слой не найден).

removeOverlay(overlay){Overlay | undefined} Map.js, строка 1592

Удаляет указанное наложение с карты.

Имя	Тип	Описание
`overlay`	Overlay	Наложение.

Возвращает:

Удаленное наложение (или undefined, если наложение не найдено).

render() Map.js, строка 1537

Запрашивает отрисовку карты (в следующем кадре анимации).

renderSync() Map.js, строка 1510

Запрашивает немедленную синхронную отрисовку.

set(key, value, silent) унаследовано Object.js, строка 218

Задает значение.

Имя	Тип	Описание
`key`	string	Имя ключа.
`value`	*	Значение.
`silent`	boolean \| undefined	Обновить без вызова события.

setLayerGroup(layerGroup) Map.js, строка 1714

Задает группу слоев этой карты.

Имя	Тип	Описание
`layerGroup`	LayerGroup	Группа слоев, содержащая слои этой карты.

setLayers(layers) Map.js, строка 964

Удаляет все существующие слои и добавляет слои на карту.

Имя	Тип	Описание
`layers`	Array<BaseLayer> \| Collection<BaseLayer>	Слои, которые необходимо добавить на карту.

setPixelRatio(pixelRatio) Map.js, строка 1054

Задает коэффициент пикселей для отрисовываемой карты.

Имя	Тип	Описание
`pixelRatio`	number	Коэффициент пикселей.

setProperties(values, silent) унаследовано Object.js, строка 238

Задает набор пар «ключ-значение». Обратите внимание: существующие свойства изменяются, а новые добавляются (существующие свойства не удаляются).

Имя	Тип	Описание
`values`	Partial.<NoInfer.<Properties>>	Значения.
`silent`	boolean \| undefined	Обновить без вызова события.

setSize(size) Map.js, строка 1728

Задает размер этой карты.

Имя	Тип	Описание
`size`	Size \| undefined	Размер карты в пикселях в DOM.

setTarget(target) Map.js, строка 1742

Задает целевой элемент для отрисовки карты. Для обеспечения доступности (фокусировки и обработки событий клавиатуры для навигации по карте) элемент target должен иметь правильно настроенный атрибут tabindex. Если элемент target находится внутри Shadow DOM, атрибут tabindex должен быть задан для хост-элемента пользовательского элемента.

Имя	Тип	Описание
`target`	HTMLElement \| string \| undefined	Элемент или идентификатор элемента, в котором отображается карта.

setView(view) Map.js, строка 1755

Задает вид для этой карты.

Имя	Тип	Описание
`view`	View \| Promise<ViewOptions> \| null	Вид, управляющий этой картой. Также можно передать промис, который разрешается в параметры для создания вида. Этот вариант позволяет источникам или другим компонентам, загружающим метаданные, связанные с видом, определить его свойства.

un(type, listener) унаследовано Observable.js, строка 173

Прекращает прослушивание событий заданного типа.

Имя	Тип	Описание
`type`	string \| Array.<string>	Тип события или массив типов событий.
`listener`	function	Функция-обработчик.

unset(key, silent) унаследовано Object.js, строка 262

Удаляет свойство.

Имя	Тип	Описание
`key`	string	Имя ключа.
`silent`	boolean \| undefined	Удалить без вызова события.

updateSize() Map.js, строка 1773

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