Яндекс карты api 2.1 примеры

В данной статье я хочу начать цикл статей по работе с API Яндекс.Карт. Документация Яндекс.Карт достаточно полна, но степень разрозненности информации в ней высокая, при первом заходе в документацию без пол-литры не разобраться, и для решения какой-то проблемы можно потратить много времени на поиск по документации и в поисковике. Этот цикл статей будет рассказывать о практических решениях наиболее частых случаев использования API Яндекс.Карт последней, на момент написания статьи, версии 2.1.

При вёрстке сайта в контактной информации часто бывает необходимость вставки карты, на которой будет отмечено местоположение организации, для которой разрабатывается сайт. В самых простых случаях это может быть просто скриншот c онлайн-карт (или не онлайн):

Для вставки интерактивной карты может использоваться конструктор карт
https://tech.yandex.ru/maps/tools/constructor/ :

В случае, если нам нужно более продвинутое использование карт (свои метки, программное перемещение карт и т.п.), то для этого надо использовать API Яндекс.Карт: https://tech.yandex.ru/maps/jsapi/ . В качестве примера использования карт в статье будет рассмотрено создание карты с простым добавлением пользовательских метки и балуна.

Для начала подключим компоненты API:

Если разрабатывается какое-то большое приложение с использованием карт, то лучше подключать компоненты API определённой версии, чтобы при обновлении API на стороне Яндекса у нас ничего не сломалось на продакшине:

Карту необходимо будет расположить в каком-нибудь блоке, например в div#map . Далее карту необходимо создать в данном блоке (после срабатывания события готовности карты и DOM):

ymaps.ready (init) ; function init() { var myMap; myMap = new ymaps.Map ("map" , { center: [ 55.76 , 37.64 ] , zoom: 7 } ) ; }

Здесь мы указываем:

  • идентификатор блока «map» , где у нас будет создана карта;
  • center — центр карты с указанием ширины и долготы;
  • zoom — коэффициент масштаба карты.

    • По умолчанию Яндекс.Карты создают много лишних элементов, которые в большинстве случаев не нужны на сайтах. В основном к элементам управления и к поведению карты достаточно применить 2 условия:

  • из элементов карты присутствует только ползунок изменения масштаба;
  • карта не должна менять масштаб скроллом мыши.

    • Для выполнения этих требований дополняем код:

    ymaps.ready (init) ; function init() { var myMap; myMap = new ymaps.Map ("map" , { center: [ 55.76 , 37.64 ] , zoom: 13 , controls: } ) ; myMap.behaviors .disable ("scrollZoom" ) ; myMap.controls .add ("zoomControl" , { position: { top: 15 , left: 15 } } ) ; }

    Здесь мы отключили «scrollZoom» и добавили «zoomControl» с позиционированием от левого верхнего угла.

    Теперь нужно добавить на карту метку, для статьи скачаём её картинку с http://medialoot.com/item/free-vector-map-location-pins/ и расположим в коде следующим образом:

    ymaps.ready (init) ; function init() { var myMap; myMap = new ymaps.Map ("map" , { center: [ 55.7652 , 37.63836 ] , zoom: 17 , controls: } ) ; myMap.behaviors .disable ("scrollZoom" ) ; myMap.controls .add ("zoomControl" , { position: { top: 15 , left: 15 } } ) ; var myPlacemark = new ymaps.Placemark ([ 55.7649 , 37.63836 ] , { } , { iconLayout: "default#image" , iconImageHref: , iconImageSize: [ 40 , 51 ] , iconImageOffset: [ - 20 , - 47 ] } ) ; myMap.geoObjects .add (myPlacemark) ; }

    Здесь мы объявляем переменную myPlacemark , в которой запишем маркер, в первом параметре ymaps.Placemark указываем координаты метки, а в третьем параметре:

  • указываем в iconLayout , что будет использоваться пользовательское изображение метки;
  • iconImageHref — путь к изображению;
  • iconImageSize — указываем размеры изображения;
  • iconImageOffset — указываем сдвиг от левого верхнего угла картинке к точке изображения, которая показываем на нужный нам объет. Нужно это чтобы при масштабировании карты положение метки не сбивалось. Почему смещение указывается в отрицательных значениях — одному Богу создателю API известно.

    • И через myMap.geoObjects.add() добавляем метку на карту.

    А теперь сделаем баллун, который у нас будет показываться при клике на метку карты, макет баллуна и его содержимое возьмём с http://designdeck.co.uk/a/1241

    ymaps.ready (init) ; function init() { var myMap; myMap = new ymaps.Map ("map" , { center: [ 55.7652 , 37.63836 ] , zoom: 17 , controls: } ) ; myMap.behaviors .disable ("scrollZoom" ) ; myMap.controls .add ("zoomControl" , { position: { top: 15 , left: 15 } } ) ; var html = "" ; html += "" ; html += "" ; html += "

    The Victoria Tower Gardens

    " ; html += "" ; html += "

    City of London

    " ; html += "" ; html += "

    United Kingdom

    " ; html += "

    020 7641 5264

    " ; html += "" ; html += "" ; var myPlacemark = new ymaps.Placemark ([ 55.7649 , 37.63836 ] , { balloonContent: html } , { iconLayout: "default#image" , iconImageHref: "http://сайт/files/APIYaMaps1/min_marker.png" , iconImageSize: [ 40 , 51 ] , iconImageOffset: [ - 20 , - 47 ] , balloonLayout: "default#imageWithContent" , balloonContentSize: [ 289 , 151 ] , balloonImageHref: "http://сайт/files/APIYaMaps1/min_popup.png" , balloonImageOffset: [ - 144 , - 147 ] , balloonImageSize: [ 289 , 151 ] , balloonShadow: false } ) ; myMap.geoObjects .add (myPlacemark) ; }

    Здесь мы:

  • в balloonContent указываем контент, который будет отображаться при открытии балуна;
  • balloonLayout — указываем, что в качестве макета баллуна будет использоваться пользовательское изображение;
  • balloonContentSize и balloonImageSize — размеры контента и изображения соответственно;
  • balloonImageHref — путь к изображению;
  • balloonImageOffset — смещение относительно левого верхнего угла;
  • balloonShadow — отключение тени у балуна (с пользовательскими изображениями ни на что не влияет).

    • Мы выпустили бета-версию API Яндекс.Карт 2.1 . Главная ее особенность - полный редизайн интерфейса карты. Причем изменения затронули не только внешний вид, но и поведение элементов управления картой. Поскольку изначально было понятно, что поломки обратной совместимости не избежать, мы также внесли архитектурные изменения, которые были необходимы для улучшения работы API (о них ближе к концу поста).

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

    Для решения наших задач мы решили в новой версии реализовать адаптивный дизайн интерфейса. На Yet another Conference дизайнер madhare и разработчик zloylos выступили с докладом о том, зачем нам понадобилась адаптивность и как именно мы ее реализовали в API . В этом посте я опишу предысторию и концепцию наших решений, расскажу о том, что еще нового появилось в версии 2.1-beta, а также о том, что еще изменится к релизу 2.1.

    Зачем мы думаем о дизайне? После релиза версии 2.0 мы уже писали пост , в котором рассказывали о нашем подходе к разработке API. Суть концепции заключается в том, что мы делаем продукт не только для разработчиков, но и для тех, кто будет пользоваться результатами их работы. Если человеку будет удобно и приятно пользоваться нашими картами, и он будет требовать от любимых сервисов именно их - это будет настоящий успех. При этом разработчикам тоже должно быть легко и приятно удовлетворять желания пользователей, а значит мы должны по-максимуму упростить их работу с API. С такими мыслями мы начали работу над версией 2.0, а новая 2.1-бета стала логичным продолжением этой же концепции.Исследование Наблюдая за инсталляциями нашего API и анализируя кейсы использования карт, мы выделили два основных типа разработчиков:
    • Решают типовые задачи, не хотят тратить много времени, предпочитают готовые интерфейсы Яндекса. Таких примерно 90%.
    • Решают нестандартные задачи или предпочитают даже типовые задачи решать по-своему. Им не подходят стандартные элементы управления. Нужна серьезная кастомизация карт. Логично, что это оставшиеся 10%.
    Итак, нам нужно было сделать хорошо первым, оставив пространство для маневра вторым. Т.е. подготовить набор готовых решений, которые сами контролируют внешний вид итоговой карты, т.е. «делают хорошо», но при этом при желании их можно настроить под собственные нужды. Задачей максимум стало соблюсти баланс.

    Определившись с аудиториями, мы начали изучать кейсы использования. Оказалось, что в нашем случае основное значение имеет, как ни странно, размер. У нас получилось 3+1 варианта: маленькая, средняя, большая карта и мобильные сайты.

    Рисуем дизайн для карт разных размеров Самый тяжелый случай - маленькие карты. Кажется, что из-за маленького размера стоит убирать все элементы управления картой, но и терять функциональность тоже не хочется. Поэтому специально для маленьких карт мы сделали новый набор контролов:

    Также был добавлен новый элемент управления - «развернуть карту на весь экран». Он экономит место на сайте за счет размещения небольшой карты, а у конечного пользователя остается возможность посмотреть большую карту. Все нужное поведение карты запрограммировано уже на стороне API. Вообще идея этой кнопки родилась, когда мы думали о решении для мобильных устройств. Карта приемлемого размера на десктопе может стать совершенно бесполезной на мобильном. Фулскрин решает эту проблему:

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

    Со средними картами все гораздо проще. Поскольку есть, где развернуться:

    Как и с большими картами:

    Чтобы максимально упростить работу разработчиков при выборе элементов управления картой, мы сделали три готовых набора для разных размеров карты.
    map.controls.add("default");
    Список доступных ключей:
    smallMapDefaultSet // для маленькой
    mediumMapDefaultSet // для обычной
    largeMapDefaultSet // для большой

    Разумеется, по-прежнему можно самостоятельно указывать нужные контролы.
    myMap.controls .add("trafficControl") // пробки.add("searchControl") // поиск.add("zoomControl") // зум-контрол.add("typeSelector") // слои.add("geolocationControl") // геолокация.add("fullscreenControl") // фуллскрин …

    Адаптивность Недостаточно просто отрисовать дизайн интерфейса для разных размеров карт. Ведь страницу с картой могут открывать на разных экранах. Именно поэтому решено было реализовывать адаптивное поведение интерфейсов карты. Различные элементы интерфейса перестраиваются и меняют свой размер в зависимости от фактического размера контейнера карты.

    Адаптивное поведение мы реализовали через control.Manager . Также его можно задавать и для тех кнопок и списков, которые вы создаете сами:


    Работы по ускорению и оптимизации Геообъект - это главная сущность на карте. За такой титул ему приходится расплачиваться довольно сложной и громоздкой структурой. Первая итерация работ над геообъектами заключалась в распределении нагрузки при их создании. Мы постарались вынести все подготовительные операции из конструктора геообъекта в места, где они действительно становятся нужны. Это дало очень хорошие результаты. Также в некоторых местах мы сделали ленивую инициализацию сущностей с помощью _defineGetter_ и defineProperty (_defineGetter_, кстати, немного быстрее). Мы сократили количество подписок на события геообъектов внутри нашей системы событий. Частично помог прием подписки сразу на группу геообъектов с последующим определением в обработчике целевого объекта. Здесь нужно признаться, что ускорение можно пощупать только на dom и canvas метках, новые svg метки нам предстоит дорабатывать (why we call it beta? Because it beta then nothing… ;)

    Во время работы у нас было время на небольшую уборку в коде, по ее результатам приведем микровыводы:
    Микровывод 1. При передаче функции-обработчика намного выгоднее передавать отдельно функцию, отдельно контекст. Если у вас чешутся руки сделать bind сразу, подумайте, можете ли вы это себе позволить.
    Микровывод 2. Сокращайте количество промежуточных массивов, объектов и анонимных функций. Они не всегда хорошо чистятся garbage collector-ом.

    Прочие изменения
  • В версии API 2.0 для определения местоположения по IP или с помощью Geolocation API разработчикам приходится самостоятельно использовать необходимые методы и обрабатывать полученный результат. В версии 2.1 достаточно просто добавить новый стандартный элемент управления:
    control.GeolocationControl(parameters) Также был улучшен механизм определения местоположения пользователя, используемый в API. Теперь автоматически выбирается наиболее точный результат из браузерной геолокации и геолокации по IP-адресу.
  • Стандартные метки в API были перерисованы в SVG, а это значит, что им можно задавать произвольные цвета.
  • Система пакетов в версии 2.1 будет ликвидирована. Интерфейсы API изменены таким образом, чтобы максимально вынести загрузку компонент API по требованию, для чего большинство отображений были переведены в асинхронный режим. Работы еще ведутся.
  • Для такого масштабного обновления нам пришлось пожертвовать обратной совместимостью с версией 2.0. Также к официальному релизу версии 2.1 может сломаться обратная совместимость для некоторых частей бета-версии:
    • Существенно изменится кластеризатор.
    • Будет переписан map.action.Manager.
    • Promises будут реализованы по

    • 29 апреля 2014 года было объявлено, что новая версия API Яндекс.Карт 2.1 выходит из статуса беты и теперь Вы можете на неё безопасно переходить.

    В нескольких ближайших заметках я планирую познакомить Вас с данной версией API.

    Основные отличительные особенности JavaScript API Яндекс.Карт версии 2.1:

    — новый адаптивный дизайн интерфейсов карты;

    — мультимаршрутизатор — возможность построения всех возможных маршрутов вместо одного;

    — модульная система API. Список всех модулей API приведен в справочнике.

    — новый способ отображения объектов на карте, который позволяет создавать больше меток, чем в версии 2.0.

    Подробную документацию по новой версии API Яндекс.Карт 2.1 можно прочитать .

    Давайте рассмотрим простейший пример создания карты с использованием API Яндекс.Карт 2.1.

    Вот его код:

    Простейший пример создания карты с использованием API Яндекс.Карт 2.1. var myMap; // Дождёмся загрузки API и готовности DOM. ymaps.ready(init); function init () { // Создание экземпляра карты и его привязка к контейнеру с // заданным id ("map"). myMap = new ymaps.Map("map", { // При инициализации карты обязательно нужно указать // её центр и коэффициент масштабирования. center: , // Нижний Новгород zoom: 12 }); }

    В самом начале, мы подключаем API карт по адресу http://api-maps.yandex.ru/

    Давайте рассмотрим параметры подробнее:

    lang - задается двумя параметрами language_region,

    language - двузначный код языка. Указывается в формате ISO 639-1.
    region - двузначный код страны. Указывается в формате ISO 3166-1.

    На данный момент поддерживаются следующие локали:

    lang=ru_RU;
    lang=en_US;
    lang=ru_UA;
    lang=uk_UA;
    lang=tr_TR.

    Могут использоваться дополнительные параметры:

    coordorder — порядок задания географических координат в функциях API, принимающих на вход пары долгота-широта (например, Placemark).

    Возможные значения:

    latlong - [широта, долгота] - используется по умолчанию;
    longlat - [долгота, широта].

    Значение по умолчанию: latlong.

    load — Список загружаемых модулей.

    Значение по умолчанию: package.full.

    mode — Режим загрузки API.

    mode=release - код API может быть загружен в упакованном виде для минимизации трафика и скорости исполнения в браузере;
    mode=debug - режим загрузки в виде исходного кода.

    Значение по умолчанию: release.

    Подробнее о параметрах подключения можно прочитать

    Для отображения карты задается контейнер ненулевого размера, в качестве контейнера может использоваться любой HTML-элемент блочного типа, в примере это div.

    Параметры карты задаются в коде:

    myMap = new ymaps.Map(‘map’, {
    center: , // центр карты Нижний Новгород
    zoom: 12 - уровень масштаба
    });

    Создавать карту следует после того, как веб-страница загрузится целиком. Это даст уверенность в том, что контейнер для карты создан и к нему можно обращаться по id. Чтобы инициализировать карту после загрузки страницы, можно воспользоваться функцией ready().

    Функция ready вызовется тогда, когда API будет загружен и DOM сформирован

    ymaps.ready(init);

    function init () {
    // Создание экземпляра карты и его привязка к контейнеру с
    // заданным id ("map").
    myMap = new ymaps.Map(‘map’, {
    // При инициализации карты обязательно нужно указать
    // её центр и коэффициент масштабирования.
    center: , // Нижний Новгород
    zoom: 12
    });

    По умолчанию на карте отображаются все доступные элементы управления.

    Тип карты - схема.

    API предоставляет пять встроенных типов карт:

    Схема (yandex#map) - по умолчанию;
    Спутник (yandex#satellite);
    Гибрид (yandex#hybrid);
    Народная карта (yandex#publicMap);
    Гибрид народной карты (yandex#publicMapHybrid).

    Пример с определением типа карты Спутник

    Код примера:

    Задем тип карты - Спутник. Пример создания карты с использованием API Яндекс.Карт 2.1. body, html { padding: 0; margin: 0; width: 100%; height: 100%; } var myMap; // Дождёмся загрузки API и готовности DOM. ymaps.ready(init); function init () { // Создание экземпляра карты и его привязка к контейнеру с // заданным id ("map"). myMap = new ymaps.Map("map", { // При инициализации карты обязательно нужно указать // её центр и коэффициент масштабирования. center: , // Нижний Новгород zoom: 12, type: "yandex#satellite" }); }

    Как я уже говорил, на карту по умолчанию на карту добавляется стандартный набор элементов управления ‘mediumMapDefaultSet’.

    Для того чтобы добавить на карту нужные элементы управления, в параметре controls при ее создании можно указать список соответствующих ключей.

    Вот код примера элементами управления масштабом и типом карт.

    Код примера:

    body, html { padding: 0; margin: 0; width: 100%; height: 100%; }

    Элементы управления картой. Пример создания карты с использованием API Яндекс.Карт 2.1. body, html { padding: 0; margin: 0; width: 100%; height: 100%; } var myMap; // Дождёмся загрузки API и готовности DOM. ymaps.ready(init); function init () { // Создание экземпляра карты и его привязка к контейнеру с // заданным id ("map"). myMap = new ymaps.Map("map", { // При инициализации карты обязательно нужно указать // её центр и коэффициент масштабирования. center: , // Нижний Новгород zoom: 12, controls: ["zoomControl", "typeSelector"] }); }

    Существует возможность задания поведения карты, используя параметр behaviors.

    Задавая его значения, мы можем включать или отключать различные параметры поведения карты:

    масштабирование карты двойным щелчком кнопки мыши;

    перетаскивание карты с помощью мыши либо одиночного касания;

    масштабирование карты при выделении области левой кнопкой мыши;

    масштабирование карты мультисенсорным касанием;

    масштабирование карты при выделении области правой кнопкой мыши;

    измерение расстояния;

    масштабирование карты колесом мыши.

    Пример кода с отключенной возможностью масштабирования колесиком мыши.

    body, html { padding: 0; margin: 0; width: 100%; height: 100%; }

    Управление поведением карты. Пример создания карты с использованием API Яндекс.Карт 2.1. body, html { padding: 0; margin: 0; width: 100%; height: 100%; } var myMap; // Дождёмся загрузки API и готовности DOM. ymaps.ready(init); function init () { // Создание экземпляра карты и его привязка к контейнеру с // заданным id ("map"). myMap = new ymaps.Map("map", { // При инициализации карты обязательно нужно указать // её центр и коэффициент масштабирования. center: , // Нижний Новгород zoom: 12 }); myMap.behaviors.disable("scrollZoom"); }

    Возможно изменение параметров карты после ее создания.

    Включаем возможность масштабирования колесиком мыши

    myMap.behaviors.enable("scrollZoom");

    Выключаем

    myMap.behaviors.disable("scrollZoom");

    Устанавливаем новый тип карты Народная

    myMap.setType(‘yandex#publicMap’);

    Устанавливаем новый центр карты

    На этом пока все.

    Продолжение следует…

    A release candidate is a version of the API, which is available for public use, but is still under approval. Before installing the release candidate as a stable version, as soon as it is released, it is tested for bugs that may lead to API functionality degradation. By using release candidates in your projects, you can help us timely identify potential errors. You can also pretest your app"s operation with a new version of the API.

    Release candidates should be used in the app development and testing environment. This will help you avoid errors in the production environment. You can enable a release candidate as follows:

    If some time after publishing a release candidate no errors that lead to functionality degradation are found, the release candidate is installed as a stable version of the API and can be accessed via the link api-maps.yandex.ru/2.1.

    Enabling the current version

    When using your application, we recommend specifying the major version (i.e., do not specify the third number of the version). This guarantees that the current version, that is, the latest stable version of the corresponding major version, will be automatically enabled. For example, if you specify version 2.1, the latest available stable version 2.1.x will be enabled (for example, 2.1.47):

    Enabling a set version

    Although full compatibility is guaranteed between minor versions, in rare cases you may find that your client application does not work as intended when you enable the latest API version. To avoid these situations, in particularly crucial cases you may need to enable a specific API version. For that, specify its number in its entirety:

    Note. If you use a set version, try regularly switching it to a newer version (for example, once every few months). The matter is that over time we can disable the minor version you are using in your project, and then the current version of the API will be enabled automatically. However, the version update might cause your app to stop working correctly. For this reason, we recommend that you keep track of API updates and switch to newer versions as soon as possible.

    Summary table

    The table below provides recommendations for enabling different versions of the API, depending on the type and complexity of your project.

    Project type
    Project type Recommended version for running applications Recommended version under development

    Medium and large projects with a basic map

    Latest version of to test the functionality.

    Medium and large projects with complex map features

    Set version to test the functionality.

    Projects using the commercial version of the API

    		 Set version (see the note below)

    Note. If you use a set version, try regularly switching it to a newer version. The matter is that over time we can disable the minor version you are using in your app, and then the current version of the API will be enabled automatically. However, the version update might cause your app to stop working correctly. For this reason, we recommend that you keep track of API updates and switch to newer versions as soon as possible.

    Читайте также