Руководство по переходу на JavaScript API 2.0

Документ содержит примеры кода для выполнения основных операций с JavaScript API Яндекс.Карт первой и второй версий.

Подключение API

Версия 1.1

Версия 2.0

 
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <!-- Загружаем API-->
        <script src="https://api-maps.yandex.ru/1.1/index.xml" type="text/javascript"></script>
        <script type="text/javascript">
            /* При успешной загрузке API выполняется
               соответствующая функция */
            YMaps.jQuery(function () {
                …
            });

        </script>
    </head>
    ...
</html>

URL API: https://api-maps.yandex.ru/1.1/index.xml.

Загруженный API включает в себя библиотеку jQuery.

 
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <!-- Загружаем API-->
        <script src="https://api-maps.yandex.ru/2.0/?apikey=ваш API-ключ&load=package.standard&mode=debug&lang=ru-RU" type="text/javascript"></script>
        <script type="text/javascript">
            /* При успешной загрузке API выполняется
               соответствующая функция */
            ymaps.ready(function () {
                …
            });
        </script>
    </head>
    ...
</html>

URL API: https://api-maps.yandex.ru/2.0/.

Обязательным является параметр lang.

Доступные параметры:

  • lang - язык (обязательный параметр);
  • apikey - API-ключ, полученный в Кабинете Разработчика;
  • load - пакеты, которые необходимо загрузить;
  • mode - режим работы с API. По умолчанию release (код обфусцирован, ошибки API не генерируются);
  • coordorder - порядок координат. По умолчанию принимает значение latlong (широта, долгота);
  • ns - пространство имен. По умолчанию ymaps.

API не включает в себя библиотеку jQuery и допускает пакетную загрузку (минимизация трафика).

Создание карты

Версия 1.1

Версия 2.0

 
/* Создание экземпляра карты и его привязка
   к контейнеру с id="YMapsID" */
var myMap = new YMaps.Map(YMaps.jQuery("#YMapsID")[0]);

// Установка для карты ее центра, типа и масштаба
myMap.setCenter(
    // Центр карты
    new YMaps.GeoPoint(37.64, 55.76),
    // Коэффициент масштабирования
    10,
    // Тип карты
    YMaps.MapType.SATELLITE
)

Центр, тип и коэффициент масштабирования карты задаются после ее инициализации.

 
/* Создание экземпляра карты и его привязка
   к контейнеру с id="YMapsID" */
var myMap = new ymaps.Map("YMapsID", {
        // Центр карты
        center: [55.76, 37.64],
        // Коэффициент масштабирования
        zoom: 10,
        // Тип карты
        type: "yandex#satellite"
    }
);

Центр, тип и коэффициент масштабирования карты задаются при ее инициализации.

Параметры карты

Изменение области просмотра карты

Версия 1.1

Версия 2.0

 
myMap.setBounds(new YMaps.GeoBounds(
    /* Координаты юго-западного угла области просмотра
       карты */
    new YMaps.GeoPoint(0, 0),
    /* Координаты северо-восточного угла области просмотра
       карты */
    new YMaps.GeoPoint(40, 40);
    )
)

myMap.setBounds([
    /* Координаты юго-западного угла области просмотра
       карты */
    [0, 0],
    /* Координаты северо-восточного угла области
       просмотра карты */
    [40, 40]
    ]
)

Плавное перемещение центра карты

Версия 1.1

Версия 2.0

 
myMap.panTo(
    // Координаты нового центра карты
    new YMaps.GeoPoint(37.609,55.753), {
            /* Опции перемещения:
               разрешить уменьшать и затем увеличивать
               зум карты при перемещении между точками */
            flying: true
        }
)

myMap.panTo(
    // Координаты нового центра карты
    [55.753, 37.609], {
        /* Опции перемещения:
           разрешить уменьшать и затем увеличивать зум
           карты при перемещении между точками
        */
        flying: true
    }
)

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

Версия 1.1

Версия 2.0

 
/* Определение максимального значения коэффициента
   масштабирования для заданной области просмотра карты */
var maxZoom = myMap.getMaxZoom(
        new YMaps.GeoBounds(
            new YMaps.GeoPoint(0, 0),
            new YMaps.GeoPoint(40, 40)
        )
    );

/* Определение минимального значения коэффициента
   масштабирования для заданной области просмотра карты */
var minZoom = myMap.getMinZoom(
        new YMaps.GeoBounds(
            new YMaps.GeoPoint(0, 0),
            new YMaps.GeoPoint(40, 40)
        )
    );

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

Максимальное и минимальное значения коэффициентов масштабирования определяются для заданной области просмотра карты.

 
/* Определение максимального и минимального
   значений коэффициентов масштабирования
  (производится для центра карты) */
myMap.zoomRange.get(
    /* Координаты точки, в которой определяются
       значения коэффициентов масштабирования */
    [55.8,37.6])
    .then(function (zoomRange, err) {
        if (!err) {
            // zoomRange[0] - минимальный масштаб
            // zoomRange[1] - максимальный масштаб
            ...
        }
    }
)

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

Максимальное и минимальное значения коэффициентов масштабирования определяются для заданной точки карты.

Поведения карты

Включение поведений карты

Версия 1.1

Версия 2.0

 
// После создания карты включаем нужные поведения
myMap.enableRuler();
myMap.enableScrollZoom();

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

 
/* При создании карты помимо поведений "по умолчанию"
   включаем еще дополнительные поведения (scrollZoom) */
var myMap = new ymaps.Map("map", {
            center: [59.93, 30.31],
            zoom: 10,
            behaviors: ["default", "scrollZoom"]
        }
    );

// Включаем поведения после создания карты
myMap.behaviors.enable("ruler");

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

Отключение поведений карты

Версия 1.1

Версия 2.0

 
// Отключаем поведения только после создания карты
myMap.disableDragging();
myMap.disableScrollZoom();

Поведения карты отключаются после ее инициализации.

 
/* При инициализации карты отключаем все поведения,
   кроме scrollZoom */
var myMap = new ymaps.Map("map", {
            center: [59.93, 30.31],
            zoom: 10,
            behaviors: ["scrollZoom"]
        }
    );

// Отключаем поведение после инициализации карты
myMap.behaviors.disable("scrollZoom");

Отключать поведения карты можно как при ее инициализации, так и после.

Добавление геообъектов на карту

Версия 1.1

Версия 2.0

 
myMap.addOverlay(geoObject)

Все геообъекты добавляются на карту с помощью метода addOverlay().

 
myMap.geoObjects.add(geoObject);

Все геообъекты добавляются на карту через глобальную коллекцию map.geoObjects с помощью метода add().

Метка

Версия 1.1.

Версия 2.0

 
// Создание метки
var myPlacemark = new YMaps.Placemark(
        // Координаты метки
        new YMaps.GeoPoint(37.6, 55.8), {
            /* Опции метки:
               - флаг перетаскивания метки */
            draggable: true,
            /* - показывать значок метки
               при открытии балуна */
            hideIcon: false
        }
    );

// Задание контента значка метки
myPlacemark.name = "Москва";
// Задание контента балуна
myPlacemark.description = "Столица России";

// Добавление метки на карту
myMap.addOverlay(myPlacemark); 

// Создание метки
var myPlacemark = new ymaps.Placemark(
        // Координаты метки
        [55.8, 37.6], {
            /* Свойства метки:
               - контент значка метки */
            iconContent: "Москва",
            // - контент балуна метки
            balloonContent: "Столица России"
        }, {
            /* Опции метки:
               - флаг перетаскивания метки */
            draggable: true,
            /* - показывать значок метки
               при открытии балуна */
            hideIconOnBalloonOpen: false
        }
    );

// Добавление метки на карту
myMap.geoObjects.add(myPlacemark);

Балун

Версия 1.1

Версия 2.0

 
myMap.openBalloon(
    // Координаты балуна
    new YMaps.GeoPoint(37.6, 55.7),
    // Контент балуна
    "Москва", {
        /* Опции балуна:
           - балун имеет кнопку закрытия */
        hasCloseButton: true
    }
);

myMap.balloon.open(
    // Координаты балуна
    [55.76, 37.64], {
        /* Свойства балуна:
           - контент балуна */
        content: "Москва"
    }, {
        /* Опции балуна:
           - балун имеет кнопку закрытия */
        closeButton: true
    }
);

Всплывающая подсказка

Версия 1.1

Версия 2.0

 
myMap.hint.show(
    // Координаты подсказки
    myMap.converter.coordinatesToLocalPixels(myMap.getCenter()),
    // Контент подсказки
    "Москва", {
        /* Опции подсказки:
           - задержка показа хинта */
        showTimeout: 2000
    }
)

Позиция всплывающей подсказки задается локальными пиксельными координатами.

 
myMap.hint.show(
    // Координаты подсказки
    myMap.getCenter(),
    // Контент подсказки
    "Москва", {
        /* Опции подсказки:
           - задержка показа хинта */
        showTimeout: 2000
    }
)

Позиция всплывающей подсказки может быть задана как в географических, так и пиксельных координатах (при указании пиксельных координат нужно передать специальную проекцию).

Ломаная линия

Версия 1.1

Версия 2.0

 
// Создание ломаной линии
var myPolyline = new YMaps.Polyline(
        // Координаты линии
        [
            new YMaps.GeoPoint(37.7, 55.7),
            new YMaps.GeoPoint(37.7, 55.8),
            new YMaps.GeoPoint(37.8, 55.8),
            new YMaps.GeoPoint(37.8, 55.7),
            new YMaps.GeoPoint(37.7, 55.7)
        ], {
            /* Опции линии:
               - отключение кнопки закрытия балуна */
            hasCloseButton: false
        }
);

// Создание стиля для ломанной
var s = new YMaps.Style();
s.lineStyle = new YMaps.LineStyle();
// Цвет и прозрачность линии
s.lineStyle.strokeColor = "0000FF55";
// Ширина линии
s.lineStyle.strokeWidth = "5";

// Добавление стиля в хранилище стилей карты
YMaps.Styles.add("example#CustomLine", s);

// Задание стиля для ломаной
myLine.setStyle("example#CustomLine");

// Установка контента балуна ломаной
myPolyline.setBalloonContent("Ломаная линия");

// Добавление линии на карту
myMap.addOverlay(myPolyline);

// Создание ломаной линии
var myPolyline  = new ymaps.Polyline([
        // Координаты вершин ломаной
            [55.80, 37.30],
            [55.80, 37.40],
            [55.70, 37.30],
            [55.70, 37.40]
        ], {
            /* Свойства линии:
               - балун ломаной */
            balloonContent: "Ломаная линия"
        }, {
            /* Опции линии:
               - отключение кнопки закрытия балуна */
            balloonCloseButton: false,
            // - цвет  и прозрачность линии
            strokeColor: "0000FF55",
            // - ширина линии
            strokeWidth: 5
         }
    );

// Добавление линии на карту
myMap.geoObjects.add(myPolyline);

Многоугольник

Версия 1.1

Версия 2.0

 
// Создание многоугольника
var myPolygon = new YMaps.Polygon([
            // Координаты многоугольника
            new YMaps.GeoPoint(37.7, 55.7),
            new YMaps.GeoPoint(37.7, 55.8),
            new YMaps.GeoPoint(37.8, 55.8),
            new YMaps.GeoPoint(37.8, 55.7)
        ]
),

    // Создание стиля многоугольника
    style = new YMaps.Style();
style.polygonStyle = new YMaps.PolygonStyle();
// Флаг использования заливки
style.polygonStyle.fill = true;
// Флаг отрисовки контурной линии
style.polygonStyle.outline = true;
// Ширина линии
style.polygonStyle.strokeWidth = 10;
// Цвет и прозрачность линии
style.polygonStyle.strokeColor = "ffff0088";
// Цвет и прозрачность заливки
style.polygonStyle.fillColor = "ff000055";

// Задание стиля для многоугольника
myPolygon.setStyle(style);

// Задание контента всплывающей подсказки многоугольника
myPolygon.setHintContent = ("Многоугольник");

// Добавление многоугольника на карту
myMap.addOverlay(myPolygon);

Если координаты первой и последней вершин многоугольника не совпадают, то при его отрисовке эти вершины будут автоматически соединены.

 
// Создание многоугольника
var myPolygon = new ymaps.Polygon([
            // Координаты многоугольника
            [
               [55.75, 37.50],
               [55.76, 37.60],
               [55.80, 37.70],
               [55.69, 37.72]
            ]
        ], {
            /* Свойства многоугольника:
               - контент хинта */
            hintContent: "Многоугольник"
        }, {
            /* Опции многоугольника:
               - флаг использования заливки */
            fill: true,
            // - флаг отрисовки контурной линии
            stroke: true,
            // - ширина линии
            strokeWidth: 5,
            // - цвет и прозрачность линии
            strokeColor: "ffff0088",
            // - цвет и прозрачность заливки
            fillColor: "ff000055"
         }
    );

// Добавление многоугольника на карту
myMap.geoObjects.add(myPolygon);

Если у многоугольника координаты первой и последней вершин не совпадают, то при создании этого многоугольника добавится еще одна вершина, совпадающая с первой.

Коллекции

Создание коллекции

Версия 1.1

Версия 2.0

 
var myCollection = new YMaps.GeoObjectCollection();

var myCollection = new ymaps.GeoObjectCollection();

Отображение элементов коллекции на карте

Версия 1.1

Версия 2.0

 
// Создание метки
var myPlacemark = new YMaps.Placemark(new YMaps.GeoPoint(37.64, 55.76));

// Добавление объекта (метки) в коллекцию
myCollection.add(myPlacemark);

// Добавление коллекции на карту
myMap.addOverlay(myCollection);

// Создание метки
var myPlacemark = new ymaps.Placemark([55.8,37.6]);

// Добавление объекта (метки) в коллекцию
myCollection.add(myPlacemark);

// Добавление коллекции на карту
myMap.geoObjects.add(myCollection);

Удаление элементов из коллекции

Версия 1.1

Версия 2.0

 
// Удаление одного элемента из коллекции
myCollection.remove(myPlacemark);

// Удаление всех элементов из коллекции
myCollection.removeAll();

// Удаление одного элемента из коллекции
myCollection.remove(myPlacemark);

// Удаление всех элементов из коллекции
myCollection.removeAll();

Задание стиля для элементов коллекции

Версия 1.1

Версия 2.0

 
// Задание стиля для коллекции при ее создании
var myCollection = new YMaps.GeoObjectCollection("default#greenPoint");

// Задание стиля коллекции после ее создания
myCollecton.setStyle("default#redPoint")

// Задание стиля для коллекции при ее создании
var myCollection = new ymaps.GeoObjectCollection({}, {
            preset: "twirl#greenIcon"
        }
    );

// Задание стиля коллекции после ее создания
myCollection.options.set("preset", "twirl#redIcon");

Элементы управления картой

Добавление элементов управления на карту

Версия 1.1

Версия 2.0

 
// Добавление стандартного набора кнопок
myMap.addControl(new YMaps.ToolBar());
// Добавление кнопки изменения масштаба
myMap.addControl(new YMaps.Zoom());
// Добавление списка типов карты
myMap.addControl(new YMaps.TypeControl());

// Добавление стандартного набора кнопок
myMap.controls.add("mapTools")
    // Добавление кнопки изменения масштаба
    .add("zoomControl")
    // Добавление списка типов карты
    .add("typeSelector");

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

Версия 1.1

Версия 2.0

 
// Удаление стандартного набора кнопок
myMap.removeControl(new YMaps.ToolBar());
// Удаление кнопки изменения масштаба
myMap.removeControl(new YMaps.Zoom());
// Удаление списка типов карты
myMap.removeControl(new YMaps.TypeControl());

// Удаление стандартного набора кнопок
myMap.controls.remove("mapTools")
    // Удаление кнопки изменения масштаба
    .remove("zoomControl")
    // Удаление списка типов карты
    .remove("typeSelector");

События

Добавление обработчика события карты

Версия 1.1

Версия 2.0

 
/* При щелчке на карте показывается балун со
   значениями координат в месте клика */
YMaps.Events.observe(myMap, myMap.Events.Click,
    function (myMap, mEvent) {
        myMap.openBalloon(
            // Позиция балуна
            mEvent.getGeoPoint(),
            // Контент балуна
            "Значение: " + mEvent.getGeoPoint()
       );
    }
);

/* При щелчке на карте показывается балун со
   значениями координат в месте клика */
myMap.events.add("click",
    function(e) {
        myMap.balloon.open(
            // Позиция балуна
            e.get("coordPosition"), {
                // Свойства балуна:
                // контент балуна
                contentBody: "Значение: " +
                e.get("coordPosition")
            }
        )
    }
);

Удаление обработчика события

Версия 1.1

Версия 2.0

 
// Удаление обработчика события после того, как событие произошло
var myEventListener = YMaps.Events.observe(map, map.Events.Click,
        function (map, mEvent) {
            alert("Щелк!");
            myEventListener.cleanup();
        }
    );

// Удаление обработчика события после того, как событие произошло
var onClick = function() {
        alert("Щелк!");
        myMap.events.remove("click", onClick);
    };

myMap.events.add("click", onClick);

Геопоиск

Прямое геокодирование

Версия 1.1

Версия 2.0

 
var geocoder = new YMaps.Geocoder(
        // Строка с адресом, который нужно геокодировать
        "Москва", {
            /* Опции поиска:
               - область поиска */
            boundedBy: myMap.getBounds(),
            // - искать только в этой области
            strictBounds: true,
            // - требуемое количество результатов
            results: 1
        }
    );

/* Размещение полученной коллекции
   геообъектов на карте */
myMap.addOverlay(geocoder);

var myGeocoder = ymaps.geocode(
        // Строка с адресом, который нужно геокодировать
        "Москва", {
            /* Опции поиска:
               - область поиска */
            boundedBy: myMap.getBounds(),
            // - искать только в этой области
            strictBounds: true,
            // - требуемое количество результатов
            results: 1
        }
    );

/* После того, как поиск вернул результат, вызывается
   callback-функция */
myGeocoder.then(
    function (res) {
        /* Размещение полученной коллекции
           геообъектов на карте */
        myMap.geoObjects.add(res.geoObjects);
    }
);

Обработка событий геокодера

Версия 1.1

Версия 2.0

 
/* Добавление обработчика события "Load" (геокодирование
   успешно закончено) */
YMaps.Events.observe(geocoder, geocoder.Events.Load,
    function () {
        if (this.length()) {
            // Добавление первого полученного объекта на карту
                        myMap.addOverlay(this.get(0));
            // Центрирование карты на добавленном объекте
            myMap.panTo(this.get(0).getGeoPoint())
        } else {
            alert("Ничего не найдено");
        }
    }
)

/* Добавление обработчика события "Fault" (при
   выполнении геокодирования произошла ошибка) */
YMaps.Events.observe(geocoder, geocoder.Events.Fault,
    function (error) {
        alert("Произошла ошибка: " + error.message)
    }
)

// Результат поиска передается в callback-функцию
myGeocoder.then(
    function (res) {
        if (res.geoObjects.getLength()) {
            // point - первый элемент коллекции найденных объектов
            var point = res.geoObjects.get(0);
            // Добавление полученного элемента на карту
            myMap.geoObjects.add(point);
            // Центрирование карты на добавленном объекте
            myMap.panTo(point.geometry.getCoordinates());
        }
    },
    // Обработка ошибки
    function (error) {
        alert("Возникла ошибка: " + error.message);
    }
)

Маршрутизатор

Создание маршрута

Версия 1.1

Версия 2.0

 
var router = new YMaps.Router([
        // Список точек, которые необходимо посетить
        'Арбатская',
        'Кропоткинская',
        // Метро 'Третьяковская'
        new YMaps.GeoPoint(37.62561,55.74062)
    ],
        // Кропоткинская — транзитная точка
    [1], {
        /* Опции маршрутизатора:
           - автоматически позиционировать карту */
        viewAutoApply: true
    });

Точки маршрута можно задавать, указав либо их координаты (объект класса YMaps.GeoPoint), либо адрес.

 
var myRouter = ymaps.route([
        // Список точек, которые необходимо посетить
        'Москва, метро Арбатская', {
            // Кропоткинская — транзитная точка
            type: "viaPoint",                   point: "Москва, метро Кропоткинская"
        },
        [55.74062, 37.62561] // метро "Третьяковская"
    ], {
        /* Опции маршрутизатора:
           - автоматически позиционировать карту */
        mapStateAutoApply: true
    });

Точки маршрута могут быть заданы в одном из следующих форматов:

  • адрес точки;
  • объект с полями type (тип точки) и point (адрес точки);
  • массив координат точки.

Добавление маршрута на карту

Версия 1.1

Версия 2.0

 
// Добавление маршрута на карту
myMap.addOverlay(router);

/* После того, как маршрут был построен, вызывается
   callback-функция */
myRouter.then(function(route) {
    // Добавление маршрута на карту
    myMap.geoObjects.add(route);
    }
);

Обработка событий маршрутизатора

Версия 1.1

Версия 2.0

 
/* Добавление обработчика события "Success" (успешное
   построение маршрута) */
YMaps.Events.observe(router, router.Events.Success, function() {
        // Задание текста для меток
        router.getWayPoint(0).setIconContent("А");
        router.getWayPoint(1).setIconContent("Б");
       // Добавление маршрута на карту
       myMap.addOverlay(router);
});

/* Добавление обработчика события "Error" (неудачное
   построение маршрута) */
YMaps.Events.observe(router, router.Events.RouteError,
    function (link, num) {
        alert("Не удается проложить маршрут до точки " + num);
    }
)

/* В случае успешного построение маршрута вызывается
   callback-функция */
myRouter.then(function(route) {
        /* Задание контента меток в начальной и
           конечной точках */
        var points = route.getWayPoints();         points.get(0).properties.set("iconContent", "А");
        points.get(1).properties.set("iconContent", "Б");
        // Добавление маршрута на карту
        myMap.geoObjects.add(route);
    },
    // Обработка ошибки
    function (error) {
        alert("Возникла ошибка: " + error.message);
    }
)
Предыдущая
IZoomControlLayout
Следующая
Примеры