Руководство по переходу на JS API v3
Руководство содержит примеры, демонстрирующие различия между JavaScript API версий v3 и 2.1. Так как API отличны в корне, в этом разделе освещены лишь различия в базовых компонентах и подходах.
Подключение API
Версия 2.1
<!DOCTYPE html>
<head>
<!-- Загружаем API -->
<script src="https://api-maps.yandex.ru/2.1/?apikey=YOUR_API_KEY&lang=ru_RU"></script>
<script>
// При успешной загрузке API выполняется
// соответствующая функция.
ymaps.ready(function () {
…
});
</script>
</head>
...
</html>
Версия v3
<!DOCTYPE html>
<html>
<head>
<!-- Загружаем API -->
<script src="https://api-maps.yandex.ru/v3/?apikey=YOUR_API_KEY&lang=ru_RU"></script>
<script>
// При успешной загрузке API доступен промис `ymaps3.ready`
ymaps3.ready.then(() => {
…
});
</script>
</head>
...
</html>
Обязательные параметры:
apikey— API-ключ. Как получить ключ;lang— язык.
Важно.
В API v3 раздельная подзагрузка модулей по требованию отсутствует. Нет параметра onload. Единственный способ выполнить код после готовности API — это промис ymaps3.ready.
Создание карты
Версия 2.1
// Создание экземпляра карты
// и его привязка к
// контейнеру с id="YMapsID".
const map = new ymaps.Map('YMapsID', {
center: [37.64, 55.76],
zoom: 10,
type: 'yandex#satellite',
// Карта будет создана без
// элементов управления.
controls: []
});
Версия v3
// Создание экземпляра карты.
const map = new ymaps3.YMap(document.getElementById('YMapsID'), {
location: {
center: [37.64, 55.76],
zoom: 10
}
});
Примечание.
В API v3 нет слоя со спутниковыми данными. Если вам необходим такой слой, то вы можете создать его сами, указав url для получения тайлов.
Поведения
Версия 2.1
По умолчанию включены следующие поведения: drag, multiTouch, dblClickZoom, rightMouseButtonMagnifier, scrollZoom.
Версия v3
Полный список поведений приведен в разделе События.
По умолчанию включены следующие поведения: drag, scrollZoom, pinchZoom, dblClick, magnifier.
Геообъекты
Задание стиля метки
Версия 2.1
// Метка с одним из стандартных значков.
// Список стандартных стилей приведен
// в справочнике в разделе
// option.preset.storage.
var placemark = new ymaps.Placemark(
[37.6, 55.8],
{},
{
preset: 'islands#greenCircleIcon'
}
);
// Создание метки с собственным значком.
var placemark2 = new ymaps.Placemark(
[37.6, 55.8],
{},
{
// Один из двух стандартных макетов
// меток со значком-картинкой:
// - default#image - без содержимого;
// - default#imageWithContent - с текстовым
// содержимым в значке.
iconLayout: 'default#image',
iconImageHref: '/path/to/icon.png',
iconImageSize: [20, 30],
iconImageOffset: [-10, -20]
}
);
Версия v3
const defaultMarker = new ymaps3.YMapDefaultMarker({
title: 'Привет мир!',
subtitle: 'Добрый и светлый',
color: 'blue'
});
const content = document.createElement('div');
const marker = new ymaps3.YMapMarker(content);
content.innerHTML = '<div>Тут может быть все что угодно</div>';
const map = new ymaps3.YMap(document.getElementById('map-root'), {
location: INITIAL_LOCATION
})
.addChild(new ymaps3.YMapDefaultSchemeLayer())
.addChild(new ymaps3.YMapDefaultFeaturesLayer({zIndex: 1800}))
.addChild(defaultMarker)
.addChild(marker);
В API v3 есть лишь один дефолтный тип маркеров: YMapDefaultMarker.
Для кастомных маркеров используйте YMapMarker. Он позволяет использовать любые HTML внутри.
Кластеризация
Версия v3
В API v3 нет механизма кластеризации.
Элементы управления картой
Версия v3
По умолчанию карта создается без стандартных элементов управления: полноэкранный режим, кнопки масштаба, геолокация. О том, как добавить на карту необходимые элементы управления, см. в разделе Элементы управления.
В API v3 остались только три элемента управления: геолокация, кнопки масштаба и обычная кнопка. Подробнее
Попап
Версия v3
В API v3 нет встроенного всплывающего окна. Вместо этого вы можете самостоятельно управлять содержимым HTML-элемента маркера.