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

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

Обзор

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

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

Изменения в V3 Maps JavaScript API

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

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

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

Обновите свое приложение

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

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

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

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

Загрузить API

Первое изменение, которое вам нужно будет сделать в вашем коде, касается способа загрузки API. В v2 вы загружаете Maps JavaScript API через запрос к http://maps.google.com/maps . Если вы загружаете Maps JavaScript API v3, вам нужно будет внести следующие изменения:

  1. Загрузите API с //maps.googleapis.com/maps/api/js
  2. Удалить параметр file .
  3. Обновите параметр key с помощью нового ключа v3. Клиенты Google Maps APIs 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 по умолчанию помещает все объекты в глобальное пространство имен, что может привести к конфликтам имен. В v3 все объекты располагаются в пространстве имен google.maps .

При миграции вашего приложения на v3 вам придется изменить свой код, чтобы использовать новое пространство имен. К сожалению, поиск "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 v3 имеет параллели для большинства функций в v2; однако есть некоторые классы, которые больше не поддерживаются. В рамках миграции вам следует либо заменить эти классы сторонними библиотеками утилит, либо удалить эти ссылки из вашего кода. Существует множество отличных библиотек 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.
  • Свойства теперь загружаются через классы Options. В приведенном выше примере мы задаем три свойства, необходимые для загрузки карты — center , zoom и mapTypeId — с помощью встроенного объекта MapOptions .
  • Пользовательский интерфейс по умолчанию включен в v3. Вы можете отключить его, установив свойство disableDefaultUI в значение true в объекте MapOptions .

Краткое содержание

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

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

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

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

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

События

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

Управление

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

Накладки

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

Типы карт

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

Слои

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

Услуги