uk en pl it
Web Monarx
BACK NEXT

Основные сведения о Google Maps JavaScript API V3


Примечание. Пакет Google Maps javascript API V3, описание которого приводится на этих страницах, теперь имеет статус официального javascript API. В соответствии с правилами версия 2 этого API является официально устаревшей. Рекомендуем перевести свой код на обновленную и улучшенную версию.

Представляем обновленный и официальный пакет Google Maps javascript API V3! Этот API официально пришел на замену пакета Google Maps javascript API V2. Внешне эти версии очень похожи, но внутри многое изменилось: версия 3 (для краткости обозначаемая как V3 в этом документе) оптимизирована для быстрой загрузки, особенно в мобильных браузерах таких устройств, как iPhone™ и смартфоны на платформе Android.

Мы будем рады получить ваши отзывы и комментарии об этой версии в группе обсуждения Google Maps API V3.

  1. Представляем API версии 3
  2. Аудитория
  3. Геопозиционирование
    1. Определение местоположения пользователя
    2. Определение параметров датчика
  4. Разработка приложений для мобильных устройств (iPhone и устройств на платформе Android)
  5. Локализация в Maps API V3
  6. Библиотеки в Maps API V3
  7. Загрузка API по протоколу HTTPS (Новинка!)
  8. Асинхронная загрузка API
  9. Версии
    1. Типы версий
    2. История версий
  10. Устранение неполадок

Представляем API версии 3

Представляем версию 3 Google Maps API. Этот javascript API внешне схож с существующей версией 2 Google Maps API. Однако многое изменилось внутри: версия 3 оптимизирована для быстрой загрузки, особенно в мобильных браузерах таких устройств, как iPhone™ и смартфоны на платформе Android. В первоначальном выпуске доступен сокращенный набор функций по сравнению с API версии 2. Мы работаем над переносом дополнительных функций из версии 2, а также над сохранением небольшого размера кода javascript и оптимизированной скоростью загрузки. Мы будем рады получить ваши отзывы и комментарии об этой версии в группе обсуждения Google Maps API V3.

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

Особо следует отметить интеграцию в этот API надежной и быстрой загрузки карт. Рекомендуем проверить работу этого API на мобильных устройствах и сообщить о проблемах, возникших с определенными устройствами, в указанной выше группе.

Примечание. Для этой версии Google Maps javascript API больше не нужны ключи API!

Аудитория

Данная документация предназначена для пользователей, имеющих навыки работы с javascript и знакомых с принципами объектно-ориентированного программирования. Следует также знать, что такое Google Maps с точки зрения пользователя. В Интернете доступно большое количество руководств по javascript.

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

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

  • Базовые объекты карт
  • События карт
  • Элементы управления карт
  • Наложенная графика карт
  • Службы карт

Будем рады получить отзывы об этой версии API и документации. Отправляйте свои отзывы в группу обсуждения Google Maps javascript API V3.

Геопозиционирование

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

Определение местоположения пользователя

В настоящее время существует несколько способов определения в браузере местоположения пользователя. Ни один из этих методов не входит в Google Maps API. Фактически это распространенные отраслевые стандарты.

  • Более новые браузеры уже начинают поддерживать стандарт W3C Geolocation. Этот стандарт является частью HTML5 и, скорее всего, станет стандартом де-факто. Все приложения, которые используют геопозиционирование, должны его поддерживать.
  • Некоторые браузеры с поддержкой Google Gears могут использовать службу Google Gears Geolocation API. Поскольку стандарт W3C пока не получил большого распространения, проверка наличия Gears – неплохой резервный механизм.
  • Некоторые браузеры используют для определения местоположения пользователя IP-адрес, но этот метод не отличается высокой точностью.

Поскольку местоположение пользователя по IP-адресу определяется очень приблизительно, использовать этот подход для геопозиционирования не рекомендуется. W3C – это самый простой и наиболее полно поддерживаемый способ, поэтому прежде всего следует рассматривать его. Если вы решите использовать Google Gears, то предварительно нужно проверить, поддерживает ли браузер стандарт W3C (Обратите внимание, что использование Google Gears потребует загрузки кода javascript для инициализации Gears).

В следующем примере делается попытка определить местоположение пользователя сначала через свойство W3C navigator.geolocation, а затем через Google Gears. Если ни один из методов не срабатывает, выдается сообщение об ошибке.

// Note that using Google Gears requires loading the javascript
// at http://code.google.com/apis/gears/gears_init.js

var initialLocation;
var siberia = new google.maps.LatLng(60, 105);
var newyork = new google.maps.LatLng(40.69847032728747, -73.9514422416687);
var browserSupportFlag =  new Boolean();

function initialize() {
 
var myOptions = {
    zoom
: 6,
    mapTypeId
: google.maps.MapTypeId.ROADMAP
 
};
 
var map = new google.maps.Map(document.getElementById("map_canvas"), myOptions);
 
 
// Try W3C Geolocation (Preferred)
 
if(navigator.geolocation) {
    browserSupportFlag
= true;
    navigator
.geolocation.getCurrentPosition(function(position) {
      initialLocation
= new google.maps.LatLng(position.coords.latitude,position.coords.longitude);
      map
.setCenter(initialLocation);
   
}, function() {
      handleNoGeolocation
(browserSupportFlag);
   
});
 
// Try Google Gears Geolocation
 
} else if (google.gears) {
    browserSupportFlag
= true;
   
var geo = google.gears.factory.create(\'beta.geolocation\');
    geo
.getCurrentPosition(function(position) {
      initialLocation
= new google.maps.LatLng(position.latitude,position.longitude);
      map
.setCenter(initialLocation);
   
}, function() {
      handleNoGeoLocation
(browserSupportFlag);
   
});
 
// Browser doesn\'t support Geolocation
 
} else {
    browserSupportFlag
= false;
    handleNoGeolocation
(browserSupportFlag);
 
}
 
 
function handleNoGeolocation(errorFlag) {
   
if (errorFlag == true) {
      alert
("Geolocation service failed.");
      initialLocation
= newyork;
   
} else {
      alert
("Your browser doesn\'t support geolocation. We\'ve placed you in Siberia.");
      initialLocation
= siberia;
   
}
    map
.setCenter(initialLocation);
 
}
}

Просмотреть пример (map-geolocation.php)

Определение параметров датчика

При использовании Google Maps API требуется указывать, используется ли в приложении датчик (например, устройство GPS) для определения местоположения пользователя. Это особенно актуально для мобильных устройств. При добавлении кода javascript из Maps API приложения должны передавать обязательный параметр sensor в тег <script>, тем самым указывая, использует ли приложение устройство с датчиком.

Приложения, определяющие местоположение пользователя по датчику, должны передавать значение sensor=true при загрузке кода javascript Maps API.

#
# Example using sensor when loading the Maps javascript API
#
<script type="text/javascript" src="https://maps.google.com/maps/api/js?sensor=true"></script>

Обратите внимание, что даже если в приложении не используется датчик местоположения, все равно нужно указывать этот параметр, присваивая ему значение false.

Разработка приложений для мобильных устройств (iPhone и устройств на платформе Android)

Google Maps API V3 разработан для быстрой загрузки и успешной работы в мобильных устройствах. В частности, мы уделили особое внимание разработке приложений для современных мобильных устройств, таких как iPhone и смартфоны на платформе Android. Размер экрана мобильных устройств гораздо меньше, чем у обычного компьютера. Кроме того, в них реализуется особое поведение (например, функция масштабирования двумя пальцами Pinch-to-zoom в iPhone). Чтобы приложение работало на мобильных устройствах должным образом, мы рекомендуем выполнить следующие действия.

  • Для содержащего карту элемента <div> в качестве значения атрибутов width и height установите 100%. Примите во внимание, что некоторые браузеры более ранних версий на ПК могут неправильно работать с этими значениями.

  • iPhone и устройства на платформе Android можно определить по свойству navigator.userAgent объекта DOM:

    function detectBrowser() {
     
    var useragent = navigator.userAgent;
     
    var mapdiv = document.getElementById("map_canvas");
       
     
    if (useragent.indexOf(\'iPhone\') != -1 || useragent.indexOf(\'Android\') != -1 ) {
        mapdiv
    .style.width = \'100%\';
        mapdiv
    .style.height = \'100%\';
     
    } else {
        mapdiv
    .style.width = \'600px\';
        mapdiv
    .style.height = \'800px\';
     
    }
    }

    Благодаря этому можно изменять дизайн страницы для определенных устройств. В этом примере представлен вариант изменения полезной площади экрана для всех устройств.

  • iPhone учитывает содержание следующего тега <meta>:

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

    В этом теге указано, что карта должна быть показана в полноэкранном режиме и ее размер не может быть изменен пользователем. Устройства на платформе Android версии 1.5 (Cupcake) также поддерживают эти параметры. Обратите внимание, что для браузера Safari в iPhone нужно включить тег <meta> в элемент страницы <head>.

Подробнее о разработке приложений для iPhone рассказано в документации для разработчиков Apple. Подробнее о разработке приложений для устройств на платформе Android рассказано в документации по Android.

Локализация в Maps API V3

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

Локализация по языку

Google Maps API использует параметр предпочтительного языка в браузере при выводе текста (названий элементов управления, уведомлений об авторском праве, маршрутов и меток на карте). В большинстве случаев этот способ предпочтителен; не рекомендуется переопределять языковые настройки, которые задал пользователь. Но если нужно, чтобы Maps API игнорировал языковые настройки браузера и выдавал информацию на определенном языке, можно при включении кода javascript Maps API добавить необязательный параметр language в тег <script>, указав нужный язык.

Например, чтобы приложение Maps API отображалось на японском языке, добавьте код &language=ja в тег <script>, как показано ниже.

<script type="text/javascript" src="https://maps.google.com/maps/api/js?sensor=false&language=ja">

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

Просмотреть пример (map-language.php)

Maps javascript API поддерживает также двунаправленный (Bidi) текст, который содержит символы языков с написанием как слева направо (LTR), так и справа налево (RTL). Примерами языков RTL являются арабский, иврит и фарси. Как правило, чтобы страница на языке RTL отображалась правильно, добавляется dir=\'rtl\' в элемент <html> этой страницы. В следующем примере выводится карта Каира (Египет) с помощью арабских элементов управления:

Просмотреть пример (map-rtl.php)

См. также список поддерживаемых языков. Обратите внимание, что список языков может быть неполным.

Локализация по региону

По умолчанию Maps API обрабатывает фрагменты и привязки для страны несущего домена, из которой загружается API (например, для maps.google.com это США). Если приложение должно работать с другими фрагментами карты и привязками (например, с привязкой результатов геокодирования к региону), то при включении кода javascript Maps API можно переопределить поведение по умолчанию, добавив параметр region к тегу <script>.

Параметр region принимает идентификаторы вложенных тегов регионов Юникода, которые обычно один к одному соответствуют доменам верхнего уровня для кодов стран (ccTLD). Большинство идентификаторов регионов Юникода идентичны кодам ISO 3166-1 с некоторыми существенными исключениями. Например, ccTLD Великобритании – uk (соответствует домену .co.uk), а идентификатор региона – GB.

Чтобы локализовать приложение Maps API для Великобритании, нужно добавить &region=GB в тег <script>, как показано ниже:

<script type="text/javascript" src="https://maps.google.com/maps/api/js?sensor=false&region=GB">

В следующем примере показано две карты, одна с геокодированием "Толедо" для региона по умолчанию (США), т. е. "Толедо, Огайо", а вторая – с привязкой результатов к коду region, заданному в ES (Испания), т. е. "Толедо, Испания".

 

Библиотеки в Maps API V3

Код javascript для Maps API загружается с помощью URL начального этапа, имеющего следующий формат: http://maps.google.com/maps/api/js. Запрос начального этапа загружает все главные объекты и символы javascript, которые используются в Maps API. Некоторые компоненты Maps API также доступны в автономных библиотеках, для загрузки которых требуется отправить специальный запрос. Благодаря тому что вспомогательные элементы вынесены в библиотеки, загрузка (и синтаксический анализ) API выполняется быстро. Загрузка и синтаксический анализ библиотек осуществляются только по необходимости.

Для загрузки дополнительных библиотек в запросе начального этапа следует указать параметр libraries, передав ему название одной или нескольких библиотек. Названия библиотек в запросе разделяются запятой. Для доступа к загруженным библиотекам используется пространство имен google.maps.libraryName.

Ниже перечислены библиотеки, доступные в настоящее время.

  • geometry включает в себя вспомогательные функции для расчета скалярных геометрических значений (например, расстояния и площади) на поверхности земли. Подробнее см. в документации по библиотеке Geometry.
  • adsense позволяет включать в приложение на основе Maps API контекстные текстовые объявления для распределения дохода от показа рекламы пользователям. Подробнее см. в документации по библиотеке AdSense.
  • panoramio содержит функции для добавления слоев фотографий из Panoramio в приложение на основе Maps API. Подробнее см. в документации по слоям Panoramio.

По мере выпуска дополнительных функций количество библиотек будет увеличиваться.

Следующий запрос начального этапа показывает, как запросить библиотеку google.maps.geometry из Maps javascript API:

<script type="text/javascript" src="https://maps.google.com/maps/api/js?libraries=geometry&sensor=true_or_false"></script>

Загрузка API по протоколу HTTPS

Доступ к Google Maps javascript API можно осуществлять по протоколу HTTPS, что позволяет работать с ним в приложениях, использующих этот защищенный протокол. Чтобы загрузить Google Maps javascript API Version 3 по протоколу HTTPS, загрузите API с помощью следующего URL:

<script src="https://maps-api-ssl.google.com/maps/api/js?v=3&sensor=true_or_false"
type="text/javascript"></script>

Загрузив Google Maps javascript API V3 по HTTPS, вы сможете работать с Maps API на страницах, использующих этот безопасный протокол (HTTP over the Secure Socket Layer (SSL)). Загрузка Maps API по HTTPS поможет избежать появления предупреждений при работе с SSL-приложениями в большинстве браузеров. Кроме того, этот протокол рекомендуется использовать, если приложение передает в запросах конфиденциальные данные пользователей (например, данные о местоположении).

Асинхронная загрузка javascript API

Обычно javascript Maps API следует загружать одновременно со страницей. Для этого API нужно включить в тег <script>, чтобы код javascript выполнялся после загрузки скрипта. Однако во время синтаксического анализа этого кода javascript браузер не сможет отображать дополнительное содержание на странице. В большинстве случаев такая задержка незаметна. Тем не менее, существует возможность загрузить javascript-код Maps API после того, как загрузка страницы будет завершена. Загрузку javascript-кода Maps API также можно осуществлять по запросу.

Чтобы загрузить Maps javascript API после того, как завершится загрузка страницы, вставьте тег <script> в качестве ответа на событие window.onload. Кроме того, в запросе Maps javascript API начального этапа нужно указать, что перед выполнением кода вашего приложения следует дождаться полной загрузки Maps javascript API. Для этого используется параметр callback. В качестве аргумента он принимает функцию, которую следует выполнить после завершения загрузки API.

В приведенном ниже фрагменте кода приложение получает указание загрузить Maps API после полной загрузки страницы (с помощью window.onload) и записать Maps javascript API в тег <script> на этой странице. Кроме того, API выполнит функцию initialize() только после того, как будет полностью загружен. Для этого на начальном этапе передается параметр callback=initialize.

function initialize() {
 
var myLatlng = new google.maps.LatLng(-34.397, 150.644);
 
var myOptions = {
    zoom
: 8,
    center
: myLatlng,
    mapTypeId
: google.maps.MapTypeId.ROADMAP
 
}
 
var map = new google.maps.Map(document.getElementById("map_canvas"), myOptions);
}
 
function loadScript() {
 
var script = document.createElement("script");
  script
.type = "text/javascript";
  script
.src = "http://maps.google.com/maps/api/js?sensor=false&callback=initialize";
  document
.body.appendChild(script);
}
 
window
.onload = loadScript;

Просмотреть пример (map-simple-async.php)

Версии

Команда Google Maps API регулярно внедряет в javascript API новые функции, исправления и средства повышения эффективности. Все изменения в API имеют обратную совместимость. Таким образом, если приложение создается на основе текущих документированных интерфейсов, оно будет работать и после обновления API. (Примечание. На экспериментальные функции эта гарантия не распространяется. Экспериментальные функции четко помечены в документации по API.)

Типы версий

Указать, какая версия API должна загружаться в приложении, можно с помощью параметра v в запросе начальной загрузки Maps javascript API. В настоящее время существует два варианта:

  • Ночная (разрабатываемая) версия, которая указывается как v=3 или путем исключения параметра v. Эта версия отражает все последние изменения, исправления и новые функции, выпущенные для общего использования.
  • Версия с номером, которая указывается как v=3.number и определяет набор компонентов API. Такая версия может быть версией выпуска или стандартизированной версией. (См. ниже.)

Следующий запрос начальной загрузки показывает, как запросить конкретную версию Maps javascript API:

http://maps.google.com/maps/api/js?v=3.3&sensor=true_or_false

Раз в квартал выходит новая версия с номером для открытого использования. В течение квартала разработчики исправляют ошибки, найденные в этой версии (что отмечается в истории изменений Maps javascript API), но набор компонентов не изменяется.

Когда выходит очередная версия с номером, предыдущая версия с номером стандартизируется. Это означает, что в ней больше не будет обновляться код, не будут вноситься исправления, и можно быть полностью уверенным в стабильности такой версии. При этом существующая на тот момент стандартизированная версия устаревает. Таким образом, существует только одна стандартизированная версия. Если приложение запрашивает устаревшую версию с номером, ему будет автоматически предоставлена текущая стандартизированная версия.

Выбор версии API

При выборе версии API, подходящей для вашего приложения на основе Maps API V3, руководствуйтесь следующим:

  • Для производственных приложений следует всегда указывать дополнительный номер версии API (например, 3.6, 3.7 и т. д.).
  • Соглашение об уровне обслуживания для Maps API Premier не распространяется на текущую ночную (разрабатываемую) версию. В приложениях на основе Maps API Premier необходимо использовать текущую версию выпуска или более раннюю версии, на которые распространяется действие соглашения об уровне обслуживания.
  • При создании нового приложения на основе Maps API v3 рекомендуется выбирать последнюю ночную версию по номеру (например, 3.5) и затем использовать ее до тех пор, пока не потребуются дополнительные функции, присутствующие в более поздней версии. При таком подходе используемая вашим приложением версия будет совершенствоваться, станет версией выпуска, а затем и стандартизированной версией.
  • Производственные приложения, работающие с текущей или более ранней стандартизированной версией, должны ежеквартально проверяться на предмет совместимости с последней версией выпуска для выявления проблем обратной совместимости этой версии до ее стандартизации.

История версий

В истории всегда отражается ночная (разрабатываемая) версия. Тем не менее, для каждой версии существует отдельный справочник.

  • Справочник по ночной версии (3.8) (текущая)
  • Справочник по версии выпуска (3.7) (стабильная)
  • Справочник по версии выпуска (3.6) (стандартизированная)
  • Версии 3.0 - 3.5 являются устаревшими.

Устранение неполадок

Несколько подходов, которые могут помочь, если код не работает:

  • Убедитесь в отсутствии опечаток. Не забывайте, что в javascript учитывается разница между верхним и нижним регистром.
  • Используйте отладчик javascript. В Firefox можно использовать консоль javascript, Venkman Debugger и дополнение Firebug. В Internet Explorer можно использовать Microsoft Script Debugger. В этих видеороликах показано использование различных инструментов отладки.
  • Отправляйте свои вопросы в группу обсуждения Google Maps API V3.

Сайт является частным собранием материалов и представляет собой любительский информационно-образовательный ресурс. Вся информация получена из открытых источников. Администрация не претендует на авторство использованных материалов. Все права принадлежат их правообладателям