API Яндекс Карт. Основные методы и классы. Добавление карты на сайт

В данной записи мы с вами детально рассмотрим JavaScript API Яндекс.Карт и попрактикуемся в кастомизации карта от Яндекса. JavaScript API Яндекс.Карт представляет собой набор JavaScript-компонентов, предназначенных для создания интерактивных карт. Компоненты размещены на серверах Яндекса и доступны для использования сразу после их загрузки на страницу.

Документация по API Яндекс здесь — https://tech.yandex.ru/maps/doc/archive/jsapi/2.0/dg/concepts/about-docpage/

Песочница с примерами здесь — https://tech.yandex.ru/maps/jsbox/2.1/customSet_controls

Как подключается API от Яндекс

Для того чтобы подключить API нужно внутрь тега head прописать следующий код.

<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>

В первом примере мы подключаем полный пакет всех классов и методов ( GET запрос — load=package.full )

Могут быть загружены как все компоненты API, так и отдельные пакеты, содержащие только необходимые компоненты. Это позволяет регулировать объем трафика, передаваемого клиентскому приложению.

В следующем примере подключены только пакеты package.controls и package.geoObjects. Набор загружаемых пакетов задается параметром load.

<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU&load=package.controls,package.geoObjects" type="text/javascript"></script>

Контейнер для карты

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

<div id="myMap" style="width: 700px; height: 700px;"></div>

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

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

<!-- КОНТЕЙНЕР ДЛЯ КАРТЫ -->
<div id="myMap" style="width: 700px; height: 700px;"></div>

<!-- СКРИПТ КАРТЫ -->
<script>
ymaps.ready(init);
function init(){     
    var myMap = new ymaps.Map ('myMap', {
        center: [68.964033, 33.068066], //координаты центра
        zoom: 10 //уровень приближения
    });
}
</script>

Динамическое удаление Яндекс Карты

Для динамического удаления карты можете использовать метод
.destroy();

// Удаление карты.
myMap.destroy();

Выбор типа карты

Вы можете указать тип карты. Для этого нужно прописать дополнительный параметр type с одним из значений.

• yandex#map — тип карты «схема» (по умолчанию);
• yandex#satellite — тип карты «спутник»;
• yandex#hybrid — тип карты «гибрид»;
• yandex#publicMap — тип карты «народная карта»;
• yandex#publicMapHybrid — тип карты «народный гибрид».

<!-- КОНТЕЙНЕР ДЛЯ КАРТЫ -->
<div id="myMap" style="width: 700px; height: 700px;"></div>

<!-- СКРИПТ КАРТЫ -->
<script>
ymaps.ready(init);
function init(){     
    var myMap = new ymaps.Map ('myMap', {
        center: [68.964033, 33.068066],
        zoom: 10,
        type: 'yandex#hybrid' //указываем тип карты гибрид
    });
}
</script>

Локализация. Выбор языка для карты

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

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

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

<script src="https://api-maps.yandex.ru/2.1/?lang=en_US" type="text/javascript">

Подробнее о локализации здесь — https://tech.yandex.ru/maps/doc/jsapi/2.1/dg/concepts/localization-docpage/

Как добавить метку на яндекс карту

В API от Яндекс метки реализуются с помощью класса Placemark. Перед тем как добавить метку на карту, создайте экземпляр этого класса. При создании метки вы можете задать текст её иконки, а также текст балуна, который откроется при щелчке кнопкой мыши на этой метке.

<!-- КОНТЕЙНЕР ДЛЯ КАРТЫ -->
<div id="myMap" style="width: 700px; height: 700px;"></div>

<!-- СКРИПТ КАРТЫ -->
<script>
ymaps.ready(init);
function init(){     
    var myMap = new ymaps.Map ('myMap', {
        center: [68.964033, 33.068066],
        zoom: 7
    });
    /*СОЗДАЕМ ЭКЗЕМПЛЯР КЛАССА Placemark*/
    var myPlacemark = new ymaps.Placemark([68.964033, 33.068066], { 
        iconContent: 'Мурманск', //текст на иконке
        balloonContent: 'Красивый город' /*текст появляющийся после нажатия*/
    }, {
        preset: 'twirl#blueStretchyIcon' //тип иконки
    });
    
    /*ДОБАВЛЯЕМ СОЗДАННУЮ КНОПКУ НА НАШУ КАРТУ*/
    myMap.geoObjects.add(myPlacemark);
}
</script>

Вы можете использовать стандартные стили кнопок. Все стандартные стили кнопок находятся здесь — https://tech.yandex.ru/maps/doc/jsapi/2.1/ref/reference/option.presetStorage-docpage/

Как задать собственный стиль для кнопки

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

• iconLayout — значение ‘default#image’ или ‘default#imageWithContent’ для меток соответственно без текста и с текстом поверх картинки;
• iconImageHref — URL графического файла значка;
• iconImageSize — размер значка в пикселах;
• iconImageOffset — сдвиг значка в пикселах относительно точки привязки (задается, если «ножка» значка не находится в левом верхнем углу изображения;
• iconContentOffset — для меток с текстом сдвиг текста относительно точки привязки метки.

var myPlacemark = new ymaps.Placemark([55.76, 37.56], {}, {
    iconLayout: 'default#image',
    iconImageHref: '/maps/doc/jsapi/2.1/examples/images/myIcon.gif',
    iconImageSize: [30, 42],
    iconImageOffset: [-3, -42]
});

Я предоставляю только часть информации, которая используется в большинстве случаев реализации карты. Вся подробная информация находится на сайте с документацией — https://tech.yandex.ru/maps/doc/jsapi/2.1/dg/concepts/geoobjects-docpage/

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

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

<!-- КОНТЕЙНЕР ДЛЯ КАРТЫ -->
<div id="myMap" style="width: 700px; height: 400px;"></div>

<!-- СКРИПТ КАРТЫ -->
<script>
ymaps.ready(init);

function init(){
    /*СОЗДАЕМ КАРТУ*/     
    var myMap = new ymaps.Map ('myMap', {
        center: [55.75, 37.61],
        zoom: 3,
        type: 'yandex#satellite'
    });
    /*ПОДКЛЮЧАЕМ СТАНДАРТНЫЕ КНОПКИ УПРАВЛЕНИЯ*/
    myMap.controls
        .add('mapTools')       // стандартные кнопки
        .add('typeSelector')   // переключатель типа карты
        .add('zoomControl');   // изменение масштаба   
}
</script>

Можно изменить расположение кнопок управления.

<!-- КОНТЕЙНЕР ДЛЯ КАРТЫ -->
<div id="myMap" style="width: 700px; height: 400px;"></div>

<!-- СКРИПТ КАРТЫ -->
<script>
ymaps.ready(init);
function init(){
    /*СОЗДАЕМ КАРТУ*/     
    var myMap = new ymaps.Map ('myMap', {
        center: [55.75, 37.61],
        zoom: 3,
        type: 'yandex#satellite'
    });

    /*ПОДКЛЮЧАЕМ СТАНДАРТНЫЕ КНОПКИ УПРАВЛЕНИЯ*/
    myMap.controls
    .add('mapTools', {left:5, bottom:35})
    .add('typeSelector', {left:5, top:5})
    .add('zoomControl', {right:5, top:15});
}
</script>

Добавление кастомных балунов на Яндекс карту

Балун — это всплывающее окно, в котором может быть показано любое HTML-содержимое. Одновременно на карте может быть показан только один балун.

<!-- КОНТЕЙНЕР ДЛЯ КАРТЫ -->
<div id="myMap" style="width: 700px; height: 700px;"></div>

<!-- СКРИПТ КАРТЫ -->
<script>
ymaps.ready(init);
function init() {
    var tinkoMap = new ymaps.Map('myMap', { center: [55.750, 37.607], zoom: 11 });
    // Масштабирование с помощью колесика мышки
    tinkoMap.behaviors.enable('scrollZoom');
    // Добавляем стандартные элементы управления
 tinkoMap.controls.add('zoomControl').add('typeSelector').add('mapTools');
    // Создаем метку центрального офиса
    var centralOfficePlacemark = new ymaps.Placemark([55.752422, 37.77163], {
        // Свойства
        iconContent: 'Центральный',
        name: 'Центральный офис',
        address: '3-й проезд Перова поля, дом 8',
        phone: 'тел: (495) 708-42-13, факc: (495) 708-42-14',
        photo: '<img src="http://prog-time.ru/wp-content/uploads/2019/05/polnyj-razbor-api-yandeks-kart.jpg" alt="Центральный офис" />',
        print: '<a href="" alt="Центральный офис" target="_blank" / rel="noopener noreferrer">Версия для печати</a>'
    }, {
        // Опции
        preset: 'twirl#redStretchyIcon' // иконка растягивается под контент
    });


    // Создаем метку офиса продаж Сокол
    var sokolOfficePlacemark = new ymaps.Placemark([55.810463, 37.524699], {
        // Свойства
        iconContent: 'Сокол',
        name: 'Офис продаж Сокол',
        address: 'ул. Часовая, д. 24, стр. 2',
        phone: 'тел: (495) 708-42-13 доб. 401',
        photo: '<img src="http://prog-time.ru/wp-content/uploads/2019/05/akkordeon-na-chistom-css.jpg" alt="Офис продаж Сокол" />',
        print: '<a href="/images/print1.jpg" alt="Офис продаж Сокол" target="_blank" / rel="noopener noreferrer">Версия для печати</a>'
    }, {
        // Опции
        preset: 'twirl#redStretchyIcon' // иконка растягивается под контент
    });
    
    // Создаем коллекцию, в которую будем добавлять метки
    var tinkoCollection = new ymaps.GeoObjectCollection();

    // Добавляем метки в коллекцию геообъектов
    tinkoCollection
        .add(centralOfficePlacemark)
        .add(sokolOfficePlacemark);

    // Создаем шаблон для отображения контента балуна
    var tinkoBalloonLayout = ymaps.templateLayoutFactory.createClass(
        '<p><strong>$[properties.name]</strong></p>' +
        '<p>$[properties.address]</p>' +
        '<p>$[properties.phone]</p>' +
        '<p>$[properties.photo]</p>' +
        '<p>$[properties.print]</p>'
    );

    // Помещаем созданный шаблон в хранилище шаблонов.
    // Теперь наш шаблон доступен по ключу 'tinko#officeslayout'
    ymaps.layout.storage.add('tinko#officeslayout', tinkoBalloonLayout);

    // Задаем наш шаблон для балунов геобъектов коллекции
    tinkoCollection.options.set({
        balloonContentBodyLayout:'tinko#officeslayout',
        // Максимальная ширина балуна в пикселах
        balloonMaxWidth: 350
    });

    // Добавляем коллекцию геообъектов на карту
    tinkoMap.geoObjects.add(tinkoCollection);
}
</script>

Добавляем многоугольник на Яндекс карту

Для того чтобы добавить фигуру на карту нужно прописать координаты его углов. Делается это так…

<!-- КОНТЕЙНЕР ДЛЯ КАРТЫ -->
<div id="myMap" style="width: 100%; height: 400px;"></div>

<!-- СКРИПТ КАРТЫ -->
<script>
ymaps.ready(init);
function init () {
    var myMap = new ymaps.Map ('myMap', {
        center: [55.75, 37.61],
        zoom: 10
    });
    // создаем многоугольник
    var myPolygon = new ymaps.Polygon([[
        // координаты вершин внешней границы многоугольника
        [55.778607,37.553126],
        [55.792923,37.647883],
        [55.724391,37.709681],
        [55.708887,37.583339]
    ]]);
    myMap.geoObjects.add(myPolygon);
}
</script>

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

Круг на карте создаётся с помощью метода ymaps.Circle.

ymaps.ready(init);

function init() {
    // Создаем карту.
    var myMap = new ymaps.Map("myMap", {
        center: [55.76, 37.64],
        zoom: 10
    });

    // Создаем круг.
    var myCircle = new ymaps.Circle([
        // Координаты центра круга.
        [55.76, 37.60],
        // Радиус круга в метрах.
        10000
    ], {
        // Описываем свойства круга.
        // Содержимое балуна.
        balloonContent: "Радиус круга - 10 км",
        // Содержимое хинта.
        hintContent: "Подвинь меня"
    }, {
        // Задаем опции круга.
        // Включаем возможность перетаскивания круга.
        draggable: true,
        // Цвет заливки.
        // Последний байт (77) определяет прозрачность.
        // Прозрачность заливки также можно задать используя опцию "fillOpacity".
        fillColor: "#DB709377",
        // Цвет обводки.
        strokeColor: "#990066",
        // Прозрачность обводки.
        strokeOpacity: 0.8,
        // Ширина обводки в пикселях.
        strokeWidth: 5
    });

    // Добавляем круг на карту.
    myMap.geoObjects.add(myCircle);
}

Ломанная с возможностью редактирования

ymaps.ready(init);

function init() {
    // Создаем карту.
    var myMap = new ymaps.Map("map", {
        center: [55.72, 37.64],
        zoom: 10
    });

    // Создаем ломаную.
    var myPolyline = new ymaps.Polyline([
        // Указываем координаты вершин.
        [55.80, 37.50],
        [55.80, 37.40],
        [55.70, 37.50],
        [55.70, 37.40]
    ], {}, {
        // Задаем опции геообъекта.
        // Цвет с прозрачностью.
        strokeColor: "#00000088",
        // Ширину линии.
        strokeWidth: 4,
        // Максимально допустимое количество вершин в ломаной.
        editorMaxPoints: 6,
        // Добавляем в контекстное меню новый пункт, позволяющий удалить ломаную.
        editorMenuManager: function (items) {
            items.push({
                title: "Удалить линию",
                onClick: function () {
                    myMap.geoObjects.remove(myPolyline);
                }
            });
            return items;
        }
    });

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

    // Включаем режим редактирования.
    myPolyline.editor.startEditing();
}

Редактор многоугольника

ymaps.ready(init);

function init() {
    var myMap = new ymaps.Map("map", {
        center: [55.73, 37.75],
        zoom: 10
    });

    // Создаем многоугольник без вершин.
    var myPolygon = new ymaps.Polygon([], {}, {
        // Курсор в режиме добавления новых вершин.
        editorDrawingCursor: "crosshair",
        // Максимально допустимое количество вершин.
        editorMaxPoints: 5,
        // Цвет заливки.
        fillColor: '#00FF00',
        // Цвет обводки.
        strokeColor: '#0000FF',
        // Ширина обводки.
        strokeWidth: 5
    });
    // Добавляем многоугольник на карту.
    myMap.geoObjects.add(myPolygon);

    // В режиме добавления новых вершин меняем цвет обводки многоугольника.
    var stateMonitor = new ymaps.Monitor(myPolygon.editor.state);
    stateMonitor.add("drawing", function (newValue) {
        myPolygon.options.set("strokeColor", newValue ? '#FF0000' : '#0000FF');
    });

    // Включаем режим редактирования с возможностью добавления новых вершин.
    myPolygon.editor.startDrawing();
}