Введение в OpenLayers

Всем привет! Мы рассмотрим библиотеку для построения карт OpenLayers (версии 8.2.х). Вы узнаете о том, какие возможности она предоставляет, как ей пользоваться и почему в команде НСПД мы выбрали именно её. В статье будет много примеров кода, которые также доступны на GitHub и StackBlitz.

Для чтения статьи необходимо иметь хотя бы базовые знания HTML, CSS и JavaScript; иметь представление о сборщиках кода (в примерах использую Vite).

Приятного чтения! ?

---

Что такое OpenLayers?

OpenLayers — библиотека для создания карт с открытым исходным кодом (ссылка на исходники кода). Написана на JavaScript, имеет хорошую поддержку Typescript. Является одним из популярнейших решений для работы с картами, конкурируя с Leaflet.

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

Почему OpenLayers?

OpenLayers любят за это:

1. Быстродействие. Поддержка WebGL из коробки.

2. Богатый функционал из коробки. Небольшой список я приведу ниже

3. Архитектурная гибкость. Довольно просто расширять, настраивать под специфические нужды, проводить unit-тестирование.

4. Отличная поддержка браузеров и девайсов (т.к. мобильные устройства, Retina-дисплей)

5. Обилие примеров и документации. 240+ примеров

6. Поддержка всех протоколов OGC, таких как WMF, WFS, WMTS, WPS.

7. OpenSource. Исходники кода можно (и нужно) читать для лучшего понимания того, что происходит под капотом в Вашем приложении.

8. Поддержка TreeShaking. В бандл идёт только то, что вы используете (импортируете).

9. Поддержка любой проекции карты. В библиотеке указаны только EPSG:3857 и EPSG:4326, однако есть возможность добавить любую другую проекцию (пример).

Скрытый текст

• Поддержка растровых и и векторных тайлов

  • Динамическая замена тайлов по зуму (разрешению)

• Работа с векторной графикой по стандарту GeoJSON

• Интерактивные взаимодействия с пользователем (Примеры), в том числе:

  • Рисование (Примеры)

    • Рисование по шаблону (Пример)

    • “Свободное” рисование (Пример)

  • Изменение (Пример)

  • Выбор геометрии (Пример)

    • Указать свою hit detection функцию (Пример) 

  • “Прилипание” (Пример)

  • Drag’n’Drop (Пример)

• Стилизация

  • Возможность указать свою функцию рендера на канвасе (Пример)

  • Возможность стилизовать на разных уровнях: от всего слоя, до отдельной фичи

  • Возможность стилизовать части геометрии (Пример)

• Возможность привязать любой HTML или SVG элемент к любому месту на карте по координатам 

• Поддержка GeoTIFF

• Поддержка D3.js

• и многое другое

И всё это из коробки, из одного пакета npm!

Проработав с библиотекой несколько лет, выявилась и пара недостатков:

• есть небольшие неудобства в типизации некоторых методов подписки на события (`.on`)

• требует очистки памяти после окончания использования на каждом компоненте (issue #14583)

Мы, в команде НСПД, очень довольны этой библиотекой и рекомендуем к ознакомлению и использованию.

Принцип работы

Библиотека построена с на принципах ООП с добавлением событийно-ориентированного. Сам код представляет собой набор классов, которые общаются друг с другом посредством отправки событий.

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

Однако этот же подход может породить утечки памяти и порождает требование к конечному пользователю не забывать удалять связи между классами, вызывая публичный метод dispose() (issue #14583). Об этом я обязательно напишу отдельную небольшую статью: наша команда уже обожглась с этим моментом и хотелось бы поделиться этим опытом.

Лицензия

OpenLayers распространяется по лицензии FreeBSD или 2-clause BSD. Ссылка на полный текст лицензии.  Лицензия всего лишь обязывает сохранять уведомление об авторских правах и позволяет использовать её в коммерческой разработке без раскрытия исходного кода коммерческого продукта.

---

Практика

Для использования библиотеки необходим любой сборщик модулей, будь то Webpack, Vite, Rollup или любой другой. В своих примерах я буду использовать Vite, он прекрасен.

Для использования OpenLayers, достаточно установить npm пакет командой

npm install ol

Все примеры кода из статьи доступны в онлайн-редакторе StackBlitz, так что для того, чтобы их пощупать совершенно не обязательно устанавливать всё локально. Также весь исходный код примеров доступен на GitHub.

Создаём первую карту

Ссылки на Онлайн-пример и Исходный код.

Создадим простую карту с центром в Москве и тайлами от OpenStreetMap

HTML

<head>   <!-- Стили по умолчанию от OpenLayers -->   <link rel="stylesheet" href="/node_modules/ol/ol.css" />   <!-- Наши стили: сделаем карту во всю ширину страницы -->   <link rel="stylesheet" href="./style.css" /> </head> <body>   <!-- Контейнер для карты -->   <div id="map"></div>   <!-- JavaScript код для инициализации карты -->   <script type="module" src="./index.js"></script> </body>

Стили

html, body {  margin: 0;  height: 100%; } #map {  position: absolute;  top: 0;  bottom: 0;  width: 100%; } 

JavaScript

import { Map, View } from "ol"; import OSM from "ol/source/OSM"; import TileLayer from "ol/layer/Tile";  // Создаём экземпляр карты const map = new Map({  // HTML-элемент, в который будет инициализирована карта  target: document.getElementById("map"),     // Список слоёв на карте  layers: [    // Создадим тайловый слой. Источником тайлов будет OpenStreetMap    new TileLayer({ source: new OSM() }),  ],     // Параметры отображения карты по умолчанию: координата центра и зум  view: new View({    center: [4190701.0645526173, 7511438.408408914],    zoom: 10,  }), });

Каждый установленный параметр затем можно будет изменить в любой момент в ходе выполнения программы

// Можем изменить значения любых переданных параметров map.setTarget(document.getElementById("#another-place-for-map")); map.getView().setZoom(5); map.getView().setCenter([4190701.0645526173, 7511438.408408914]); // и так далее…

Изменим проекцию

Ссылки на Онлайн-пример и Исходный код.

По умолчанию, карта создается с проекцией EPSG:3857 (Web Mercator). Для того, чтобы изменить систему координат на, допустим, EPSG:4326 (WGS 84), следует обновить вызов View.

new View({    projection: 'EPSG:4326',    // ... }),

Соответственно, изменяя проекцию, изменяется и система координат.

Так, например, если мы хотим центрировать карту на Москву для EPSG:3857 мы используем:

new View({    // Москва в EPSG:3857 (метры)    center: [4190701.0645526173, 7511438.408408914], }),

, а для EPSG:4326:

new View({    // Москва в EPSG:4326 (градусы)    center: [37.645708, 55.7632972], })

По умолчанию, OpenLayers включает в себя лишь указанные выше две проекции. Остальные можно добавить самостоятельно. Подробнее об этом можно прочитать здесь.

Подсказка: как получить координаты точки на карте?

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

// Добавляем обработчик клика по карте map.on("click", function (event) {  // Кидаем в консоль координаты  console.log(event.coordinate);  // Часто бывает полезно знать текущий зум  console.log(map.getView().getZoom()); });

Подсказка: конвертация координат

Часто бывает так, что координаты могут быть в разных проекциях. Для удобства использования, OpenLayers предоставляет 2 функции для конвертации координат между EPSG:4326 и EPSG:3857:

import { fromLonLat, toLonLat } from "ol/proj";  // Конвертация координат из EPSG:4326 в EPSG:3857 // Вернёт: [4190701.0645526173, 7511438.408408914] fromLonLat([37.64570817463565, 55.76329720561773]);  // И обратно // Вернёт: [37.64570817463565, 55.76329720561773] toLonLat([4190701.0645526173, 7511438.408408914]);

Тайловые слои

В предыдущем примере мы использовали OpenStreetMap, однако, OpenLayers позволяет использовать любой провайдер тайлов. Также добавлю, что библиотека поддерживает как растровые тайлы, так и векторные.

ArcGIS

Ссылки на Онлайн-пример и Исходный код.

Довольно часто приходится менять тайлы для наших приложений. Для примера, давайте добавим тайлы из сервиса ArcGIS.

import { Map, View } from "ol"; import XYZ from "ol/source/XYZ"; import TileLayer from "ol/layer/Tile";  const map = new Map({  target: document.getElementById("map"),  layers: [    new TileLayer({      source: new XYZ({        attributions:          'Tiles © <a href="https://services.arcgisonline.com/ArcGIS/' +          'rest/services/World_Topo_Map/MapServer">ArcGIS</a>',        url: "https://server.arcgisonline.com/ArcGIS/rest/services/" + "World_Topo_Map/MapServer/tile/{z}/{y}/{x}",      }),    }),  ],  view: new View({    center: [4517934.495704523, -2284501.936731553],    zoom: 5,  }), });

OGC (растровые тайлы)

Ссылки на Онлайн-пример и Исходный код.

import OGCMapTile from 'ol/source/OGCMapTile.js'; import TileLayer from 'ol/layer/Tile.js';  new TileLayer({   // API не подходит для использования XYZ?   // Решение: создать свой подкласс и доработать API под свои нужды   source: new OGCMapTile({     url: 'https://maps.gnosis.earth/ogcapi/collections/blueMarble/map/tiles/WebMercatorQuad',   }), }),

OGC (векторные тайлы)

Ссылки на Онлайн-пример и Исходный код.

Преимущество векторных тайлов над растровыми в том, что они:

• имеют меньший размер файла

• быстрее загружаются

• легко стилизуются

• не размываются

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

import MVT from 'ol/format/MVT.js'; import OGCVectorTile from 'ol/source/OGCVectorTile.js'; import VectorTileLayer from 'ol/layer/VectorTile.js';  new VectorTileLayer({   source: new OGCVectorTile({     url: 'https://maps.gnosis.earth/ogcapi/collections/NaturalEarth:cultural:ne_10m_admin_0_countries/tiles/WebMercatorQuad',     format: new MVT(),   }),   background: '#e2e3e3',   style: {     'stroke-width': 1,     'stroke-color': '#8c8b8b',     'fill-color': '#f7f7e9',   }, })

Подробнее об этом можно прочесть здесь или в Workshop.

Используем дебаггер тайлов

Ссылки на Онлайн-пример и Исходный код.

import TileLayer from "ol/layer/Tile.js"; import TileDebug from "ol/source/TileDebug";  new TileLayer({ source: new TileDebug() })

Подробнее можно почитать здесь. 

Стилизация

Ссылки на Онлайн-пример и Исходный код.

const layer = new TileLayer({  // Выбираем источник для тайлов  source: new OGCMapTile({    url: "https://maps.gnosis.earth/ogcapi/collections/blueMarble/map/tiles/WebMercatorQuad",  }),  // Можем сделать прозрачным  opacity: 0.9,  // Можем скрывать слой, не убирая его из карты (и теряя тем самым настройки)  visible: true,  // Можем менять наложение слоёв друг на друга  zIndex: 5,  // Можем ограничить слой определённой областью  extent: [6717612.447527122, 583571.8523972307, 10985130.57817296, 3294022.5569966147],  // Можем показывать слой лишь в заданных границах зума  maxZoom: 7,  // Можем так же показывать слой лишь на определённых разрешениях (масштабе) карты  // minResolution: 10000,  // maxResolution: 100000, }); map.addLayer(layer);

Пример в видео (не удалось загрузить гифку, так как она больше 8мб ?).

Более того, мы можем использовать ещё и CSS стили для этого слоя. Именно для этого я прописал класс «favorite-layer».

const layer = new TileLayer({  // Можем добавить CSS-стилей  className: "favorite-layer",  // ... });

Так, например, можно добавить эффект размытия

.favorite-layer {   filter: blur(1px); }

Оверлей (Overlay)

Часто бывает, что нужно обычный HTML-элемент «привязать» к определенной координате на карте. 

Для этих целей существует класс `Overlay`. Он хранит в себе координаты позиции на карте и ссылку на HTML-элемент и их связывает. 

Добавляем попап с координатами по клику

В HTML файле мы добавляем такой шаблон

<!-- Шаблон попапа --> <div style="display: none">   <div id="popup" class="popup">     <p>Координаты</p>     <p><span id="coordinates"></span></p>   </div> </div>

В JS файле используем HTML-шаблон

// Попап (без указанного `position` он не будет показан) const popup = document.getElementById("popup"); const overlay = new Overlay({  element: popup,  positioning: "bottom-center",  offset: [0, -4], }); map.addOverlay(overlay);   map.on("click", (event) => {  // Переводим координаты в географические (широта, долгота)  const [lon, lat] = toLonLat(event.coordinate);    // Отображаем в формате "широта, долгота"  const coordsEl = popup.querySelector("#coordinates");  coordsEl.textContent = createStringXY(6)([lat, lon]);    // Закрепляем оверлей за координатой  overlay.setPosition(event.coordinate); });

Отобразим офис компании, использовав маркер и попап

Довольно часто карту используют только для этих целей ?

HTML

<!-- Шаблон маркера --> <template id="marker">  <img width="36" src="/public/icons/marker.svg" alt="Marker" /> </template>   <!-- Шаблон попапа --> <template id="popup">  <div class="popup">    <p>Головной офис БФТ-Холдинг</p>    <p>129085, г. Москва, ст. м. «Алексеевская» ул. Годовикова, д. 9, стр. 17</p>  </div> </template>

JavaScript

// Позиция на карте (головной офис в БФТ) const position = [4188878.742882752, 7520435.741484543];   // Маркер const markerTemplate = document.getElementById("marker"); const marker = markerTemplate.content.cloneNode(true); const markerOverlay = new Overlay({  element: marker,  positioning: "bottom-center",  position: position, }); map.addOverlay(markerOverlay);   // Попап const popupTemplate = document.getElementById("popup"); const popup = popupTemplate.content.cloneNode(true); const popupOverlay = new Overlay({  element: popup,  positioning: "bottom-center",  offset: [0, -36],  position: position, }); map.addOverlay(popupOverlay);

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

Кликабельные маркеры на примере аэропортов Москвы

Мне понравилась эта иконка, поэтому решил добавить этот пример ?

HTML

<div style="display: none">  <!-- Шаблон маркера -->  <img id="marker" class="marker" width="36" src="/public/icons/airport.svg" alt="Marker" />    <!-- Шаблон попапа -->  <div id="popup" class="popup">    <p id="title"></p>  </div> </div>

JavaScript

// Попап const popup = document.getElementById("popup").cloneNode(true); const popupOverlay = new Overlay({  element: popup,  positioning: "bottom-center",  offset: [0, -42], }); map.addOverlay(popupOverlay);   // Функция создания маркеров // По клику на маркер, покажется попап function createMarker(position, title) {  const marker = document.getElementById("marker").cloneNode(true);  const markerOverlay = new Overlay({    element: marker,    positioning: "bottom-center",    position: position,  });  map.addOverlay(markerOverlay);    marker.addEventListener("click", function () {    popupOverlay.setPosition(position);    popup.querySelector("#title").textContent = title;  }); }   // Создание маркеров аэропортов // Аэропорты хранятся в .json файле airports.forEach((airport) => {  createMarker(airport.position, airport.title); });

От себя добавлю, что мы можем использовать не только SVG формат, но и PNG, JPEG и прочие. Всё, что можно добавить в HTML, можно закрепить за координатой на карте.

Также добавлю, что для отображения маркера и всплывашки вместо HTML мы могли бы использовать и векторный слой. Или добавить свою render-функцию в Style и рисовать картинку прямо на canvas-элементе.

Векторный слой

OpenLayers даёт широкие возможности для работы с векторной графикой. 

Ранее я привёл пример добавления векторного тайлового слоя (`VectorTileLayer`). Векторные тайлы хранятся в базе данных на бэкенде, карта запрашивает и рисует тайлы. Здесь же мы рассмотрим работу именно с геометрией: как её нарисовать, как стилизовать, как добавить интерактив.

Как это работает?

OpenLayers предоставляет нам несколько классов для рисования примитивных геом. фигур:

• Point — Точка

• LineString — Линия

• Polygon — Многоугольник

• Circle — Окружность

Из примитивных геометрических фигур складываются сложные, такие как:

• MultiPoint — Множество точек

• MultiLineString — Множество линий

• MultiPolygon — Множество точек

• GeometryCollection — Множество разных геометрий

Пример создания геометрии:

// Создаем геометрию точки const geometry = new Point([6216653.792416765, 2341922.265922518])

Зачастую, с геометрией связаны некие абстрактные данные. Это может быть ID, кадастровый номер, стоимость участка и многое другое. Чтобы связать геометрию на карте и разнородные связанные данные, используется Feature. Грубо говоря, `Feature = Geometry + Properties`.

// Создаем фичу, назначая геометрию (точку, созданную ранее) при инициализации const feature = new Feature(geometry); // Можем заменить геометрию "на лету" feature.setGeometry(geometry); // Можем сохранить ID, чтобы фичу можно было получить в дальнейшем feature.setId(12345); // Можем сохранить абстрактные свойства внутри фичи feature.setProperties({ ... });

Для хранения фич используется векторное хранилище — VectorSource. Оно необходимо, чтобы абстрагировать источник данных.

// Создаем хранилище векторных данных (фич) const source = new VectorSource({   // Можем назначить фичи при инициализации   features: [feature], }); // Можем добавить "на лету" source.addFeature(feature); // В процессе работы, можем получить желаемую фичи по её ID source.getFeatureById(12345);

В текущем примере, мы геометрию и фичу создали вручную. Однако, порой удобнее оставить ссылку на API бэкенда, возвращающего фичи, чтобы VectorSource сам их запросил и сохранил в себе.

import KML from "ol/format/KML";  const source = new VectorSource({   // Ссылка на бэкенд   url: '/some-api',   // Можем задать форматтер входящих данных   // Например, для KML формата   format: new KML(), }); // Ссылку можно динамически обновить source.setUrl('/some-api');

Для того, чтобы отрисовать данные из хранилища данных на карте, нужно использовать векторный слой — VectorLayer. Он нужен, чтобы правильно отрисовать на карте фичи из хранилища.

const layer = new VectorLayer({  source: source,  // Можем добавить фон  background: 'rgba(255, 255, 255, 0.5)',  // Можем добавить HTML-класс, чтобы застилить слой с помощью CSS  className: 'my-layer',  // Можем скрыть/показать  visible: true,  // Можем изменить порядок между слоями, подняв/опустив слой относительно других  zIndex: 5,  // Меняем уровень прозрачности  opacity,  // Можем показывать только в границах заданного зума  minZoom: 3,  maxZoom: 15,  // Или в границах заданного разрешения карты  minResolution: 10_000,  maxResolution: 1_000_000, }); 

Таким образом, шаг за шагом поднимается уровень абстракции. Цепочка добавления геометрии на карту выглядит так: `Geometry -> Feature -> Source -> Layer`.

Добавим геометрических фигур на карту

Ссылки на Онлайн-пример и Исходный код.

Попробуем нарисовать немного простых геометрических фигур на карте. Для этого нам необходимо использовать векторный слой (VectorLayer) и векторное хранилище (VectorSource).

import VectorSource from "ol/source/Vector"; import VectorLayer from "ol/layer/Vector";   const source = new VectorSource(); const layer = new VectorLayer({ source: source });   // Нарисуем точку const point = new Feature({ geometry: new Point([6216653.792416765, 2341922.265922518]) }); source.addFeature(point);   // Нарисуем линию const line = new Feature({  geometry: new LineString([    [6098023.524518171, 2417747.7979814108],    [6195862.920723196, 2569398.8620992005],    [6290033.3395705335, 2406740.865908345],  ]), }); source.addFeature(line);   // Нарисуем полигон const polygon = new Feature({  geometry: new Polygon([    [      [5929250.566064502, 2369439.5961051816],      [5857094.011363296, 2479508.916835835],      [5968386.324546512, 2583463.275303675],      [6096800.532065609, 2503968.765887092],      [6096800.532065609, 2503968.765887092],      [5929250.566064502, 2369439.5961051816],    ],  ]), }); source.addFeature(polygon);   // Нарисуем окружность const circle = new Feature({  geometry: new Circle([6401325.652753751, 2559003.4262524187], 100000), }); source.addFeature(circle);   map.addLayer(layer);

Таким образом, чтобы нарисовать геометрию, нам просто нужно добавить Feature с необходимой геометрией в VectorSource. Карта обновится автоматически и они будут нарисованы. Работать с этим довольно удобно: всё что связанно с данными в одном месте, а всё что связано со стилизацией или группировкой данных — в другом. Главное — не забыть добавить слой на карту ?

Для примера я сохранил в коде несколько координат. На практике, зачастую их предоставляет либо сервер, либо пользователь, загружая файл с координатами (будь-то GeoJSON, KML, ShapeFile) или рисуя на самой карте.

Классы геометрии очень напоминают объекты из стандарта GeoJSON. И не спроста: классы принимают координаты в формате GeoJSON и рисуют соответствующие фигуры из стандарта, что довольно удобно на практике, поскольку и бекенд и фронтенд подчинены одному стандарту. Как пример, в кольцах из линий Polygon-а первая и последняя координаты должны быть равны:

new Polygon([    [      [5929250.566064502, 2369439.5961051816],  // ... координаты ...      [5929250.566064502, 2369439.5961051816],    ], ])

Есть одно исключение — это Circle: мы можем нарисовать окружность, хотя в стандарте GeoJSON никакой окружности не описано.

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

Стилизация

Ссылки на Онлайн-пример и Исходный код.

Попробуем добавить других стилей для всех фич внутри слоя.

new VectorLayer({   // Для стилизации используем класс Style   style: new Style({     // Заливка     fill: new Fill({ color: "rgba(230, 161, 79, 0.4)" }),     // Обводка    stroke: new Stroke({ color: "rgba(230, 161, 79, 1)", width: 2 }),     // Стиль для точки     image: new CircleStyle({       radius: 6,       fill: new Fill({ color: "rgba(230, 161, 79, 0.4)" }),       stroke: new Stroke({ color: "rgba(230, 161, 79, 1)", width: 2 }),     }),  }), });

Свойство `color` может быть любым свойством, которое принимает CanvasRenderingContext2D.fillStyle, т.е. цветом, градиентом или паттерном. Ссылка на более сложный пример здесь.

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

Попробуем добавить стили только для полигона

polygon.setStyle([  // Стили для полигона  new Style({    fill: new Fill({ color: "rgba(193, 211, 63, 0.4)" }),    stroke: new Stroke({ color: "rgba(193, 211, 63, 1)", width: 2 }),  }),  // Стили для вершин  new Style({    image: new CircleStyle({      radius: 6,      fill: new Fill({ color: "rgba(255, 255, 255, 0.7)" }),      stroke: new Stroke({ color: "rgba(147, 211, 63, 1)", width: 4 }),    }),    // Чтобы стилизовать часть геометрии, достаточно получить желаемые части    // Это могут быть грани для полигона или линий, центр для окружности, вершины полигона    geometry: function (feature) {      // Получаем все вершины      const coordinates = feature.getGeometry().getCoordinates()[0];      return new MultiPoint(coordinates);    },  }), ]);

Более подробно о стилизации напишу в отдельной статье, а пока что идем дальше.

Взаимодействие с геометрией

Здесь мы рассмотрим классы из группы `ol/interaction/…`  — классы взаимодействий.

Эти классы дают возможность пользователю непосредственно взаимодействовать с векторными данными: рисовать, изменять, выбирать (кликом или наведением мышкой), использовать Drag’n’Drop и прочее.

Примеры взаимодействий можно посмотреть по ссылке.

Рисование

Попробуем добавить пользователю возможность нарисовать геометрию на карте

import { Draw } from 'ol/interaction';  // Draw - класс для рисования const interaction = new Draw({  type: "Polygon",  source: source, }); map.addInteraction(interaction);   // Колбек на завершение рисовании фичи interaction.on("drawend", (event) => {  const geometry = event.feature.getGeometry();  console.log({    type: geometry.getType(),    coordinates: geometry.getCoordinates(),  }); }); 

Редактирование геометрии

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

import { Modify } from 'ol/interaction';  // Modify - класс для редактирования const interaction = new Modify({  // Мы можем передать VectorSource или список фич  source: source, }); map.addInteraction(interaction);   interaction.on('modifyend', (event) => {  console.log(event.features); });

Выделение

Попробуем совместить получение знания по Overlay и добавим его при выделении объекта.

import { Select } from 'ol/interaction';  // Select - позволяет пользователю выделять кликом мыши геометрию на карте const interaction = new Select({  // Мы можем передать VectorSource или список фич  source: source,  style: new Style({    fill: new Fill({ color: "rgba(255, 255, 255, 0.5)" }),    stroke: new Stroke({ color: "#674ea7", width: 4 }),    image: new CircleStyle({      radius: 6,      fill: new Fill({ color: "#674ea7" }),      stroke: new Stroke({ color: "#fff", width: 4 }),    }),  }), }); map.addInteraction(interaction);   // Попап const popup = document.getElementById("popup").cloneNode(true); const popupOverlay = new Overlay({  element: popup,  positioning: "bottom-center",  offset: [0, 0], }); map.addOverlay(popupOverlay);   // Опционально: добавим оверлей сверху над выделенной геометрией interaction.on("select", (event) => {  const feature = event.selected[0];  if (!feature) {    popupOverlay.setPosition(undefined);    return;  }  const center = getCenter(feature.getGeometry().getExtent());  const title = feature.getProperties().name;  popup.querySelector("#title").textContent = title;  popupOverlay.setPosition(center); });

Контролы (Controls)

Контрол — видимый пользователю интерактивный элемент, который находится в фиксированном положении на карте (зачастую в углах или на краях).

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

Как добавить контрол на карту?

Добавление контрола, так же как и в случае с другими инструментами карты, может происходить либо в конструкторе, либо по вызову `addControl`.

Важно помнить, что по умолчанию, OpenLayers инициализируется с несколькими контролами, в числе которых Zoom, Rotate, Attribution. И если мы хотим их оставить, то необходимо это явно указать.

import { defaults } from "ol/control";   new Map({   // Мы можем оставить контролы по умолчанию   controls: defaults().extend([ new ScaleLine() ]),   // Или не оставлять   controls: [new ScaleLine()], }); // Мы можем добавить/убрать контрол в любой момент map.addControl(new ScaleLine());

Полный список доступных по умолчанию контролов можно посмотреть в документации к API OpenLayers (в поиске следует ввести `ol/control`)

Перемещение пользователя к определённому месту на карте

Ссылки на Онлайн-пример и Исходный код.

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

import { ZoomToExtent } from "ol/control.js";  new ZoomToExtent({   extent: [     4076072.4828566443,     7450792.337368891,     4300910.783649025,     7554077.43179539   ],   label: "М",   tipLabel: "Переместиться в Москву", })

Подробнее об этом контроле можно почитать здесь.

Анимируем контрол из примера выше

Ссылки на Онлайн-пример и Исходный код.

Хотя предыдущий контрол делает свою работу, но всё же что-то не то. Выглядит резко и не очень приятно. Давайте добавим анимацию, расширив изначальный класс контрола.

Наконец-то нашёл место, где уместно показать расширение через наследование ?

import { ZoomToExtent } from "ol/control.js"; import { easeOut } from "ol/easing";  class ZoomToExtentWithAnimation extends ZoomToExtent {   /**    * @protected    */   handleZoomToExtent() {     const view = this.getMap().getView();     const extent = this.extent || view.getProjection().getExtent();      // Добавляем анимацию     view.fit(extent, { duration: 300, easing: easeOut });   } }  new ZoomToExtentWithAnimation({   extent: [4076072.4828566443, 7450792.337368891, 4300910.783649025, 7554077.43179539],   label: "М",   tipLabel: "Переместиться в Москву", }); 

Получается более приятная анимация перехода к заданному месту

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

Миникарта

Ссылки на Онлайн-пример и Исходный код.

Для этого используем контрол из библиотеки — OverviewMap.

import TileLayer from "ol/layer/Tile.js"; import OSM from "ol/source/OSM.js"; import { OverviewMap } from "ol/control.js";  const сontrol = new OverviewMap({  // На эти классы добавим CSS (в примере style.css)  className: "ol-overviewmap ol-custom-overviewmap",  layers: [new TileLayer({ source: new OSM() })],  collapseLabel: "\u00BB",  label: "\u00AB",  collapsed: false, });

Миникарта, как и многие контролы, легко стилизуема. Мы можем заменить контейнер на любой HTML-элемент, вынося таким образом миникарту в любое место страницы. Можно заменить тайловый слой и стили.

Немного поигравшись со стилями легко получаем следующий пример комбинации OSM-слоя на основной карте и StadiaMaps в миникарте со скруглёнными краями.

Ссылки на Онлайн-пример и Исходный код.

Подробнее об этом контроле можно почитать здесь.

Отобразим текущие координаты под курсором

Ссылки на Онлайн-пример и Исходный код.

import MousePosition from "ol/control/MousePosition.js";  const mousePositionControl = new MousePosition({   // Количество цифр после запятой   coordinateFormat: createStringXY(4),   projection: "EPSG:4326",   className: "control-coordinates ol-unselectable ol-control",   target: document.querySelector("#map .ol-overlaycontainer-stopevent"), }); map.addControl(mousePositionControl);

Подробнее об этом контроле можно почитать здесь.

Геолокация

Ссылки на Онлайн-пример и Исходный код.

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

import Feature from "ol/Feature.js"; import Geolocation from "ol/Geolocation.js"; import Point from "ol/geom/Point.js"; import { Circle as CircleStyle, Fill, Stroke, Style } from "ol/style.js"; import { Vector as VectorSource } from "ol/source.js"; import { Vector as VectorLayer } from "ol/layer.js"; import Control from "ol/control/Control";  /** * Создаем свой класс контрола как дочерний от Control */ export class GeolocationControl extends Control {  // При обновлении геометрии в фичах, автоматически произойдёт перерисовка слоя карты  accuracyFeature = new Feature();  positionFeature = new Feature();  layer = new VectorLayer({ source: new VectorSource({ features: [this.accuracyFeature, this.positionFeature] }) });   constructor() {    const element = document.createElement("div");    super({ element: element });     // Подготавливаем вёрстку    // Иконка взята из https://icons8.com/icons/set/location    element.className = "control-geolocation ol-unselectable ol-control";    const button = document.createElement("button");    button.innerHTML = '<img src="https://img.icons8.com/ios/50/marker--v1.png" alt="marker--v1"/>';    element.appendChild(button);    button.addEventListener("click", this._handleClick.bind(this));     // Подготавливаем класс, отслеживающий геолокацию    // Является оберткой над Geolocation API    // @see https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API    const geolocation = new Geolocation({ trackingOptions: { enableHighAccuracy: true } });    geolocation.on("error", (error) => {      alert(error.message);    });    geolocation.on("change:accuracyGeometry", () => {      this.accuracyFeature.setGeometry(geolocation.getAccuracyGeometry());    });    geolocation.on("change:position", () => {      const coordinates = geolocation.getPosition();      const geometry = coordinates ? new Point(coordinates) : null;      this.positionFeature.setGeometry(geometry);      if (geometry) {        this.getMap()?.getView().fit(geometry, { duration: 300, maxZoom: 13 });      }    });     // Добавляем чуть более красивых стилей    this.positionFeature.setStyle(      new Style({        image: new CircleStyle({          radius: 6,          fill: new Fill({ color: "#3399CC" }),          stroke: new Stroke({ color: "#fff", width: 2 }),        }),      })    );    this.geolocation = geolocation;    this.button = button;  }  /**   * @overrides   * Метод вызывает OpenLayers при встраивании контрола в карту   */  setMap(map) {    super.setMap(map);    if (map) {      this.geolocation.setProjection(map.getView().getProjection());      map.addLayer(this.layer);    }  }  /**   * Обработчик клика по кнопке контрола   */  _handleClick() {    this.geolocation.setTracking(true);  } }

Стоит обратить внимание на стиль самой точки на карте — она изображена в виде иконки.

new Style({  image: new Icon({    width: 36,    src: "/public/icons/human.svg",  }), });

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

Подробнее о классах Geolocation и Control можно почитать, перейдя по ссылкам.

Заключение

Мы рассмотрели и попробовали на практике библиотеку OpenLayers. В дальнейшем я планирую написать ещё несколько статей на более специфичные темы: работа с GeoTIFF, как работает рендер, внутреннее устройство классов, подробнее про интерактив, и так далее. Если у вас остались вопросы, смело оставляйте их в комментариях.

И в завершение хотелось бы узнать, какую библиотеку для построения карт вы используете и почему выбрали именно её?

А я с вами прощаюсь, до новых встреч!