Руководство по переходу на 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 выполняется
// соответствующая функция.
ymaps3.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 ymaps3.Map('YMapsID', {
center: [37.588144, 55.733842],
zoom: 10,
type: 'yandex#satellite',
// Карта будет создана без
// элементов управления.
controls: []
});
Версия v3
// Создание экземпляра карты.
const map = new ymaps3.YMap(document.getElementById('YMapsID'), {
location: {
center: [37.588144, 55.733842],
zoom: 10
}
});
Примечание
В API v3 нет слоя со спутниковыми данными. Если вам необходим такой слой, то вы можете создать его сами, указав url для получения тайлов.
Поведения
Версия 2.1
По умолчанию включены следующие поведения: drag, multiTouch, dblClickZoom, rightMouseButtonMagnifier, scrollZoom.
Версия v3
Полный список поведений приведен в разделе YMapListener.
По умолчанию включены следующие поведения: drag, scrollZoom, pinchZoom, dblClick, magnifier.
Геообъекты
Задание стиля метки
Версия 2.1
// Метка с одним из стандартных значков.
// Список стандартных стилей приведен
// в справочнике в разделе
// option.preset.storage.
var placemark = new ymaps3.Placemark(
[37.6, 55.8],
{},
{
preset: 'islands#greenCircleIcon'
}
);
// Создание метки с собственным значком.
var placemark2 = new ymaps3.Placemark(
[37.6, 55.8],
{},
{
// Один из двух стандартных макетов
// меток со значком-картинкой:
// - default#image - без содержимого;
// - default#imageWithContent - с текстовым
// содержимым в значке.
iconLayout: 'default#image',
iconImageHref: '/path/to/icon.png',
iconImageSize: [20, 30],
iconImageOffset: [-10, -20]
}
);
Версия v3
import {YMapDefaultMarker} from '@yandex/ymaps3-default-ui-theme';
const defaultMarker = new YMapDefaultMarker({
title: 'Привет мир!',
subtitle: 'Добрый и светлый'
});
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, который находится во внешнем npm пакете @yandex/ymaps3-default-ui-theme.
Для кастомных маркеров используйте YMapMarker. Он позволяет использовать любые HTML внутри.
Кластеризация
Версия v3
В API v3 отсутствует встроенный механизм кластеризации.
Для работы с кластеризацией маркеров используйте класс YMapClusterer из пакета @yandex/ymaps3-clusterer, который добавляет расширенные возможности в JS API. Порядок подключения описан в инструкции.
Элементы управления картой
Версия v3
По умолчанию карта создается без стандартных элементов управления: полноэкранный режим, кнопки масштаба, геолокация. О том, как добавить на карту необходимые элементы управления, см. в разделе Элементы управления.
В API v3 остались только три элемента управления: геолокация, кнопки масштаба и обычная кнопка. Подробнее
Попап
Версия v3
В API v3 нет встроенного всплывающего окна. Вместо этого вы можете самостоятельно управлять содержимым HTML-элемента маркера.