نمایش مسیرها روی نقشه سه‌بعدی

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

می‌توانید مسیرها را به دو روش در عنصر <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 را در نیمه مسیر لنگر کنید.

مراحل بعدی