События клавиатуры

Базовая модель обработки клавиатурного ввода

В браузерной версии картографического SDK HERE Technologies взаимодействие с клавиатурой строится на двух уровнях:

  • DOM-события клавиатуры (keydown, keyup, keypress)
  • Интерактивные события поведения карты через модуль H.mapevents.Behavior

Первый уровень работает на уровне HTML-страницы и контейнера карты, второй — интегрирован в систему управления картой и отвечает за перемещение, масштабирование и навигацию.

Ключевая особенность архитектуры заключается в том, что карта сама по себе не «слушает клавиатуру» — это делает либо DOM-узел, либо слой поведения (Behavior), который интерпретирует ввод как команды навигации.

Подключение обработки клавиатуры к контейнеру карты

Контейнер карты — это обычный HTML-элемент, например:

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

Чтобы он начал получать события клавиатуры, необходимо обеспечить фокусировку:

const mapContainer = document.getElementById('map');

mapContainer.tabIndex = 0;
mapContainer.focus();

Без установки tabIndex элемент не может получить фокус, а значит — не будет получать keydown события.

Прямое использование DOM-событий клавиатуры

DOM-уровень применяется, когда требуется:

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

Пример базовой обработки:

mapContainer.addEventListener('keydown', (event) => {
    switch (event.key) {
        case 'ArrowUp':
            console.log('Движение вверх');
            break;
        case 'ArrowDown':
            console.log('Движение вниз');
            break;
        case '+':
            console.log('Увеличение масштаба');
            break;
        case '-':
            console.log('Уменьшение масштаба');
            break;
    }
});

При этом важно учитывать, что браузер может перехватывать некоторые клавиши (например, стрелки или пробел), вызывая прокрутку страницы.

Для предотвращения этого используется:

event.preventDefault();

Поведение карты и клавиатурная навигация

Основной механизм управления картой в HERE Maps реализован через модуль:

H.mapevents.Behavior

Он позволяет интерпретировать ввод пользователя (мышь, сенсор, клавиатура) как действия над картой: панорамирование, зум, вращение.

Инициализация выглядит следующим образом:

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

const defaultLayers = platform.createDefaultLayers();

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

const beh * avior = new H.mapevents.Behavior(new H.mapevents.MapEvents(map));

После этого карта получает стандартную поддержку:

  • стрелки — перемещение карты
  • + / - — масштабирование
  • иногда Shift + колесо мыши синхронизируется с клавиатурными сценариями
  • PageUp / PageDown могут использоваться в кастомных конфигурациях

Конфигурация включения и отключения клавиатурного управления

Хотя Behavior активирует множество взаимодействий, управление клавиатурой можно ограничивать или полностью отключать.

Отключение поведения:

behavior.disable(H.mapevents.Behavior.Feature.KEYBOARD);

Включение обратно:

behavior.enable(H.mapevents.Behavior.Feature.KEYBOARD);

Если требуется полностью убрать интерактивность:

behavior.disable(H.mapevents.Behavior.Feature.ALL);

Такой подход применяется в сценариях:

  • статических карт
  • режимов предпросмотра
  • кастомных интерфейсов навигации

Перехват клавиш до обработки картой

Иногда необходимо изменить стандартное поведение до того, как карта его обработает.

Реализуется через capture-фазу:

mapContainer.addEventListener(
    'keydown',
    (event) => {
        if (event.key === 'ArrowLeft') {
            event.preventDefault();
            map.setCenter({
                lat: map.getCenter().lat,
                lng: map.getCenter().lng - 0.1
            });
        }
    },
    true
);

Параметр true включает фазу захвата, позволяя перехватывать события раньше системы карты.

Связь клавиатуры и состояния карты

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

  • изменение масштаба
  • перемещение центра
  • переключение слоёв
  • управление маркерами

Пример масштабирования:

mapContainer.addEventListener('keydown', (event) => {
    const zoom = map.getZoom();

    if (event.key === '+') {
        map.setZoom(zoom + 1, true);
    }

    if (event.key === '-') {
        map.setZoom(zoom - 1, true);
    }
});

Флаг true включает анимацию перехода.

Комбинации клавиш и кастомные сценарии

Сложные интерфейсы часто требуют обработки комбинаций:

mapContainer.addEventListener('keydown', (event) => {
    if (event.ctrlKey && event.key === 'ArrowUp') {
        map.setZoom(map.getZoom() + 2);
    }

    if (event.shiftKey && event.key === 'ArrowDown') {
        map.setZoom(map.getZoom() - 2);
    }
});

При проектировании таких схем важно учитывать:

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

Доступность и клавиатурная навигация

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

В контексте HERE Maps это выражается в:

  • поддержке навигации без мыши
  • возможности перемещения фокуса
  • управлении картой через стандартные клавиши

Рекомендуемая практика — всегда обеспечивать:

mapContainer.setAttribute('role', 'application');
mapContainer.setAttribute('aria-label', 'Map');
mapContainer.tabIndex = 0;

Это позволяет вспомогательным технологиям корректно интерпретировать элемент карты.

Конфликты клавиатурных событий с браузером

Некоторые клавиши по умолчанию имеют системное поведение:

  • стрелки — прокрутка страницы
  • пробел — скролл вниз
  • PageUp/PageDown — навигация по документу

Чтобы карта не конфликтовала с этим поведением, используется:

event.preventDefault();
event.stopPropagation();

Но применение должно быть избирательным, чтобы не блокировать общий UX страницы.

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

Внутренний механизм H.mapevents.Behavior объединяет разные источники ввода в единый поток:

  • клавиатура
  • мышь
  • тач-интерфейс

Это означает, что:

  • изменение зума с клавиатуры синхронизируется с колесом мыши
  • панорамирование стрелками влияет на тот же state, что и drag
  • все изменения проходят через единый слой трансформации карты

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

Хотя keydown не является тяжёлым событием, в контексте карты важно:

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

Пример оптимизации:

let timeout;

mapContainer.addEventListener('keydown', (event) => {
    clearTimeout(timeout);

    timeout = setTimeout(() => {
        if (event.key === 'ArrowRight') {
            map.setCenter({
                lat: map.getCenter().lat,
                lng: map.getCenter().lng + 0.05
            });
        }
    }, 10);
});

Итоговая модель взаимодействия клавиатуры с картой

Клавиатурные события в HERE Maps JavaScript API формируют многоуровневую систему:

  • DOM-слой отвечает за захват и обработку клавиш
  • H.mapevents.MapEvents преобразует ввод в события карты
  • H.mapevents.Behavior интерпретирует события как навигационные действия
  • API карты применяет изменения к состоянию отображения

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

Оглавление