Usługa Trasy

Omówienie

Możesz obliczyć trasę (korzystając z różnych metod transportu) za pomocą obiektu DirectionsService. Ten obiekt komunikuje się z usługą Directions Service interfejsu API Map Google, która odbiera żądania dotyczące wskazówek dojazdu i zwraca najkrótszą możliwą trasę. Czas podróży jest głównym czynnikiem, który jest optymalizowany, ale można wziąć pod uwagę inne czynniki, takie jak odległość, liczba zakrętów i wiele innych. Możesz samodzielnie obsługiwać wyniki wyszukiwania tras lub użyć obiektu DirectionsRenderer do ich renderowania.

Podczas podawania punktu początkowego lub docelowego w prośbie o trasę możesz podać ciąg znaków zapytania (np. „Chicago, IL” lub „Darwin, NSW, Australia”), wartość LatLng lub obiekt Place.

Usługa Wskazówki może zwracać wskazówki dojazdu w kilku częściach, korzystając z serii punktów pośrednich. Trasa jest wyświetlana jako linia złożona z punktów, która wyznacza trasę na mapie. Dodatkowo może być wyświetlana jako seria tekstowych opisów w elemencie <div> (np. „Skręć w prawo na rampę do Williamsburg Bridge”).

Pierwsze kroki

Zanim użyjesz usługi wyznaczania trasy w interfejsie Maps JavaScript API, upewnij się, że interfejs Directions API jest włączony w konsoli Google Cloud w tym samym projekcie, który został skonfigurowany pod kątem interfejsu Maps JavaScript API.

Aby wyświetlić listę włączonych interfejsów API:

  1. Otwórz konsolę Google Cloud.
  2. Kliknij przycisk Wybierz projekt, a potem wybierz ten sam projekt, który skonfigurowałeś/skonfigurowałaś dla interfejsu Maps JavaScript API, i kliknij Otwórz.
  3. Na liście interfejsów API w panelu odszukaj interfejs Directions API.
  4. Jeśli interfejs API jest widoczny na liście, nie musisz nic więcej robić. Jeśli interfejs API nie jest wymieniony, włącz go:
    1. U góry strony kliknij WŁĄCZ INTERFEJS API, aby wyświetlić kartę Biblioteka. Możesz też w menu po lewej stronie wybrać Biblioteka.
    2. Wyszukaj Directions API i wybierz go z listy wyników.
    3. Wybierz WŁĄCZ. Po zakończeniu procesu interfejs Directions API pojawi się na liście interfejsów API w panelu.

Ceny i zasady

Ceny

Od 16 lipca 2018 r. w przypadku Map, Tras i Miejsc obowiązuje nowy plan taryfowy „Pay-as-you-go”. Więcej informacji o nowych cenach i o ograniczeniach korzystania z usługi JavaScript Directions znajdziesz w sekcji Korzystanie i płatności w interfejsie Directions API.

Zasady

Korzystanie z usługi Mapy musi być zgodne z zasadami opisanymi w przypadku interfejsu Directions API.

Zapytania o trasę

Dostęp do usługi Wytyczanie trasy jest asynchroniczny, ponieważ interfejs API Map Google musi wykonać wywołanie do zewnętrznego serwera. Z tego powodu musisz przekazać metodę callback, która zostanie wykonana po zakończeniu przetwarzania żądania. Ta metoda wywołania zwrotnego powinna przetwarzać wyniki. Pamiętaj, że usługa Directions może zwrócić więcej niż 1 możliwą trasę jako tablicę osobnych wartości routes[].

Aby korzystać z usług kierowania w interfejsie Maps JavaScript API, utwórz obiekt typu DirectionsService i wywołaj metodę DirectionsService.route(), aby zainicjować żądanie do usługi kierowania, przekazując jej literał obiektu DirectionsRequest zawierający warunki wejściowe i metodę wywołania po otrzymaniu odpowiedzi.

Obiekt dosłowny DirectionsRequest zawiera te pola:

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidFerries: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

Poniżej opisujemy te pola:

  • origin (wymagane) określa lokalizację początkową, na podstawie której obliczane są wskazówki. Ta wartość może być podana jako String (np. „Chicago, IL”), jako wartość LatLng lub jako obiekt Place. Jeśli używasz obiektu Place, możesz podać identyfikator miejsca, ciąg znaków zapytania lub lokalizację LatLng. Identyfikatory miejsc możesz pobrać z usług geokodowania, wyszukiwania miejsc i autouzupełniania miejsc w interfejsie Maps JavaScript API. Przykład użycia identyfikatorów miejsc z autouzupełniania miejsc znajdziesz w artykule Autouzupełnianie miejsc i wskazówki dojazdu.
  • destination (wymagane) określa lokalizację końcową, dla której mają zostać wyznaczone wskazówki. Opcje są takie same jak w przypadku pola origin opisanego powyżej.
  • travelMode (wymagany) określa, jakiego środka transportu użyć do obliczenia trasy. Prawidłowe wartości są określone w sekcji Tryby podróży poniżej.
  • transitOptions (opcjonalnie) określa wartości, które mają zastosowanie tylko do żądań, w których travelMode to TRANSIT. Prawidłowe wartości opisano w sekcji Opcje transportu.
  • drivingOptions (opcjonalnie) określa wartości, które mają zastosowanie tylko do żądań, w których travelMode to DRIVING. Prawidłowe wartości opisano w sekcji Opcje jazdy.

  • unitSystem (opcjonalnie) określa system jednostek do wyświetlania wyników. Prawidłowe wartości są podane w sekcji Systemy jednostek.

  • waypoints[] (opcjonalnie) określa tablicę wartości DirectionsWaypoint. Punkty pośrednie zmieniają trasę, kierując ją przez określone lokalizacje. Punkt kontrolny jest określony jako literał obiektu z pola wymienionymi poniżej:

    • location określa lokalizację punktu kontrolnego jako LatLng, obiektu Place lub String, który zostanie zgeokodowany.
    • stopover to wartość logiczna wskazująca, że punkt kontrolny to przystanek na trasie, co powoduje rozdzielenie trasy na 2 trasy.

    (więcej informacji o punktach drogi znajdziesz poniżej w artykule Używanie punktów drogi na trasach).

  • optimizeWaypoints (opcjonalnie) określa, że trasa korzystająca z podanych danych waypoints może zostać zoptymalizowana przez przetasowanie punktów pośrednich w bardziej wydajnej kolejności. Jeśli true, usługa Wytyczanie trasy zwróci posortowane waypoints w polu waypoint_order.(Więcej informacji znajdziesz w sekcji Używanie punktów orientacyjnych na trasach poniżej).
  • provideRouteAlternatives (opcjonalny), gdy jest ustawiony na true, oznacza, że usługa Directions może podać więcej niż 1 alternatywną trasę w odpowiedzi. Pamiętaj, że podanie alternatywnych tras może wydłużyć czas odpowiedzi serwera. Ta opcja jest dostępna tylko w przypadku żądań bez punktów pośrednich.
  • avoidFerries (opcjonalny) w pozycji true wskazuje, że obliczone trasy powinny w miarę możliwości unikać promów.
  • avoidHighways (opcjonalny) w pozycji true wskazuje, że obliczone trasy powinny w miarę możliwości unikać głównych autostrad.
  • avoidTolls (opcjonalny), gdy jest ustawiony na true, oznacza, że obliczone trasy powinny w miarę możliwości unikać dróg płatnych.
  • region (opcjonalnie) określa kod regionu, podany jako 2-znakowa wartość domeny krajowej najwyższego poziomu (ccTLD). (więcej informacji znajdziesz w sekcji Uwzględnianie regionów poniżej).

Oto przykładowa wartość DirectionsRequest:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

Tryby podróży

Podczas obliczania trasy musisz określić, jakiego środka transportu chcesz użyć. Obecnie obsługiwane są te tryby podróży:

  • DRIVING (domyślne) wskazuje standardowe wskazówki dojazdu z wykorzystaniem sieci drogowej.
  • BICYCLING prosi o wskazanie trasy rowerowej po ścieżkach rowerowych i po wybranych ulicach.
  • TRANSIT zapytania o trasę dojazdu transportem publicznym.
  • WALKING prosi o wskazówki dojazdu pieszo po ścieżkach dla pieszych i chodnikach.

Aby określić, w jakim stopniu dany kraj obsługuje wskazówki, zapoznaj się z szczegółami dotyczącymi zasięgu platformy Mapy Google. Jeśli poprosisz o trasę w regionie, w którym ten typ trasy jest niedostępny, odpowiedź będzie zawierać wartość DirectionsStatus="ZERO_RESULTS".

Uwaga: wskazówki dojazdu pieszo mogą nie uwzględniać wyraźnych chodników, dlatego w przypadku wskazówek dojazdu pieszo będą wyświetlane ostrzeżenia w DirectionsResult. Ostrzeżenia te muszą być zawsze wyświetlane użytkownikowi. Jeśli nie używasz domyślnego DirectionsRenderer, ponosisz odpowiedzialność za wyświetlanie ostrzeżeń.

Opcje transportu

Dostępne opcje w przypadku prośby o wyznaczanie trasy różnią się w zależności od wybranego środka transportu. Podczas żądania wskazówek dojazdu transportu publicznego opcje avoidHighways, avoidTolls, waypoints[] i optimizeWaypoints są ignorowane. Opcje routingu dotyczące transportu możesz określić za pomocą literału obiektu TransitOptions.

Trasy komunikacji zbiorowej są podawane w czasie rzeczywistym. Trasy będą podawane tylko na czasy w przyszłości.

Obiekt TransitOptions zawiera te pola:

{
  arrivalTime: Date,
  departureTime: Date,
  modes[]: TransitMode,
  routingPreference: TransitRoutePreference
}

Poniżej opisujemy te pola:

  • arrivalTime (opcjonalnie) określa żądany czas przybycia jako obiekt Date. Jeśli podany jest czas przyjazdu, czas wyjazdu jest ignorowany.
  • departureTime (opcjonalnie) określa żądany czas wyjazdu jako obiekt Date. Jeśli podano wartość arrivalTime, wartość departureTime zostanie zignorowana. Jeśli nie określono wartości dla właściwości departureTime ani arrivalTime, domyślnie zostanie przyjęta bieżąca data i godzina.
  • modes[] (opcjonalnie) to tablica zawierająca co najmniej jeden literał obiektu TransitMode. To pole może być uwzględnione tylko wtedy, gdy żądanie zawiera klucz interfejsu API. Każdy element TransitModeokreśla preferowany środek transportu. Dozwolone wartości:
    • BUS oznacza, że obliczona trasa powinna preferować podróż autobusem.
    • RAIL oznacza, że obliczona trasa powinna preferować podróż pociągiem, tramwajem, kolejką miejską lub metrem.
    • SUBWAY oznacza, że obliczona trasa powinna preferować podróż metrem.
    • TRAIN oznacza, że obliczona trasa powinna preferować podróż pociągiem.
    • TRAM oznacza, że obliczona trasa powinna preferować przejazd tramwajem i koleją miejską.
  • routingPreference (opcjonalny) określa preferencje dotyczące tras tranzytowych. Dzięki tej opcji możesz wpływać na zwracane opcje, zamiast akceptować domyślną najlepszą trasę wybraną przez interfejs API. To pole może być określone tylko wtedy, gdy żądanie zawiera klucz API. Dozwolone wartości:
    • FEWER_TRANSFERSWskazuje, że obliczona trasa powinna preferować ograniczoną liczbę przesiadek.
    • LESS_WALKINGWskazuje, że obliczona trasa powinna preferować ograniczone spacery piesze.

Poniżej znajduje się przykład DirectionsRequest w transmisji:

{
  origin: 'Hoboken NJ',
  destination: 'Carroll Gardens, Brooklyn',
  travelMode: 'TRANSIT',
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: ['BUS'],
    routingPreference: 'FEWER_TRANSFERS'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

Opcje jazdy

Opcje wyznaczania trasy dojazdu możesz określić za pomocą obiektu DrivingOptions.

Obiekt DrivingOptions zawiera te pola:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Poniżej opisujemy te pola:

  • departureTime (wymagany, aby literalny obiekt drivingOptions był prawidłowy) określa żądany czas wyjazdu jako obiekt Date. Wartość musi być ustawiona na bieżącą godzinę lub godzinę w przyszłości. Nie może ona przypadać w przeszłości. (Aby zapewnić spójne działanie w różnych strefach czasowych, interfejs API konwertuje wszystkie daty na czas UTC). W przypadku klientów korzystających z abonamentu premium w Google Maps Platform, jeśli w żądaniu uwzględnisz parametr departureTime, interfejs API zwróci najlepszą trasę z uwzględnieniem przewidywanych warunków ruchu drogowego w danym momencie oraz uwzględni przewidywany czas przejazdu (duration_in_traffic) w odpowiedzi. Jeśli nie określisz godziny wyjazdu (czyli jeśli żądanie nie zawiera parametru drivingOptions), zwrócona trasa będzie ogólnie dobra, ale nie będzie uwzględniać warunków na drodze.
  • trafficModel (opcjonalny) określa założenia stosowane podczas obliczania czasu w ruchu. To ustawienie wpływa na wartość zwróconą w polu duration_in_traffic w odpowiedzi, która zawiera przewidywany czas w ruchu na podstawie średnich wartości historycznych. Domyślna wartość to bestguess. Dozwolone wartości:
    • bestguess (domyślnie) wskazuje, że zwrócona wartość duration_in_traffic powinna być najlepszą estymacją czasu przejazdu na podstawie znanych danych o historycznych warunkach ruchu i ruchu w czasie rzeczywistym. Im bliżej bieżącej daty departureTime, tym większy staje się ruch na żywo.
    • pessimistic oznacza, że zwrócona wartość duration_in_traffic powinna być dłuższa niż rzeczywisty czas podróży w większości dni, ale w niektórych dniach, gdy warunki drogowe są szczególnie niekorzystne, może przekroczyć tę wartość.
    • optimistic oznacza, że zwrócona wartość duration_in_traffic powinna być krótsza niż rzeczywisty czas podróży w większości dni, ale w niektóre dni o szczególnie dobrych warunkach na drodze może być krótsza niż ta wartość.

Poniżej znajdziesz przykładowy DirectionsRequest z instrukcjami dojazdu:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Systemy jednostek

Domyślnie wskazówki są obliczane i wyświetlane w układzie jednostek kraju lub regionu pochodzenia. (Uwaga: pochodzenie wyrażone za pomocą współrzędnych geograficznych zamiast adresów zawsze domyślnie używa jednostek metrycznych). Na przykład trasa z „Chicago, IL” do „Toronto, ONT” wyświetli wyniki w milach, a trasa w odwrotnym kierunku – w kilometrach. Możesz zastąpić ten system jednostek, ustawiając go wprost w żądaniu, używając jednej z tych wartości UnitSystem:

  • UnitSystem.METRIC określa użycie systemu metrycznego. Odległości są podawane w kilometrach.
  • UnitSystem.IMPERIAL określa użycie systemu imperialnego (angielskiego). Odległości są podawane w milach.

Uwaga: to ustawienie systemu jednostek dotyczy tylko tekstu wyświetlanego użytkownikowi. Wynik wyszukiwania trasy zawiera też wartości odległości, które nie są wyświetlane użytkownikowi, ale zawsze wyrażone w metrach.

Kierowanie na region w przypadku wskazówek

Usługa Mapy Google API Directions Service zwraca wyniki adresu, które są zależne od domeny (regionu lub kraju), z której wczytano bootstrap JavaScript. (ponieważ większość użytkowników wczytuje https://maps.googleapis.com/, domyślna domena jest ustawiona na Stany Zjednoczone). Jeśli wczytasz bootstrap z innej obsługiwanej domeny, otrzymasz wyniki, na które wpływa ta domena. Na przykład wyszukiwanie hasła „San Francisco” może zwracać inne wyniki w przypadku aplikacji https://maps.googleapis.com/ (w Stanach Zjednoczonych) niż w przypadku aplikacji http://maps.google.es/ (w Hiszpanii).

Za pomocą parametru region możesz też ustawić usługę Wytyczenie trasy tak, aby zwracała wyniki z uwzględnieniem określonego regionu. Ten parametr przyjmuje kod regionu podany jako dwuznakowy (niecyfrowy) tag regionu w kodzie Unicode. W większości przypadków te tagi są mapowane bezpośrednio na 2-znakowe wartości domen krajowych najwyższego poziomu (np. „uk” w „co.uk”). W niektórych przypadkach tag region obsługuje też kody ISO-3166-1, które czasami różnią się od wartości ccTLD (np. „GB” zamiast „Wielka Brytania”).

Podczas korzystania z parametrza region:

  • Podaj tylko 1 kraj lub region. Wiele wartości jest ignorowanych, co może spowodować niepowodzenie żądania.
  • Używaj tylko 2-znakowych podtagów regionów (w formacie Unicode CLDR). Wprowadzanie innych danych spowoduje wyświetlenie błędów.

Kierowanie na region jest obsługiwane tylko w przypadku krajów i regionów, w których są dostępne wskazówki. Aby sprawdzić międzynarodowy zasięg interfejsu Directions API, zapoznaj się z szczegółami zasięgu Google Maps Platform.

Wyświetlanie wskazówek

Rozpoczynanie zapytania o trasę dojazdu do usługi DirectionsService za pomocą metody route() wymaga przekazania wywołania zwrotnego, które jest wykonywane po zakończeniu obsługi żądania usługi. To wywołanie zwrotne zwróci w odpowiedzi kod DirectionsResult i kod DirectionsStatus.

Stan zapytania o wskazówki dojazdu

Funkcja DirectionsStatus może zwracać te wartości:

  • OK wskazuje, że odpowiedź zawiera prawidłowy DirectionsResult.
  • NOT_FOUND oznacza, że co najmniej jednej z lokalizacji określonych w źródle, miejscu docelowym lub punktach pośrednich żądania nie udało się przetworzyć na dane geoprzestrzenne.
  • ZERO_RESULTS oznacza, że nie udało się znaleźć trasy między miejscem wyjazdu a miejscem docelowym.
  • MAX_WAYPOINTS_EXCEEDED wskazuje, że w pliku DirectionsRequest podano zbyt wiele pól DirectionsWaypoint. Zobacz sekcję poniżej o ograniczeniach dotyczących punktów drogi.
  • MAX_ROUTE_LENGTH_EXCEEDED oznacza, że żądana trasa jest zbyt długa i nie może zostać przetworzona. Ten błąd występuje, gdy zwracane są bardziej złożone wskazówki. Spróbuj zmniejszyć liczbę punktów orientacyjnych, zakrętów lub instrukcji.
  • INVALID_REQUEST wskazuje, że podany element DirectionsRequest jest nieprawidłowy. Najczęstsze przyczyny tego kodu błędu to żądania, w których brakuje punktu początkowego lub docelowego albo żądania dotyczącego tranzytu, które zawiera punkty pośrednie.
  • OVER_QUERY_LIMIT oznacza, że strona wysłała zbyt wiele żądań w dozwolonym czasie.
  • REQUEST_DENIED oznacza, że strona internetowa nie może korzystać z usługi wskazywania kierunków.
  • UNKNOWN_ERROR oznacza, że żądanie trasy nie mogło zostać przetworzone z powodu błędu serwera. Jeśli spróbujesz ponownie, żądanie może się powieść.

Zanim przetworzysz wyniki, sprawdź, czy zapytanie o trasę zwróciło prawidłowe wyniki, sprawdzając tę wartość.

Wyświetlanie obiektu DirectionsResult

Obiekt DirectionsResult zawiera wynik zapytania o kierunki, który możesz obsłużyć samodzielnie lub przekazać do obiektu DirectionsRenderer, który może automatycznie wyświetlać wynik na mapie.

Aby wyświetlić DirectionsResult za pomocą DirectionsRenderer, wykonaj te czynności:

  1. Utwórz obiekt DirectionsRenderer.
  2. Aby powiązać go z przekazaną mapą, wywołaj metodę setMap() w renderze.
  3. Wywołaj funkcję setDirections() w renderzerze, przekazując jej parametr DirectionsResult zgodnie z opisem powyżej. Render jest elementem typu MVCObject, więc automatycznie wykrywa wszelkie zmiany w jego właściwościach i aktualizuje mapę, gdy zmienią się powiązane z nim wskazówki.

W tym przykładzie obliczamy trasę między 2 miejscami na Drodze 66, gdzie punkt początkowy i docelowy są ustawione przez podane wartości "start" i "end" na listach rozwijanych. DirectionsRenderer obsługuje wyświetlanie łagodnego przejścia między wskazanymi lokalizacjami oraz umieszczanie znaczników na początku, końcu i w miejscach pośrednich (jeśli takie występują).

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(result);
    }
  });
}

W treści HTML:

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

Zobacz przykład

Ten przykład pokazuje wskazówki dojazdu z Haight-Ashbury na Ocean Beach w San Francisco w Kalifornii za pomocą różnych środków transportu:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that JavaScript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

W treści HTML:

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

Zobacz przykład

DirectionsRenderer nie tylko obsługuje wyświetlanie łańcucha i powiązanych z nim znaczników, ale też wyświetlanie tekstowych wskazówek w postaci serii kroków. Aby to zrobić, wywołaj funkcję setPanel() w obiekcie DirectionsRenderer, przekazując jej argument <div>, w którym mają być wyświetlane te informacje. Dzięki temu wyświetlisz odpowiednie informacje o prawach autorskich oraz ostrzeżenia, które mogą być związane z wynikiem.

Instrukcje tekstowe będą podawane w preferowanym języku przeglądarki lub języku określonym podczas wczytywania kodu JavaScript interfejsu API za pomocą parametru language. (Więcej informacji znajdziesz w artykule Lokalizacja). W przypadku wskazówek dotyczących transportu publicznego czas będzie wyświetlany w strefie czasowej przystanku.

Ten przykład jest identyczny jak powyższy, ale zawiera panel <div>, w którym można wyświetlać wskazówki:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
  directionsRenderer.setPanel(document.getElementById('directionsPanel'));
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin:start,
    destination:end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

W treści HTML:

<div id="map" style="float:left;width:70%;height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height:100%"></div>

Zobacz przykład

Obiekt DirectionsResult

Gdy wysyłasz żądanie trasy do usługi DirectionsService, otrzymujesz odpowiedź zawierającą kod stanu i wynik, który jest obiektem DirectionsResult. DirectionsResult to literał obiektu z tymi polami:

  • Obiekt geocoded_waypoints[] zawiera tablicę obiektów DirectionsGeocodedWaypoint, z których każdy zawiera szczegółowe informacje o geokodowaniu punktu początkowego, docelowego i punktów pośrednich.
  • routes[] zawiera tablicę obiektów DirectionsRoute. Każda trasa wskazuje sposób dotarcia z miejsca wyjazdu do miejsca docelowego podanego w DirectionsRequest. Zazwyczaj w przypadku każdego żądania zwracana jest tylko jedna trasa, chyba że pole provideRouteAlternatives żądania ma wartość true, co powoduje zwrócenie wielu tras.

Uwaga: w przypadku alternatywnych tras właściwość via_waypoint jest nieużywana. Wersja 3.27 to ostatnia wersja interfejsu API, która dodaje dodatkowe punkty pośrednie na alternatywnych trasach. W wersjach interfejsu API 3.28 i wyższych możesz nadal stosować przeciągane wskazówki za pomocą usługi Directions, wyłączając przeciąganie alternatywnych tras. Tylko główna trasa powinna być przeciągana. Użytkownicy mogą przeciągać główną trasę, aż dopasuje się ona do trasy alternatywnej.

Punkty nawigacyjne z geokodem

DirectionsGeocodedWaypoint zawiera szczegółowe informacje o geokodowaniu punktu początkowego, docelowego i punktów pośrednich.

DirectionsGeocodedWaypoint to literał obiektu z tymi polami:

  • geocoder_status wskazuje kod stanu z operacji geokodowania. To pole może zawierać te wartości.
    • "OK" oznacza, że nie wystąpiły żadne błędy; adres został pomyślnie przeanalizowany i zwrócono co najmniej 1 geokod.
    • "ZERO_RESULTS" oznacza, że geokodowanie się udało, ale nie zwróciło żadnych wyników. Może się tak zdarzyć, jeśli geokoder otrzymał nieistniejący adres address.

  • partial_match oznacza, że geokoder nie zwrócił dokładnego dopasowania do pierwotnego żądania, ale udało mu się dopasować część żądanego adresu. Możesz sprawdzić pierwotną prośbę, aby sprawdzić, czy nie zawiera ona literówek ani niepełnego adresu.

    Częściowe dopasowania występują najczęściej w przypadku adresów ulic, które nie istnieją w miejscowości podanej w żądaniu. W przypadku dopasowania do co najmniej 2 lokalizacji w tej samej miejscowości mogą być zwracane również częściowe dopasowania. Na przykład wyszukiwanie „Hillpar St, Bristol, UK” zwróci dopasowanie częściowe zarówno do Henry Street, jak i Henrietta Street. Pamiętaj, że jeśli żądanie zawiera niepoprawnie zapisany element adresu, usługa geokodowania może zaproponować alternatywny adres. Propozycje wygenerowane w ten sposób będą też oznaczone jako częściowe dopasowanie.

  • place_idto unikalny identyfikator miejsca, którego można używać w innych interfejsach API Google. Możesz na przykład używać interfejsu place_id z biblioteką Google Places API, aby uzyskać informacje o firmie działającej lokalnie, takie jak numer telefonu, godziny otwarcia, opinie użytkowników itp. Zapoznaj się z omówieniem identyfikatora miejsca.
  • types[] to tablica wskazująca typ zwróconego wyniku. Tablica ta zawiera co najmniej 1 tag, który identyfikuje typ zwracanej w wyniku funkcji. Na przykład geokod „Chicago” zwraca „locality”, co oznacza, że „Chicago” to miasto, a także „political”, co wskazuje, że jest to jednostka polityczna.

Wskazówki dojazdu

Uwaga: starszy obiekt DirectionsTrip został przemianowany na DirectionsRoute. Pamiętaj, że trasa odnosi się teraz do całej podróży od początku do końca, a nie tylko do etapu podróży nadrzędnej.

DirectionsRoute zawiera pojedynczy wynik z określonego miejsca odjazdu i miejsca docelowego. Trasa może składać się z jednego lub większej liczby odcinków (typu DirectionsLeg), w zależności od tego, czy zostały określone jakieś punkty pośrednie. Trasa zawiera też informacje o prawach autorskich i ostrzeżenia, które muszą być wyświetlane użytkownikowi oprócz informacji o kierowaniu.

DirectionsRoute to literał obiektu z tymi polami:

  • legs[] zawiera tablicę obiektów DirectionsLeg, z których każdy zawiera informacje o odcinku trasy z 2 miejsc na danej trasie. Dla każdego punktu kontrolnego lub miejsca docelowego będzie widoczny oddzielny odcinek. (Trasa bez punktów pośrednich będzie zawierać dokładnie 1 DirectionsLeg). Każdy etap składa się z ciągu DirectionStep.
  • waypoint_order zawiera tablicę wskazującą kolejność punktów pośrednich na obliczonej trasie. Ta tablica może zawierać zmienioną kolejność, jeśli przekazano parametr DirectionsRequest.optimizeWaypoints: true.
  • overview_path zawiera tablicę LatLng, która reprezentuje przybliżoną (wygładzoną) ścieżkę uzyskanych wskazówek.
  • overview_polyline zawiera pojedynczy obiekt points, który przechowuje zaszyfrowaną reprezentację wielokąta trasy. Ta linia łamana to przybliżona (wygładzona) ścieżka uzyskanych wskazówek.
  • bounds zawiera LatLngBounds, który wskazuje granice polilinii na danej trasie.
  • copyrights zawiera tekst dotyczący praw autorskich, który ma być wyświetlany na tej trasie.
  • warnings[] zawiera tablicę ostrzeżeń, które mają być wyświetlane podczas wyświetlania tych wskazówek. Jeśli nie używasz udostępnionego obiektu DirectionsRenderer, musisz samodzielnie wyświetlać te ostrzeżenia.
  • fare zawiera łączną cenę (czyli łączny koszt biletu) na tej trasie. Ta właściwość jest zwracana tylko w przypadku zapytań dotyczących transportu publicznego i tylko w przypadku tras, na których są dostępne informacje o cenie wszystkich etapów przejazdu. Informacje obejmują:
    • currency: kod waluty w formacie ISO 4217 wskazujący walutę, w której wyrażona jest kwota.
    • value: łączna kwota opłat za przejazd w walucie wskazanej powyżej.

Nogi

Uwaga: starszy obiekt DirectionsRoute został przemianowany na DirectionsLeg.

Obiekt DirectionsLeg definiuje pojedynczy etap przejazdu z miejsca wyjazdu do miejsca docelowego na obliczonej trasie. W przypadku tras, które nie zawierają punktów pośrednich, trasa będzie składać się z jednego „odcinka”, ale w przypadku tras, które zawierają co najmniej 1 punkt pośredni, trasa będzie składać się z co najmniej 1 odcinka odpowiadającego określonym odcinkom podróży.

DirectionsLeg to literał obiektu z tymi polami:

  • steps[] zawiera tablicę obiektów DirectionsStep, która zawiera informacje o każdym kroku na trasie podróży.

  • distance wskazuje całkowity dystans przebyty na tym odcinku, jako obiekt Distance o tym kształcie:

    • value oznacza odległość w metrach
    • text zawiera ciąg znaków reprezentujący odległość, która domyślnie jest wyświetlana w jednostkach użytych w źródle. (np. mil będzie używana w przypadku każdego miejsca pochodzenia w Stanach Zjednoczonych). Możesz zastąpić ten system jednostek, podając wartość UnitSystem w pierwotnym zapytaniu. Pamiętaj, że niezależnie od tego, którego systemu jednostek używasz, pole distance.value zawsze zawiera wartość wyrażoną w metrach.

    Jeśli odległość jest nieznana, te pola mogą być nieokreślone.

  • duration wskazuje łączny czas trwania tego etapu jako obiekt Duration o tym kształcie:

    • value oznacza czas trwania w sekundach.
    • text zawiera ciąg znaków reprezentujący czas trwania.

    Jeśli czas trwania jest nieznany, te pola mogą być nieokreślone.

  • duration_in_traffic wskazuje łączny czas trwania tego odcinka, biorąc pod uwagę aktualne warunki na drodze. Wartość duration_in_traffic jest zwracana tylko wtedy, gdy są spełnione wszystkie te warunki:

    • Prośba nie zawiera punktów pośrednich postoju. Oznacza to, że nie uwzględnia punktów pośrednich, w których stopover to true.
    • Zapytanie dotyczy wskazówek dojazdu samochodem – parametr mode ma wartość driving.
    • Wartość departureTime jest zawarta w polu drivingOptions w żądaniu.
    • Warunki na drogach na żądanej trasie.

    Formularz duration_in_traffic zawiera te pola:

    • value oznacza czas trwania w sekundach.
    • text zawiera zrozumiałą dla człowieka reprezentację czasu trwania.
  • arrival_time zawiera szacowany czas dotarcia do celu na tym odcinku. Ta właściwość jest zwracana tylko w przypadku wskazówek dotyczących transportu publicznego. Wynik jest zwracany jako obiekt Time z 3 właściwościami:
    • value czas podany jako obiekt JavaScriptDate.
    • text czas podany jako ciąg znaków. Czas jest wyświetlany w strefie czasowej przystanku.
    • time_zone zawiera strefę czasową tej stacji. Wartość to nazwa strefy czasowej zdefiniowana w bazie danych stref czasowych IANA, np. „America/New_York”.
  • departure_time zawiera szacowany czas wyjazdu dla tego odcinka, podany jako obiekt Time. departure_time jest dostępna tylko w przypadku wskazówek dojazdu transportem publicznym.
  • start_location zawiera LatLng tego etapu. Usługa Directions Web Service oblicza trasy między lokalizacjami, korzystając z najbliższej opcji transportu (zwykle drogi) w punktach początkowym i końcowym, dlatego start_location może różnić się od podanego punktu początkowego tego etapu, jeśli na przykład droga nie znajduje się w pobliżu tego punktu.
  • end_location zawiera LatLng miejsca docelowego tego etapu. Ponieważ usługa DirectionsService oblicza trasy między lokalizacjami, używając najbliższej opcji transportu (zwykle drogi) na początku i na końcu, end_location może być inna niż podana lokalizacja docelowego przystanku, jeśli na przykład droga nie znajduje się w pobliżu miejsca docelowego.
  • start_address zawiera adres zrozumiały dla człowieka (zwykle adres ulicy) początku tego etapu.

    Treści te należy odczytać w postaci, w której są zapisane. Nie należy ich analizować programowo.
  • end_address zawiera adres zrozumiały dla człowieka (zwykle adres ulicy) miejsca docelowego tego etapu.

    Treści te należy odczytać w postaci, w której są zapisane. Nie należy ich analizować programowo.

Etapy trasy

DirectionsStep to najbardziej elementarna jednostka na trasie, która zawiera jeden krok opisujący konkretny, pojedynczy instrukcję dotyczącą podróży. Przykład: „Skręć w lewo na W. 4th St. Krok nie tylko opisuje instrukcję, ale zawiera też informacje o odległości i czasie trwania, które pokazują, jak ten krok jest powiązany z następnym. Na przykład krok oznaczony jako „Wjedź na I-80 w kierunku zachodnim” może zawierać czas trwania „37 mil” i „40 minut”, co oznacza, że następny krok znajduje się w odległości 37 mil lub 40 minut od tego kroku.

Gdy korzystasz z usługi Directions do wyszukiwania wskazówek dotyczących transportu, tablica steps zawiera dodatkowe informacje dotyczące transportu w postaci obiektu transit. Jeśli trasa obejmuje różne środki transportu, szczegółowe wskazówki dotyczące chodzenia lub jazdy zostaną podane w tablicy steps[]. Na przykład etap pieszy będzie zawierać wskazówki z miejsca początkowego do miejsca docelowego: „Przejdź do Innes Ave & Fitch St”. Ten krok będzie zawierać szczegółowe wskazówki dojścia do tego miejsca w tablicy steps[], takie jak „Skręć na północny zachód”, „Skręć w lewo na Arelious Walker” i „Skręć w lewo na Innes Ave”.

DirectionsStep to literał obiektu z tymi polami:

  • instructions zawiera instrukcje dotyczące tego kroku w ciągu tekstowym.
  • distance zawiera odległość pokonaną w tym kroku do następnego kroku w postaci obiektu Distance. (patrz opis w sekcji DirectionsLeg powyżej). To pole może być nieokreślone, jeśli odległość jest nieznana.
  • duration zawiera szacowany czas wykonania kroku do następnego kroku w postaci obiektu Duration. (patrz opis w sekcji DirectionsLeg powyżej). To pole może być nieokreślone, jeśli czas trwania jest nieznany.
  • start_location zawiera geokodowany LatLng punktu początkowego tego kroku.
  • end_location zawiera LatLng punktu końcowego tego kroku.
  • Obiekt polyline zawiera pojedynczy obiekt points, który przechowuje zaszyfrowaną reprezentację wielokąta kroku. Ten poliliniarny łuk jest przybliżoną (wygładzoną) ścieżką kroku.
  • steps[] to literałowy obiekt DirectionsStep zawierający szczegółowe wskazówki dojazdu pieszo lub samochodem. Podkroki są dostępne tylko w przypadku wskazówek dotyczących transportu publicznego.
  • travel_mode zawiera TravelMode użyty w tym kroku. Trasa może obejmować połączenie trasy pieszej i publicznego transportu.
  • path zawiera tablicę LatLngs opisująca przebieg tego kroku.
  • transit zawiera informacje o transporcie, takie jak czas przyjazdu i odjazdu oraz nazwa linii.

Informacje o transporcie

Wskazówki dojazdu komunikacją zbiorową zwracają dodatkowe informacje, które nie są istotne w przypadku innych środków transportu. Te dodatkowe właściwości są dostępne za pomocą obiektu TransitDetails, zwracanego jako właściwość obiektu DirectionsStep. Z obiektu TransitDetails możesz uzyskać dostęp do dodatkowych informacji o obiektach TransitStop, TransitLine, TransitAgency i VehicleType, jak opisano poniżej.

Szczegóły dotyczące transportu

Obiekt TransitDetails udostępnia te właściwości:

  • arrival_stop zawiera obiekt TransitStop reprezentujący stację docelową/przystan z tymi właściwościami:
    • name nazwa stacji/przystanku. np. „Union Square”.
    • location lokalizacja stacji/przystanku transportu publicznego, reprezentowana jako LatLng.
  • departure_stop zawiera obiekt TransitStop reprezentujący stację/przystanek odjazdu.
  • arrival_time zawiera czas przybycia określony jako obiekt Time z 3 właściwościami:
    • value czas podany jako obiekt JavaScriptDate.
    • text czas podany jako ciąg znaków. Czas jest wyświetlany w strefie czasowej przystanku.
    • time_zone zawiera strefę czasową tej stacji. Wartość to nazwa strefy czasowej zdefiniowana w bazie danych stref czasowych IANA, np. „Ameryka/Nowy Jork”.
  • departure_time zawiera czas wyjazdu określony jako obiekt Time.
  • headsign określa kierunek jazdy na tej linii, jak jest on oznaczony na pojeździe lub na przystanku. Często jest to stacja końcowa.
  • headway (jeśli jest dostępny) określa spodziewaną liczbę sekund pomiędzy odjazdami z tego samego przystanku w tym czasie. Na przykład, jeśli wartość headway wynosi 600, w przypadku spóźnienia autobusu musisz się spodziewać 10-minutowego oczekiwania.
  • line zawiera literał obiektu TransitLine, który zawiera informacje o linii tranzytowej użytej w tym kroku. W elementach TransitLine podana jest nazwa i operator linii, a także inne właściwości opisane w dokumentacji referencyjnej dotyczącej elementu TransitLine.
  • num_stops zawiera liczbę przystanków na tym etapie. Obejmuje przystanek docelowy, ale nie przystanek początkowy. Jeśli na przykład Twoje wskazówki obejmują wyjście z przystanku A, przejście przez przystanki B i C oraz przybycie na przystanek D, funkcja num_stops zwróci 3.

Linia transportu publicznego

Obiekt TransitLine udostępnia te właściwości:

  • name zawiera pełną nazwę tej linii transportu publicznego, np. „7 Avenue Express” lub „14th St Crosstown”.
  • short_name zawiera krótką nazwę tej linii transportu publicznego. Zwykle jest to numer wiersza, np. „2” lub „M14”.
  • agencies to tablica zawierająca 1 obiekt TransitAgency. Obiekt TransitAgency zawiera informacje o operatorze tej linii, w tym: te właściwości:
    • name zawiera nazwę agencji transportowej.
    • phone zawiera numer telefonu agencji transportowej.
    • url zawiera adres URL przewoźnika.

    Uwaga: jeśli renderujesz wskazówki dojazdu ręcznie zamiast używać obiektu DirectionsRenderer, musisz wyświetlić nazwy i adresy URL firm transportowych obsługujących wyniki podróży.

  • url zawiera adres URL tej linii transportu publicznego podany przez przewoźnika.
  • icon zawiera adres URL ikony powiązanej z tą linią. Większość miast będzie używać ogólnych ikon, które różnią się w zależności od typu pojazdu. Niektóre linie transportu publicznego, takie jak nowojorskie metro, mają ikony charakterystyczne dla danej linii.
  • color zawiera kolor często używany na tablicach informacyjnych dotyczących tego środka transportu. Kolor zostanie określony jako ciąg szesnastkowy, np. #FF0033.
  • text_color zawiera kolor tekstu powszechnie używany do oznaczania tej linii. Kolor zostanie określony jako ciąg szesnastkowy.
  • vehicle zawiera obiekt Vehicle, który zawiera te właściwości:
    • name zawiera nazwę pojazdu na tej linii. np. „Metro”.
    • type zawiera typ pojazdu używanego na tej trasie. Pełną listę obsługiwanych wartości znajdziesz w dokumentacji Typ pojazdu.
    • icon zawiera adres URL ikony zwykle kojarzonej z tym typem pojazdu.
    • local_icon zawiera adres URL ikony powiązanej z tym typem pojazdu na podstawie lokalnych znaków drogowych.

Typ pojazdu

Obiekt VehicleType udostępnia te właściwości:

Wartość Definicja
VehicleType.RAIL Rail.
VehicleType.METRO_RAIL Kolej miejska.
VehicleType.SUBWAY Podziemna kolej miejska.
VehicleType.TRAM Kolej miejska na powierzchni.
VehicleType.MONORAIL Kolej jednoszynowa.
VehicleType.HEAVY_RAIL Koleje ciężkie.
VehicleType.COMMUTER_TRAIN Kolej podmiejska.
VehicleType.HIGH_SPEED_TRAIN Pociąg szybkobieżny.
VehicleType.BUS Autobus.
VehicleType.INTERCITY_BUS Autobus dalekobieżny.
VehicleType.TROLLEYBUS Trolejbus.
VehicleType.SHARE_TAXI W przypadku wspólnej taksówki pasażerowie mogą wsiadać i wysiadać w dowolnym miejscu na trasie.
VehicleType.FERRY Prom.
VehicleType.CABLE_CAR Pojazd poruszający się na kablu, zwykle na ziemi. Samochody szynowe mogą być typu VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT Kolej gondolowa.
VehicleType.FUNICULAR Pojazd ciągnięty na stromym wzniesieniu za pomocą kabla. Kolejka linowa składa się zazwyczaj z 2 wagoników, z których każdy jest przeciwwagą dla drugiego.
VehicleType.OTHER Wszystkie inne pojazdy będą zwracać ten typ.

Sprawdzanie instrukcji i wyników

Komponenty DirectionsResults (DirectionsRoute, DirectionsLeg, DirectionsStep i TransitDetails) mogą być sprawdzane i wykorzystywane podczas analizowania odpowiedzi na żądanie dotyczące wskazówek.

Ważne: jeśli renderujesz wskazówki dotyczące transportu publicznego ręcznie zamiast używać obiektu DirectionsRenderer, musisz wyświetlić nazwy i adresy URL instytucji transportowych obsługujących wyniki podróży.

W tym przykładzie pokazano trasy piesze do niektórych atrakcji turystycznych w Nowym Jorku. Sprawdzamy trasę, aby dodać znaczniki do każdego kroku, a także dołączamy do InfoWindow informacje z instrukcjami dotyczącymi tego kroku.DirectionsStep

Uwaga: ponieważ obliczamy trasy piesze, wyświetlamy użytkownikowi ostrzeżenia w osobnym panelu <div>.

var map;
var directionsRenderer;
var directionsService;
var stepDisplay;
var markerArray = [];

function initMap() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsRenderer = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
      origin: start,
      destination: end,
      travelMode: 'WALKING'
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsRenderer.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

W treści HTML:

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

Zobacz przykład

Korzystanie z punktów pośrednich na trasach

Jak wspomniano w DirectionsRequest, podczas obliczania tras za pomocą usługi Directions na potrzeby wskazówek dojazdu pieszo, rowerem lub samochodem możesz też określić punkty pośrednie (typu DirectionsWaypoint). Punkty pośrednie są niedostępne w przypadku wskazówek dojazdu transportem publicznym. Punkty pośrednie umożliwiają obliczanie tras przez dodatkowe lokalizacje. W takim przypadku zwrócona trasa przebiega przez podane punkty pośrednie.

waypoint składa się z tych pól:

  • location (wymagany) określa adres punktu kontrolnego.
  • stopover (opcjonalnie) wskazuje, czy ten punkt drogi jest rzeczywistym przystankiem na trasie (true) czy tylko preferowanym punktem na trasie (false). Domyślnie przystanki są ustawione jako true.

Domyślnie usługa Wytyczanie trasy oblicza trasę przez podane punkty kontrolne w podanej kolejności. Opcjonalnie możesz przekazać optimizeWaypoints: true w ramach DirectionsRequest, aby umożliwić usłudze Directions zoptymalizowanie podawanej trasy przez przetasowanie punktów pośrednich w bardziej wydajnej kolejności. (Ta optymalizacja jest zastosowaniem problemu sprzedawcy obwoźnego). Czas przejazdu jest głównym czynnikiem, który jest optymalizowany, ale przy wyborze najskuteczniejszej trasy można wziąć pod uwagę inne czynniki, takie jak odległość, liczba zakrętów i wiele innych. Aby można było zoptymalizować trasę, wszystkie punkty pośrednie muszą być punktami pośrednimi w usłudze Mapy.

Jeśli usługa Directions zostanie poproszona o zoptymalizowanie kolejności punktów pośrednich, ich kolejność zostanie zwrócona w polu waypoint_order obiektu DirectionsResult.

W tym przykładzie obliczamy trasy przez Stany Zjednoczone, korzystając z różnych punktów początkowych, końcowych i przelotnych. (aby wybrać wiele punktów drogi, podczas wybierania elementów na liście naciśnij Ctrl i kliknij). Pamiętaj, że sprawdzamy tagi routes.start_address i routes.end_address, aby uzyskać tekst dotyczący punktu początkowego i końcowego każdej trasy.

TypeScript

function initMap(): void {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 6,
      center: { lat: 41.85, lng: -87.65 },
    }
  );

  directionsRenderer.setMap(map);

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      calculateAndDisplayRoute(directionsService, directionsRenderer);
    }
  );
}

function calculateAndDisplayRoute(
  directionsService: google.maps.DirectionsService,
  directionsRenderer: google.maps.DirectionsRenderer
) {
  const waypts: google.maps.DirectionsWaypoint[] = [];
  const checkboxArray = document.getElementById(
    "waypoints"
  ) as HTMLSelectElement;

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: (checkboxArray[i] as HTMLOptionElement).value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: (document.getElementById("start") as HTMLInputElement).value,
      destination: (document.getElementById("end") as HTMLInputElement).value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById(
        "directions-panel"
      ) as HTMLElement;

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance!.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

function initMap() {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 6,
    center: { lat: 41.85, lng: -87.65 },
  });

  directionsRenderer.setMap(map);
  document.getElementById("submit").addEventListener("click", () => {
    calculateAndDisplayRoute(directionsService, directionsRenderer);
  });
}

function calculateAndDisplayRoute(directionsService, directionsRenderer) {
  const waypts = [];
  const checkboxArray = document.getElementById("waypoints");

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: document.getElementById("start").value,
      destination: document.getElementById("end").value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById("directions-panel");

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

window.initMap = initMap;
index.js

Limity i ograniczenia dotyczące punktów pośrednich

Obowiązują te limity i ograniczenia korzystania:

  • Maksymalna liczba punktów pośrednich dozwolonych podczas korzystania z usługi Directions w Maps JavaScript API wynosi 25, dodając do tego punkt początkowy i docelowy. Te same limity obowiązują w przypadku usługi internetowej Directions API.
  • W przypadku usługi internetowej interfejsu Directions API klienci mogą podać 25 punktów pośrednich oraz punkt początkowy i docelowy.
  • Klienci korzystający z abonamentu Premium w Google Maps Platform mogą ustawić 25 punktów pośrednich, a także punkt początkowy i docelowy.
  • Punkty pośrednie nie są obsługiwane w przypadku wskazówek dojazdu transportem publicznym.

Przeciągane wskazówki

Użytkownicy mogą modyfikować wyświetlane trasy rowerowe, piesze lub samochodowe za pomocą dynamicznego DirectionsRenderer, jeśli są one przeciągane, co pozwala użytkownikowi wybierać i zmieniać trasy przez klikanie i przeciąganie ich na mapie. Możesz określić, czy wyświetlacz renderera umożliwia przeciąganie kierunków, ustawiając właściwość draggable na true. Wskazówki dojazdu transportem publicznym nie mogą być przeciągane.

Gdy wskazówki można przeciągać, użytkownik może wybrać dowolny punkt na ścieżce (lub punkt orientacyjny) wyrenderowanego wyniku i przenieść wskazany komponent w nowe miejsce. Element DirectionsRenderer będzie się dynamicznie aktualizować, aby wyświetlać zmodyfikowaną ścieżkę. Po zwolnieniu przycisku na mapie zostanie dodany punkt orientacyjny przejściowy (oznaczony małym białym znacznikiem). Wybranie i przesunięcie odcinka ścieżki spowoduje zmianę tego odcinka trasy, a wybranie i przesunięcie znacznika punktu kontrolnego (w tym punktu początkowego i końcowego) zmieni odcinki trasy przechodzące przez ten punkt kontrolny.

Ponieważ przeciągane wskazówki są modyfikowane i renderowane po stronie klienta, warto monitorować i obsługiwać zdarzenie directions_changed w komponencie DirectionsRenderer, aby otrzymywać powiadomienia, gdy użytkownik zmodyfikuje wyświetlane wskazówki.

Poniższy kod pokazuje podróż z Perth na zachodnim wybrzeżu Australii do Sydney na wschodnim wybrzeżu. Kod sprawdza zdarzeniedirections_changed, aby zaktualizować łączną odległość wszystkich etapów podróży.

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -24.345, lng: 134.46 }, // Australia.
    }
  );

  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel") as HTMLElement,
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });

  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(
  origin: string,
  destination: string,
  service: google.maps.DirectionsService,
  display: google.maps.DirectionsRenderer
) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result: google.maps.DirectionsResult) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result: google.maps.DirectionsResult) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i]!.distance!.value;
  }

  total = total / 1000;
  (document.getElementById("total") as HTMLElement).innerHTML = total + " km";
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -24.345, lng: 134.46 }, // Australia.
  });
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel"),
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });
  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer,
  );
}

function displayRoute(origin, destination, service, display) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }

  total = total / 1000;
  document.getElementById("total").innerHTML = total + " km";
}

window.initMap = initMap;
index.js
Zobacz przykład

Wypróbuj próbkę