แสดงเส้นทางบนแผนที่ 3 มิติ

นักพัฒนาซอฟต์แวร์ในเขตเศรษฐกิจยุโรป (EEA)

คุณสามารถคำนวณและแสดงผลเส้นทางในองค์ประกอบ <gmp-map-3d> ได้ 2 วิธีดังนี้

  • ประกาศด้วย Route3DElement (<gmp-route-3d>): เพิ่มคอมโพเนนต์เว็บที่ขอเส้นทางจาก Routes API และแสดงผลเส้นประกอบของเส้นทาง 3 มิติ เครื่องหมายต้นทางและปลายทาง และป๊อปโอเวอร์สรุปเส้นทาง
  • ใช้เมธอดตัวช่วย Route แบบเป็นโปรแกรม: เรียกใช้ Route.computeRoutes และส่งเส้นทางไปยัง create3DPolylines, createWaypointMarkers และ createPopover เมื่อต้องการจุดอ้างอิงระดับกลาง มาสก์ฟิลด์ที่กำหนดเอง หรือรูปแบบเส้นประกอบที่กำหนดเอง

ทั้ง 2 วิธีพร้อมใช้งานในแชแนล v=beta ของ Maps JavaScript API ดูวิธีการโหลดเวอร์ชันเบต้าได้ที่การกำหนดเวอร์ชัน

ข้อกำหนดเบื้องต้นและการเรียกเก็บเงิน

ก่อนแสดงเส้นทาง 3 มิติ ให้ตั้งค่าโปรเจ็กต์ Google Cloud และเปิดใช้ทั้ง Maps JavaScript API และ Routes API สำหรับโปรเจ็กต์นั้น โหลดทั้งไลบรารี maps3d และ routes

ระบบจะเรียกเก็บเงินสำหรับการแสดงผล <gmp-map-3d> ภายใต้แผนที่ 3 มิติแบบไดนามิก (Immersive Maps Pro) ระบบจะเรียกเก็บเงินคำขอเส้นทางแต่ละรายการที่ทำโดย <gmp-route-3d> หรือ Route.computeRoutes ภายใต้ SKU 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

เพิ่มเส้นทาง 3 มิติโดยใช้ 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 Maps Platform

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 หากการคำนวณเส้นทางล้มเหลวหรือแสดงผลเป็น 0 เส้นทาง หลังจาก 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 กับเมธอดตัวช่วย 3 มิติเมื่อต้องการจุดอ้างอิงระดับกลาง การเลือกเส้นทางอื่น มาสก์ช่องการตอบกลับที่กำหนดเอง หรือเส้นประกอบและรูปแบบเครื่องหมายที่กำหนดเอง

ปรับแต่งการแสดงผลเส้นทาง 3 มิติด้วยคลาส Route

สำหรับเวิร์กโฟลว์เส้นทาง 3 มิติที่กำหนดเอง ให้เรียกใช้ Route.computeRoutes และแสดงผลอินสแตนซ์ Route ที่แสดงผลลงใน <gmp-map-3d> โดยใช้เมธอดตัวช่วย 3 มิติ ดังนี้

<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 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 ไว้ที่กึ่งกลางของเส้นทาง

ขั้นตอนถัดไป