Maps JavaScript API v2 больше не доступен с 26 мая 2021 г. В результате карты v2 вашего сайта перестанут работать и будут возвращать ошибки JavaScript. Чтобы продолжить использовать карты на своем сайте, перейдите на Maps JavaScript API v3. Это руководство поможет вам в этом процессе.
Обзор
Каждое приложение будет иметь несколько иной процесс миграции; однако есть некоторые шаги, общие для всех проектов:
- Получить новый ключ. Maps JavaScript API теперь использует Google Cloud Console для управления ключами. Если вы все еще используете ключ v2, обязательно получите новый ключ API перед началом миграции.
- Обновите загрузочный API. Большинство приложений загружают Maps JavaScript API версии 3 со следующим кодом:
<script src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
- Обновите свой код. Количество требуемых изменений будет во многом зависеть от вашего приложения. Общие изменения включают в себя:
- Всегда ссылайтесь на пространство имен google.maps. В версии 3 весь код Maps JavaScript API хранится в пространстве имен
google.maps.*
, а не в глобальном пространстве имен. Большинство объектов также были переименованы в рамках этого процесса. Например, вместо GMap2
теперь вы будете загружать google.maps.Map
. - Удалите любые ссылки на устаревшие методы. Был удален ряд служебных методов общего назначения, таких как
GDownloadURL
и GLog
. Либо замените эту функциональность сторонними служебными библиотеками, либо удалите эти ссылки из своего кода. - (Необязательно) Добавьте библиотеки в свой код. Многие функции были реализованы в служебных библиотеках, так что каждому приложению нужно будет загружать только те части API, которые будут использоваться.
- (Необязательно) Настройте свой проект для использования внешних модулей версии 3. Внешние модули v3 можно использовать для проверки кода с помощью компилятора Closure или для запуска автозаполнения в вашей среде IDE. Узнайте больше о Advanced Compilation и Externs .
- Тестируйте и повторяйте. На этом этапе вам еще предстоит проделать определенную работу, но хорошая новость заключается в том, что вы уже на пути к своему новому картографическому приложению версии 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, вам потребуется внести следующие изменения:
- Загрузите API с
//maps.googleapis.com/maps/api/js
- Удалите параметр
file
. - Обновите
key
параметр с помощью нового ключа v3. Клиенты Google Maps API for Work должны использовать client
параметр. - (Только для плана "Премиум" платформы Google Карт) Убедитесь, что параметр
client
указан в соответствии с инструкциями в Руководстве разработчика для плана "Премиум" платформы Google Карт . - Удалите параметр
v
, чтобы запросить последнюю выпущенную версию, или измените его значение в соответствии со схемой управления версиями v3 . - (Необязательно) Замените параметр
hl
на language
и сохраните его значение. - (Необязательно) Добавьте параметр
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 Карт. Существует дополнительная информация, которую вам может понадобиться знать, но это будет зависеть от вашего приложения. В следующих разделах мы включили инструкции по миграции для конкретных случаев, с которыми вы можете столкнуться. Кроме того, есть несколько ресурсов, которые могут оказаться полезными в процессе обновления.
Если у вас есть какие-либо проблемы или вопросы по поводу этой статьи, воспользуйтесь ссылкой ОТПРАВИТЬ ОТЗЫВ в верхней части этой страницы.
В этом разделе представлено подробное сравнение наиболее популярных функций для версий 2 и 3 API JavaScript для Карт. Каждый раздел справочника предназначен для индивидуального чтения. Мы рекомендуем вам не читать этот справочник целиком; вместо этого используйте этот материал, чтобы облегчить миграцию в каждом конкретном случае.
- События - регистрация и обработка событий.
- Элементы управления — управление навигационными элементами управления, которые появляются на карте.
- Оверлеи - добавление и редактирование объектов на карте.
- Типы карт — тайлы, из которых состоит базовая карта.
- Слои — добавление и редактирование контента в виде группы, например слоев KML или трафика.
- Сервисы — работа с геокодированием Google, маршрутами или сервисами просмотра улиц.
События
Модель событий для Maps JavaScript API версии 3 аналогична модели, используемой в версии 2, хотя внутри многое изменилось.
Новое событие для поддержки MVC
В v3 API добавлен новый тип события, отражающий изменения состояния MVC. Теперь есть два типа событий:
- Пользовательские события (например, события щелчка мышью) передаются из модели DOM в Maps JavaScript API. Эти события являются отдельными и отличными от стандартных событий DOM.
- Уведомления об изменении состояния MVC отражают изменения в объектах Maps API и именуются с использованием соглашения о
property _changed
.
Каждый объект Maps API экспортирует ряд именованных событий. Приложения, заинтересованные в определенных событиях, должны регистрировать прослушиватели событий для этих событий и выполнять код при получении этих событий. Этот управляемый событиями механизм одинаков и в Maps JavaScript API v2, и в v3, за исключением того, что пространство имен изменилось с GEvent
на google.maps.event
:
GEvent.addListener(map, 'click', function() {
alert('You clicked the map.');
});
google.maps.event.addListener(map, 'click', function() {
alert('You clicked the map.');
});
Удаление прослушивателей событий
По соображениям производительности лучше удалить прослушиватель событий, когда он больше не нужен. Удаление прослушивателя событий работает одинаково в v2 и v3:
- Когда вы создаете прослушиватель событий, возвращается непрозрачный объект ( GEventListener в версии 2, MapsEventListener в версии 3).
- Если вы хотите удалить прослушиватель событий, передайте этот объект
removeListener()
( GEvent.removeListener()
в версии 2 или google.maps.event.removeListener()
в версии 3), чтобы удалить прослушиватель событий.
Прослушивание событий DOM
Если вы хотите перехватывать события DOM (объектная модель документа) и реагировать на них, версия 3 предоставляет статический метод google.maps.event.addDomListener()
, эквивалентный GEvent.addDomListener()
в версии 2.
Использование переданных аргументов в событиях
События пользовательского интерфейса часто передают аргумент события, к которому затем может получить доступ прослушиватель событий. Большинство аргументов событий в v3 были упрощены, чтобы быть более согласованными с объектами в API. (Подробности см. в Справочнике v3 .)
В прослушивателях событий v3 не существует аргумента overlay
. Если вы зарегистрируете событие click
на карте v3, обратный вызов будет происходить только тогда, когда пользователь щелкнет базовую карту. Вы можете зарегистрировать дополнительные обратные вызовы для интерактивных оверлеев, если вам нужно реагировать на эти клики.
// Passes an overlay argument when clicking on a map
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();
GEvent.addListener(map,'click', function(overlay, latlng) {
if (latlng) {
var marker = new GMarker(latlng);
map.addOverlay(marker);
}
});
// Passes only an event argument
var myOptions = {
center: new google.maps.LatLng(-25.363882, 131.044922),
zoom: 4,
mapTypeId: google.maps.MapTypeId.ROADMAP
};
var map = new google.maps.Map(document.getElementById('map'),
myOptions);
google.maps.event.addListener(map, 'click', function(event) {
var marker = new google.maps.Marker({
position: event.latLng,
map: map
});
});
Элементы управления
Maps JavaScript API отображает элементы управления пользовательского интерфейса, которые позволяют пользователям взаимодействовать с вашей картой. Вы можете использовать API, чтобы настроить внешний вид этих элементов управления.
Изменения в типах управления
Некоторые изменения в типах элементов control
были внесены в API версии 3.
- API версии 3 поддерживает дополнительные типы карт, включая карты местности, и возможность добавлять пользовательские типы карт.
- Иерархический элемент управления v2,
GHierarchicalMapTypeControl
, больше недоступен. Аналогичного эффекта можно добиться с помощью элемента управления google.maps.MapTypeControlStyle.HORIZONTAL_BAR
. - Горизонтальное расположение, предоставляемое
GMapTypeControl
в версии 2, недоступно в версии 3.
Добавление элементов управления на карту
С Maps JavaScript API v2 вы можете добавлять элементы управления на свою карту с помощью addControl()
вашего объекта карты. В v3 вместо прямого доступа или изменения элементов управления вы изменяете связанный объект MapOptions
. В приведенном ниже примере показано, как настроить карту, чтобы добавить следующие элементы управления:
- кнопки, которые позволяют пользователю переключаться между доступными типами карт
- масштаб карты
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
// Add controls
map.addControl(new GMapTypeControl());
map.addControl(new GScaleControl());
var myOptions = {
center: new google.maps.LatLng(-25.363882, 131.044922),
zoom: 4,
mapTypeId: google.maps.MapTypeId.ROADMAP,
// Add controls
mapTypeControl: true,
scaleControl: true
};
var map = new google.maps.Map(document.getElementById('map'),
myOptions);
Расположение элементов управления на карте
Элементы управления позиционированием сильно изменились в v3. В версии 2 метод addControl()
принимает необязательный второй параметр, который позволяет указать положение элемента управления относительно углов карты.
В версии 3 положение элемента управления устанавливается с помощью свойства position
параметров элемента управления. Расположение этих элементов управления не является абсолютным; вместо этого API будет разумно размещать элементы управления, «обтекая» их вокруг существующих элементов карты в рамках заданных ограничений (например, размера карты). Это гарантирует, что элементы управления по умолчанию совместимы с вашими элементами управления. Дополнительную информацию см. в разделе Позиционирование элементов управления в версии 3 .
Следующий код перемещает элементы управления из приведенных выше примеров:
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
// Add map type control
map.addControl(new GMapTypeControl(), new GControlPosition(
G_ANCHOR_TOP_LEFT, new GSize(10, 10)));
// Add scale
map.addControl(new GScaleControl(), new GControlPosition(
G_ANCHOR_BOTTOM_RIGHT, new GSize(20, 20)));
var myOptions = {
center: new google.maps.LatLng(-25.363882, 131.044922),
zoom: 4,
mapTypeId: google.maps.MapTypeId.ROADMAP,
// Add map type control
mapTypeControl: true,
mapTypeControlOptions: {
style: google.maps.MapTypeControlStyle.HORIZONTAL_BAR,
position: google.maps.ControlPosition.TOP_LEFT
},
// Add scale
scaleControl: true,
scaleControlOptions: {
position: google.maps.ControlPosition.BOTTOM_RIGHT
}
};
var map = new google.maps.Map(document.getElementById('map'),
myOptions);
Пользовательские элементы управления
Maps JavaScript API позволяет создавать собственные элементы управления навигацией. Чтобы настроить элементы управления с помощью v2 API, вы должны создать подкласс класса GControl
и определить обработчики для методов initialize()
и getDefaultPosition()
. В v3 нет эквивалента классу GControl
. Вместо этого элементы управления представлены в виде элементов DOM. Чтобы добавить настраиваемый элемент управления с помощью v3 API, создайте структуру DOM для элемента управления в конструкторе как дочерний элемент Node
(например, элемент <div>
) и добавьте прослушиватели событий для обработки любых событий DOM. Поместите Node
в массив controls[ position ]
, чтобы добавить экземпляр пользовательского элемента управления на карту.
Учитывая реализацию класса HomeControl
, которая соответствует указанным выше требованиям к интерфейсу (дополнительные сведения см. в документации по пользовательским элементам управления ), в следующих примерах кода показано, как добавить пользовательский элемент управления на карту.
map.addControl(new HomeControl(),
GControlPosition(G_ANCHOR_TOP_RIGHT, new GSize(10, 10)));
var homeControlDiv = document.createElement('DIV');
var homeControl = new HomeControl(homeControlDiv, map);
map.controls[google.maps.ControlPosition.TOP_RIGHT].push(
homeControlDiv);
Накладки
Наложения отражают объекты, которые вы «добавляете» на карту для обозначения точек, линий, областей или наборов объектов.
Добавление и удаление наложений
Типы объектов, представляемых наложением, одинаковы между версиями 2 и 3, однако они обрабатываются по-разному.
Наложения в v2 API добавлялись и удалялись с карты с помощью addOverlay()
и removeOverlay()
объекта GMap2
. В версии 3 вы назначаете карту наложению через свойство map
соответствующего класса параметров наложения. Вы также можете добавить или удалить наложение напрямую, вызвав метод setMap()
объекта наложения и указав нужную карту. Установка для свойства карты null
удаляет наложение.
В v3 не существует метода clearOverlays()
. Если вы хотите управлять набором наложений, вам следует создать массив для хранения наложений. Используя этот массив, вы можете вызывать setMap()
для каждого наложения в массиве (передавая null
, если вам нужно их удалить).
Перетаскиваемые маркеры
По умолчанию маркеры кликабельны, но не перетаскиваемы. В следующих двух примерах добавлен перетаскиваемый маркер:
var myLatLng = new GLatLng(-25.363882, 131.044922);
var map = new GMap2(document.getElementById('map'));
map.setCenter(myLatLng, 4);
var marker = new GMarker(latLng, {
draggable: true
});
map.addOverlay(marker);
var myLatLng = new google.maps.LatLng(-25.363882, 131.044922);
var map = new google.maps.Map(
document.getElementById('map'), {
center: myLatLng,
zoom: 4,
mapTypeId: google.maps.MapTypeId.ROADMAP
});
var marker = new google.maps.Marker({
position: myLatLng,
draggable: true,
map: map
});
Иконки
Вы можете определить собственный значок, который будет отображаться вместо маркера по умолчанию. Чтобы использовать собственное изображение в v2, вы можете создать экземпляр GIcon
из G_DEFAULT_ICON type
и изменить его. Если ваше изображение больше или меньше значка по умолчанию, вы должны указать его с помощью экземпляра GSize
. API v3 немного упрощает этот процесс. Просто установите свойство icon
маркера на URL-адрес вашего пользовательского изображения, и API автоматически изменит размер значка.
Maps JavaScript API также обеспечивает поддержку сложных значков. Сложный значок может включать в себя несколько фрагментов, сложные формы или указывать «порядок стека» того, как изображения должны отображаться по отношению к другим наложениям. Чтобы добавить фигуру к маркеру в версии 2, вам нужно указать дополнительное свойство в каждом экземпляре GIcon
и передать его как параметр конструктору GMarker
. В версии 3 значки, указанные таким образом, должны устанавливать свои свойства icon
на объект типа Icon
. Маркерные тени не поддерживаются в v3.
В следующих примерах показан пляжный флаг на пляже Бонди в Австралии, при этом прозрачная часть значка не активна:
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(-25.363882, 131.044922), 4);
map.setUIToDefault();
var flagIcon = new GIcon(G_DEFAULT_ICON);
flagIcon.image = '/images/beachflag.png';
flagIcon.imageMap = [1, 1, 1, 20, 18, 20, 18 , 1];
var bbLatLng = new GLatLng(-33.890542, 151.274856);
map.addOverlay(new GMarker(bbLatLng, {
icon: flagIcon
}));
var map = new google.maps.Map(
document.getElementById('map'), {
center: new google.maps.LatLng(-25.363882, 131.044922),
zoom: 4,
mapTypeId: google.maps.MapTypeId.ROADMAP
});
var shape = {
coord: [1, 1, 1, 20, 18, 20, 18 , 1],
type: 'poly'
};
var bbLatLng = new google.maps.LatLng(-33.890542, 151.274856);
var bbMarker = new google.maps.Marker({
icon: '/images/beachflag.png'
shape: shape,
position: bbLatLng,
map: map
});
Полилинии
Ломаная линия состоит из массива LatLng
и ряда сегментов линии, которые соединяют эти местоположения в упорядоченной последовательности. Создание и отображение объекта Polyline
в версии 3 аналогично использованию объекта GPolyline
в версии 2. Следующие примеры рисуют полупрозрачную геодезическую полилинию шириной 3 пикселя от Цюриха до Сиднея через Сингапур:
var polyline = new GPolyline(
[
new GLatLng(47.3690239, 8.5380326),
new GLatLng(1.352083, 103.819836),
new GLatLng(-33.867139, 151.207114)
],
'#FF0000', 3, 0.5, {
geodesic: true
});
map.addOverlay(polyline);
var polyline = new google.maps.Polyline({
path: [
new google.maps.LatLng(47.3690239, 8.5380326),
new google.maps.LatLng(1.352083, 103.819836),
new google.maps.LatLng(-33.867139, 151.207114)
],
strokeColor: '#FF0000',
strokeOpacity: 0.5,
strokeWeight: 3,
geodesic: true
});
polyline.setMap(map);
Кодированные полилинии
В v3 отсутствует поддержка создания объектов Polyline
непосредственно из закодированных полилиний . Вместо этого библиотека геометрии предоставляет методы для кодирования и декодирования полилиний. Дополнительные сведения о том, как загрузить эту библиотеку, см. в разделе Библиотеки в API Карт v3.
Примеры ниже рисуют одну и ту же закодированную полилинию; код версии 3 использует метод decodePath()
из пространства имен google.maps.geometry.encoding
.
var polyline = new GPolyline.fromEncoded({
points: 'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H',
levels: 'PPP',
zoomFactor: 2,
numLevels: 18,
color: '#ff0000',
opacity: 0.8,
weight: 3
});
map.addOverlay(polyline);
var polyline = new google.maps.Polyline({
path: google.maps.geometry.encoding.decodePath(
'kwb`Huqbs@ztzwGgvpdQbw}uEoif`H'),
strokeColor: '#FF0000',
strokeOpacity: 0.5,
strokeWeight: 3,
});
polyline.setMap(map);
Полигоны
Полигон определяет область внутри замкнутого контура. Подобно объекту Polyline
, объекты Polygon
состоят из ряда точек в упорядоченной последовательности. Класс Polygon
версии 3 во многом аналогичен классу GPolygon
версии 2, за исключением того, что вам больше не нужно повторять начальную вершину в конце пути, чтобы замкнуть цикл. API версии 3 автоматически закрывает любые полигоны, рисуя линию, соединяющую последнюю координату с первой координатой. Следующие фрагменты кода создают многоугольник, представляющий Бермудский треугольник:
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(24.886436, -70.268554), 5);
var bermudaTriangle = new GPolygon(
[
new GLatLng(25.774252, -80.190262),
new GLatLng(18.466465, -66.118292),
new GLatLng(32.321384, -64.75737),
new GLatLng(25.774252, -80.190262)
],
'#FF0000', 2, 0.8, '#FF0000', 0.35);
map.addOverlay(bermudaTriangle);
var map = new google.maps.Map(document.getElementById('map'), {
center: new google.maps.LatLng(24.886436, -70.268554),
mapTypeId: google.maps.MapTypeId.TERRAIN,
zoom: 5
});
var bermudaTriangle = new google.maps.Polygon({
paths: [
new google.maps.LatLng(25.774252, -80.190262),
new google.maps.LatLng(18.466465, -66.118292),
new google.maps.LatLng(32.321384, -64.75737)
],
strokeColor: '#FF0000',
strokeWeight: 2,
strokeOpacity: 0.8,
fillColor: '#FF0000',
fillOpacity: 0.35
});
bermudaTriangle.setMap(map);
Редактируемые пользователем формы
Полилинии и многоугольники могут быть сделаны редактируемыми пользователем. Следующие фрагменты кода эквивалентны:
map.addOverlay(polyline);
polyline.enableEditing();
polyline.setMap(map);
polyline.setEditable(true);
Дополнительные возможности рисования см. в библиотеке чертежей в документации по версии 3.
Информационные окна
InfoWindow
отображает содержимое в плавающем окне над картой. Между информационными окнами v2 и v3 есть несколько ключевых различий:
- API версии 2 поддерживает только
GInfoWindow
для каждой карты, тогда как API версии 3 поддерживает несколько одновременных InfoWindow
на каждой карте. - Информационное
InfoWindow
версии 3 останется открытым, когда вы щелкнете по карте. GInfoWindow
v2 автоматически закрывается при нажатии на карту. Вы можете эмулировать поведение версии 2, добавив прослушиватель click
в объект Map
. - API версии 3 не обеспечивает встроенную поддержку
InfoWindow
с вкладками.
Накладки на землю
Чтобы разместить изображение на карте, вы должны использовать объект GroundOverlay
. Конструктор для GroundOverlay
практически одинаков в версиях 2 и 3: он указывает URL-адрес изображения и границы изображения в качестве параметров.
В следующем примере старинная карта Ньюарка, штат Нью-Джерси, размещается на карте в качестве наложения:
var bounds = new GLatLngBounds(
new GLatLng(40.716216, -74.213393),
new GLatLng(40.765641, -74.139235));
var overlay = new GGroundOverlay(
'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
bounds);
map.addOverlay(overlay);
var bounds = new google.maps.LatLngBounds(
new google.maps.LatLng(40.716216, -74.213393),
new google.maps.LatLng(40.765641, -74.139235));
var overlay = new google.maps.GroundOverlay(
'http://lib.utexas.edu/maps/historical/newark_nj_1922.jpg',
bounds);
overlay.setMap(map);
Типы карт
Типы карт, доступных в v2 и v3, немного различаются, но все основные типы карт доступны в обеих версиях API. По умолчанию v2 использует стандартные «раскрашенные» плитки дорожной карты. Однако версия 3 требует указания определенного типа карты при создании объекта google.maps.Map
.
Распространенные типы карт
Четыре основных типа карт доступны как в v2, так и в v3:
-
MapTypeId.ROADMAP
(заменяет G_NORMAL_MAP
) отображает представление дорожной карты. -
MapTypeId.SATELLITE
(заменяет G_SATELLITE_MAP
) отображает спутниковые изображения Google Earth. -
MapTypeId.HYBRID
(заменяет G_HYBRID_MAP
) отображает смесь обычных и спутниковых изображений. -
MapTypeId.TERRAIN
(заменяет G_PHYSICAL_MAP
) отображает физическую карту на основе информации о местности.
Ниже приведен пример v2 и v3, устанавливающих карту для просмотра местности:
map.setMapType(G_PHYSICAL_MAP);
map.setMapTypeId(google.maps.MapTypeId.TERRAIN);
Maps JavaScript API v3 также внес несколько изменений в менее распространенные типы карт:
- Фрагменты карты для небесных тел, отличных от Земли, недоступны как типы карт в v3 API, но к ним можно получить доступ как к пользовательским типам карт, как показано в этом примере .
- В v3 нет специального типа карты, который заменяет тип
G_SATELLITE_3D_MAP
из v2. Вместо этого вы можете интегрировать подключаемый модуль Google Планета Земля в свои карты v3 с помощью этой библиотеки .
Изображение с максимальным увеличением
Спутниковые снимки не всегда доступны при большом увеличении. Если вам может понадобиться узнать самый высокий уровень масштабирования, доступный перед установкой уровня масштабирования, используйте класс google.maps.MaxZoomService
. Этот класс заменяет метод GMapType.getMaxZoomAtLatLng()
из версии 2.
var point = new GLatLng(
180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new GMap2(document.getElementById("map"));
map.setUIToDefault();
map.setCenter(point);
map.setMapType(G_HYBRID_MAP);
map.getCurrentMapType().getMaxZoomAtLatLng(point,
function(response) {
if (response.status) {
map.setZoom(response.zoom);
} else {
alert("Error in Max Zoom Service.");
}
});
var myLatlng = new google.maps.LatLng(
180 * Math.random() - 90, 360 * Math.random() - 180);
var map = new google.maps.Map(
document.getElementById("map"),{
zoom: 0,
center: myLatlng,
mapTypeId: google.maps.MapTypeId.HYBRID
});
var maxZoomService = new google.maps.MaxZoomService();
maxZoomService.getMaxZoomAtLatLng(
myLatlng,
function(response) {
if (response.status == google.maps.MaxZoomStatus.OK) {
map.setZoom(response.zoom);
} else {
alert("Error in Max Zoom Service.");
}
});
Аэрофотосъемка
При включении аэрофотосъемки в версии 3 элементы управления аналогичны элементу управления GLargeZoomControl3D
версии 2 с дополнительным промежуточным элементом управления поворотом для поворота в поддерживаемых направлениях.
На этой карте вы можете отслеживать города, для которых в настоящее время доступно изображение под углом 45° . Когда доступно изображение под углом 45°, к кнопке Maps API Satellite добавляется пункт подменю.
Слои
Слои — это объекты на карте, состоящие из одного или нескольких наложений. Ими можно манипулировать как единым целым, и обычно они отражают наборы объектов.
Поддерживаемые слои
API версии 3 предоставляет доступ к нескольким различным уровням. Эти слои перекрываются с классом v2 GLayer
в следующих областях:
- Объект
KmlLayer
элементы KML и GeoRSS в наложения версии 3, обеспечивая эквивалент слоя GeoXml
2. - Объект
TrafficLayer
отображает слой, отображающий условия дорожного движения, аналогично наложению GTrafficOverlay
версии 2.
Эти слои отличаются от v2. Различия описаны ниже. Их можно добавить на карту, вызвав setMap()
и передав ему объект Map
, на котором будет отображаться слой.
Более подробная информация о поддерживаемых слоях доступна в документации по слоям.
Слои KML и GeoRSS
Maps JavaScript API поддерживает форматы данных KML и GeoRSS для отображения географической информации. Файлы KML или GeoRSS должны быть общедоступны, если вы хотите включить их в карту. В версии 3 эти форматы данных отображаются с использованием экземпляра KmlLayer
, который заменяет объект GGeoXml
из версии 2.
API v3 более гибок при отображении KML, позволяя отключать InfoWindows и изменять отклик на клик. Дополнительные сведения см. в документации по слоям KML и GeoRSS v3.
При рендеринге KmlLayer
применяются ограничения по размеру и сложности; подробности см. в документации KmlLayer .
В следующих примерах сравнивается загрузка файла KML.
geoXml = new GGeoXml(
'https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml');
map.addOverlay(geoXml);
var layer = new google.maps.KmlLayer(
'https://googlearchive.github.io/js-v2-samples/ggeoxml/cta.kml', {
preserveViewport: true
});
layer.setMap(map);
Уровень трафика
v3 позволяет вам добавлять информацию о трафике в реальном времени (где это поддерживается) на ваши карты с помощью объекта TrafficLayer
. Информация о трафике предоставляется на момент запроса. Эти примеры показывают информацию о трафике для Лос-Анджелеса:
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(34.0492459, -118.241043), 13);
map.setUIToDefault();
var trafficOptions = {incidents:false};
trafficInfo = new GTrafficOverlay(trafficOptions);
map.addOverlay(trafficInfo);
var map = new google.maps.Map(
document.getElementById('map'), {
center: new google.maps.LatLng(34.0492459, -118.241043),
mapTypeId: google.maps.MapTypeId.ROADMAP,
zoom: 13
});
var trafficLayer = new google.maps.TrafficLayer();
trafficLayer.setMap(map);
В отличие от версии 2, в версии 3 для конструктора TrafficLayer
не существует опций. Инциденты недоступны в v3.
Услуги
Геокодирование
Maps JavaScript API предоставляет объект geocoder
для динамического геокодирования адресов на основе пользовательского ввода. Если вы хотите геокодировать статические известные адреса, см. документацию API геокодирования .
API геокодирования был значительно обновлен и улучшен, добавлены новые функции и изменен способ представления данных.
GClientGeocoder
в v2 API предоставляет два разных метода прямого и обратного геокодирования, а также дополнительные методы, влияющие на то, как выполняется геокодирование. Напротив, объект Geocoder
v3 предоставляет только метод geocode()
, который принимает литерал объекта, содержащий входные условия (в форме объекта запросов геокодирования ) и метод обратного вызова. В зависимости от того, содержит ли запрос текстовый атрибут address
или объект LatLng
, API геокодирования вернет прямой или обратный ответ геокодирования. Вы можете повлиять на то, как выполняется геокодирование, передав дополнительные поля в запрос геокодирования:
- Включение текстового
address
запускает прямое геокодирование, эквивалентное вызову метода getLatLng()
. - Включение объекта
latLng
запускает обратное геокодирование, эквивалентное вызову getLocations()
. - Включение атрибута
bounds
включает смещение области просмотра, что эквивалентно вызову метода setViewport setViewport()
. - Включение атрибута
region
включает смещение кода региона , что эквивалентно вызову setBaseCountryCode()
.
Ответы геокодирования в версии 3 сильно отличаются от ответов версии 2. API версии 3 заменяет вложенную структуру, используемую в версии 2, более плоской структурой, которую легче анализировать. Кроме того, ответы v3 являются более подробными: каждый результат имеет несколько адресных компонентов , которые помогают лучше понять разрешение каждого результата.
Следующий код берет текстовый адрес и показывает первый результат его геокодирования:
var geocoder = new GClientGeocoder();
var infoPanel;
var map;
var AccuracyDescription = [
'Unknown accuracy', 'country level accuracy',
'region level accuracy', 'sub-region level accuracy',
'town level accuracy', 'post code level accuracy',
'street level accuracy', 'intersection level accuracy',
'address level accuracy', 'premise level accuracy',
];
function geocode_result_handler(response) {
if (!response || response.Status.code != 200) {
alert('Geocoding failed. ' + response.Status.code);
} else {
var bounds = new GLatLngBounds(new GLatLng(
response.Placemark[0].ExtendedData.LatLonBox.south,
response.Placemark[0].ExtendedData.LatLonBox.west
), new GLatLng(
response.Placemark[0].ExtendedData.LatLonBox.north,
response.Placemark[0].ExtendedData.LatLonBox.east
));
map.setCenter(bounds.getCenter(),
map.getBoundsZoomLevel(bounds));
var latlng = new GLatLng(
response.Placemark[0].Point.coordinates[1],
response.Placemark[0].Point.coordinates[0]);
infoPanel.innerHTML += '<p>1st result is <em>' +
// No info about location type
response.Placemark[0].address +
'</em> of <em>' +
AccuracyDescription[response.Placemark[0].
AddressDetails.Accuracy] +
'</em> at <tt>' + latlng + '</tt></p>';
var marker_title = response.Placemark[0].address +
' at ' + latlng;
map.clearOverlays();
var marker = marker = new GMarker(
latlng,
{'title': marker_title}
);
map.addOverlay(marker);
}
}
function geocode_address() {
var address = document.getElementById('input-text').value;
infoPanel.innerHTML = '<p>Original address: ' + address + '</p>';
geocoder.getLocations(address, geocode_result_handler);
}
function initialize() {
map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(38, 15), 2);
map.setUIToDefault();
infoPanel = document.getElementById('info-panel');
}
var geocoder = new google.maps.Geocoder();
var infoPanel;
var map;
var marker;
function geocode_result_handler(result, status) {
if (status != google.maps.GeocoderStatus.OK) {
alert('Geocoding failed. ' + status);
} else {
map.fitBounds(result[0].geometry.viewport);
infoPanel.innerHTML += '<p>1st result for geocoding is <em>' +
result[0].geometry.location_type.toLowerCase() +
'</em> to <em>' +
result[0].formatted_address + '</em> of types <em>' +
result[0].types.join('</em>, <em>').replace(/_/, ' ') +
'</em> at <tt>' + result[0].geometry.location +
'</tt></p>';
var marker_title = result[0].formatted_address +
' at ' + latlng;
if (marker) {
marker.setPosition(result[0].geometry.location);
marker.setTitle(marker_title);
} else {
marker = new google.maps.Marker({
position: result[0].geometry.location,
title: marker_title,
map: map
});
}
}
}
function geocode_address() {
var address = document.getElementById('input-text').value;
infoPanel.innerHTML = '<p>Original address: ' + address + '</p>';
geocoder.geocode({'address': address}, geocode_result_handler);
}
function initialize() {
map = new google.maps.Map(document.getElementById('map'), {
center: new google.maps.LatLng(38, 15),
zoom: 2,
mapTypeId: google.maps.MapTypeId.HYBRID
});
infoPanel = document.getElementById('info-panel');
}
Направления
Maps JavaScript API v3 заменяет класс GDirections
из v2 классом DirectionsService
для расчета маршрутов.
Метод route()
в версии 3 заменяет методы load()
и loadFromWaypoints()
из API версии 2. Этот метод принимает один литерал объекта DirectionsRequest
, содержащий входные условия и метод обратного вызова, который выполняется после получения ответа. В этом литерале объекта могут быть заданы параметры, аналогичные GDirectionsOptions
объекта GDirectionsOptions в v2.
В Maps JavaScript API v3 задача отправки запросов направления была отделена от задачи обработки запросов, которая теперь обрабатывается классом DirectionsRenderer
. Вы можете связать объект DirectionsRenderer
с любой картой или объектом DirectionsResult
с помощью его setMap()
и setDirections()
. Поскольку средство визуализации является MVCObject
, оно обнаружит любые изменения своих свойств и обновит карту при изменении связанных направлений.
В следующем коде показано, как запросить пешеходные маршруты до определенного места, используя пешеходные дорожки по адресу. Обратите внимание, что только v3 может предоставить маршруты для пешеходов в Дублинском зоопарке.
var map;
var directions;
var directionsPanel;
function initialize() {
var origin = new google.maps.LatLng(53.348172, -6.297285);
var destination = new google.maps.LatLng(53.355502, -6.30557);
directionsPanel = document.getElementById("route");
map = new GMap2(document.getElementById('map'));
map.setCenter(origin, 10);
map.setUIToDefault();
directions = new GDirections(map, directionsPanel);
directions.loadFromWaypoints(
[origin, destination], {
travelMode: 'G_TRAVEL_MODE_WALKING',
});
}
var map;
var directionsRenderer;
var directionsService = new google.maps.DirectionsService();
function initialize() {
var origin = new google.maps.LatLng(53.348172, -6.297285);
var destination = new google.maps.LatLng(53.355502, -6.30557);
directionsRenderer = new google.maps.DirectionsRenderer();
map = new google.maps.Map(
document.getElementById('map'), {
center: origin,
zoom: 10,
mapTypeId: google.maps.MapTypeId.ROADMAP
});
directionsRenderer.setPanel(document.getElementById("route"));
directionsRenderer.setMap(map);
directionsService.route({
origin: origin,
destination: destination,
travelMode: google.maps.DirectionsTravelMode.WALKING
}, function(result, status) {
if (status == google.maps.DirectionsStatus.OK) {
directionsRenderer.setDirections(result);
}
});
}
Просмотр улиц
Google Street View обеспечивает интерактивный обзор на 360° из определенных мест в пределах зоны покрытия. API версии 3 изначально поддерживает Просмотр улиц в браузере, в отличие от версии 2, в которой для отображения изображений Просмотра улиц требовался подключаемый модуль Flash®.
Изображения просмотра улиц поддерживаются за счет использования объекта StreetViewPanorama
в версии 3 или объекта GStreetviewPanorama
в версии 2. У этих классов разные интерфейсы, но они играют одну и ту же роль: соединяют контейнер div
с изображениями Street View и позволяют указать местоположение и POV (точку обзора) панорамы Street View.
function initialize() {
var fenwayPark = new GLatLng(42.345573, -71.098326);
panoramaOptions = {
latlng: fenwayPark,
pov: {
heading: 35,
pitch: 5,
zoom: 1
}
};
var panorama = new GStreetviewPanorama(
document.getElementById('pano'),
panoramaOptions);
GEvent.addListener(myPano, "error", handleNoFlash);
}
function handleNoFlash(errorCode) {
if (errorCode == FLASH_UNAVAILABLE) {
alert('Error: Your browser does not support Flash');
return;
}
}
function initialize() {
var fenway = new google.maps.LatLng(42.345573, -71.098326);
var panoramaOptions = {
position: fenway,
pov: {
heading: 35,
pitch: 5,
zoom: 1
}
};
var panorama = new google.maps.StreetViewPanorama(
document.getElementById('pano'),
panoramaOptions);
}
Прямой доступ к данным просмотра улиц возможен через объект StreetViewService
в версии 3 или аналогичный объект GStreetviewClient
в версии 2. Оба предоставляют аналогичные интерфейсы для получения или проверки доступности данных просмотра улиц, а также позволяют выполнять поиск по местоположению или идентификатору панорамы.
В версии 3 просмотр улиц включен по умолчанию. Карта появится с элементом управления Pegman Street View, а API будет повторно использовать div карты для отображения панорам StreetView. В следующем коде показано, как эмулировать поведение v2 путем разделения панорам Street View на отдельный div.
var marker;
var panoClient = new GStreetviewClient();
function initialize() {
if (GBrowserIsCompatible()) {
var myPano = new GStreetviewPanorama(
document.getElementById('pano'));
GEvent.addListener(myPano, 'error', handleNoFlash);
var map = new GMap2(document.getElementById('map'));
map.setCenter(new GLatLng(42.345573, -71.098326), 16);
map.setUIToDefault();
GEvent.addListener(map, 'click', function(overlay, latlng) {
if (marker) {
marker.setLatLng(latlng);
} else {
marker = new GMarker(latlng);
map.addOverlay(marker);
}
var nearestPano = panoClient.getNearestPanorama(
latlng, processSVData);
});
function processSVData(panoData) {
if (panoData.code != 200) {
alert("Panorama data not found for this location.");
}
var latlng = marker.getLatLng();
var dLat = latlng.latRadians()
- panoData.location.latlng.latRadians();
var dLon = latlng.lngRadians()
- panoData.location.latlng.lngRadians();
var y = Math.sin(dLon) * Math.cos(latlng.latRadians());
var x = Math.cos(panoData.location.latlng.latRadians()) *
Math.sin(latlng.latRadians()) -
Math.sin(panoData.location.latlng.latRadians()) *
Math.cos(latlng.latRadians()) * Math.cos(dLon);
var bearing = Math.atan2(y, x) * 180 / Math.PI;
myPano.setLocationAndPOV(panoData.location.latlng, {
yaw: bearing
});
}
function handleNoFlash(errorCode) {
if (errorCode == FLASH_UNAVAILABLE) {
alert('Error: Your browser does not support Flash');
return;
}
}
}
}
// Load the API with libraries=geometry
var map;
var marker;
var panorama;
var sv = new google.maps.StreetViewService();
function radians(degrees) { return Math.PI * degrees / 180.0 };
function initialize() {
panorama = new google.maps.StreetViewPanorama(
document.getElementById("pano"));
map = new google.maps.Map(
document.getElementById('map'), {
center: new google.maps.LatLng(42.345573, -71.098326),
mapTypeId: google.maps.MapTypeId.ROADMAP,
zoom: 16
});
google.maps.event.addListener(map, 'click', function(event) {
if (!marker) {
marker = new google.maps.Marker({
position: event.latLng,
map: map
});
} else {
marker.setPosition(event.latLng);
}
sv.getPanoramaByLocation(event.latLng, 50, processSVData);
});
}
function processSVData(panoData, status) {
if (status == google.maps.StreetViewStatus.OK) {
alert("Panorama data not found for this location.");
}
var bearing = google.maps.geometry.spherical.computeHeading(
panoData.location.latLng, marker.getPosition());
panorama.setPano(panoData.location.pano);
panorama.setPov({
heading: bearing,
pitch: 0,
zoom: 1
});
panorama.setVisible(true);
marker.setMap(panorama);
}