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

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

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

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

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

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

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

<script src="https://api-maps.yandex.ru/2.1/?apikey=<ваш API-ключ>&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) {
        // Нужно вручную добавить класс в пространство имен ymaps,
        // так как при использовании метода require()
        // этого не происходит.
        ymaps.Map = Map;
        var map = new ymaps.Map('map', { 
            center: [55.76, 37.64], 
            zoom: 10    
        });
        // Класс Placemark не добавлен в публичную область видимости.
        var placemark = new Placemark([55.55, 37.00]);
        map.geoObjects.add(placemark);
    });
}

Поскольку для работы загруженных модулей может потребоваться загрузка других модулей, функция 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('Кликните, чтобы добавить метку'));
});