Миграция с версии 2.x

Мотивация

Версия 3.0 изначально создавалась с целью дропнуть поддержку Vue 2, что и произошло. Одновременно с началом работ, Яндекс признали ряд внутренних библиотек устаревшими в пользу npm-пакетов, что также стало поводом сделать это в версии 3.0.

TLDR

Очень сильно поменялся YandexMapDefaultMarker. Это самое жирное изменение, которое потребует апгрейда. Также отказались от неймспейса VueYandexMaps в пользу обычного экспорта.

Смайлики

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

Смайлики подчеркивают критичность того или иного изменения при обновлении.

🟥 Требует пристального внимания
🟨 Возможно, придется внести минимальные изменения
🟩 Изменений, вероятно, не требуется

Breaking Changes

🟥 Минимальная версия Node

Минимальная версия Node поднята до 20.

Поддержка Node 20 будет прекращена в апреле 2026, после чего с некоторой задержкой минимальной версией станет 22.

Рекомендуется всегда использовать актуальную LTS-версию Node.

🟥 Минимальные версии

Поддержка Vue 2, Nuxt 2, а также Nuxt Bridge была завершена.

Кроме того, минимальная версия Nuxt была поднята до 3.12.

🟥 Удалён компонент `YandexMapDefaultSatelliteLayer`

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

Компонент удалён в связи с тем, что он и так был кривой, а какое-то время назад был полностью удален Яндексом из документации и типизации.

Если хотите, вы можете добавить его вручную - но делать это крайне не рекомендуется: **официально он не поддерживается **.

Добавить вручную (не рекомендуется)

javascript

const map = shallowRef < null | YMap > (null);
map.value.addChild(new ymaps3.YMapDefaultSatelliteLayer({visible: true}));

🟥 Замёнен компонент `YandexMapDefaultMarker` на `YandexMapUiMarker`

Яндекс признали старый компонент устаревшим.

Миграция

Если вы использовали компонент YandexMapUiMarker, переименуйте его в YandexMapDefaultMarker
Мигрируйте YandexMapDefaultMarker
- title и subtitle стали однострочными и больше не принимают HTML
- color теперь не строковый, а содержит такие параметры, как:
  - day (обязательный, цвет в светлой теме)
  - night (обязательный, цвет в тёмной теме)
  - iconDay, iconNight, strokeDay, strokeNight
  - popup теперь не открывается автоматически: требуется передать параметр show
  - Функции close у popup в слоте больше нет
  - Свойство hidesMarker у popup удалено
Проверьте отображение: оно поменялось полностью

Тип нового маркераТип старого маркера

typescript

export type YMapPopupMarkerProps = YMapMarkerProps & {
    /** The function of creating popup content */
    content: YMapPopupContentProps;
    /** The position of the popup in relation to the point it is pointing to */
    position?: YMapPopupPositionProps;
    /** The offset in pixels between the popup pointer and the point it is pointing to. */
    offset?: number;
    /** Hide or show popup on map */
    show?: boolean;
    /** Popup closing callback */
    onClose?: () => void;
    /** Popup opening callback */
    onOpen?: () => void;
};

export type MarkerPopupProps = Omit<YMapPopupMarkerProps, keyof YMapMarkerProps>;
export type YMapDefaultMarkerProps = YMapMarkerProps & {
    iconName?: IconName;
    color?: MarkerColorProps;
    size?: MarkerSizeProps;
    title?: string;
    subtitle?: string;
    staticHint?: boolean;
    popup?: MarkerPopupProps;
};

typescript

type DefaultMarkerCustomProps = {
    /** Marker title HTML */
    title?: string;
    /** Marker subtitle HTML */
    subtitle?: string;
    /** Marker icon color */
    color?: string;
    /** Popup */
    popup?: {
        /** Popup content */
        content: string | ((close: () => void) => HTMLElement);
        /** Popup position */
        position: "left" | "right" | "top";
        /** Should popup hide marker. Default is false */
        hidesMarker?: boolean;
    };
};

Вернуть старый маркер

Если вы не хотите мигрировать, или хотите отложить этот момент то на свой страх и риск можете воскресить старый маркер.

Так как он признан устаревшим, он может быть удален Яндексом в любой момент.

Старый маркер

vue


<template>
  <div
      v-if="!!slots.popup"
      ref="popup"
      class="old-marker-popup"
  >
    <slot
        :close="closeFunc"
        name="popup"
    />
  </div>
</template>

<script lang="ts" setup>
  import {useSlots} from 'vue';
  import type {PropType} from 'vue';
  import {computed, onMounted, ref, watch} from 'vue';
  import type {YMapDefaultMarker} from '@yandex/ymaps3-types/packages/markers';
  import type {DefaultMarkerCustomProps} from '@yandex/ymaps3-types/packages/markers/YMapDefaultMarker';
  import {setupMapChildren} from 'vue-yandex-maps';

  type Settings = ConstructorParameters<typeof YMapDefaultMarker>[0];
  export type YandexMapOldDefaultMarkerSettings = Omit<Settings, 'popup'> & {
    popup?: Omit<NonNullable<DefaultMarkerCustomProps['popup']>, 'content'> & {
      content?: NonNullable<DefaultMarkerCustomProps['popup']>['content'];
    };
  };

  defineOptions({name: 'YandexMapOldDefaultMarker'});

  const props = defineProps({
    modelValue: {
      type: Object as PropType<YMapDefaultMarker | null>,
      default: null,
    },
    settings: {
      type: Object as PropType<YandexMapOldDefaultMarkerSettings>,
      default: () => ({}),
    },
  });

  const emit = defineEmits<{ (e: 'update:modelValue', value: YMapDefaultMarker): void }>();

  defineSlots<{ popup: (settings: { close: () => void }) => unknown }>();
  const slots = useSlots();

  let mapChildren: YMapDefaultMarker | undefined;
  const popup = ref<HTMLDivElement | null>(null);
  const closeFunc = ref<() => void>(() => {
  });

  const contentFunc = (close: () => void) => {
    closeFunc.value = close;
    return popup.value!;
  };

  const getSettings = computed<YandexMapOldDefaultMarkerSettings>(() => {
    const settings = {...props.settings};

    if (settings.popup && (typeof settings.popup.content === 'undefined' || settings.popup.content === 'fromSlot') && popup.value) {
      settings.popup = {
        ...settings.popup,
        content: contentFunc,
      };
    }

    return settings;
  });

  onMounted(async () => {
    if (!props.settings.coordinates) {
      throw new Error('You must specify coordinates in YandexMapOldDefaultMarker settings');
    }

    mapChildren = await setupMapChildren({
      createFunction: ({YMapDefaultMarker: Marker}) => new Marker(getSettings.value as Settings),
      requiredImport: () => ymaps3.import('@yandex/ymaps3-markers@0.0.1'),
      settings: getSettings,
    });
    emit('update:modelValue', mapChildren);
  });

  watch(popup, () => {
    if (popup.value) popup.value.parentNode?.removeChild(popup.value);
  });
</script>

🟨 Удалён неймспейс `VueYandexMaps`

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

Мигрируйте с неймспейса на обычные методы

VueYandexMaps.*:

settings -> yandexMapSettings
readyToInit -> isYandexMapReadyToInit
ymaps -> удалено из публичного доступа
script -> yandexMapScript
YandexMapException -> название не изменилось (VueYandexMaps.YandexMapException -> YandexMapException)
loadStatus -> yandexMapLoadStatus
isLoaded -> yandexMapIsLoaded
loadError -> yandexMapLoadError
Тип PluginSettings -> YandexMapPluginSettings
Тип DefProductSettings -> удалено из публичного доступа
Тип LoadStatus -> YandexMapLoadStatus
importLayersExtra (если пользовались) -> название не изменилось
Тип LayersExtra -> YandexMapLayersExtra

🟨 Переименован компонент `YandexMapSphericalMercatorProjection`

Компонент YandexMapSphericalMercatorProjection теперь называется YandexMapWebMercatorProjection и подгружает CDN-модуль @yandex/ymaps3-web-mercator-projection.

Никаких других изменений в нём обнаружено не было.

🟨 Удалён метод `useYMapsLocationFromBounds`

Вместо него используйте getLocationFromBounds.

Никаких изменений между функциями нет, название приведено к общему стилю.

🟩 Изменения событий и props

События input удалены, ровно как и value, остались только modelValue и update:modelValue.

Если вы использовали v-model, никаких действий для перехода производить не нужно.

🟩 script setup

Библиотека практически полностью перешла на script setup, за исключением ряда компонентов, где требуется Render-функция.

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

За счёт этого:

У многих компонентов теперь будут нормально подтягиваться top-level атрибуты, навешанные прямо на компонент (data-v-*, классы, и т.д.)
Многим компонентам добавлены классы
Убраны слоты там, где их быть не могло

🟩 Устаревшие компоненты

Яндекс признал устаревшими ряд импортов из ymaps3.import. Скорее всего, ничего не изменилось существенно (кроме маркера и WebMercator), но это важно знать - например, могли незначительно поменяться стили или классы.

API входных параметров у компонентов не изменилось, за исключением YandexMapDefaultMarker, который изменился полностью.

YandexMapClusterer теперь подгружает CDN-модуль @yandex/ymaps3-clusterer
YandexMapGeolocationControl теперь подгружает CDN-модуль @yandex/ymaps3-default-ui-theme
YandexMapZoomControl теперь подгружает CDN-модуль @yandex/ymaps3-default-ui-theme
YandexMapHint теперь подгружает CDN-модуль @yandex/ymaps3-hint
YandexMapCartesianProjection теперь подгружает CDN-модуль @yandex/ymaps3-cartesian-projection
🟥 YandexMapDefaultMarker упразднён в пользу компонента, который ранее назывался YandexMapUiMarker (гайд по миграции находится выше)
- YMapDefaultMarkerProps
🟥 YandexMapSphericalMercatorProjection переименован в YandexMapWebMercatorProjection без каких-либо изменений - теперь он также грузит CDN-модуль @yandex/ymaps3-web-mercator-projection

Общие изменения по сравнению с 2.x

Добавлена поддержка указания runtimeConfig.public.yandexMaps в Nuxt
Добавлена поддержка index в YandexMapMiniMap,
Добавлен тип YandexMapPopupMarkerSettings
Сделаны публичными и документированы внутренние методы для написания своих компонентов:
- provideMapRoot
- setupMapChildren
- deleteMapChildren
- injectMap
Исправлена работа проекта в Astro clientRouter mode

Установка

Переход с 0.x/1.x

Про компоненты

Миграция с версии 2.x

Мотивация

TLDR

Breaking Changes

🟥 Минимальная версия Node

🟥 Минимальные версии

🟥 Удалён компонент `YandexMapDefaultSatelliteLayer`

🟥 Замёнен компонент `YandexMapDefaultMarker` на `YandexMapUiMarker`

Миграция

Вернуть старый маркер

🟨 Удалён неймспейс `VueYandexMaps`

🟨 Переименован компонент `YandexMapSphericalMercatorProjection`

🟨 Удалён метод `useYMapsLocationFromBounds`

🟩 Изменения событий и props

🟩 script setup

🟩 Устаревшие компоненты

Общие изменения по сравнению с 2.x

Миграция с версии 2.x ​

Мотивация ​

TLDR ​

Breaking Changes ​

🟥 Минимальная версия Node ​

🟥 Минимальные версии ​

🟥 Удалён компонент YandexMapDefaultSatelliteLayer ​

🟥 Замёнен компонент YandexMapDefaultMarker на YandexMapUiMarker ​

Миграция ​

Вернуть старый маркер ​

🟨 Удалён неймспейс VueYandexMaps ​

🟨 Переименован компонент YandexMapSphericalMercatorProjection ​

🟨 Удалён метод useYMapsLocationFromBounds ​

🟩 Изменения событий и props ​

🟩 script setup ​

🟩 Устаревшие компоненты ​

Общие изменения по сравнению с 2.x ​

Миграция с версии 2.x

Мотивация

TLDR

Breaking Changes

🟥 Минимальная версия Node

🟥 Минимальные версии

🟥 Удалён компонент `YandexMapDefaultSatelliteLayer`

🟥 Замёнен компонент `YandexMapDefaultMarker` на `YandexMapUiMarker`

Миграция

Вернуть старый маркер

🟨 Удалён неймспейс `VueYandexMaps`

🟨 Переименован компонент `YandexMapSphericalMercatorProjection`

🟨 Удалён метод `useYMapsLocationFromBounds`

🟩 Изменения событий и props

🟩 script setup

🟩 Устаревшие компоненты

Общие изменения по сравнению с 2.x