MousePosition

Контрол MousePosition относится к группе UI-компонентов библиотеки и предназначен для отображения текущих координат курсора мыши над картой. Он интегрируется как стандартный control и работает поверх объекта ol.Map, реагируя на события pointermove и преобразуя координаты в заданную систему отображения.

Основная задача MousePosition — обеспечить непрерывную визуализацию координат точки, над которой находится курсор, с возможностью кастомизации формата, системы координат и способа вывода.

Архитектура и место в системе controls

MousePosition реализован как класс ol.control.MousePosition, входящий в модуль управления интерфейсом карты.

Он взаимодействует с:

  • объектом карты Map
  • системой координат View
  • трансформацией координат ol/proj
  • DOM-элементом контейнера отображения

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

Инициализация и базовое подключение

MousePosition подключается как обычный control:

import Map from 'ol/Map.js';
import View from 'ol/View.js';
import MousePosition from 'ol/control/MousePosition.js';

const mousePositionControl = new MousePosition();

const map = new Map({
  target: 'map',
  controls: [
    mousePositionControl
  ],
  view: new View({
    center: [0, 0],
    zoom: 2
  })
});

По умолчанию координаты выводятся в проекции карты (обычно EPSG:3857), без форматирования и без явного контейнера стилизации.

Параметры конфигурации

MousePosition поддерживает набор опций, определяющих поведение и формат отображения.

projection

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

projection: 'EPSG:4326'

Наиболее часто используется:

  • EPSG:4326 — широта/долгота
  • EPSG:3857 — Web Mercator (по умолчанию)

coordinateFormat

Функция форматирования координат. Принимает массив координат и возвращает строку.

import {createStringXY} from 'ol/coordinate.js';

coordinateFormat: createStringXY(4)

Где число задаёт количество знаков после запятой.

Пример пользовательской функции:

coordinateFormat: function(coord) {
  return `X: ${coord[0].toFixed(2)} | Y: ${coord[1].toFixed(2)}`;
}

className

CSS-класс контейнера отображения координат.

className: 'mouse-position'

Позволяет интегрировать контрол в сложные интерфейсные системы и применять кастомные стили.

target

DOM-элемент, в который будет рендериться вывод координат.

target: document.getElementById('coords')

При отсутствии параметра координаты отображаются в стандартной панели управления картой.

undefinedHTML

Строка, отображаемая при отсутствии координат (например, при выходе курсора за пределы карты).

undefinedHTML: 'координаты недоступны'

Полная конфигурация контроллера

import MousePosition from 'ol/control/MousePosition.js';
import {createStringXY} from 'ol/coordinate.js';

const mousePosition = new MousePosition({
  coordinateFormat: createStringXY(6),
  projection: 'EPSG:4326',
  className: 'custom-mouse-position',
  undefinedHTML: ' ',
  target: document.getElementById('mouse-position')
});

Работа с проекциями координат

MousePosition не ограничивается текущей проекцией карты. Перед выводом координаты могут быть преобразованы через ol/proj.transform.

Внутренний механизм использует следующую логику:

  1. Получение координат из события pointermove
  2. Определение текущей проекции карты
  3. Трансформация координат в целевую систему
  4. Форматирование результата
  5. Обновление DOM

Пример смены системы координат:

projection: 'EPSG:4326'

При этом Web Mercator координаты автоматически преобразуются в географические значения.

Форматирование координат

Форматирование — ключевой элемент контроля MousePosition.

Базовое форматирование XY

createStringXY(2)

Результат:

12.34, 56.78

Пользовательский формат

coordinateFormat: function(coord) {
  const lon = coord[0];
  const lat = coord[1];

  return `${lat}° N, ${lon}° E`;
}

Условное форматирование

coordinateFormat: function(coord) {
  if (!coord) return '';

  return coord.map(c => c.toFixed(3)).join(' | ');
}

Поведение при отсутствии координат

Состояние undefined возникает:

  • при выходе курсора за пределы карты
  • при неинициализированном view
  • при отключённом взаимодействии pointer events

В таких случаях используется undefinedHTML.

undefinedHTML: '---'

Стилизация вывода

MousePosition не ограничивает внешний вид. Контейнер можно стилизовать через CSS:

.custom-mouse-position {
  position: absolute;
  bottom: 10px;
  right: 10px;
  background: rgba(0,0,0,0.6);
  color: #fff;
  padding: 6px 10px;
  font-family: monospace;
  border-radius: 4px;
}

Класс применяется к внутреннему элементу, создаваемому контролом.

Интеграция с пользовательскими интерфейсами

MousePosition часто размещается в отдельных UI-блоках вне карты.

<div id="coords"></div>
<div id="map"></div>
new MousePosition({
  target: document.getElementById('coords')
});

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

Обновление и жизненный цикл

MousePosition автоматически синхронизируется с картой:

  • при добавлении в map.controls
  • при изменении view
  • при движении pointer

При удалении контрол отключает подписки на события, освобождая ресурсы.

map.removeControl(mousePosition);

Производительность и особенности работы

Контрол оптимизирован для частых обновлений событий мыши. Основные особенности:

  • обновление происходит на каждом pointermove
  • минимальная нагрузка на GC при стандартном форматировании
  • возможна деградация при тяжёлых пользовательских format-функциях

При использовании сложных вычислений внутри coordinateFormat увеличивается задержка отображения координат.

Типовые сценарии использования

Отображение широты и долготы

projection: 'EPSG:4326'

Отображение координат в метрах (Web Mercator)

projection: 'EPSG:3857'

Вывод координат в отдельный HUD-блок

target: document.getElementById('hud')

Кастомный формат с подписями

coordinateFormat: function(c) {
  return `Easting: ${c[0]} | Northing: ${c[1]}`;
}

Взаимодействие с View и Projection

MousePosition тесно связан с объектом View. Изменение центра, зума или проекции автоматически влияет на отображаемые координаты.

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

Оглавление