Исходный код библиотеки Leaflet организован как модульная структура, рассчитанная на поддержку расширяемости, сборки и повторного использования компонентов. Репозиторий построен таким образом, чтобы отделять исходные модули, утилиты, стили, конфигурации сборки и готовые артефакты дистрибуции.
В основе проекта лежит каталог src, содержащий весь
функциональный код библиотеки. Он разбит на логические группы модулей,
отражающие архитектуру картографического ядра.
Структура src:
map/ — реализация объекта карты, управление состоянием,
слоями, событиями взаимодействия.layer/ — набор классов слоёв, включая тайловые,
векторные и группы слоёв.geo/ — географические вычисления, преобразования
координат, работа с проекциями.dom/ — утилиты для взаимодействия с DOM, обработка
событий мыши и сенсорных устройств.control/ — элементы управления интерфейсом карты (зум,
слои, масштабная линейка).geometry/ — математические структуры: точки, границы,
прямоугольники, полигоны.util/ — вспомогательные функции общего назначения.Каждый модуль внутри этих директорий реализует отдельный класс или набор связанных функций, минимизируя взаимные зависимости.
Ключевым компонентом является объект карты, определённый в модуле
Map. Он не существует изолированно, а связан с системой
слоёв и системой координат.
Внутри структуры исходников логика карты отделена от визуального представления. Это выражается в том, что:
Такое разделение обеспечивает возможность тестирования отдельных компонентов без необходимости инициализации всей карты.
Директория layer содержит реализацию всех типов слоёв,
которые добавляются на карту. Каждый слой наследуется от базового класса
Layer, определяющего общий интерфейс жизненного цикла.
Основные подтипы:
Каждый слой реализует стандартные методы:
onAdd);onRemove);Такое унифицированное поведение позволяет карте управлять любыми слоями одинаковым способом.
Каталог geo отвечает за математическую модель
отображения карты. В нём реализованы:
Важная часть этой подсистемы — работа с проекцией Web Mercator, которая используется для большинства тайловых карт. Здесь же находятся функции масштабирования и вычисления тайловых индексов.
Отдельное внимание уделяется точности вычислений, поскольку любые ошибки в преобразовании координат напрямую влияют на визуальное позиционирование объектов.
Модуль dom изолирует работу с браузерным окружением. Он
обеспечивает:
Важной особенностью является абстракция над нативными DOM-событиями. Leaflet приводит их к унифицированному формату, используемому внутри всей библиотеки.
Директория control содержит элементы пользовательского
интерфейса, которые накладываются поверх карты.
Типичная структура контролов:
Control, определяющий позиционирование и
жизненный цикл;Контролы реализуются как DOM-элементы, но интегрируются в систему событий карты, что позволяет им реагировать на изменения состояния карты без прямых зависимостей.
Модуль geometry содержит базовые структуры данных:
Эти структуры используются во всех частях библиотеки, обеспечивая единый формат представления пространственных данных.
Операции над геометрией реализованы как чистые функции или методы классов без побочных эффектов, что упрощает тестирование и повторное использование.
Каталог util включает функции общего назначения:
Эти функции используются в разных частях библиотеки и не привязаны к конкретной предметной области. Их задача — минимизировать дублирование кода.
Стили библиотеки находятся отдельно от JavaScript-кода. Они определяют:
CSS-структура организована так, чтобы минимально вмешиваться в стили пользовательского приложения. Основной принцип — нейтральность оформления.
Каталог сборки обычно включает конфигурации и скрипты, отвечающие за генерацию финальных файлов библиотеки.
Типичные компоненты:
В результате сборки формируются файлы:
Финальная структура дистрибуции организована вокруг единой глобальной точки входа и модульных экспортов.
Основные принципы:
Экспортируемая часть минимизирует поверхность API, скрывая внутренние детали реализации.
В репозитории присутствует каталог тестов, в котором проверяется:
Тесты разделены на модульные и интеграционные. Первые проверяют отдельные функции, вторые — взаимодействие компонентов в составе карты.
Отдельный каталог содержит примеры использования библиотеки. Он включает:
Примеры синхронизированы с исходным кодом, что позволяет отслеживать актуальность API.
Структура файлов построена вокруг нескольких базовых принципов:
Каждый файл выполняет строго определённую роль, а группировка по директориям отражает логическое деление системы на подсистемы карты, геометрии, слоёв и интерфейса.