Рассчитать и отобразить маршруты на элементе <gmp-map-3d> можно двумя способами:
- Декларативно с помощью
Route3DElement(<gmp-route-3d>). Добавьте веб-компонент, который запрашивает маршруты из Routes API и отрисовывает трехмерные ломаные линии маршрутов, маркеры начальной и конечной точек, а также всплывающее окно со сводными данными о маршруте. - Программно с помощью вспомогательных методов
Route. ВызовитеRoute.computeRoutesи передайте маршрут вcreate3DPolylines,createWaypointMarkersиcreatePopover, если вам нужны промежуточные путевые точки, специальные маски полей или стили ломаных линий.
Оба подхода доступны в канале v=beta Maps JavaScript API. Инструкции по загрузке бета-канала приведены в разделе Версии.
Требования и оплата
Прежде чем показывать 3D-маршруты, настройте облачный проект Google Cloud и включите в нем Maps JavaScript API и Routes API. Загрузите библиотеки maps3d и routes.
Отрисовка <gmp-map-3d> оплачивается по тарифу "Динамические 3D-карты" (Immersive Maps Pro).
Каждый запрос маршрута, сделанный <gmp-route-3d> или Route.computeRoutes, оплачивается по коду Compute Routes Routes API в зависимости от запрошенных функций:
| Конфигурация | Уровень SKU Routes |
|---|---|
Запросы маршрутов по умолчанию (TRAFFIC_UNAWARE или способы передвижения WALKING, BICYCLING и TRANSIT без полилиний трафика)
|
Compute Routes Essentials |
Для параметра routing-preference задано значение traffic-aware или traffic-aware-optimal, а параметр traffic-polylines-disabled включен.
|
Compute Routes Pro |
routing-preference со значением traffic-aware или traffic-aware-optimal с включенными ломаными линиями, цвет которых зависит от загруженности дорог (по умолчанию, если заданы настройки с учетом трафика).
|
Compute Routes Enterprise |
Подробную информацию о кодах SKU вы найдете в статье Статистика использования и оплата Maps JavaScript API.
Как добавить 3D-маршрут с помощью HTML
Чтобы показать маршрут между пунктами отправления и назначения с минимальным количеством кода, вложите <gmp-route-3d> в <gmp-map-3d> и добавьте autofits-camera, чтобы маршрут автоматически вписывался в границы карты.
<gmp-map-3d
style="height: 400px; width: 100%;"
mode="hybrid">
<gmp-route-3d
origin="Space Needle, Seattle, WA"
destination="Tacoma Dome, Tacoma, WA"
travel-mode="driving"
routing-preference="traffic-aware"
autofits-camera>
</gmp-route-3d>
</gmp-map-3d>
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&libraries=maps3d,routes">
</script>
Замените YOUR_API_KEY ключом API платформы Google Карт.
Route3DElement автоматически подбирает цвета ломаной линии и всплывающего окна со сводными данными в соответствии со светлой или темной цветовой схемой родительского элемента <gmp-map-3d> и поддерживает следующие атрибуты и свойства:
originиdestination. Принимают строку координат"lat,lng", название ресурса места, например"places/ChIJ-bfVTh8VkFQRDZLQnmioK9s", или строку адреса. В JavaScript эти свойства также принимают объектыLatLng,LatLngLiteral,LatLngAltitude,LatLngAltitudeLiteralиPlace.travel-mode(travelMode). Допустимые значения:driving(по умолчанию),walking,bicyclingилиtransit(отображает мультимодальные пешеходные и транзитные сегменты).routing-preference(routingPreference): принимает значенияtraffic-unaware,traffic-awareилиtraffic-aware-optimal.traffic-polylines-disabled(trafficPolylinesDisabled): отключает выделение цветом ломаных линий, обозначающих скорость движения, на маршрутах с учетом трафика, чтобы запрос оплачивался по тарифу Compute Routes Pro, а не Compute Routes Enterprise.departure-time(departureTime) – принимает строку временной метки ISO 8601 в HTML, например"2027-03-15T16:00:00Z", или объектDateв JavaScript.autofits-camera(autofitsCamera) – помещает загруженный маршрут в область просмотра<gmp-map-3d>.
Обработка событий маршрута и чтение данных маршрута
Route3DElement отправляет gmp-load, когда маршрут отрисован, и gmp-error, если расчет маршрута не удался или не дал результатов. После срабатывания gmp-load вы можете прочитать вычисленные свойства routes, fallbackInfo и geocodingResults:
const routeElement = document.querySelector('gmp-route-3d');
routeElement.addEventListener('gmp-load', () => {
const primaryRoute = routeElement.routes?.[0];
console.log('Distance (m):', primaryRoute?.distanceMeters);
console.log('Duration:', primaryRoute?.localizedValues?.duration);
});
routeElement.addEventListener('gmp-error', () => {
console.error('Failed to load the 3D route.');
});
Когда использовать вспомогательные методы Route вместо gmp-route-3d
<gmp-route-3d> отрисовывает основной маршрут между одной точкой origin и одной точкой destination с маркером и ломаной линией по умолчанию. Используйте Route.computeRoutes со вспомогательными методами 3D, если вам нужны промежуточные путевые точки, выбор альтернативного маршрута, специальные маски полей ответа или специальные стили ломаных линий и маркеров.
Настройка отрисовки 3D-маршрута с помощью класса Route
Для пользовательских рабочих процессов с 3D-маршрутами вызовите Route.computeRoutes и отрисуйте возвращенный экземпляр Route на <gmp-map-3d>, используя вспомогательные методы 3D:
<div id="map-container" style="height: 400px; width: 100%;"></div>
<script>
async function initMap() {
const { Map3DElement, MapMode } =
await google.maps.importLibrary('maps3d');
const { Route } = await google.maps.importLibrary('routes');
const map = new Map3DElement({
mode: MapMode.HYBRID,
});
document.getElementById('map-container').append(map);
const { routes } = await Route.computeRoutes({
origin: '1800 Amphibious Blvd., Mountain View, CA 94045',
destination: 'San Francisco Ferry Building, San Francisco, CA',
travelMode: 'DRIVING',
routingPreference: 'TRAFFIC_AWARE',
extraComputations: ['TRAFFIC_ON_POLYLINE'],
fields: ['path', 'speedPaths', 'localizedValues'],
});
const route = routes?.[0];
if (!route) return;
const [polylines, markers, popover] = await Promise.all([
route.create3DPolylines({
polylineOptions: {
strokeWidth: 10,
autofitsCamera: true,
},
}),
route.createWaypointMarkers(),
route.createPopover(),
]);
map.append(...polylines, ...markers, popover);
}
</script>
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=beta&loading=async&callback=initMap">
</script>
Замените YOUR_API_KEY ключом API платформы Google Карт.
Для каждого вспомогательного метода, который вы вызываете, укажите обязательные поля в ComputeRoutesRequest.fields:
create3DPolylines: запросите'path'или'legs'для стандартных ломаных линий,'path'и'legs', когдаtravelMode–'TRANSIT', или'speedPaths'сextraComputations: ['TRAFFIC_ON_POLYLINE']для ломаных линий с цветовым обозначением загруженности дорог. ПередайтеRoutePolyline3DOptions, чтобы настроитьpolylineOptionsили задатьtrafficPolylinesDisabled.createWaypointMarkers: запрос'path'вfields. Создает маркеры начальной и конечной точек (Marker3DElementпо умолчанию илиMarkerElement,MarkerInteractiveElementилиMarker3DInteractiveElement, если указано с помощьюmarkerClassвCreateWaypointMarkersOptions). Промежуточные путевые точки этим методом не генерируются.createPopover: запросите'path'и'localizedValues'(а также'legs'для маршрутов общественного транспорта), чтобы закрепить сводкуPopoverElementв середине маршрута.