Документация |
Номер версии API состоит из трех чисел, например 2.1.44. При каждом обновлении API номер версии увеличивается по следующим правилам:
Первые два числа образуют т. н. мажорную версию (например, 2.1), все три числа вместе — минорную версию (например, 2.1.47).
В настоящий момент поддерживаются четыре мажорные версии JS API Яндекс.Карт:
Архивные версии API продолжают поддерживаться, но не развиваются — т. е. в них исправляются критические ошибки, но не добавляется новая функциональность, в т. ч. поддержка новых веб-технологий.
Версия 2.1 в настоящий момент поддерживается и развивается. Список доступных минорных версий приведен в конце раздела.
Примерно раз в месяц выпускается новая минорная версия текущей мажорной версии. Жизненный цикл минорной версии состоит из следующих этапов:
Релиз-кандидат
Первое время после релиза минорная версия является релиз-кандидатом, то есть она доступна для открытого использования, но еще находится на стадии утверждения. Релиз-кандидат содержит последние исправления и новую функциональность API, но использование релиз-кандидата в своих проектах не гарантирует стабильную работу. Как подключить релиз-кандидат
Текущая версия (последняя стабильная версия)
Если спустя некоторое время после выпуска в релиз-кандидате не было выявлено ошибок функциональности, то релиз-кандидат признается стабильным и устанавливается как текущая минорная версия соответствующей мажорной версии. Текущая версия может не содержать последние изменения в API (так как уже может быть выпущен следующий релиз-кандидат), но гарантирует стабильную функциональность. Как подключить текущую версию
Фиксированная версия
Как только следующий релиз-кандидат будет установлен как стабильный, предыдущая стабильная версия замораживается и устанавливается как фиксированная. Фиксированные версии доступны продолжительное время, но со временем они удаляются и заменяются ссылкой на текущую версию API. Как подключить фиксированную версию
Для каждой версии API в документации существуют отдельные справочники:
Ниже приведены рекомендации по подключению и использованию версий API.
Релиз-кандидат — это версия API, которая доступна для открытого использования, но находится на стадии утверждения. Прежде чем релиз-кандидат будет установлен как стабильная версия, первое время после выпуска он тестируется на наличие ошибок, которые могут привести к деградации функциональности API. Используя релиз-кандидат в своих проектах, вы поможете нам своевременно выявить возможные ошибки. Кроме того, вы сможете заранее протестировать работу приложения с новой версией API.
Релиз-кандидат следует использовать в среде разработки и тестирования приложения. Это позволит избежать появления ошибок в рабочем окружении. Подключить релиз-кандидат можно следующим образом:
<script src="https://api-maps.yandex.ru/2.1-dev/?lang=ru_RU" type="text/javascript"/>
Если через некоторое время после публикации релиз-кандидата не было выявлено ошибок, приводящих к деградации функциональности, релиз-кандидат устанавливается как стабильная версия API и становится доступным по ссылке api-maps.yandex.ru/2.1.
При эксплуатации приложения рекомендуется указывать мажорную версию (т. е. не указывать третье число версии). В этом случае будет автоматически подключена текущая версия, то есть последняя стабильная версия соответствующей мажорной версии. Так, например, если указана версия 2.1, то будет подключена последняя стабильная на данный момент версия 2.1.x (например, 2.1.47):
<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"/>
Хотя между минорными версиями гарантируется полная совместимость, в редких случаях может оказаться, что ваше приложение при подключении последней версии API не работает так, как было задумано. Поэтому для предотвращения таких ситуаций, в особо ответственных случаях, может потребоваться подключить строго определенную версию API. Для этого нужно указать ее номер целиком:
<script src="https://api-maps.yandex.ru/2.1.44/?lang=ru_RU" type="text/javascript"/>
Ниже приведена сводная таблица, содержащая рекомендации по подключению разных версий API в зависимости от типа и сложности проекта.
Тип проекта | Рекомендуемая версия при эксплуатации приложения | Рекомендуемая версия в разработке |
---|---|---|
Небольшие проекты |
Конструктор карт. |
Конструктор карт. |
Средние и крупные проекты, с простой картой |
Последняя версия api-maps.yandex.ru/2.1. |
Релиз-кандидат версия api-maps.yandex.ru/2.1-dev для проверки функциональности. |
Средние и крупные проекты, со сложной функциональностью карты |
Фиксированная версия api-maps.yandex.ru/2.1.x (см. примечание ниже). |
Релиз-кандидат версия api-maps.yandex.ru/2.1-dev для проверки функциональности. |
Проекты, использующие платную версию API | Фиксированная версия enterprise.api-maps.yandex.ru/2.1.x (см. примечание ниже). | Фиксированная версия enterprise.api-maps.yandex.ru/2.1.x (см. примечание ниже) |
API Яндекс.Карт корректно работает в следующих браузерах:
В этих браузерах доступна и работает полностью одинаково вся функциональность API Яндекс.Карт.
Частично поддерживаются следующие браузеры:
В этих браузерах доступна та функциональность API Яндекс.Карт, которую технически возможно реализовать на данной платформе. Например, в IE8 не поддерживается задание произвольных цветов меток в силу отсутствия полноценной поддержки SVG этим браузером. Кроме того, внешний вид графических объектов и элементов управления может отличаться в разных браузерах.
Для пользователей, которые работают в браузерах IE8, IE9 и IE10, будет подключаться версия 2.1.oldie.1 (даже если в ссылке подключения указана другая версия API). Версия 2.1.oldie.1 функционально соответствует версии 2.1.59 и не содержит более поздних обновлений.
Если необходимо поддерживать браузеры IE8, IE9 и IE10, при написании кода ориентируйтесь на справочник версии 2.1.59 (скачать справочник). Использование функциональности более поздних версий может привести к некорректной работе API в IE8, IE9 и IE10.
Корректная работа API в браузерах, функционирующих в режиме совместимости со старыми версиями (Quirks mode) не гарантируется.
Ниже приведен список изменений в JavaScript API Яндекс.Карт от версии к версии. В скобках указана дата выпуска соответствующей версии.
Изменено:
Исправлено:
Добавлено:
Изменено:
Исправлено:
Исправлено:
Добавлено:
Изменено:
Исправлено:
Добавлено:
Изменено:
Исправлено:
Исправлено:
Добавлено:
Изменено:
Исправлено:
Исправлено:
Исправлено:
Изменено:
Исправлено:
Исправлено:
Добавлено:
Изменено:
Исправлено:
Добавлено:
Изменено:
Исправлено:
Исправлено:
Добавлено:
Изменено:
Исправлено:
Добавлено:
Исправлено:
Добавлено:
Исправлено:
Добавлено:
Исправлено:
Изменено:
Исправлено:
Добавлено:
Изменено:
Исправлено:
Исправлено:
Добавлено:
Исправлено:
Добавлено:
Изменено:
Исправлено:
Исправлено:
Добавлено:
Исправлено:
Исправлено:
Добавлено:
Исправлено:
Добавлено:
Изменено:
Исправлено:
Добавлено:
Изменено:
Исправлено:
Добавлено:
Исправлено:
Исправлено:
Исправлено:
Изменено:
Исправлено:
Исправлено:
Исправлено:
Исправлено:
Исправлено:
Исправлено:
Исправлено:
Исправлено:
Исправлено:
Исправлено:
Если при переключении версии API ваше приложение стало работать некорректно или вы обнаружили какие-либо ошибки в функциональности, пожалуйста, напишите нам об этом. Постарайтесь максимально подробно описать проблему и по возможности приложите скриншот.