Загрузка API

Использовать методы API можно только после того, как его модули загружены в память. Загрузить API на веб-страницу можно двумя способами:

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

Примечание

О том, как отслеживать ошибки загрузки API, читайте в разделе Обработка ошибок загрузки.

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

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

Внимание

В браузере Internet Explorer при загрузке страницы с картой, где ломаные и многоугольники создаются до события window.onLoad, возможно возникновение ошибки загрузки API. Ошибка вызвана тем, что браузер не может создать VML-элементы (с помощью которых отображается векторная графика), если на странице с картой не объявлено пространство имен vml. Для устранения ошибки добавьте объявление vml в корневой тег страницы:

<html xmlns:vml="urn:schemas-microsoft-com:vml">

Внимание

В стандартном браузере мобильной операционной системы Android и Apple iOS версии ниже 3.2 жест масштабирования над картой приводит к увеличению масштаба всей страницы средствами браузера. Для того, чтобы отключить обработку жеста масштабирования, необходимо добавить в тег head страницы следующий код:

<meta name="viewport" content="initial-scale=1.0, user-scalable=no, maximum-scale=1" />

Подробнее см. описание метатега viewport в Safari HTML Reference.

Полная загрузка

Чтобы загрузить API целиком в момент загрузки страницы с картой никаких дополнительных действий производить не требуется:

<script src="https://api-maps.yandex.ru/1.1/index.xml" type="text/javascript"></script>

По окончании загрузки доступна вся функциональность API.

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

Чтобы получить возможность загружать API по требованию, а не в момент загрузки страницы, необходимо в URL скрипта загрузки добавить параметр loadByRequire = 1:

<script src="https://api-maps.yandex.ru/1.1/index.xml?loadByRequire=1" type="text/javascript"></script>

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

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

Например, функцию создания карты можно вызвать следующим образом:

YMaps.load(init);

Предполагается, что функция с именем init уже существует и в ней определен скрипт, создающий карту:

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

    // Устанавливает центр и масштаб карты
    map.setCenter(new YMaps.GeoPoint(37.64, 55.76), 10);
}

Открыть пример в новом окне

Обработка ошибок загрузки

Для работы с JavaScript API 1.x ключи не требуются. С полученными ранее ключами API поддерживает работу, но новые ключи уже не выдаются.

Если при подключении API был указан неправильный ключ, то с помощью стандартной JavaScript-функции alert()на экран будет выведено сообщение об ошибке "неправильный ключ":

<script src="https://api-maps.yandex.ru/1.1/index.xml?key=abcd" type="text/javascript"></script>

Открыть пример в новом окне

Чтобы перекрыть это поведение и обрабатывать ошибки неудачной загрузки API самостоятельно, добавьте в строку подключения API параметр onerror с именем пользовательской функции-обработчика, например, apifault:

<script src="https://api-maps.yandex.ru/1.1/index.xml?onerror=apifault" type="text/javascript"></script>

При неудачной загрузке API будет вызвана пользовательская функция-обработчик, которая, например, выводит сообщение об ошибке не в окне, а в HTML-элементе:

// Пользовательская функция-обработчик ошибок загрузки API
function apifault (err) {
    // Создает обработчик события window.onLoad
    // Отображает сообщение об ошибке в контейнере над картой
    window.onload = function () {
        var errorContainer = document.getElementById("error");
        errorContainer.innerHTML = "При загрузке API произошел сбой. Сообщение об ошибке: \"" + err + "\"";
        errorContainer.style.display = "";
    }
}

Внимание

Функция, имя которой передается в параметре onerror, должна быть объявлена до загрузки API.

Открыть пример в новом окне

Предыдущая
Основы
Следующая
Создание карты