میتوانید مسیرها را به دو روش در عنصر <gmp-map-3d> محاسبه و پرداز کنید:
- بهصورت اعلانی با
Route3DElement(<gmp-route-3d>): یک مؤلفه وب اضافه کنید که مسیرها را از Routes API درخواست میکند و چندخطیهای مسیر سهبعدی، نشانگرهای مبدأ و مقصد، و یک پنجره بالاپر خلاصه مسیر را ارائه میدهد. - بهصورت برنامهنویسیشده با روشهای کمکی
Route:Route.computeRoutesرا فراخوانی کنید و مسیر را بهcreate3DPolylines،createWaypointMarkers، وcreatePopoverارسال کنید، وقتی به نقطهمسیرهای میانی، پوششهای فیلد سفارشی، یا سبکهای چندخطی سفارشی نیاز دارید.
هر دو رویکرد در کانال v=beta
Maps JavaScript API دردسترس است. برای دستورالعملهای مربوط به بار کردن کانال بتا،
نسخهسازی را ببینید.
پیشنیازها و صورتحساب
قبلاز نمایش دادن مسیرهای سهبعدی، پروژه Google Cloud خود را راهاندازی کنید و هم
Maps JavaScript API و هم Routes API را برای آن پروژه فعال کنید. هر دو کتابخانه
maps3d و routes را بار کنید.
پرداخت هزینه برای رندر کردن <gmp-map-3d> تحت «نقشههای سهبعدی پویا» (Immersive Maps Pro) صورتحساب میشود.
هر درخواست مسیری که توسط <gmp-route-3d> یا Route.computeRoutes انجام میشود،
تحت یک شناسه کالا Compute Routes Routes API براساس ویژگیهای درخواستشده صورتحساب میشود:
| پیکربندی | سطح SKU مسیرها |
|---|---|
درخواستهای مسیر پیشفرض (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 مراجعه کنید.
افزودن مسیر سهبعدی بااستفاده از 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 را با کلید میانای برنامهسازی کاربردی Google Maps Platform جایگزین کنید.
Route3DElement بهطور خودکار رنگهای چندخطی و بالاپر خلاصه خود را با طرح رنگ روشن یا تیره <gmp-map-3d> والد مطابقت میدهد و از مشخصهها و ویژگیهای زیر پشتیبانی میکند:
originوdestination: رشته مختصات"lat,lng"، نام منبع مکان مانند"places/ChIJ-bfVTh8VkFQRDZLQnmioK9s"، یا رشته نشانی را میپذیرد. در جاوا اسکریپت، این ویژگیها همچنین اشیاء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 با روشهای کمکی سهبعدی استفاده کنید.
سفارشیسازی کردن رندر سهبعدی مسیر با کلاس «مسیر»
برای گردش کارهای سفارشی مسیر سهبعدی، Route.computeRoutes را فراخوانی کنید
و نمونه Route برگرداندهشده را بااستفاده از روشهای کمکی سهبعدی آن
در <gmp-map-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 را با کلید میانای برنامهسازی کاربردی Google Maps Platform جایگزین کنید.
فیلدهای الزامی را در 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را در نیمه مسیر لنگر کنید.