Directions Renderer

DirectionsRenderer представляет собой компонент визуализации маршрутов, полученных через DirectionsService. Его основная задача — отрисовка результата маршрутизации на карте, включая полилинии маршрута, маркеры начала и конца пути, а также текстовые инструкции (при необходимости — в отдельной панели).

В архитектуре Google Maps JavaScript API этот компонент выступает связующим звеном между вычисленным маршрутом и его визуальным представлением.

Основная роль DirectionsRenderer

DirectionsRenderer не выполняет расчёт маршрута. Он:

  • получает объект результата маршрутизации (DirectionsResult);
  • отображает маршрут на карте;
  • управляет маркерами;
  • может выводить пошаговые инструкции;
  • позволяет кастомизировать визуализацию.

Получение маршрута происходит через DirectionsService.route(), после чего результат передаётся в DirectionsRenderer.

Базовая инициализация

const directionsRenderer = new google.maps.DirectionsRenderer();
const directionsService = new google.maps.DirectionsService();

const map = new google.maps.Map(document.getElementById("map"), {
  center: { lat: 40.7128, lng: -74.0060 },
  zoom: 7,
});

directionsRenderer.setMap(map);

Ключевой момент — привязка рендера к карте через setMap().

Запрос маршрута и отображение

const request = {
  origin: "New York, NY",
  destination: "Boston, MA",
  travelMode: google.maps.TravelMode.DRIVING,
};

directionsService.route(request, (result, status) => {
  if (status === "OK") {
    directionsRenderer.setDirections(result);
  }
});

Метод setDirections() принимает объект результата и инициирует отрисовку.

Структура DirectionsResult

Объект результата содержит:

  • routes — массив маршрутов;
  • legs — сегменты пути;
  • steps — отдельные инструкции;
  • overview_polyline — упрощённая геометрия маршрута.

DirectionsRenderer использует именно эти данные для построения визуального слоя.

Основные опции DirectionsRenderer

При создании объекта можно передать конфигурацию:

const directionsRenderer = new google.maps.DirectionsRenderer({
  map: map,
  suppressMarkers: false,
  preserveViewport: true,
  draggable: false,
});

suppressMarkers

Управляет отображением стандартных маркеров:

  • false — маркеры начала и конца отображаются;
  • true — маркеры скрываются.

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

preserveViewport

Определяет поведение карты при установке маршрута:

  • false — карта автоматически подстраивается под маршрут;
  • true — текущий viewport сохраняется.

draggable

Позволяет изменять маршрут мышью:

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

Отрисовка текстовых инструкций

DirectionsRenderer может привязывать текстовые инструкции к DOM-элементу:

const panel = document.getElementById("directionsPanel");

const directionsRenderer = new google.maps.DirectionsRenderer({
  map: map,
  panel: panel,
});

В этом режиме API автоматически формирует HTML-структуру с шагами маршрута.

Работа с маршрутами (routes)

Если в ответе несколько маршрутов, DirectionsRenderer отображает первый по умолчанию.

Выбор маршрута:

directionsRenderer.setRouteIndex(1);

Это позволяет переключаться между альтернативными вариантами пути.

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

Повторная отрисовка выполняется через повторный вызов:

directionsRenderer.setDirections(newResult);

Старый маршрут полностью заменяется новым.

Очистка маршрута:

directionsRenderer.setDirections({ routes: [] });

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

directionsRenderer.setMap(null);

Кастомизация линии маршрута

Настройка внешнего вида полилинии осуществляется через polylineOptions:

const directionsRenderer = new google.maps.DirectionsRenderer({
  map: map,
  polylineOptions: {
    strokeColor: "#1a73e8",
    strokeOpacity: 0.9,
    strokeWeight: 5,
  },
});

Используется для визуального соответствия интерфейсу приложения.

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

При suppressMarkers: true маркеры полностью отключаются, после чего их можно создать вручную:

new google.maps.Marker({
  position: { lat: 40.7128, lng: -74.0060 },
  map: map,
  label: "A",
});

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

Интерактивные изменения маршрута

При включённом draggable: true маршрут становится редактируемым.

Изменения можно отслеживать:

directionsRenderer.addListener("directions_changed", () => {
  const updated = directionsRenderer.getDirections();
});

Это позволяет реагировать на перестроение маршрута в реальном времени.

Сохранение состояния маршрута

При работе с динамическими интерфейсами часто требуется сохранить текущий маршрут:

const currentRoute = directionsRenderer.getDirections();

Полученный объект можно сериализовать и восстановить позже через setDirections().

Использование нескольких DirectionsRenderer

В одном приложении допускается несколько рендереров:

const renderer1 = new google.maps.DirectionsRenderer({
  map: map1,
});

const renderer2 = new google.maps.DirectionsRenderer({
  map: map2,
});

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

Поведение при ошибках маршрутизации

DirectionsRenderer не обрабатывает ошибки напрямую, но зависит от результата DirectionsService:

  • NOT_FOUND — один из адресов не распознан;
  • ZERO_RESULTS — маршрут невозможен;
  • OVER_QUERY_LIMIT — превышение лимита запросов.

В случае ошибки setDirections() не вызывается.

Взаимодействие с viewport карты

При стандартной работе компонент автоматически изменяет область отображения карты, чтобы маршрут полностью помещался в экран. Это поведение контролируется preserveViewport.

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

Внутренние слои отображения

При рендеринге создаются следующие визуальные элементы:

  • Polyline (основной маршрут);
  • Markers (start/end);
  • InfoWindows (инструкции при кастомной реализации);
  • Overlay layers для интерактивных сегментов.

Практика комбинирования с DirectionsService

Типовой цикл работы:

  1. Создание DirectionsService;
  2. Формирование запроса;
  3. Получение DirectionsResult;
  4. Передача в DirectionsRenderer;
  5. Отображение маршрута на карте.

Этот цикл является основой навигационных приложений на JavaScript.

Поведение при изменении карты

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

Ограничения компонента

  • невозможность прямого редактирования геометрии маршрута без draggable;
  • зависимость от DirectionsService;
  • ограничение на количество альтернативных маршрутов;
  • отсутствие встроенной бизнес-логики маршрутизации.

Кастомные сценарии отображения

В сложных приложениях DirectionsRenderer часто используется только как визуальный слой, а логика маршрутов выносится отдельно:

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

В таких случаях компонент выполняет роль «отрисовщика», а не навигационного ядра.

Оглавление