Стандартные контролы HERE

Архитектура пользовательского интерфейса в HERE Maps API JavaScript построена вокруг модуля H.ui, который предоставляет набор готовых контролов для взаимодействия с картой. Эти элементы интегрируются в контейнер карты и управляются через экземпляр H.ui.UI, связанный с объектом H.Map.

Контролы в системе делятся на стандартные (встроенные), расширяемые и кастомные. Стандартные обеспечивают базовую навигацию, управление отображением слоёв и вспомогательные функции интерфейса.

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

Перед использованием любых контролов необходимо создать экземпляр UI:

const platform = new H.service.Platform({
  apikey: 'YOUR_API_KEY'
});

const defaultLayers = platform.createDefaultLayers();

const map = new H.Map(
  document.getElementById('mapContainer'),
  defaultLayers.vector.normal.map,
  {
    zoom: 10,
    center: { lat: 52.5, lng: 13.4 }
  }
);

const ui = H.ui.UI.createDefault(map, defaultLayers);

Метод H.ui.UI.createDefault автоматически добавляет набор стандартных контролов, включая масштабирование, настройки отображения и элементы навигации.

Zoom Control (контрол масштаба)

Zoom Control отвечает за изменение уровня масштабирования карты. Он обычно представлен кнопками «+» и «−».

Основные характеристики:

  • Интегрирован в H.ui.ZoomControl
  • Управляет map.getZoom() и map.setZoom()
  • Поддерживает ограничение диапазона масштабов

Пример использования:

const zoomControl = new H.ui.ZoomControl();
ui.addControl('zoomControl', zoomControl);

Поведение:

  • Клик по «+» увеличивает zoom
  • Клик по «−» уменьшает zoom
  • Поддерживает удержание кнопки для непрерывного масштабирования

MapSettings Control (настройки карты)

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

Возможности:

  • Переключение между типами карты (vector, satellite и др.)
  • Управление стилями отображения
  • Включение/выключение тематических слоёв

Пример добавления:

const mapSettingsControl = new H.ui.MapSettingsControl({
  baseLayers: ui.getBaseLayerEntries(),
  layers: ui.getLayerEntries()
});

ui.addControl('mapsettings', mapSettingsControl);

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

  • Интегрируется с системой слоёв платформы
  • Автоматически синхронизируется с текущим состоянием карты

Scalebar (масштабная линейка)

Scalebar отображает реальное расстояние на карте в зависимости от текущего масштаба.

Назначение:

  • Визуализация расстояний
  • Поддержка метрической и имперской систем

Пример:

const scalebar = new H.ui.ScaleBar();
ui.addControl('scalebar', scalebar);

Поведение:

  • Автоматически обновляется при изменении zoom
  • Пересчитывает расстояния на основе проекции карты

Overview Map (обзорная карта)

Overview Map представляет собой миниатюрную карту, показывающую текущее положение основного viewport.

Функции:

  • Отображение текущей области просмотра
  • Быстрая навигация по глобальной карте
  • Индикация масштаба основного окна

Пример подключения:

const overview = new H.ui.OverviewMap({
  position: H.ui.LayoutAlignment.BOTTOM_RIGHT,
  size: { w: 150, h: 150 }
});

ui.addControl('overview', overview);

Поведение:

  • Синхронизируется с основным H.Map
  • Позволяет перетаскивать область просмотра

Fullscreen Control (полноэкранный режим)

Контрол полноэкранного режима управляет переходом карты в fullscreen.

Возможности:

  • Разворачивание карты на весь экран
  • Возврат в оконный режим
  • Обработка событий браузера Fullscreen API

Пример:

const fullscreenControl = new H.ui.FullscreenControl();
ui.addControl('fullscreen', fullscreenControl);

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

  • Использует нативный Fullscreen API браузера
  • Может требовать пользовательского взаимодействия (ограничение безопасности браузеров)

Attribution Control (атрибуция)

Контрол атрибуции отображает обязательные юридические данные и источники картографических данных.

Функции:

  • Отображение копирайтов
  • Управление ссылками на поставщиков данных
  • Автоматическое обновление при смене слоя

Пример:

const attributionControl = new H.ui.AttributionControl({
  branding: true
});

ui.addControl('attribution', attributionControl);

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

Все контролы управляются через объект H.ui.UI, который предоставляет методы добавления и удаления:

Добавление:

ui.addControl('zoomControl', zoomControl);

Удаление:

ui.removeControl('zoomControl');

Перемещение контролов:

Контролы могут быть позиционированы через H.ui.LayoutAlignment:

ui.addControl('zoomControl', zoomControl, H.ui.LayoutAlignment.RIGHT_TOP);

Позиционирование и компоновка

Контролы размещаются в фиксированных зонах интерфейса:

  • LEFT_TOP
  • RIGHT_TOP
  • LEFT_BOTTOM
  • RIGHT_BOTTOM

Пример:

ui.addControl(
  'scalebar',
  scalebar,
  H.ui.LayoutAlignment.LEFT_BOTTOM
);

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

Событийная модель контролов

Контролы взаимодействуют с картой через события:

Основные события:

  • statechange — изменение состояния UI
  • zoomchange — изменение масштаба
  • baselayerchange — смена базового слоя

Пример подписки:

map.addEventListener('zoomchange', function (evt) {
  console.log('Zoom:', evt.newValue);
});

Кастомизация стандартных контролов

Хотя стандартные контролы предоставляют готовый функционал, их внешний вид и поведение можно модифицировать.

Изменение стилей:

.hui-zoomcontrol {
  background-color: rgba(0,0,0,0.5);
}

Расширение логики:

Можно наследоваться от базовых классов UI:

class CustomZoomControl extends H.ui.ZoomControl {
  constructor() {
    super();
  }

  // переопределение поведения возможно через события DOM
}

Отключение стандартных контролов

При создании UI можно отключить автоматическое добавление контролов:

const ui = H.ui.UI.createDefault(map, defaultLayers, {
  zoomControl: false,
  scalebar: false
});

Это позволяет собрать полностью кастомный интерфейс.

Поведение на мобильных устройствах

Стандартные контролы адаптируются под touch-интерфейсы:

  • увеличенные зоны нажатия
  • упрощённая компоновка
  • автоматическое скрытие второстепенных элементов

Zoom Control поддерживает жесты pinch-to-zoom, даже если кнопки скрыты.

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

Контролы напрямую взаимодействуют с объектом H.Map:

  • Zoom Control вызывает map.setZoom()
  • MapSettings изменяет слои через map.setBaseLayer()
  • Overview Map синхронизирует viewport через map.getViewModel()

Связь реализована через внутреннюю модель состояния ViewModel, обеспечивающую согласованность всех компонентов интерфейса.

Оглавление