Leaflet

Типичное использование Leaflet заключается в привязке карты к какому-либо элементу веб-страницы, например, к блоку <div>, после чего к карте добавляются слои и маркеры.

 // create a map in the "map" div, set the view to a given place and zoom
 var map = L.map('map').setView([55.432, 37.654], 13);

 // add an OpenStreetMap tile layer
 L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {
     attribution: '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
 }).addTo(map);

Библиотека Leaflet доступна через переменную L.

Leaflet поддерживает слои Web Map Service (WMS), GeoJSON, векторные и тайловые слои. Многие другие типы слоёв поддерживаются дополнительными модулями.

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

Leaflet является независимой библиотекой и не использует сторонний программный движок. Вместо этого она сама представляет собой движок, написанный на JavaScript без внешних зависимостей и использующий HTML5 и CSS3 для отрисовки. Разработчикам предоставляется программный интерфейс (API) для создания и управления элементами карты.

Библиотека не имеет встроенных языков интерфейса, поскольку локализация карты зависит от внешних факторов. Текстовые надписи на самой карте (названия городов, улиц) являются частью изображений (тайлов), которые Leaflet получает от картографического сервиса^[12], а любой другой текст в элементах управления и всплывающих окнах задаётся непосредственно разработчиком при написании кода^[13].

Основные типы объектов Leaflet:^[14]

• Растровые типы (TileLayer и ImageOverlay)
• Векторные типы (Path, Polygon и специфические типы, такие как Circle)
• Групповые типы (LayerGroup, FeatureGroup и GeoJSON)
• Управляющие элементы (Zoom, Layers и т. д.)

Также существуют вспомогательные классы для управления проекциями, трансформаций и взаимодействия с объектной моделью документа (DOM).

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

Векторные форматы

• GeoJSON — основной формат для векторных данных, поддерживаемый ядром библиотеки. Leaflet позволяет отображать все типы геометрий GeoJSON, включая точки, линии и полигоны, с помощью слоя `L.geoJSON()`^[15].
• KML, GPX, TopoJSON, WKT и CSV — поддержка этих форматов обеспечивается через плагины. Например, плагин `Leaflet-omnivore` позволяет загружать данные в этих форматах, преобразуя их в GeoJSON^[16].
• WFS — работа со слоями WFS, которые позволяют запрашивать и редактировать пространственные данные, также реализуется с помощью сторонних плагинов^[17].

Растровые форматы

• Тайловые слои — основа большинства карт в Leaflet. Библиотека загружает с сервера фрагменты карты (тайлы), как правило, в формате PNG или JPEG, и формирует из них единое изображение.
• WMS — ядро Leaflet нативно поддерживает добавление растровых слоёв, предоставляемых по протоколу WMS.
• Отдельные изображения (Image Overlays) — библиотека позволяет накладывать на карту одиночные растровые изображения (например, в формате PNG или JPG), привязывая их к географическим координатам.

Ядро библиотеки не имеет встроенных функций для экспорта файлов, однако эта функциональность достигается с помощью встроенных методов и сторонних плагинов.

GeoJSON

Векторные слои (маркеры, линии, полигоны) могут быть преобразованы в формат GeoJSON с помощью встроенного метода `.toGeoJSON()`^[18]. Полученная структура данных затем может быть сохранена в файл средствами JavaScript^[19].

Растровые изображения (PNG, JPEG)

Экспорт карты в форматы PNG или JPEG реализуется через плагины (например, Leaflet.Export^[20]) или сторонние библиотеки (например, html2canvas), которые делают «снимок» DOM-элемента карты.

Другие форматы (GPX, KML)

Экспорт в специализированные форматы, такие как GPX или KML, возможен с помощью плагинов^[21] или путём самостоятельной конвертации данных слоя в необходимую XML-структуру^[22].

Leaflet является кроссплатформенной библиотекой, и её работа поддерживается на любой операционной системе, где функционирует совместимый веб-браузер, включая настольные (Windows, macOS, Linux) и мобильные (iOS, Android) платформы. Актуальные версии библиотеки (начиная с ветки 1.9.x) ориентированы на поддержку так называемых «вечнозелёных браузеров» — последних версий Chrome, Firefox, Safari и Microsoft Edge^[23][24]. Поддержка Internet Explorer была официально прекращена^[23], и этот отказ закреплён в архитектуре будущей версии 2.0.

Leaflet является проектом с открытым исходным кодом и распространяется под разрешительной 2-пунктной лицензией BSD. Эта лицензия позволяет свободно использовать, изменять и распространять библиотеку, в том числе в коммерческих проектах, при условии сохранения уведомления об авторских правах и отказа от ответственности в исходном коде или бинарных файлах. Программное обеспечение предоставляется «как есть», без каких-либо гарантий.

Такие условия позволяют использовать Leaflet на большинстве веб-сайтов без существенных юридических ограничений. При этом следует учитывать, что лицензия самой библиотеки не распространяется на данные (например, картографические тайлы), которые отображаются с её помощью. Условия использования этих данных определяются их поставщиком (например, OpenStreetMap, Mapbox и другими).

Leaflet традиционно сравнивают с OpenLayers — обе библиотеки являются клиентскими JavaScript-библиотеками с открытым исходным кодом. Leaflet изначально создавалась как более легковесная альтернатива, и её размер составляет около 42 КБ в сжатом виде (gzipped)^[25]. Однако прямое сравнение размеров полных дистрибутивов с современными версиями OpenLayers стало некорректным. OpenLayers использует модульный подход: разработчики устанавливают пакет «ol» и импортируют только необходимые классы и функции^[26]. Благодаря механизму «tree shaking» (встряхивание дерева) в итоговый файл приложения попадает только используемый код, что значительно уменьшает его размер^[27]. Аналогичный переход на модули ECMAScript с поддержкой tree shaking реализован и в разрабатываемой версии Leaflet 2.0^[28].

Также её сравнивают с проприетарной закрытой Google Maps API (впервые вышла в 2005) и Bing Maps API — они обе используют значительную часть на стороне сервера для предоставления таких услуг, как геокодировние, прокладка маршрутов, поиск и интеграция с дополнительным ПО, таким как Google Earth. Google Maps API дают скорость и простоту вместе с гибкостью, однако дают доступ только к сервисам Google Maps. Впрочем, DataLayer — часть Google’s API — позволяет использовать внешние данные^[29].

Leaflet была создана в 2011 году украинским разработчиком Владимиром Агафонкиным во время его работы в компании CloudMade. Проект вырос из внутренней библиотеки «Web Maps API», существовавшей в 2010 году, и был официально выпущен как Leaflet 13 мая 2011 года.

• 0.1: 17 мая 2011
• 0.2: 18 июня 2011
• 0.3: 14 февраля 2012
• 0.4: 30 июля 2012
• 0.5: 17 января 2013

В версии 0.5 появилась поддержка дисплеев с повышенной плотностью и различные улучшения пользовательского интерфейса^[30].

• 0.6: 26 июня 2013

В этой версии расширен ряд методов и событий API, улучшена юзабилити и добавлено сохранение GeoJSON. Она была завершена в ходе двухдневного код-спринта, поддержанного Mapbox^[31].

• 0.7: 22 ноября 2013

Релиз был сконцентрирован на устранении неполадок. Было объявлено, что в ходе переработки будет пропадать обратная совместимость^[32].

• 1.0: 27 сентября 2016

По сравнению с версией 0.7.7 было сделано более 400 изменений^[33].

• 1.1: 27 июня 2017
• 1.2: 8 августа 2017
• 1.3: 15 января 2018
• 1.4: 30 декабря 2018
• 1.5: 8 мая 2019
• 1.6: 17 ноября 2019
• 1.7.1: 4 сентября 2020

Релиз содержал исправления, связанные с событиями касания (PointerEvent). Версия 1.7.0 была пропущена из-за проблем с публикацией в npm^[34].

• 1.8.0: 18 апреля 2022

Крупное обновление, вышедшее после полутора лет разработки и сфокусированное на исправлении ошибок и повышении надёжности^[35].

• 1.9.3: 18 ноября 2022

Релиз, подготовивший переход на версию 2.0. После его выхода ветка 1.x была переведена в режим поддержки с выпуском только критических исправлений. Поддержка модулей ESM, добавленная в версии 1.9.0, была временно отменена из-за проблем совместимости с плагинами.

• 1.9.4: 18 мая 2023

Последняя стабильная версия ветки 1.x, включающая исправления для браузеров на основе Chromium и Safari^[36].

• 2.0.0-alpha.1: 16 августа 2025

Первая публичная предварительная версия, знаменующая собой значительную модернизацию кодовой базы. Ключевые изменения включают полный переход на модули ESM с поддержкой tree shaking, использование классов ES6 и PointerEvents, а также прекращение поддержки Internet Explorer.