Панель маршрутизации

Общие сведения

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

Начальную и конечную точки можно двигать — маршрут будет перестраиваться автоматически.

Для заданных точек строится несколько оптимальных маршрутов. Самый быстрый маршрут будет выбран в качестве активного — он отображается на карте фиолетовым цветом. Альтернативные маршруты отображаются серым цветом. Все маршруты строятся с учетом пробок.

Панель маршрутизации не поддерживает промежуточные точки — маршруты можно строить только по двум точкам. Если нужно построить маршрут по трем точкам и более, используйте класс multiRouter.MultiRoute.
Внимание. Запросы к маршрутизации тарифицируются.

Добавление панели на карту

Панель маршрутизации реализуется классом control.RoutePanel и доступна по ключу 'routePanelControl'. Добавить панель на карту можно через поле controls, при создании карты:

var myMap = new ymaps.Map('map', {
    center: [55.75, 37.57],
    zoom: 9,
    controls: ['routePanelControl']
});
  
/*
// Второй способ добавить панель на карту.
// Примечание: не забудьте удалить 'routePanelControl'
// из опции controls карты.
var routePanelControl = new ymaps.control.RoutePanel();
myMap.controls.add(routePanelControl); 
*/
Посмотреть полный код примера
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
ymaps.ready(function () {
    var myMap = new ymaps.Map('map', {
        center: [55.75, 37.57],
        zoom: 9,
        controls: ['routePanelControl']
    });
  
    /*
    // Второй способ добавить панель на карту.
    // Примечание: не забудьте удалить 'routePanelControl'
    // из опции controls карты.
    var routePanelControl = new ymaps.control.RoutePanel();
    myMap.controls.add(routePanelControl); 
    */  
});
</script>  

API предоставляет возможность сворачивать панель на карте. Это можно сделать с помощью элемента управления control.RouteButton — он доступен по ключу 'routeButtonControl':

var myMap = new ymaps.Map('map', {
    center: [55.75, 37.57],
    zoom: 9,
    controls: ['routeButtonControl']
});
  
/*
// Второй способ добавить кнопку маршрутизации на карту.
// Примечание: не забудьте удалить 'routeButtonControl'
// из опции карты controls.
var routeButtonControl = new ymaps.control.RouteButton();
myMap.controls.add(routeButtonControl); 
*/
Посмотреть полный код примера
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
ymaps.ready(function () {
   var myMap = new ymaps.Map('map', {
       center: [55.75, 37.57],
       zoom: 9,
       controls: ['routeButtonControl']
   });
  
    /*
    // Второй способ добавить кнопку маршрутизации на карту.
    // Примечание: не забудьте удалить 'routeButtonControl'
    // из опции карты controls.
    var routeButtonControl = new ymaps.control.RouteButton();
    myMap.controls.add(routeButtonControl); 
    */
});
</script>  

Настройки панели маршрутизации

Для панели маршрутизации можно задавать различные настройки. Например, можно задать точки маршрута, выбрать тип маршрутизации или выставить размеры панели на карте. Ниже на конкретных примерах показано, как задавать настройки для панели:

В разделе Решение типовых задач можно посмотреть решение других распространенных задач.

Задание точек маршрута

Задать точки маршрута можно через поля fromи to:

var myMap = new ymaps.Map('map', {
    center: [55.753994, 37.622093],
    zoom: 9,
    controls: ['routePanelControl']
});

// Получение ссылки на панель маршрутизации.
var control = myMap.controls.get('routePanelControl');

// Задание состояния для панели маршрутизации.
control.routePanel.state.set({
    // Адрес начальной точки.
    from: 'Москва, Льва Толстого, 16',
    // Адрес конечной точки.
    to: 'Москва, метро Черемушки'
});
Посмотреть полный код примера
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
ymaps.ready(function () {
    var myMap = new ymaps.Map('map', {
        center: [55.753994, 37.622093],
        zoom: 9,
        controls: ['routePanelControl']
    });

    // Получение ссылки на панель маршрутизации.
    var control = myMap.controls.get('routePanelControl');

    // Задание состояния для панели маршрутизации.
    control.routePanel.state.set({
        // Адрес начальной точки.
        from: 'Москва, Льва Толстого 16',
        // Адрес конечной точки.
        to: 'метро Черемушки'
    });
});
</script>
Внимание. Для точек, которые задаются в виде строки, будут отправляться запросы в Геокодер. При этом каждая точка — это отдельный запрос. Кроме того, включение опции reverseGeocoding также приведет к дополнительным запросам в Геокодер. Следует иметь в виду, что запросы на геокодирование тарифицируются.

Открыть интерактивный пример в песочнице — Маршрут от точки на карте.

Выбор типа маршрутизации

Тип маршрутизации задается через поле type:

// Получение ссылки на панель.
var control = myMap.controls.get('routePanelControl');
    
control.routePanel.state.set({
    // Список всех настроек см. в справочнике.
    // Тип маршрутизации, который будет использоваться по умолчанию.
    type: "pedestrian", // пешком
});

control.routePanel.options.set({
    // Типы маршрутизации, которые будут доступны
    // для выбора пользователям.
    // В примере можно построить
    // автомобильный маршрут с вызовом такси и пешеходный маршрут.
    // При использовании CSP, убедитесь что у вас подключена последняя версия правил.
    // В противном случае, маршрутизация с типом "taxi" не будет работать.
    types: {
        "pedestrian": true,
        "taxi": true
    }
}); 
Посмотреть полный код примера
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
ymaps.ready(function () {
    var myMap = new ymaps.Map('map', {
        center: [55.753994, 37.622093],
        zoom: 9,
        controls: ['routePanelControl']
    });

    // Получение ссылки на панель.
    var control = myMap.controls.get('routePanelControl');
    
    // В поле 'state' задаются данные для маршрутизации.
    control.routePanel.state.set({
        // Список всех настроек см. в справочнике.
        // Тип маршрутизации, который будет использоваться по умолчанию.
        type: "pedestrian",
    });
    
    control.routePanel.options.set({
        // Типы маршрутизации, которые будут доступны
        // для выбора пользователям.
        // В примере пользователи смогут построить
        // только маршрут на такси и пешеходный маршрут.
        types: {
            "pedestrian": true,
            "taxi": true
        }
    });
});
</script>

Построение маршрута с возможностью вызвать такси

Панель маршрутизации позволяет строить маршруты с возможностью вызова такси. На карте показывается схема проезда, а также информация о поездке по данным «Яндекс.Такси» (продолжительность, примерная стоимость). При нажатии на кнопку Заказать такси откроется страница Яндекс.Такси с заданным маршрутом.

Внимание. На сайтах, использующих политику защиты контента, нужно подключить последнюю версию CSP правил.

Чтобы построить маршрут с возможностью вызова такси, в типе маршрутизации нужно указать «taxi»:

// Получение ссылки на панель.
var control = myMap.controls.get('routePanelControl');

control.routePanel.options.set({
    // Типы маршрутизации, которые будут отображаться на панели.
    // Пользователи смогут переключаться между этими типами.
    types: {
       auto: true,
       pedestrian: true,
       // Добавление на панель
       // значка «такси».
       taxi: true
    }
});

control.routePanel.state.set({
    // Пусть по умолчанию используется маршрут
    // с возможностью вызова такси.
    type: "taxi",
    from: 'Москва, Льва Толстого 16',
    to: 'метро Черемушки'
});
Посмотреть полный код примера
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
ymaps.ready(function () {
    var myMap = new ymaps.Map('map', {
        center: [55.75, 37.57],
        zoom: 9,
        controls: ['routePanelControl']
    });

    // Получение ссылки на панель.
    var control = myMap.controls.get('routePanelControl');

    control.routePanel.options.set({
        // Типы маршрутизации, которые будут отображаться на панели.
        // Пользователи смогут переключаться между этими типами.
        types: {
            auto: true,
            pedestrian: true,
            // Добавление на панель
            // значка «такси».
            taxi: true
        }
    });

    control.routePanel.state.set({
        // Пусть по умолчанию используется маршрут
        // с возможностью вызова такси.
        type: "taxi",
        from: 'Москва, Льва Толстого 16',
        to: 'метро Черемушки'
    });
});
</script>  

В песочнице можно посмотреть интерактивный пример.

Задание размеров и позиции панели

Для панели маршрутизации можно выставить размеры, а также задать расположение на карте (например, можно привязать ее к правому верхнему углу карты). Список настроек приведен в справочнике.

Обратите внимание, также можно настроить поведение панели. Например, будет ли она автоматически получать фокус при добавлении на карту (опция autofocus).

Настройки позиции и поведения панели задаются через поле options:

// Получение ссылки на элемент управления.
var control = myMap.controls.get('routePanelControl');

control.options.set({
    // Список всех опций см. в справочнике.   
    maxWidth: '180px',
    float: 'right'
});

/*
// Другой способ выставить настройки панели: 
// при ее создании, через конструктор control.RoutePanel. 
var routePanelControl = new ymaps.control.RoutePanel({
    options: {
        maxWidth: '180px', 
        float: 'right'
    }
});

// Добавление панели на карту.
// Примечание: не забудьте удалить 'routePanelControl'
// из опции controls карты.
myMap.controls.add(routePanelControl);
*/
Посмотреть полный код примера
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
ymaps.ready(function () {
    var myMap = new ymaps.Map('map', {
        center: [55.75, 37.57],
        zoom: 9,
        controls: ['routePanelControl']
    });
   
    // Получение ссылки на элемент управления.
    var control = myMap.controls.get('routePanelControl');
    control.options.set({
        // Список всех опций см. в справочнике.   
        maxWidth: '180px',
        float: 'right'
    });
});
</script>

В разделе Типовые вопросы можно посмотреть решение других распространенных задач.

Настройка внешнего вида маршрута

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

Изменить внешний вид маршрута можно через объект multiRouter.MultiRoute — сначала получите ссылку на этот объект и затем задайте внешний вид через метод set().

Получение информации о построенном маршруте

Информация о построенных маршрутах хранится в мультимаршруте. Получить ссылку на этот объект можно с помощью метода getRouteAsync():

// Получение ссылки на панель.
var control = myMap.controls.get('routePanelControl');
  
// Получение мультимаршрута.
var multiRoutePromise = control.routePanel.getRouteAsync();

Метод getRouteAsync() возвращает Promise, который будет разрешен объектом multiRouter.MultiRoute или отклонен сообщением об ошибке. Мультимаршрут будет содержать ссылки на построенные маршруты.

Ниже приведен пример, как получить информацию об активном маршруте: длину, время прохождения и сведения о перекрытых участках дорог:

multiRoutePromise.then(function(multiRoute) {
    // Подписка на событие обновления мультимаршрута.
    multiRoute.model.events.add('requestsuccess', function() {
        // Получение ссылки на активный маршрут.
        var activeRoute = multiRoute.getActiveRoute();
        // Когда панель добавляется на карту, она
        // создает маршрут с изначально пустой геометрией. 
        // Только когда пользователь выберет начальную и конечную точки,
        // маршрут будет перестроен с непустой геометрией.
        // Поэтому для избежания ошибки нужно добавить проверку,
        // что маршрут не пустой.
        if (activeRoute) {
            // Вывод информации об активном маршруте.
            console.log("Длина: " + activeRoute.properties.get("distance").text);
            console.log("Время прохождения: " + activeRoute.properties.get("duration").text);
        }
    });
}, function (err) {
  console.log(err); 
});  

Через объект multiRouter.MultiRoute также можно изменить внешний вид маршрута (например, изменить цвет или толщину линий):

multiRoute.options.set({
    // Цвет метки начальной точки.
    wayPointStartIconFillColor: "#B3B3B3",
    // Цвет метки конечной точки.
    wayPointFinishIconFillColor: "blue",     
    // Внешний вид линий (для всех маршрутов).
    // Чтобы задать внешний вид линий активного маршрута,
    // нужно использовать префикс 'routeActive'.
    routeStrokeColor: "00FF00"
});   
Посмотреть полный код примера
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
// В данном примере показано, как получить информацию о построенном маршруте,
// а также изменить его внешний вид.

ymaps.ready(function () {
  var myMap = new ymaps.Map('map', {
      center: [55.753994, 37.622093],
      zoom: 9,
      // Добавление панели маршрутизации на карту.
      controls: ['routePanelControl']
  });

  // Получение ссылки на панель.
  var control = myMap.controls.get('routePanelControl');
  
  // Получение объекта, описывающего построенные маршруты.
  var multiRoutePromise = control.routePanel.getRouteAsync();
  multiRoutePromise.then(function(multiRoute) {
    //  Подписка на событие получения данных маршрута от сервера.
    multiRoute.model.events.add('requestsuccess', function() {
      // Ссылка на активный маршрут.
      var activeRoute = multiRoute.getActiveRoute();
      if (activeRoute) {
        // Вывод информации об активном маршруте.
        console.log("Длина: " + activeRoute.properties.get("distance").text);
        console.log("Время прохождения: " + activeRoute.properties.get("duration").text);
      }
    });
    multiRoute.options.set({
      // Цвет метки начальной точки.
      wayPointStartIconFillColor: "#B3B3B3",
      // Цвет метки конечной точки.
      wayPointFinishIconFillColor: "blue", 
      // Внешний вид линий (для всех маршрутов).
      routeStrokeColor: "00FF00"
    });  
  }, function (err) {
    console.log(err); 
  });
});
</script>  

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

Решение типовых задач

Как построить маршрут по трем точкам и более?

Панель маршрутизации позволяет строить маршруты только по двум точкам. Для построения более сложных маршрутов используйте класс multiRouter.MultiRoute.

Как построить маршрут от местоположения пользователя?

Определить местоположение пользователя можно с помощью метода geolocation.get(). Метод работает асинхронно — он возвращает Promise, который будет разрешен коллекцией GeoObjectCollection. В коллекции будут содержаться координаты и адрес текущего местоположения пользователя.

var myMap = new ymaps.Map('map', {
    center: [55.751574, 37.573856],
    zoom: 9,
    controls: ['routePanelControl']
});
// Получение ссылки на панель маршрутизации.
var control = myMap.controls.get('routePanelControl');
    
// Определение местоположения пользователя.
var location = ymaps.geolocation.get();
// Метод geolocation.get() возвращает Promise, который
// будет разрешен коллекцией GeoObjectCollection.
// Ссылка на эту коллекцию будет доступна в поле res.geoObjects.
location.then(function (res) {
    // Получение адреса местоположения пользователя.
    var userTextLocation = res.geoObjects.get(0).properties.get('text');
    control.routePanel.state.set({
        // В качестве начальной точки маршрута будет установлено
        // местоположение пользователя.
        from: userTextLocation,
        // Адрес конечной точки.
        to: 'Москва, ул. Льва Толстого, 16'
    });
});
Как скрыть подписи у меток?

Чтобы скрыть подписи у меток, нужно отключить опцию reverseGeocoding. При этом если вы программно задаете точки маршрута, они должны быть заданы координатами.

Опция reverseGeocoding — это флаг, разрешающий API выполнять обратное геокодирование. Это означает, что для точек, которые задаются координатами, API будет отправлять запросы Геокодеру, чтобы по координатам определить их адрес. Полученный адрес будет автоматически отображаться в подписях к метками, а также в поле ввода на панели.

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

var myMap = new ymaps.Map('map', {
    center: [55.751574, 37.573856],
    zoom: 9,
    controls: ['routePanelControl']
});

// Получение ссылки на панель
// маршрутизации.
var control = myMap.controls.get('routePanelControl');

control.routePanel.options.set({
    reverseGeocoding: false
});

control.routePanel.state.set({
    from: [55.734470, 37.58000],
    to: [55.734336, 37.51218]
});
Как задать собственный значок для меток маршрута?

Пример:

var myMap = new ymaps.Map('map', {
    center: [55.751574, 37.573856],
    zoom: 9,
    controls: ['routePanelControl']
});
// Получение ссылки на панель маршрутизации.
var control = myMap.controls.get('routePanelControl');

// Получение мультимаршрута.
var multiRoutePromise = control.routePanel.getRouteAsync();

multiRoutePromise.then(function(multiRoute) {
  // Изменение внешнего вида маршрута.
  // Список всех опций приведен в справочнике.
  multiRoute.options.set({
    // Задаем собственную картинку
    // для конечной точки.
    wayPointFinishIconLayout: "default#image",
    wayPointFinishIconImageHref: "images/sokolniki.png",
    wayPointFinishIconImageSize: [30, 30],
    wayPointFinishIconImageOffset: [-15, -15],
  });    
}, function (err) {
  console.log(err); 
});
Как задать собственный макет балуна маршрута?

См. пример.

Как отключить возможность для пользователей задавать/изменять точки маршрута?

Чтобы пользователи не могли изменять точки маршрута на карте, нужно выставить опции toEnabled и fromEnabled в false:

var myMap = new ymaps.Map('map', {
    center: [55.751574, 37.573856],
    zoom: 9,
    controls: ['routePanelControl']
});

// Получение ссылки на панель маршрутизации.
var control = myMap.controls.get('routePanelControl');

// Задание состояния для панели маршрутизации.
control.routePanel.state.set({
    // Флаг, запрещающий пользователям изменять
    // адрес начальной точки в поле ввода.
    fromEnabled: false,
    // Флаг, запрещающий пользователям изменять
    // адрес конечной точки в поле ввода.
    toEnabled: false,
    from: 'ул. Тушинская',
    to: 'Москва, ул. Льва Толстого, 16',
});
Мне нужно рассчитать стоимость доставки в зависимости от маршрута. Как я могу это сделать?

Посмотрите интерактивный пример в песочнице — Расчёт стоимости доставки.

Как отключить автоматическую фокусировку на панели?

Отключить автоматическую фокусировку на панели можно через опцию autofocus:

var myMap = new ymaps.Map('map', {
    center: [55.751574, 37.573856],
    zoom: 9,
    controls: ['routePanelControl']
});

var control = myMap.controls.get('routePanelControl');

control.options.set({
    autofocus: false
});
Как построить маршрут с учетом пробок?

Панель маршрутизации строит маршруты с учетом пробок по умолчанию. На данный момент отключить учет пробок нельзя.

Как программно поменять местами точки маршрута?

Поменять точки маршрута можно с помощью метода switchPoints().

var control = myMap.controls.get('routePanelControl');
// Задание точек маршрута.
control.routePanel.state.set({
    from: 'ул. Тушинская',
    to: 'Москва, ул. Льва Толстого, 16',
});
// Меняем точки местами.
control.routePanel.switchPoints();

В песочнице можно посмотреть интерактивный пример.

Как скрыть кнопку, позволяющую менять местами начальную и конечную точки маршрута?

Чтобы скрыть кнопку, нужно выставить опцию allowSwitch в false:

var myMap = new ymaps.Map('map', {
    center: [55.753994, 37.622093],
    zoom: 9,
    controls: ['routePanelControl']
});

// Получение ссылки на панель.
var control = myMap.controls.get('routePanelControl');
  
control.routePanel.options.set({
    // Список всех опций см. в справочнике.
    allowSwitch: false 
}); 
Как задать заголовок для панели?
var myMap = new ymaps.Map('map', {
    center: [55.753994, 37.622093],
    zoom: 9,
    controls: ['routePanelControl']
});

// Получение ссылки на панель.
var control = myMap.controls.get('routePanelControl');
    
control.options.set({
    // Список всех опций см. в справочнике.
    // Задание заголовка для панели.
    title: 'Заголовок панели',
    // Включить отображение заголовка.
    showHeader: true
});  

В песочнице можно посмотреть пример.