عرض المسارات على خريطة ثلاثية الأبعاد

المطوّرون في المنطقة الاقتصادية الأوروبية

يمكنك احتساب المسارات وعرضها على عنصر <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 في منتصف مسار الرحلة.

الخطوات التالية