يمكنك احتساب المسارات وعرضها على عنصر <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 استنادًا إلى الميزات المطلوبة:
| التهيئة | فئة رمز التخزين التعريفي لـ 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 |
للاطّلاع على تفاصيل رموز التخزين التعريفية، يُرجى مراجعة مقالة استخدام 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".
يطابق 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 helper بدلاً من gmp-route-3d
يعرض <gmp-route-3d> المسار الأساسي بين
نقطة origin واحدة ونقطة destination واحدة مع
تنسيق تلقائي للعلامة والخطوط المتعدّدة. استخدِم Route.computeRoutes مع طرق المساعدة الثلاثية الأبعاد عندما تحتاج إلى نقاط على المسار وسيطة أو اختيار مسار بديل أو أقنعة حقول استجابة مخصّصة أو أنماط مخصّصة للخطوط المتعدّدة والعلامات.
تخصيص عرض المسار الثلاثي الأبعاد باستخدام فئة Route
بالنسبة إلى مسارات العمل المخصّصة للمسارات الثلاثية الأبعاد، يمكنك استدعاء 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".
أدرِج الحقول المطلوبة في 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في منتصف مسار الرحلة.