Документация
Справочник JavaScript API
2.1.64 (текущая версия)
collection
interactivityModel
Интерфейсы

Модульная система

API Яндекс.Карт разработан с использованием концепции модульности. Это позволяет настраивать API под конкретные задачи и предоставляет возможность регулировать объем загружаемого трафика.

В качестве модулей выступают отдельные именованные сущности, например, классы, статические объекты, функции. Список всех модулей API приведен в справочнике.

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

Примечание. Некоторые публичные модули не входят в package.full (например, overlay.Placemark). API загружает эти модули в момент их фактического использования. Как правило, такие сущности не имеют публичного конструктора. Они создаются специальными фабриками (например, объекты типа router.Route создаются маршрутизатором) либо посредством обращения по ключу к асинхронному хранилищу (например, overlay.storage). Инстанцировать такие объекты напрямую не рекомендуется, но возможность получить непосредственный конструктор в API представлена. Для этого необходимо явно указать имя модуля при подключении (в параметре load) либо через modules.require.

В целях минимизации объема трафика имеет смысл загрузить только необходимые модули. Это можно сделать двумя способами: при инициализации API или по требованию через функцию modules.require. Ниже подробно рассмотрены данные способы.

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

API предоставляет возможность добавлять в модульную систему новые модули и переопределять уже существующие.

Загрузка модулей при подключении API

Загружаемые модули задаются HTTP-параметром load в строке подключения API. Можно указать сразу несколько модулей, разделив их запятым. По умолчанию параметр load принимает значение package.full, то есть загружаются все основные модули, необходимые для работы API.

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

Загруженные модули будут включены в публичное пространство имен ymaps.

Если для работы заданных модулей требуются другие модули, то они будут загружены автоматически.

В песочнице продемонстрирован пример загрузки модулей через параметр load.

Загрузка модулей по требованию

Иногда требуется загрузить тот или иной модуль по требованию. Для этого предназначена функция modules.require:

if (!ymaps.Map) {
    ymaps.modules.require(['Map', 'Placemark'], function (Map, Placemark) {
         // Добавляем в глобальную область видимости класс вручную, так как при использовании метода require модульной системы этого не происходит.
        ymaps.Map = Map;
        var map = new ymaps.Map('map', { 
              center: [55.76, 37.64], 
              zoom: 10    
            }),
            // Класс Placemark не добавлен в публичную область видимости.
            placemark = new Placemark([55.55, 37.00]);
        map.geoObjects.add(placemark);
    })
    /* Метка не будет создана, поскольку класс Placemark не включен в ymaps.
    var newPlacemark = new ymaps.Placemark([55.50, 37.00]); 
    */
}

Поскольку для работы заданных модулей может потребоваться загрузка других модулей, функция modules.require поддерживает работу в асинхронном режиме. Когда данные, необходимые для работы указанных модулей, будут подготовлены, она вызовет callback-функцию с загруженными модулями.

Пример загрузки модулей по требованию приведен в песочнице.

Подключение аддонов

Отображение балуна и хинта геообъекта осуществляется с помощью полей balloon и hint класса GeoObject. Для инициализации этих полей необходимо подключить модули geoObject.addon.balloon и geoObject.addon.hint. Если требуется открыть балун или хинт, принадлежащие карте, необходимо подключить соответственно модули map.addon.balloon и map.addon.hint.

Если необходима возможность редактирования геометрии геообъекта, следует подключить geoObject.addon.editor.

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

Создание собственных модулей

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

Декларация модуля производится с помощью метода modules.define. Пример декларации и использования собственного модуля можно посмотреть в песочнице.

Декларация модулей может быть совершена до вызова обработчика ymaps.ready.

После того как модуль задекларирован в модульной системе, его можно использовать в приложении.

Примечание. Пользовательские модули не добавляются автоматически в общее пространство имен с модулями API. Доступ к объявленному модулю можно получить через асинхронный метод modules.require, который вернет объект-promise.

ymaps.modules.require(['PlacemarkButton'])
  .spread(function (PlacemarkButton) {
    myMap.controls.add(new PlacemarkButton('Кликните, чтобы добавить метку'));
});