Обновление приложения Maps JavaScript API с версии 2 до версии 3

Maps JavaScript API v2 больше не доступен с 26 мая 2021 г. В результате карты v2 вашего сайта перестанут работать и будут возвращать ошибки JavaScript. Чтобы продолжить использовать карты на своем сайте, перейдите на Maps JavaScript API v3. Это руководство поможет вам в этом процессе.

Обзор

Каждое приложение будет иметь несколько иной процесс миграции; однако есть некоторые шаги, общие для всех проектов:

  1. Получить новый ключ. Maps JavaScript API теперь использует Google Cloud Console для управления ключами. Если вы все еще используете ключ v2, обязательно получите новый ключ API перед началом миграции.
  2. Обновите загрузочный API. Большинство приложений загружают Maps JavaScript API версии 3 со следующим кодом:
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
  3. Обновите свой код. Количество требуемых изменений будет во многом зависеть от вашего приложения. Общие изменения включают в себя:
    • Всегда ссылайтесь на пространство имен google.maps. В версии 3 весь код Maps JavaScript API хранится в пространстве имен google.maps.* , а не в глобальном пространстве имен. Большинство объектов также были переименованы в рамках этого процесса. Например, вместо GMap2 теперь вы будете загружать google.maps.Map .
    • Удалите любые ссылки на устаревшие методы. Был удален ряд служебных методов общего назначения, таких как GDownloadURL и GLog . Либо замените эту функциональность сторонними служебными библиотеками, либо удалите эти ссылки из своего кода.
    • (Необязательно) Добавьте библиотеки в свой код. Многие функции были реализованы в служебных библиотеках, так что каждому приложению нужно будет загружать только те части API, которые будут использоваться.
    • (Необязательно) Настройте свой проект для использования внешних модулей версии 3. Внешние модули v3 можно использовать для проверки кода с помощью компилятора Closure или для запуска автозаполнения в вашей среде IDE. Узнайте больше о Advanced Compilation и Externs .
  4. Тестируйте и повторяйте. На этом этапе вам еще предстоит проделать определенную работу, но хорошая новость заключается в том, что вы уже на пути к своему новому картографическому приложению версии 3!

Изменения в версии 3 Maps JavaScript API

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

Некоторые изменения в v3 API включают:

  • Оптимизированная основная библиотека. Многие дополнительные функции были перенесены в библиотеки , что помогает сократить время загрузки и анализа для Core API, что позволяет вашей карте быстро загружаться на любом устройстве.
  • Улучшена производительность некоторых функций, таких как рендеринг полигонов и размещение маркеров.
  • Новый подход к ограничениям использования на стороне клиента для лучшего соответствия общим адресам, используемым мобильными прокси-серверами и корпоративными брандмауэрами.
  • Добавлена ​​поддержка нескольких современных браузеров и мобильных браузеров. Удалена поддержка Internet Explorer 6.
  • Удалены многие вспомогательные классы общего назначения ( GLog или GDownloadUrl ). Сегодня существует множество отличных библиотек JavaScript, предоставляющих аналогичные функции, например Closure или jQuery .
  • Реализация просмотра улиц HTML5, которая будет загружаться на любом мобильном устройстве.
  • Пользовательские панорамы просмотра улиц с вашими собственными фотографиями, позволяющие вам делиться панорамами лыжных трасс, выставленных на продажу домов или других интересных мест.
  • Настройки Styled Maps , которые позволяют изменять отображение элементов на базовой карте в соответствии с вашим уникальным визуальным стилем.
  • Поддержка нескольких новых сервисов, таких как ElevationService и Distance Matrix .
  • Усовершенствованные службы маршрутов предоставляют альтернативные маршруты, оптимизацию маршрутов (приблизительные решения задачи коммивояжёра ), велосипедные маршруты (с велосипедным слоем ), транзитные маршруты и перетаскиваемые маршруты .
  • Обновленный формат геокодирования, предоставляющий более точную информацию о типе , чем значение accuracy из Geocoding API v2.
  • Поддержка нескольких информационных окон на одной карте

Обновление вашего приложения

Ваш новый ключ

Maps JavaScript API v3 использует новую систему ключей из v2. Возможно, вы уже используете ключ v3 в своем приложении, и в этом случае никаких изменений не требуется. Чтобы убедиться в этом, проверьте key параметр URL-адреса, с которого вы загружаете Maps JavaScript API. Если значение ключа начинается с «ABQIAA», вы используете ключ v2. Если у вас есть ключ v2, вы должны обновить его до ключа v3 в рамках миграции, которая:

Ключ передается при загрузке Maps JavaScript API v3. Узнайте больше о создании ключей API .

Обратите внимание: если вы являетесь клиентом Google Maps API for Work, вы можете использовать идентификатор клиента с параметром client вместо key параметра. Идентификаторы клиентов по-прежнему поддерживаются в Maps JavaScript API v3, и для них не нужно проходить процесс обновления ключа.

Загрузка API

Первая модификация, которую вам необходимо внести в свой код, касается того, как вы загружаете API. В версии 2 вы загружаете Maps JavaScript API через запрос на http://maps.google.com/maps . Если вы загружаете Maps JavaScript API версии 3, вам потребуется внести следующие изменения:

  1. Загрузите API с //maps.googleapis.com/maps/api/js
  2. Удалите параметр file .
  3. Обновите key параметр с помощью нового ключа v3. Клиенты Google Maps API for Work должны использовать client параметр.
  4. (Только для плана "Премиум" платформы Google Карт) Убедитесь, что параметр client указан в соответствии с инструкциями в Руководстве разработчика для плана "Премиум" платформы Google Карт .
  5. Удалите параметр v , чтобы запросить последнюю выпущенную версию, или измените его значение в соответствии со схемой управления версиями v3 .
  6. (Необязательно) Замените параметр hl на language и сохраните его значение.
  7. (Необязательно) Добавьте параметр libraries для загрузки дополнительных библиотек .

В простейшем случае загрузчик v3 будет указывать только ваш параметр ключа API:

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>

В приведенном ниже примере запрашивается последняя версия Maps JavaScript API v2 на немецком языке:

<script src="//maps.google.com/maps?file=api&v=2.x&key=YOUR_API_KEY&hl=de"></script>

Пример ниже является эквивалентным запросом для v3.

<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&language=de"></script>

Представляем пространство имен google.maps

Вероятно, наиболее заметным изменением в Maps JavaScript API v3 является введение пространства имен google.maps . API v2 по умолчанию помещает все объекты в глобальное пространство имен, что может привести к конфликтам имен. В версии 3 все объекты расположены в пространстве имен google.maps .

При переносе вашего приложения на версию 3 вам придется изменить свой код, чтобы использовать новое пространство имен. К сожалению, поиск "G" и замена на "google.maps". не будет полностью работать; но это хорошее эмпирическое правило, которое следует применять при просмотре кода. Ниже приведены некоторые примеры эквивалентных классов в v2 и v3.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
or google.maps.PolylineOptions

Удаление устаревшего кода

Maps JavaScript API версии 3 имеет параллели по большинству функций версии 2; однако некоторые классы больше не поддерживаются. В рамках миграции вы должны либо заменить эти классы сторонними служебными библиотеками, либо удалить эти ссылки из своего кода. Существует множество отличных библиотек JavaScript, предоставляющих аналогичные функции, например Closure или jQuery .

Следующие классы не имеют аналогов в Maps JavaScript API v3:

GBounds GLanguage
GBrowserIsCompatible GLayer
GControl GLog
GControlAnchor GMercatorProjection
GControlImpl GNavLabelControl
GControlPosition GObliqueMercator
GCopyright GOverlay
GCopyrightCollection GPhotoSpec
GDownloadUrl GPolyEditingOptions
GDraggableObject GScreenOverlay
GDraggableObjectOptions GStreetviewFeatures
GFactualGeocodeCache GStreetviewLocation
GGeoAddressAccuracy GStreetviewOverlay
GGeocodeCache GStreetviewUserPhotosOptions
GGoogleBar GTileLayerOptions
GGoogleBarAdsOptions GTileLayerOverlayOptions
GGoogleBarLinkTarget GTrafficOverlayOptions
GGoogleBarListingTypes GUnload
GGoogleBarOptions GXml
GGoogleBarResultList GXmlHttp
GInfoWindowTab GXslt
GKeyboardHandler

Сравнение кода

Давайте сравним два довольно простых приложения, написанных с использованием API v2 и v3.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
    <style>
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script>
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>

Как видите, между двумя приложениями есть несколько различий. Заметные изменения включают:

  • Адрес, с которого загружается API, изменился.
  • GBrowserIsCompatible() и GUnload() больше не требуются в v3 и были удалены из API.
  • Объект GMap2 заменен на google.maps.Map в качестве центрального объекта в API.
  • Свойства теперь загружаются через классы параметров. В приведенном выше примере мы установили три свойства, необходимые для загрузки карты — center , zoom и mapTypeId — через встроенный объект MapOptions .
  • Пользовательский интерфейс по умолчанию включен по умолчанию в v3. Вы можете отключить это, задав для свойства disableDefaultUI значение true в объекте MapOptions .

Резюме

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

  • Документация для разработчиков Maps JavaScript API v3 — лучшее место, где можно узнать больше об API и о том, как он работает.
  • Справочник Maps JavaScript API v3 поможет вам узнать больше о новых классах и методах в API v3.
  • Сообщество Stack Overflow — отличное место, где можно задать вопросы, связанные с кодом. На сайте в вопросах и ответах, касающихся Maps JavaScript API, используются теги « google-maps » или « google-maps-api-3 ».
  • Клиенты плана Premium платформы Google Maps должны ознакомиться с документацией по плану Premium платформы Google Maps .
  • Блог Google Geo Developers — отличный способ узнать о последних изменениях в API.

Если у вас есть какие-либо проблемы или вопросы по поводу этой статьи, воспользуйтесь ссылкой ОТПРАВИТЬ ОТЗЫВ в верхней части этой страницы.

Подробная справка

В этом разделе представлено подробное сравнение наиболее популярных функций для версий 2 и 3 API JavaScript для Карт. Каждый раздел справочника предназначен для индивидуального чтения. Мы рекомендуем вам не читать этот справочник целиком; вместо этого используйте этот материал, чтобы облегчить миграцию в каждом конкретном случае.

  • События - регистрация и обработка событий.
  • Элементы управления — управление навигационными элементами управления, которые появляются на карте.
  • Оверлеи - добавление и редактирование объектов на карте.
  • Типы карт — тайлы, из которых состоит базовая карта.
  • Слои — добавление и редактирование контента в виде группы, например слоев KML или трафика.
  • Сервисы — работа с геокодированием Google, маршрутами или сервисами просмотра улиц.

События

Модель событий для Maps JavaScript API версии 3 аналогична модели, используемой в версии 2, хотя внутри многое изменилось.

Элементы управления

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

Накладки

Наложения отражают объекты, которые вы «добавляете» на карту для обозначения точек, линий, областей или наборов объектов.

Типы карт

Типы карт, доступных в v2 и v3, немного различаются, но все основные типы карт доступны в обеих версиях API. По умолчанию v2 использует стандартные «раскрашенные» плитки дорожной карты. Однако версия 3 требует указания определенного типа карты при создании объекта google.maps.Map .

Слои

Слои — это объекты на карте, состоящие из одного или нескольких наложений. Ими можно манипулировать как единым целым, и обычно они отражают наборы объектов.

Услуги