Вспомогательные функции

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

L.Util: базовые утилиты

Модуль L.Util содержит набор универсальных функций, используемых внутри всей библиотеки.

Наследование и расширение объектов

Одной из ключевых функций является L.Util.extend, обеспечивающая поверхностное копирование свойств:

L.Util.extend(target, source1, source2);

Функция последовательно копирует свойства из источников в целевой объект. Используется для объединения опций и конфигураций слоёв.

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

L.Util.bind фиксирует контекст выполнения функции:

var bound = L.Util.bind(fn, context);

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

Уникальные идентификаторы

Каждому объекту Leaflet может быть присвоен уникальный идентификатор через L.Util.stamp:

var id = L.Util.stamp(object);

Идентификатор сохраняется внутри объекта и используется для быстрого доступа в коллекциях и индексах.

Работа с настройками

Функция L.Util.setOptions стандартизирует применение параметров:

L.Util.setOptions(instance, options);

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

Ограничение значений и цикличность

Для работы с географическими координатами часто применяется wrapNum:

L.Util.wrapNum(value, range, includeMax);

Функция приводит число к заданному диапазону, например, долготу к интервалу [-180, 180].

Форматирование чисел

L.Util.formatNum ограничивает точность чисел:

L.Util.formatNum(num, precision);

Используется для уменьшения погрешностей при вычислениях координат.

Функции-заглушки

L.Util.falseFn возвращает функцию, всегда возвращающую false. Применяется как безопасный обработчик по умолчанию.

Анимационный цикл

L.Util.requestAnimFrame обеспечивает кроссбраузерный доступ к requestAnimationFrame:

L.Util.requestAnimFrame(callback, context, immediate);

Используется для плавных анимаций перемещения карты и слоёв.

L.DomUtil: работа с DOM

Модуль L.DomUtil инкапсулирует операции над DOM-элементами, минимизируя прямое использование нативного API.

Создание и получение элементов

var el = L.DomUtil.get(id);
var div = L.DomUtil.create(tagName, className, container);

create позволяет сразу задавать класс и родительский элемент, упрощая построение слоёв интерфейса.

Управление классами

L.DomUtil.addClass(el, 'active');
L.DomUtil.removeClass(el, 'active');
L.DomUtil.hasClass(el, 'active');

Операции работают с кроссбраузерной нормализацией классов.

Позиционирование элементов

Leaflet использует абсолютное позиционирование для слоёв:

L.DomUtil.setPosition(el, point);
var pos = L.DomUtil.getPosition(el);

Координаты задаются в пикселях относительно контейнера карты.

Перемещение по слоям

L.DomUtil.toFront(el);
L.DomUtil.toBack(el);

Функции изменяют z-index DOM-элементов, влияя на порядок отображения слоёв.

Отключение взаимодействия

Для предотвращения обработки событий используются:

L.DomUtil.disableClickPropagation(el);
L.DomUtil.disableScrollPropagation(el);

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

L.DomEvent: система событий

Модуль L.DomEvent стандартизирует работу с браузерными событиями.

Подписка и отписка

L.DomEvent.on(el, 'click', handler);
L.DomEvent.off(el, 'click', handler);

Поддерживается регистрация нескольких обработчиков и контекстов выполнения.

Унификация событий

Leaflet нормализует поведение событий мыши и касаний, объединяя их в единый интерфейс.

Остановка распространения

L.DomEvent.stopPropagation(e);
L.DomEvent.preventDefault(e);
L.DomEvent.stop(e);

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

Управление взаимодействием карты

L.DomEvent.disableClickPropagation(el);
L.DomEvent.disableScrollPropagation(el);

Используются для UI-элементов поверх карты (панели, контролы), чтобы они не перехватывали события карты.

L.Browser: определение возможностей окружения

Модуль L.Browser содержит флаги, определяющие поддержку функций браузера.

Типичные свойства:

  • L.Browser.ie
  • L.Browser.mobile
  • L.Browser.touch
  • L.Browser.gecko
  • L.Browser.webkit
  • L.Browser.android
  • L.Browser.retina

Эти флаги используются для адаптации поведения интерфейса и оптимизации отрисовки.

Геометрические вспомогательные структуры

L.Point

Представляет координаты в пикселях:

var p = L.point(10, 20);

Методы:

  • add, subtract
  • multiplyBy
  • divideBy
  • distanceTo
  • round

Используется для позиционирования элементов на экране.

L.LatLng

Географическая точка:

var latlng = L.latLng(55.75, 37.61);

Методы:

  • distanceTo(latlng)
  • equals(latlng)
  • toString()

L.LatLngBounds

Ограничивающий прямоугольник:

var bounds = L.latLngBounds([sw, ne]);

Основные операции:

  • extend(latlng)
  • getCenter()
  • contains(latlng)
  • intersects(bounds)

Используется для определения видимой области карты.

L.Bounds: пиксельные границы

L.Bounds работает аналогично LatLngBounds, но в пиксельной системе координат.

var b = new L.Bounds(point1, point2);

Методы:

  • extend(point)
  • getSize()
  • getBottomLeft()
  • getTopRight()

L.Transformation: преобразование координат

Класс L.Transformation отвечает за перевод географических координат в пиксельные и обратно.

var tr = new L.Transformation(a, b, c, d);

Формулы преобразования:

  • x = ax + b
  • y = cy + d

Используется в проекциях карты для масштабирования и сдвига координат.

L.LineUtil: работа с линиями

Модуль оптимизирует операции над полилиниями.

Основные функции:

  • simplify(points, tolerance)
  • pointToSegmentDistance(p, p1, p2)
  • clipSegment(a, b, bounds)

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

L.PolyUtil: полигональные операции

Работает с замкнутыми фигурами.

Основные операции:

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

Внутренние преобразования координат

Leaflet использует цепочку преобразований:

  1. LatLng — географические координаты
  2. Projection — проекция на плоскость
  3. Transformation — масштабирование
  4. Point — экранные координаты

Эта цепочка обеспечивает независимость от конкретной карты и позволяет легко менять системы координат.

Механизмы оптимизации

Вспомогательные функции активно применяются для оптимизации:

  • кеширование идентификаторов через stamp
  • уменьшение количества DOM-операций через DomUtil
  • ограничение точности координат
  • упрощение геометрии линий
  • использование флагов Browser для отключения тяжёлых эффектов

Эти механизмы позволяют Leaflet оставаться лёгкой библиотекой при работе с большими наборами геоданных.

Оглавление