JavaScript API Яндекс.Карт: полное руководство по интеграции для разработчиков

lang — язык интерфейса карты:​

• ru_RU — русский (по умолчанию)

• en_US — английский

• uk_UA — украинский

• tr_TR — турецкий

load — выборочная загрузка модулей для оптимизации:​

<script src="https://api-maps.yandex.ru/2.1/?apikey=КЛЮЧ&lang=ru_RU&load=package.map,package.geoObjects"></script>


Если параметр load не указан, загружается полный пакет package.full. Для уменьшения объема трафика загружайте только нужные модули:​

• package.map — базовая карта

• package.geoObjects — объекты на карте (метки, линии, многоугольники)

• package.controls — элементы управления

• package.clusters — кластеризация меток​

Асинхронная загрузка:

Для улучшения производительности используйте атрибут async:​

<script src="https://api-maps.yandex.ru/2.1/?apikey=КЛЮЧ&lang=ru_RU"
type="text/javascript" async></script>


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

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

Карта отображается внутри HTML-элемента (обычно <div>) с уникальным идентификатором:​

<div id="map"></div>


Обязательные CSS-стили:

Контейнер должен иметь заданные ширину и высоту:

#map {
    width: 600px;
    height: 400px;
}

Без указания размеров карта не отобразится или будет иметь нулевую высоту.​

Адаптивная карта:

Для адаптивности используйте относительные единицы:

#map {
    width: 100%;
    height: 60vh; /* 60% высоты окна браузера */
    min-height: 300px; /* минимальная высота для мобильных */
}

Создание первой карты: базовый пример

Теперь создадим простую интерактивную карту с одной меткой.​

Инициализация карты через ymaps.ready()

Функция ymaps.ready() гарантирует, что API полностью загружен перед выполнением кода:

ymaps.ready(init);

function init() {
    // Создание экземпляра карты
    var myMap = new ymaps.Map("map", {
        center: [55.76, 37.64], // Координаты центра карты [широта, долгота]
        zoom: 10 // Уровень масштабирования (0-19)
    });
}

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

center — координаты центра карты в формате [широта, долгота]:​

• Москва: [55.751244, 37.618423]

• Санкт-Петербург: [59.934280, 30.335099]

• Екатеринбург: [56.838607, 60.597474]

zoom — уровень приближения от 0 (весь мир) до 19 (максимальная детализация):​

• 0-5: континенты и страны

• 6-9: регионы и области

• 10-13: города

• 14-16: районы и улицы

• 17-19: отдельные здания​

Дополнительные параметры:

var myMap = new ymaps.Map("map", {
    center: [55.76, 37.64],
    zoom: 12,
    type: 'yandex#map', // Тип карты: схема, спутник, гибрид
    controls: ['zoomControl', 'searchControl'] // Элементы управления
}, {
    searchControlProvider: 'yandex#search' // Провайдер поиска
});

Типы карт:

• yandex#map — схема (по умолчанию)

• yandex#satellite — спутниковые снимки

• yandex#hybrid — гибрид (спутник + названия)​

Добавление метки (Placemark)

Создайте метку и добавьте её на карту:​

ymaps.ready(init);

function init() {
    var myMap = new ymaps.Map("map", {
        center: [55.751244, 37.618423],
        zoom: 15
    });
    
    // Создание метки
    var myPlacemark = new ymaps.Placemark([55.751244, 37.618423], {
        // Подпись метки
        balloonContent: 'Это Красная площадь',
        hintContent: 'Красная площадь'
    }, {
        // Опции метки
        preset: 'islands#icon',
        iconColor: '#0095b6'
    });
    
    // Добавление метки на карту
    myMap.geoObjects.add(myPlacemark);
}

Параметры Placemark:

Первый аргумент — координаты метки [широта, долгота]​

Второй аргумент — свойства (properties):​

• balloonContent — HTML-контент всплывающего балуна при клике

• balloonContentHeader — заголовок балуна

• balloonContentBody — основное тело балуна

• balloonContentFooter — подвал балуна

• hintContent — текст подсказки при наведении​

Третий аргумент — опции (options):​

• preset — предустановленный стиль иконки

• iconColor — цвет иконки (HEX или название цвета)

• iconLayout — кастомная иконка

• draggable — можно ли перетаскивать метку​

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

API предлагает набор готовых иконок:

// Круглая цветная иконка
preset: 'islands#icon'
iconColor: '#ff0000'

// Иконка с точкой
preset: 'islands#dotIcon'
iconColor: '#00ff00'

// Иконка с кругом
preset: 'islands#circleIcon'
iconColor: '#0000ff'

// Иконка с изображением
preset: 'islands#homeIcon' // дом
preset: 'islands#workIcon' // офис
preset: 'islands#nightIcon' // ночь

Пример карты с несколькими метками:

ymaps.ready(init);

function init() {
    var myMap = new ymaps.Map("map", {
        center: [55.76, 37.64],
        zoom: 10
    });
    
    // Массив меток
    var placemarks = [
        {
            coords: [55.751244, 37.618423],
            hint: 'Красная площадь',
            balloon: '<strong>Красная площадь</strong><br>Главная площадь Москвы',
            preset: 'islands#redIcon'
        },
        {
            coords: [55.753215, 37.622504],
            hint: 'ГУМ',
            balloon: '<strong>ГУМ</strong><br>Торговый центр',
            preset: 'islands#blueIcon'
        },
        {
            coords: [55.752004, 37.617734],
            hint: 'Исторический музей',
            balloon: '<strong>Исторический музей</strong>',
            preset: 'islands#greenIcon'
        }
    ];
    
    // Добавление меток на карту
    placemarks.forEach(function(item) {
        var placemark = new ymaps.Placemark(item.coords, {
            hintContent: item.hint,
            balloonContent: item.balloon
        }, {
            preset: item.preset
        });
        
        myMap.geoObjects.add(placemark);
    });
}

Кастомные иконки меток

Для уникального дизайна создайте собственные иконки вместо стандартных.​

Использование изображений в качестве иконок

var myPlacemark = new ymaps.Placemark([55.751244, 37.618423], {
    hintContent: 'Наш офис'
}, {
    iconLayout: 'default#image',
    iconImageHref: 'images/custom-icon.png', // Путь к изображению
    iconImageSize: [40, 40], // Размер иконки [ширина, высота]
    iconImageOffset: [-20, -40] // Смещение иконки [x, y]
});

Параметры кастомной иконки:

iconImageHref — путь к файлу изображения (PNG, JPG, SVG)​

iconImageSize — размер иконки в пикселях [ширина, высота]​

iconImageOffset — смещение относительно координат точки:​

• `` — левый верхний угол иконки на координатах

• [-20, -40] — центр нижней части иконки на координатах (типично для pin-иконок)

Рекомендации по изображениям:

• Используйте PNG с прозрачным фоном для лучшего вида​

• Оптимальный размер 32×32 до 64×64 пикселей​

• Для Retina-дисплеев подготовьте изображения @2x (вдвое больше)​

• SVG-иконки масштабируются без потери качества​

HTML-контент в качестве иконки

Создайте иконку из HTML и CSS для максимальной гибкости:

var myPlacemark = new ymaps.Placemark([55.751244, 37.618423], {
    hintContent: 'Наш офис'
}, {
    iconLayout: 'default#imageWithContent',
    iconImageHref: 'images/pin.png',
    iconImageSize: [48, 48],
    iconImageOffset: [-24, -48],
    iconContentOffset: [15, 15],
    iconContent: '₽99' // Текст внутри иконки
});

Полностью кастомная HTML-иконка:

var MyIconLayout = ymaps.templateLayoutFactory.createClass(
    '<div class="custom-icon">' +
        '<div class="icon-content">$[properties.iconContent]</div>' +
    '</div>'
);

var myPlacemark = new ymaps.Placemark([55.751244, 37.618423], {
    hintContent: 'Наш офис',
    iconContent: '123' // Произвольный контент
}, {
    iconLayout: MyIconLayout,
    iconShape: {
        type: 'Circle',
        coordinates: [0, 0],
        radius: 30
    }
});

Добавьте CSS-стили для кастомной иконки:

.custom-icon {
    width: 60px;
    height: 60px;
    background: #ff6b6b;
    border-radius: 50%;
    border: 3px solid #fff;
    box-shadow: 0 2px 10px rgba(0,0,0,0.3);
    display: flex;
    align-items: center;
    justify-content: center;
}

.icon-content {
    color: #fff;
    font-size: 16px;
    font-weight: bold;
}

Работа с балунами и подсказками

Балуны (balloons) и подсказки (hints) отображают дополнительную информацию об объектах на карте.​

Настройка содержимого балуна

Балун появляется при клике на метку и может содержать любой HTML:

var myPlacemark = new ymaps.Placemark([55.751244, 37.618423], {
    balloonContentHeader: '<strong>Главный офис</strong>',
    balloonContentBody: 
        '<p>Адрес: Москва, Красная площадь, д.1</p>' +
        '<p>Телефон: +7 (495) 123-45-67</p>' +
        '<p>Режим работы: Пн-Пт 9:00-18:00</p>' +
        '<a href="/contacts">Подробнее</a>',
    balloonContentFooter: 'Парковка для клиентов'
});

Структура балуна:

• Header — заголовок (шапка балуна)

• Body — основное содержимое

• Footer — подвал (дополнительная информация внизу)​

Динамическое содержимое:

Загрузите контент балуна с сервера при открытии:​

var myPlacemark = new ymaps.Placemark([55.751244, 37.618423], {
    hintContent: 'Загрузка...'
});

myPlacemark.events.add('balloonopen', function (e) {
    var placemark = e.get('target');
    
    // AJAX-запрос к серверу
    fetch('/api/office-info/1')
        .then(response => response.json())
        .then(data => {
            placemark.properties.set('balloonContentBody', 
                `<h3>${data.name}</h3>
                 <p>${data.address}</p>
                 <p>Телефон: ${data.phone}</p>`
            );
        });
});

Подсказки (hints)

Подсказка появляется при наведении курсора на метку:​

var myPlacemark = new ymaps.Placemark([55.751244, 37.618423], {
    hintContent: 'Наведите для подробностей'
}, {
    hideIconOnBalloonOpen: false // Не скрывать иконку при открытии балуна
});

Отключение балуна или подсказки:

// Метка без балуна
var placemark = new ymaps.Placemark(coords, {}, {
    hasBalloon: false
});

// Метка без подсказки
var placemark = new ymaps.Placemark(coords, {}, {
    hasHint: false
});

Геокодирование: адреса в координаты

Геокодирование — преобразование текстового адреса в географические координаты (широту и долготу).​

Прямое геокодирование (адрес → координаты)

ymaps.ready(init);

function init() {
    var myMap = new ymaps.Map("map", {
        center: [55.76, 37.64],
        zoom: 10
    });
    
    // Геокодирование адреса
    var myGeocoder = ymaps.geocode('Москва, улица Льва Толстого, 16');
    
    myGeocoder.then(
        function (res) {
            // Получение первого результата
            var firstGeoObject = res.geoObjects.get(0);
            
            // Координаты найденного адреса
            var coords = firstGeoObject.geometry.getCoordinates();
            console.log('Координаты:', coords);
            
            // Добавление метки на карту
            var myPlacemark = new ymaps.Placemark(coords, {
                balloonContent: firstGeoObject.getAddressLine()
            });
            
            myMap.geoObjects.add(myPlacemark);
            myMap.setCenter(coords, 15);
        },
        function (err) {
            console.error('Ошибка геокодирования:', err);
        }
    );
}

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

ymaps.geocode('адрес', {
    results: 5, // Максимальное количество результатов
    kind: 'house', // Тип объекта: house, street, metro, district, locality
    boundedBy: myMap.getBounds(), // Ограничение области поиска
    strictBounds: true // Искать только в указанной области
}).then(function(res) {
    // Обработка результатов
});

Обработка множественных результатов:

ymaps.geocode('Москва, Арбат').then(function(res) {
    var geoObjects = res.geoObjects;
    
    console.log('Найдено результатов:', geoObjects.getLength());
    
    // Перебор всех найденных объектов
    geoObjects.each(function(obj) {
        console.log('Адрес:', obj.getAddressLine());
        console.log('Координаты:', obj.geometry.getCoordinates());
    });
});

Обратное геокодирование (координаты → адрес)

Получение адреса по координатам:

var coords = [55.751244, 37.618423];

ymaps.geocode(coords).then(function(res) {
    var firstGeoObject = res.geoObjects.get(0);
    
    // Полный адрес
    var address = firstGeoObject.getAddressLine();
    console.log('Адрес:', address);
    
    // Компоненты адреса
    var locality = firstGeoObject.getLocalities()[0]; // Город
    var thoroughfare = firstGeoObject.getThoroughfare(); // Улица
    var premise = firstGeoObject.getPremiseNumber(); // Номер дома
    
    console.log('Город:', locality);
    console.log('Улица:', thoroughfare);
    console.log('Дом:', premise);
});

Практический пример: геокодирование из формы

<form id="geocode-form">
    <input type="text" id="address-input" placeholder="Введите адрес">
    <button type="submit">Найти на карте</button>
</form>
<div id="map"></div>

<script>
ymaps.ready(init);

function init() {
    var myMap = new ymaps.Map("map", {
        center: [55.76, 37.64],
        zoom: 10
    });
    
    document.getElementById('geocode-form').addEventListener('submit', function(e) {
        e.preventDefault();
        
        var address = document.getElementById('address-input').value;
        
        ymaps.geocode(address).then(function(res) {
            var firstGeoObject = res.geoObjects.get(0);
            var coords = firstGeoObject.geometry.getCoordinates();
            
            // Очистка предыдущих меток
            myMap.geoObjects.removeAll();
            
            // Добавление новой метки
            var placemark = new ymaps.Placemark(coords, {
                balloonContent: firstGeoObject.getAddressLine()
            }, {
                preset: 'islands#redIcon'
            });
            
            myMap.geoObjects.add(placemark);
            myMap.setCenter(coords, 15);
            placemark.balloon.open();
        });
    });
}
</script>

Кластеризация меток

При отображении большого количества меток (50+) используйте кластеризацию для улучшения производительности и читаемости карты.​

Базовая кластеризация

ymaps.ready(init);

function init() {
    var myMap = new ymaps.Map("map", {
        center: [55.76, 37.64],
        zoom: 10
    });
    
    // Создание массива меток
    var myGeoObjects = [];
    
    for (var i = 0; i < 100; i++) {
        var coords = [
            55.7 + Math.random() * 0.15,
            37.5 + Math.random() * 0.3
        ];
        
        myGeoObjects[i] = new ymaps.Placemark(coords, {
            balloonContent: 'Метка №' + i
        });
    }
    
    // Создание кластеризатора
    var clusterer = new ymaps.Clusterer({
        preset: 'islands#invertedVioletClusterIcons',
        groupByCoordinates: false,
        clusterDisableClickZoom: false,
        clusterHideIconOnBalloonOpen: false,
        geoObjectHideIconOnBalloonOpen: false
    });
    
    // Добавление меток в кластеризатор
    clusterer.add(myGeoObjects);
    
    // Добавление кластеризатора на карту
    myMap.geoObjects.add(clusterer);
}

Параметры кластеризации

var clusterer = new ymaps.Clusterer({
    preset: 'islands#invertedBlueClusterIcons', // Цвет кластеров
    clusterNumbers: [10], // Размеры кластеров
    gridSize: 64, // Размер сетки в пикселях (влияет на группировку)
    groupByCoordinates: false, // Группировать по точным координатам
    hasBalloon: true, // Показывать балуны кластеров
    hasHint: true, // Показывать подсказки
    margin: 10, // Отступ от границ для группировки
    maxZoom: 15, // Максимальный zoom для кластеризации
    minClusterSize: 2, // Минимальное количество объектов для кластера
    showInAlphabeticalOrder: false, // Сортировка в балуне
    viewportMargin: 128, // Отступ от границ viewport
    zoomMargin: 0, // Отступ при auto-zoom
    clusterDisableClickZoom: false, // Отключить зум при клике
    clusterOpenBalloonOnClick: true // Открывать балун при клике
});

Доступные цвета кластеров:

• islands#invertedBlueClusterIcons — синий

• islands#invertedVioletClusterIcons — фиолетовый

• islands#invertedRedClusterIcons — красный

• islands#invertedOrangeClusterIcons — оранжевый

• islands#invertedGreenClusterIcons — зеленый​

Кастомизация внешнего вида кластеров

var clusterer = new ymaps.Clusterer({
    clusterIconLayout: 'default#pieChart', // Круговая диаграмма
    clusterIconPieChartRadius: 25, // Радиус диаграммы
    clusterIconPieChartCoreRadius: 15, // Радиус центра
    clusterIconPieChartStrokeWidth: 3 // Толщина обводки
});

Загрузка меток из JSON

Типичный сценарий: загрузка данных о филиалах с сервера:​

ymaps.ready(init);

function init() {
    var myMap = new ymaps.Map("map", {
        center: [55.76, 37.64],
        zoom: 10
    });
    
    // Загрузка данных с сервера
    fetch('/api/offices.json')
        .then(response => response.json())
        .then(data => {
            var placemarks = [];
            
            data.forEach(function(office) {
                var placemark = new ymaps.Placemark(
                    [office.lat, office.lon],
                    {
                        balloonContentHeader: office.name,
                        balloonContentBody: office.address + '<br>' + office.phone,
                        clusterCaption: office.name
                    },
                    {
                        preset: 'islands#blueIcon'
                    }
                );
                
                placemarks.push(placemark);
            });
            
            var clusterer = new ymaps.Clusterer();
            clusterer.add(placemarks);
            myMap.geoObjects.add(clusterer);
            
            // Auto-zoom к границам всех меток
            myMap.setBounds(clusterer.getBounds(), {
                checkZoomRange: true
            });
        });
}

Построение маршрутов

API позволяет строить маршруты между точками с учетом типа транспорта.​

Простой маршрут между двумя точками

ymaps.ready(init);

function init() {
    var myMap = new ymaps.Map("map", {
        center: [55.76, 37.64],
        zoom: 10
    });
    
    // Построение маршрута
    var multiRoute = new ymaps.multiRouter.MultiRoute({
        // Точки маршрута (можно задать координатами или адресами)
        referencePoints: [
            'Москва, метро Смоленская',
            'Москва, метро Арбатская'
        ]
    }, {
        // Опции маршрута
        boundsAutoApply: true, // Автоматически подстроить bounds карты
        routeActiveStrokeWidth: 6, // Толщина линии активного маршрута
        routeActiveStrokeColor: '#ff0000' // Цвет активного маршрута
    });
    
    // Добавление маршрута на карту
    myMap.geoObjects.add(multiRoute);
}

Выбор типа маршрута

var multiRoute = new ymaps.multiRouter.MultiRoute({
    referencePoints: [
        [55.751244, 37.618423],
        [55.753215, 37.622504]
    ],
    params: {
        // Тип маршрута
        routingMode: 'auto' // auto, masstransit, pedestrian
    }
});

Типы маршрутов:

• auto — автомобильный (по умолчанию)

• masstransit — общественный транспорт

• pedestrian — пешеходный​

Множественные точки маршрута

var multiRoute = new ymaps.multiRouter.MultiRoute({
    referencePoints: [
        'Москва, Красная площадь',
        'Москва, улица Тверская, 1',
        'Москва, метро Маяковская',
        'Москва, Белорусский вокзал'
    ]
}, {
    wayPointStartIconColor: '#00FF00', // Цвет стартовой точки
    wayPointFinishIconColor: '#FF0000', // Цвет конечной точки
    routeStrokeWidth: 5,
    routeStrokeColor: '#0000FF'
});

Получение информации о маршруте

var multiRoute = new ymaps.multiRouter.MultiRoute({
    referencePoints: ['Москва, Кремль', 'Москва, МГУ']
});

multiRoute.model.events.add('requestsuccess', function () {
    var activeRoute = multiRoute.getActiveRoute();
    
    // Общее расстояние в метрах
    var distance = activeRoute.properties.get('distance');
    console.log('Расстояние:', (distance.value / 1000).toFixed(1), 'км');
    
    // Время в пути в секундах
    var duration = activeRoute.properties.get('duration');
    var minutes = Math.round(duration.value / 60);
    console.log('Время в пути:', minutes, 'минут');
    
    // Количество сегментов маршрута
    var segments = activeRoute.getPaths().get(0).getSegments();
    console.log('Сегментов:', segments.getLength());
});

myMap.geoObjects.add(multiRoute);

Динамическое изменение маршрута

// Добавление промежуточной точки
multiRoute.model.setReferencePoints([
    'Москва, Кремль',
    'Москва, Арбат', // Новая точка
    'Москва, МГУ'
]);

// Изменение типа маршрута
multiRoute.model.setParams({
    routingMode: 'pedestrian'
}, true);

Работа с событиями

События позволяют реагировать на действия пользователя: клики, наведение, перемещение карты.​

Подписка на события

ymaps.ready(init);

function init() {
    var myMap = new ymaps.Map("map", {
        center: [55.76, 37.64],
        zoom: 10
    });
    
    // Событие клика на карту
    myMap.events.add('click', function (e) {
        var coords = e.get('coords');
        console.log('Клик по координатам:', coords);
        
        // Создание метки в месте клика
        var placemark = new ymaps.Placemark(coords, {
            balloonContent: 'Координаты: ' + coords[0].toFixed(6) + ', ' + coords[1].toFixed(6)
        });
        
        myMap.geoObjects.add(placemark);
    });
}

Основные события карты

// Изменение zoom
myMap.events.add('boundschange', function (e) {
    var newZoom = e.get('newZoom');
    var oldZoom = e.get('oldZoom');
    console.log('Zoom изменился с', oldZoom, 'на', newZoom);
});

// Начало перемещения карты
myMap.events.add('actionbegin', function (e) {
    console.log('Начало действия');
});

// Окончание перемещения карты
myMap.events.add('actionend', function (e) {
    console.log('Действие завершено');
});

// Изменение центра карты
myMap.events.add('boundschange', function (e) {
    var newCenter = myMap.getCenter();
    console.log('Новый центр:', newCenter);
});

События меток

var myPlacemark = new ymaps.Placemark([55.76, 37.64], {
    hintContent: 'Кликните на меня'
});

// Клик на метку
myPlacemark.events.add('click', function () {
    alert('Вы кликнули на метку!');
});

// Наведение на метку
myPlacemark.events.add('mouseenter', function () {
    myPlacemark.options.set('iconColor', '#ff0000');
});

// Уход курсора с метки
myPlacemark.events.add('mouseleave', function () {
    myPlacemark.options.set('iconColor', '#0095b6');
});

// Перетаскивание метки (если draggable: true)
myPlacemark.events.add('dragend', function (e) {
    var coords = e.get('target').geometry.getCoordinates();
    console.log('Новые координаты:', coords);
});

myMap.geoObjects.add(myPlacemark);

События балунов

myPlacemark.events.add('balloonopen', function () {
    console.log('Балун открылся');
});

myPlacemark.events.add('balloonclose', function () {
    console.log('Балун закрылся');
});

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

// Функция-обработчик
function onMapClick(e) {
    console.log('Клик!');
}

// Подписка
myMap.events.add('click', onMapClick);

// Отписка
myMap.events.remove('click', onMapClick);

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

API предоставляет набор стандартных элементов управления.​

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

var myMap = new ymaps.Map("map", {
    center: [55.76, 37.64],
    zoom: 10,
    controls: [] // Пустой массив = без элементов управления
});

// Добавление конкретных элементов
myMap.controls.add('zoomControl', {
    position: {
        right: 10,
        top: 50
    }
});

myMap.controls.add('searchControl', {
    options: {
        float: 'left'
    }
});

myMap.controls.add('trafficControl');
myMap.controls.add('typeSelector');
myMap.controls.add('fullscreenControl');
myMap.controls.add('geolocationControl');
myMap.controls.add('routeButtonControl');

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

• zoomControl — кнопки увеличения/уменьшения масштаба

• searchControl — поиск по карте

• trafficControl — отображение пробок

• typeSelector — переключатель типов карты (схема/спутник/гибрид)

• fullscreenControl — полноэкранный режим

• geolocationControl — определение местоположения пользователя

• routeButtonControl — построение маршрута

• rulerControl — линейка для измерения расстояний​

Позиционирование элементов

myMap.controls.add('zoomControl', {
    position: {
        top: 10,       // Отступ сверху
        left: 10,      // Отступ слева
        // right: 10,  // Или отступ справа
        // bottom: 10  // Или отступ снизу
    }
});

Кастомный элемент управления

var MyControl = function (options) {
    MyControl.superclass.constructor.call(this, options);
    this._$content = null;
};

ymaps.util.augment(MyControl, ymaps.collection.Item, {
    onAddToMap: function (map) {
        MyControl.superclass.onAddToMap.call(this, map);
        this._$content = $('<div class="my-control">Мой элемент</div>');
        this.getParent().getChildElement(this).then(function ($parentElement) {
            $parentElement.append(this._$content);
        }, this);
    },
    
    onRemoveFromMap: function (oldMap) {
        this._$content.remove();
        MyControl.superclass.onRemoveFromMap.call(this, oldMap);
    }
});

myMap.controls.add(new MyControl());

Оптимизация производительности

При работе с большими объемами данных важна оптимизация.​

Ленивая загрузка API

Загружайте API только когда пользователь доскроллил до карты:​

// Проверка видимости элемента
function isElementInViewport(el) {
    var rect = el.getBoundingClientRect();
    return rect.top < window.innerHeight && rect.bottom > 0;
}

// Загрузка API при скролле
var mapContainer = document.getElementById('map');
var apiLoaded = false;

window.addEventListener('scroll', function() {
    if (!apiLoaded && isElementInViewport(mapContainer)) {
        // Динамическое подключение скрипта
        var script = document.createElement('script');
        script.src = 'https://api-maps.yandex.ru/2.1/?apikey=КЛЮЧ&lang=ru_RU';
        script.onload = function() {
            ymaps.ready(init);
        };
        document.head.appendChild(script);
        
        apiLoaded = true;
    }
});

Отключение неиспользуемых функций

Загружайте только нужные модули:

<script src="https://api-maps.yandex.ru/2.1/?apikey=КЛЮЧ&load=package.map,package.geoObjects"></script>

Оптимизация кластеризации

Для очень большого количества меток (1000+):

var clusterer = new ymaps.Clusterer({
    gridSize: 128, // Увеличить размер сетки
    minClusterSize: 5, // Увеличить минимальный размер кластера
    hasBalloon: false, // Отключить балуны кластеров
    maxZoom: 12 // Ограничить максимальный zoom для кластеризации
});