Требования и совместимость

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

Основная среда выполнения — современные браузеры с поддержкой стандартов ECMAScript, DOM и CSS. Поддержка охватывает как настольные, так и мобильные платформы.

Поддерживаемые браузеры

  • Chrome (современные версии на базе Chromium)
  • Firefox (актуальные версии с поддержкой современных API DOM)
  • Safari (macOS и iOS, включая мобильные WebKit)
  • Edge (Chromium-based)
  • Opera (Chromium-based)

Поддержка старых браузеров возможна частично, но зависит от версии. Основные ограничения связаны с отсутствием современных возможностей JavaScript и CSS, таких как requestAnimationFrame, classList, querySelector и SVG-рендеринг.

Мобильные браузеры

Leaflet изначально проектировался с учётом сенсорных устройств. Поддерживаются:

  • Safari Mobile (iOS)
  • Chrome for Android
  • Samsung Internet

Особенности мобильной совместимости:

  • обработка touch-событий вместо mouse-событий
  • инерционная прокрутка карты
  • масштабирование pinch-to-zoom
  • оптимизация отрисовки для слабых GPU

Требования к JavaScript среде

Leaflet не требует сборщиков или серверной среды. Он работает напрямую в браузере.

Минимальные требования JavaScript

  • ECMAScript 5 как базовый уровень совместимости
  • Поддержка JSON
  • Поддержка addEventListener
  • Поддержка Function.prototype.bind (в старых окружениях требуется полифилл)

Современные версии библиотеки используют возможности ES6, но с сохранением обратной совместимости через транспиляцию или встроенные проверки.

Отсутствие зависимости от фреймворков

Leaflet не зависит от:

  • React
  • Vue
  • Angular
  • jQuery

Библиотека полностью самостоятельна и взаимодействует напрямую с DOM API.

HTML и CSS требования

Контейнер карты

Ключевое требование — наличие DOM-элемента с заданной высотой:

<div id="map"></div>

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

Минимально корректное CSS-описание:

#map {
  height: 400px;
}

Стили библиотеки

Leaflet требует подключения основного CSS-файла. Он отвечает за:

  • расположение тайлов
  • стили элементов управления
  • отображение маркеров
  • анимации переходов

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

Зависимости и окружение

Внешние зависимости

Leaflet не имеет обязательных runtime-зависимостей. Все функции реализованы внутри библиотеки.

Допустимые дополнительные компоненты:

  • tile-серверы (OpenStreetMap, Mapbox и другие)
  • GeoJSON источники данных
  • WMS/WMTS сервисы

Сетевые требования

Для отображения карты требуется доступ к тайловому серверу. Обычно используются HTTP(S)-запросы к:

  • тайлам изображений (PNG, JPG, WebP)
  • векторным данным (GeoJSON, TopoJSON)

Отсутствие сети не блокирует библиотеку, но делает невозможной загрузку картографического слоя.

Поддержка модульных систем

Leaflet может использоваться в различных системах сборки.

Global namespace (классический способ)

Подключение через <script> приводит к появлению глобального объекта L.

CommonJS

Поддержка Node-сред и сборщиков:

const L = require('leaflet');

ES Modules

Современный формат импорта:

import L from 'leaflet';

Требования:

  • наличие bundler (Vite, Webpack, Rollup)
  • корректная обработка CSS через loader

Совместимость с Node.js

Leaflet не предназначен для серверного выполнения. Однако возможно ограниченное использование:

  • генерация GeoJSON
  • подготовка данных для карт
  • тестирование утилитарных функций

Отсутствуют DOM и Canvas API, поэтому рендеринг карты невозможен без эмуляции браузерного окружения.

Аппаратные требования

Leaflet рассчитан на широкий диапазон устройств.

Минимальные требования

  • 512 МБ оперативной памяти (условно для старых устройств)
  • поддержка GPU ускорения необязательна
  • процессор с поддержкой базового JavaScript исполнения

Рекомендуемые условия

  • аппаратное ускорение CSS transforms
  • WebGL (при использовании плагинов)
  • стабильное интернет-соединение для загрузки тайлов

Ограничения совместимости

Отсутствие поддержки без браузера

Leaflet не функционирует в средах без DOM:

  • чистый Node.js
  • CLI-окружения
  • серверные рендереры без DOM-эмуляции

Ограничения старых браузеров

  • отсутствие SVG → ограничение вектора
  • отсутствие Promise → требуется полифилл
  • отсутствие Object.assign → возможна деградация функциональности

Особенности CORS

Тайловые серверы должны поддерживать CORS-заголовки при кросс-доменных запросах. Без этого:

  • блокируется загрузка тайлов
  • ограничивается использование внешних GeoJSON источников

Совместимость с графическими API

Leaflet использует несколько стратегий рендеринга:

DOM-based rendering

  • основной режим
  • маркеры и слои как HTML элементы
  • максимальная совместимость

SVG rendering

  • используется для векторных слоёв
  • требует поддержки SVG в браузере

Canvas rendering

  • применяется для больших наборов данных
  • улучшает производительность при плотной визуализации

Версионная совместимость

Leaflet развивается в рамках стабильной API-архитектуры.

Особенности версионирования

  • minor-версии сохраняют обратную совместимость
  • major-версии могут изменять API поведения слоёв и событий

Совместимость плагинов

Плагины привязываются к конкретным версиям API:

  • события карты
  • система слоёв
  • интерфейсы расширений

Несовместимость версий проявляется в:

  • нарушении обработки событий
  • ошибках рендеринга слоёв
  • некорректной работе контролов

Интеграция с современными фронтенд-сборками

Webpack / Vite

Требуется обработка:

  • CSS импортов Leaflet
  • статических ассетов (иконки маркеров)

TypeScript окружение

Leaflet предоставляет типизацию:

  • определения интерфейсов Map, Layer, Marker
  • строгая типизация событий

Tree-shaking

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

Поддержка DPI и экранов высокой плотности

Leaflet адаптируется к:

  • Retina-дисплеям
  • high DPI экранам

Механизм:

  • замена тайлов с суффиксом @2x
  • масштабирование иконок маркеров
  • корректировка CSS transform scale

Географическая и проекционная совместимость

Leaflet использует Web Mercator (EPSG:3857) как базовую проекцию.

Особенности:

  • глобальная совместимость тайловых сервисов
  • поддержка WGS84 координат (EPSG:4326) через конвертацию
  • ограничение полярных областей при некоторых тайловых источниках

Итоговая структура требований окружения

  • браузер с DOM и CSS поддержкой
  • JavaScript ES5+ (желательно ES6+)
  • подключённый CSS библиотеки
  • контейнер с заданной высотой
  • доступ к сетевым ресурсам тайлов
  • отсутствие жёстких зависимостей от фреймворков
  • поддержка событийной модели браузера
Оглавление