{"canonical_url":"https://engineer.company/uk/glossary/leaflet/","content_markdown":"# Leaflet\n\n## Що це таке\n\nLeaflet — це бібліотека JavaScript із відкритим кодом, яка перетворює один\nелемент вебсторінки на карту, яку можна панорамувати, масштабувати й натискати.\nПроєкт оцінює її розмір приблизно в 42 KB JavaScript і зазначає, що вона\nобходиться без зовнішніх залежностей. Її створив Володимир Агафонкін, тепер її\nрозвиває спільнота учасників, а поширюється вона за ліцензією BSD 2-Clause.\n\nВласний огляд проєкту каже, що Leaflet не намагається робити все для всіх і\nзосереджується на тому, щоб базові речі працювали добре. `L.map` приймає елемент\nі набір параметрів і стає картою. Шар плиток завантажує квадратні зображення за\nшаблоном URL із `{z}`, `{x}` і `{y}` і розкладає їх сіткою елементів зображень,\nа варіант WMS робить те саме з Web Map Service. Ламані, полігони, кола й\nпрямокутники за замовчуванням малюються як SVG або на одному canvas, якщо карту\nстворено з `preferCanvas`. Маркери — це іконки, зображення або звичайний `div`,\nдо яких прив'язуються спливні вікна й підказки. Шар GeoJSON перетворює кожен\nоб'єкт на один із цих шарів, а точку — на маркер, якщо не вказано інше. Кнопки\nмасштабу, атрибуція, перемикач шарів і масштабна лінійка становлять елементи\nкерування. Система координат за замовчуванням — EPSG:3857, яку довідник називає\nнайпоширенішою для онлайн-карт.\n\nУсе, що виходить за межі цього списку, дають плагіни. База плагінів проєкту\nописує Leaflet як задуманий бути якомога легшим і вказує на сотні сторонніх\nплагінів, розкладених за групами: векторні плитки, кластеризація, теплові карти,\nредагування геометрії, маршрутизація, геокодування.\n\nНа момент написання існують дві лінії випусків. Стабільна — 1.9.4, випущена 18\nтравня 2023 року, і саме її відображає довідник API на сайті проєкту. Попередній\nвипуск 2.0.0-alpha.1 від 16 серпня 2025 року прибирає підтримку Internet\nExplorer і постачається як ES-модуль. Глобальний `L` у ньому лишається тільки в\nзібраному файлі `leaflet-global.js`, фабричні функції замінено конструкторами,\nтож `L.marker(latlng)` стає `new Marker(latlng)`, а введення обробляється через\npointer events.\n\n## Чому це важливо\n\nДодати карту на сторінку — це два рішення, які легко сплутати з одним: який код\nмалює карту в браузері і звідки беруться зображення карти. Leaflet тримає їх\nокремо, і вибір Leaflet здебільшого означає вибір тримати їх окремо.\n\nLeaflet малює. Плитки надходять звідти, куди вказує шаблон URL, тож базова карта\n— окреме рішення з власною ціною, умовами й власником. Це може бути сервер\nплиток OpenStreetMap, поки функцію розробляють, комерційний постачальник у\nпродакшні, сервер плиток, який проєкт тримає сам, або WMS міської адміністрації\nчерез `TileLayer.WMS`. Перехід між ними змінює один рядок у коді й текст\nатрибуції, а код застосунку навколо карти лишається як є.\n\nРозмір і ліцензія визначають, де Leaflet почувається природно. Близько 42 KB і\nвідсутність залежностей пасують сторінці, де карта — одна частина серед\nбагатьох: формі, де людина ставить шпильку, чи адмінпанелі, що показує, де\nрозташовані записи. Ліцензія BSD 2-Clause не ставить між бібліотекою і сторінкою\nні облікового запису, ні ключа, ні лічильника.\n\nЦіна малого ядра в тому, що важчі функції приходять окремими пакетами, кожен зі\nсвоїм супровідником і темпом випусків, і карта, що спирається на шість плагінів,\nуспадковує шість шляхів оновлення. Альфа 2.0 показує, що це означає: її нотатки\nпро перехід на нову версію радять користувачам старіших плагінів поліфіл V1, бо\nці плагіни очікують глобальний `L` і фабричні функції. Карті, якій потрібні\nвекторні плитки зі стилями в браузері на кожному рівні масштабу, краще підходить\nбібліотека, побудована довкола них, і це рішення варто ухвалити раніше, ніж\nшість плагінів триматимуть карту.\n\n## Як це виглядає на практиці\n\nLeaflet з'являється на двох сторінках цього сайту, обидві — з ролі керівниці\nкоманди розробки GIS-програмного забезпечення у 2015–2022 роках, і на обох він\nділить фронтенд із Mapbox.\n\nРоль охоплювала постачання\n[понад тридцяти GIS-проєктів від розробки й розгортання до підтримки](/uk/portfolio/led-30-gis-projects-from-build-to-support/).\nНа фронті цих проєктів стояли вебкарти на Mapbox GL і Leaflet, іноді з\nвикористанням API ArcGIS чи HERE, а рівень застосунку писали на JavaScript,\nPython, PHP і SQL. Під ними лежав PostgreSQL із PostGIS, а GDAL/OGR переносив\nдані між shapefile, GeoJSON, GeoTIFF, KML і векторними плитками.\nВідповідальність сягала далі за запуск, аж до підтримки в продакшні.\n\nТа сама роль брала участь і в\n[проєктуванні інтерфейсів цих проєктів](/uk/portfolio/contributed-to-user-interface-design-processes/).\nЦе були фронтенди на React, Angular і Vue поверх карт Mapbox і Leaflet, і\nсторінка робить зауваження, яке варто тримати поруч із будь-якою картографічною\nбібліотекою: у вебкартографічному продукті карта — найпростіша частина, а\nгубляться люди в елементах керування, фільтрації та послідовності дій навколо неї.\nЗручність залежала від деталей, як-от того, як фільтрувався набір даних і як\nлюдина переходила між поверхами на карті приміщення, і більшу частину різниці\nсторінка пояснює тим, що ці питання ставили під час дизайну, а не після релізу.\n\n## Де виникають проблеми\n\nLeaflet досить малий, щоб більшість його збоїв походила зі сторінки навколо\nнього або від сервісів, на які він спрямований.\n\n**Карта показується як сірий прямокутник або смужка розкиданих плиток.** Leaflet\nбере розмір від свого контейнера. Посібник Quick Start називає дві речі, які\nтреба зробити до запуску будь-якого коду карти: підключити CSS-файл Leaflet\nперед JavaScript і задати контейнеру визначену висоту. `div` без висоти дає\nкарту без висоти. Підступніший випадок — карта, створена у вкладці чи діалозі,\nякі в той момент приховані: вона вимірює себе як нуль і зберігає цей розмір,\nколи з'являється. Leaflet 1.x стежить за зміною розміру вікна браузера через\n`trackResize`, тож контейнер, що змінює розмір сам, лишається непоміченим, доки\nкод не викличе `invalidateSize()`, який довідник радить викликати після зміни\nрозміру карти. Альфа 2.0 використовує `ResizeObserver` замість події resize\nвікна.\n\n**Точки опиняються за тисячі кілометрів.** GeoJSON, як його визначає RFC 7946,\nзаписує позицію з довготою першою. `LatLng` у Leaflet і масиви, які бібліотека\nприймає замість нього, мають широту першою. `L.geoJSON` сам перетворює одне в\nінше, тож помилка з'являється, коли координати витягають із GeoJSON вручну й\nпередають прямо в маркер чи ламану. Точка в Копенгагені з переставленими\nкоординатами потрапляє в Аравійське море. Розпакуйте пару в іменовані змінні на\nмежі:\n\n```js\nconst res = await fetch(\"/api/sites/42\");\nconst site = await res.json();\nconst [lon, lat] = site.geometry.coordinates; // GeoJSON: lon, lat\nL.marker([lat, lon]).addTo(map); // Leaflet: lat, lng\n```\n\n**Панорамування смикається, коли даних стає більше.** Із рендерером SVG кожна\nлінія чи полігон — окремий елемент документа, і кожен стандартний маркер —\nокреме зображення. Шар із багатьма тисячами об'єктів — це багато тисяч\nелементів, які браузер має пересувати під час кожного панорамування й\nмасштабування. `preferCanvas: true` малює контури на одному canvas, але\nстосується лише контурів, тож точки треба перетворити на `L.circleMarker`, коло\nз фіксованим радіусом у пікселях, яке саме є контуром, через параметр\n`pointToLayer` шару GeoJSON. Далі відповідь — надсилати менше: плагін\nкластеризації або API, що повертає лише те, що потрапляє в поточну область перегляду на заданому\nмасштабі.\n\n**Плитки перестають завантажуватися після запуску.** Посібник Quick Start будує\nпершу карту на сервері плиток OpenStreetMap і прямо каже, що ці плитки годяться\nдля програмування, але перед продакшеном слід прочитати Tile Usage Policy. Ці\nправила вимагають видимої атрибуції, User-Agent, що ідентифікує застосунок, і\nкоректного Referer із вебсторінок, кешування відповідно до HTTP-заголовків, а\nмасове й попереднє завантаження плиток забороняють. Вони не дають угоди про\nрівень обслуговування й дозволяють заблокувати доступ без попередження.\nНавантаженій продакшен-карті місце в постачальника, чиї умови пасують до її\nтрафіку, або на власному сервері плиток, і з Leaflet такий перехід зводиться до\nшаблону URL і тексту атрибуції.\n\n## Що почитати далі\n\n- [Leaflet](https://leafletjs.com/) — огляд проєкту, перелік можливостей і перша\n  карта в кілька рядків.\n- [Leaflet API reference](https://leafletjs.com/reference.html) — кожен клас,\n  параметр і метод у 1.9.4, зокрема `preferCanvas`, `invalidateSize` і параметри\n  GeoJSON.\n- [Leaflet Quick Start Guide](https://leafletjs.com/examples/quick-start/) —\n  CSS, висота контейнера й перший шар плиток, крок за кроком.\n- [Leaflet 2.0 Alpha released](https://leafletjs.com/2025/05/18/leaflet-2.0.0-alpha.html)\n  — що змінюється у 2.0 і як мігрувати код і плагіни.\n- [Tile Usage Policy](https://operations.osmfoundation.org/policies/tiles/) —\n  умови користування серверами плиток openstreetmap.org.\n- [RFC 7946: The GeoJSON Format](https://www.rfc-editor.org/rfc/rfc7946) —\n  стандарт GeoJSON, зокрема порядок позицій із довготою першою.\n\n\u003chttps://engineer.company/uk/glossary/leaflet/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"Як Leaflet перетворює елемент сторінки на вебкарту, що лишає постачальникам плиток і плагінам, і пастки з висотою, координатами та правилами плиток.","formats":{"gemtext":"https://engineer.company/uk/glossary/leaflet/index.gmi","gopher":"https://engineer.company/uk/glossary/leaflet/gophermap","html":"https://engineer.company/uk/glossary/leaflet/","json":"https://engineer.company/uk/glossary/leaflet/index.json","markdown":"https://engineer.company/uk/glossary/leaflet/index.md","pdf":"https://engineer.company/uk/glossary/leaflet/index.pdf"},"kind":"page","language":"uk","title":"Що таке Leaflet?","url":"https://engineer.company/uk/glossary/leaflet/","version":1}