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

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

Обзор

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

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

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

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

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

  • Оптимизированная базовая библиотека. Многие дополнительные функции были перенесены в библиотеки , что помогает сократить время загрузки и анализа 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. Возможно, вы уже используете ключ версии 3 в своем приложении, и в этом случае никаких изменений не требуется. Для проверки проверьте URL-адрес, с которого вы загружаете Maps JavaScript API, на предмет его key параметра. Если значение ключа начинается с «ABQIAA», вы используете ключ версии 2. Если у вас есть ключ версии 2, вам необходимо перейти на ключ версии 3 в рамках миграции, которая:

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

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

Загрузка API

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

  1. Загрузите API с //maps.googleapis.com/maps/api/js
  2. Удалите параметр file .
  3. Обновите key параметр, указав новый ключ версии 3. Клиентам 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>

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

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

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

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

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

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 имеет параллели по большинству функций версии 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() больше не требуются в версии 3 и были удалены из API.
  • Объект GMap2 заменяется на google.maps.Map в качестве центрального объекта API.
  • Свойства теперь загружаются через классы Options. В приведенном выше примере мы установили три свойства, необходимые для загрузки карты — center , zoom и mapTypeId — через встроенный объект MapOptions .
  • Пользовательский интерфейс по умолчанию включен по умолчанию в версии 3. Вы можете отключить это, установив для свойства disableDefaultUI значение true в объекте MapOptions .

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

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

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

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

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

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

События

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

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

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

Наложения

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

Типы карт

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

Слои

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

Услуги