--- metadata: - name: generator content: Diplodoc Platform v5.37.1 alternate: - https://yandex.ru/dev/jsapi-v1-1/doc/ru/dg/tasks/api-loading.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/jsapi-v1-1/doc/ru/llms.txt # Загрузка API Использовать методы API можно только после того, как его модули загружены в память. Загрузить API на веб-страницу можно двумя способами: - [полностью](https://yandex.ru/dev/jsapi-v1-1/doc/ru/dg/tasks/api-loading.md) - загружается весь API целиком (используется по умолчанию); - [по требованию](https://yandex.ru/dev/jsapi-v1-1/doc/ru/dg/tasks/api-loading.md) - загружается только специальный инициализирующий скрипт, сам API подгружается по требованию. {% note info %} О том, как отслеживать ошибки загрузки API, читайте в разделе [Обработка ошибок загрузки](https://yandex.ru/dev/jsapi-v1-1/doc/ru/dg/tasks/api-loading.md#how-to-catch-api-loading-errors). {% endnote %} Если карту требуется отобразить сразу после загрузки страницы, то следует воспользоваться [полной загрузкой](https://yandex.ru/dev/jsapi-v1-1/doc/ru/dg/tasks/api-loading.md). Если же при загрузке страницы в браузер API не используется, например, в случаях когда карта показывается только после того, как пользователь совершит какие-либо действия на странице, то следует использовать [загрузку по требованию](https://yandex.ru/dev/jsapi-v1-1/doc/ru/dg/tasks/api-loading.md). {% note alert %} В браузере Internet Explorer при загрузке страницы с картой, где [ломаные](https://yandex.ru/dev/jsapi-v1-1/doc/ru/dg/tasks/how-to-add-polyline.md) и [многоугольники](https://yandex.ru/dev/jsapi-v1-1/doc/ru/dg/tasks/how-to-add-polygon.md) создаются до события `window.onLoad`, возможно возникновение ошибки загрузки API. Ошибка вызвана тем, что браузер не может создать VML-элементы (с помощью которых отображается векторная графика), если на странице с картой не объявлено пространство имен `vml`. Для устранения ошибки добавьте объявление `vml` в корневой тег страницы: ```html ``` {% endnote %} {% note alert %} В стандартном браузере мобильной операционной системы Android и Apple iOS версии ниже 3.2 жест масштабирования над картой приводит к увеличению масштаба всей страницы средствами браузера. Для того, чтобы отключить обработку жеста масштабирования, необходимо добавить в тег `head` страницы следующий код: ```html ``` Подробнее см. описание метатега `viewport` в [Safari HTML Reference](http://developer.apple.com/safari/library/documentation/appleapplications/reference/safarihtmlref/articles/metatags.html). {% endnote %} # Полная загрузка {#how-to-load-full-api} Чтобы загрузить API целиком в момент загрузки страницы с картой никаких дополнительных действий производить не требуется: ```html ``` По окончании загрузки доступна вся функциональность API. # Загрузка по требованию {#how-to-load-api-on-demand} Чтобы получить возможность загружать API по требованию, а не в момент загрузки страницы, необходимо в URL скрипта загрузки добавить параметр `loadByRequire = 1`: ```html ``` В этом случае вместо API будет загружен специальный инициализирующий скрипт, дающий возможность подгрузить API в любой момент с помощью метода [YMaps.load()](https://yandex.ru/dev/jsapi-v1-1/doc/ru/ref/reference/ymaps.md#load). В метод передается функция-обработчик, которая будет вызвана по окончании загрузки API. Метод [YMaps.load()](https://yandex.ru/dev/jsapi-v1-1/doc/ru/ref/reference/ymaps.md#load) может быть вызван неограниченное количество раз. При первом вызове метода загружается API, затем вызывается обработчик. При последующих вызовах обработчик выполняется сразу же, то есть повторной загрузки API не происходит. Например, функцию создания карты можно вызвать следующим образом: ```javascript YMaps.load(init); ``` Предполагается, что функция с именем `init` уже существует и в ней определен скрипт, создающий карту: ```javascript function init () { // Создает экземпляр карты и привязывает его к созданному контейнеру var map = new YMaps.Map(YMaps.jQuery("#YMapsID")[0]); // Устанавливает центр и масштаб карты map.setCenter(new YMaps.GeoPoint(37.64, 55.76), 10); } ``` [Открыть пример в новом окне](https://yandex.github.io/mapsapi-examples-old/html/maploadbyrequire.html) ## Обработка ошибок загрузки {#how-to-catch-api-loading-errors} Для работы с JavaScript API 1.x ключи не требуются. С полученными ранее ключами API поддерживает работу, но новые ключи уже не выдаются. Если при подключении API был указан неправильный ключ, то с помощью стандартной JavaScript-функции `alert()`на экран будет выведено сообщение об ошибке "неправильный ключ": ```javascript ``` [Открыть пример в новом окне](https://yandex.github.io/mapsapi-examples-old/html/maploadapifault.html) Чтобы перекрыть это поведение и обрабатывать ошибки неудачной загрузки API самостоятельно, добавьте в строку подключения API параметр `onerror` с именем пользовательской функции-обработчика, например, `apifault`: ```javascript ``` При неудачной загрузке API будет вызвана пользовательская функция-обработчик, которая, например, выводит сообщение об ошибке не в окне, а в HTML-элементе: ```javascript // Пользовательская функция-обработчик ошибок загрузки API function apifault (err) { // Создает обработчик события window.onLoad // Отображает сообщение об ошибке в контейнере над картой window.onload = function () { var errorContainer = document.getElementById("error"); errorContainer.innerHTML = "При загрузке API произошел сбой. Сообщение об ошибке: \"" + err + "\""; errorContainer.style.display = ""; } } ``` {% note alert %} Функция, имя которой передается в параметре `onerror`, должна быть объявлена до загрузки API. {% endnote %} [Открыть пример в новом окне](https://yandex.github.io/mapsapi-examples-old/html/maploadapifaultcustom.html)