Подключение JavaScript API Яндекс.Карт

project author

Если Вам понравился данный материал, поделитесь им с вашими друзьями в соц сетях


JavaScript API Яндекс.Карт - это набор JavaScript-компонентов, позволяющий размещать на страницах сайта или в веб-приложении интерактивные карты.

Компоненты размещены на серверах Яндекса и доступны для использования сразу после их загрузки на страницу.

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

Для этого необходимо добавить в заголовок head HTML-страницы строку следующего вида.

Подключение JavaScript API Яндекс.Карт

<head>
    ...
    <script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
    ...
</head>

Подключении API Яндекс.Карт возможно выполнить используя дополнительные параметры, которые будут описаны в таблице ниже, при этом URL будет иметь следующий вид:

https://api-maps.yandex.ru/<номер версии>/?lang=<идентификатор языка>&<дополнительные параметры>
т.е.
<script src="https://api-maps.yandex.ru/<номер версии>/?lang=<идентификатор языка>&<дополнительные параметры>" type="text/javascript"></script>

 

Параметры загрузки API

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

Параметр Описание
lang (*)

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

Локаль задается параметром lang:

lang=language_region

language — двузначный код языка. Указывается в формате ISO 639-1.

region — двузначный код страны. Указывается в формате ISO 3166-1.

На данный момент поддерживаются следующие локали:

  • lang=ru_RU;
  • lang=en_US;
  • lang=ru_UA;
  • lang=uk_UA;
  • lang=tr_TR

Параметр является обязательным.

указываем локализацию: lang=ru_RU

<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
        
apikey (*)

API-ключ. Используется только в платных версиях API.

coordorder

Порядок задания географических координат в функциях API, принимающих на вход пары значений: широта(ось Y) - долгота(ось X).

Возможные значения:

  • latlong — [широта, долгота]
  • longlat — [долгота, широта]

Значение по умолчанию: latlong.

указываем порядок задания географических координат: coordorder=latlong

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

Список загружаемых модулей.

Имена модулей перечисляются через запятую. Например, load=Map,Placemark,map.addon.balloon.

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

package.full оптимизирован таким образом, чтобы подгружать функциональность в момент ее фактического использования, поэтому в большинстве случаев нет необходимости настраивать параметр load.

Компоненты также можно загружать "по требованию", используя функцию require.

Значение по умолчанию: package.full.

mode

Режим загрузки API.

Возможные значения:

  • release - код API может быть загружен в упакованном виде для минимизации трафика и скорости исполнения в браузере.
  • debug - код API может быть загружен в виде исходного кода удобна для отладки JavaScript-компонентов, код всех загруженных компонентов доступен для просмотра. Кроме того, в этом режиме в консоль выводятся сообщения об ошибках и исключениях. При загрузке в упакованном виде (release) эти сообщения не выводятся.

Значение по умолчанию: release.

указываем режим загрузки API: mode=debug

<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU&mode=debug" type="text/javascript"></script>
        
ns

Пространство имен, в котором локализованы программные компоненты API. По умолчанию все объекты принадлежат пространству имен ymaps (например, ymaps.Map). Если при загрузке API указать ns=myNameSpace, то объекты будут доступны уже как myNameSpace.Map.

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

Вы можете задать пустое значение ns. В этом случае API не будет создавать объектов в глобальной области видимости, и доступ к функциональности API получит только функция, указанная в параметре onload.

Значение по умолчанию: ymaps.

создадим карту не указывая пространство имен, т.е. использую его значение по умолчанию ns=ymaps

<!--загружаем API-->
<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript"></script>
...
<script type="text/javascript">
var myMap;
// при успешной загрузке API выполняется соответствующая функция
ymaps.ready(function(){
    // создание экземпляра карты и его привязка к контейнеру с id="map"
    myMap = new ymaps.Map("map", {
        center: [55.75396, 37.620393], // центр карты
        zoom: 8, // коэффициент масштабирования
    });
}); // end ymaps.ready
</script>
        

теперь создадим карту указав собственное пространство имен, к примеру ns=myNameSpace

<!--загружаем API-->
<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU&ns=myNameSpace" type="text/javascript"></script>
...
<script type="text/javascript">
var myMap;
// при успешной загрузке API выполняется соответствующая функция
myNameSpace.ready(function(){
    // создание экземпляра карты и его привязка к контейнеру с id="map"
    myMap = new myNameSpace.Map("map", {
        center: [55.75396, 37.620393], // центр карты
        zoom: 8, // коэффициент масштабирования
    });
}); // end myNameSpace.ready
</script>
        
onload

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

Допускается использование вложенных пространств имён:

  • onload=myfunction
  • onload=myapp.dosmth

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

создадим карту вызвав функцию указанную при загрузки API onload=initMap

<!--загружаем API-->
<script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU&onload=initMap" type="text/javascript"></script>
...
<script type="text/javascript">
var myMap;
// выполняем функцию инициализации карты указанную при загрузки API onload=initMap
function initMap(ymaps) {
    myMap = new ymaps.Map("map", {
        center: [55.75396, 37.620393], // центр карты
        zoom: 8, // коэффициент масштабирования
    });
}
</script>
        
onerror Имя callback-функции, которая будет вызвана в случае ошибки загрузки API. В эту функцию в качестве аргумента будет передан объект, содержащий информацию об ошибке.

 


  Теги: API Яндекс.Карт