นําทางในจุดหมายเดียว

ประกาศ: fromLatLng() และ fromPlaceId() เลิกใช้งานแล้ว แต่จะยังคงใช้งานได้โดยไม่มีการอัปเดตเพิ่มเติม เราขอแนะนําให้ย้ายข้อมูลไปยัง Waypoint.Builder เวอร์ชันใหม่

ทำตามคำแนะนำนี้เพื่อวางเส้นทางภายในแอปโดยใช้ Navigation SDK สำหรับ Android คู่มือนี้ถือว่าคุณได้ผสานรวม Navigation SDK ไว้ในแอปแล้ว ตามที่อธิบายไว้ในตั้งค่าโปรเจ็กต์

สรุป

1. เพิ่มองค์ประกอบ UI ลงในแอป ไม่ว่าจะเป็นส่วนของการนำทางหรือมุมมองการนำทาง องค์ประกอบ UI นี้จะเพิ่มแผนที่แบบอินเทอร์แอกทีฟและ UI การนำทางแบบเลี้ยวต่อเลี้ยวลงในกิจกรรม
2. ขอสิทธิ์เข้าถึงตำแหน่ง แอปของคุณต้องขอสิทธิ์เข้าถึงตำแหน่งเพื่อระบุตำแหน่งของอุปกรณ์
3. เริ่มต้นใช้งาน SDK โดยใช้คลาส NavigationApi

4. กำหนดจุดหมายและควบคุมการนําทางแบบเลี้ยวต่อเลี้ยวโดยใช้คลาส Navigator ซึ่งประกอบด้วย 3 ขั้นตอนดังนี้

   • กำหนดปลายทางโดยใช้ setDestination()
   • เริ่มการนำทางด้วย startGuidance()
   • ใช้ getSimulator() เพื่อจำลองความคืบหน้าของยานพาหนะตามเส้นทางสำหรับการทดสอบ การแก้ไขข้อบกพร่อง และการแสดงแอป

5. สร้างและเรียกใช้แอป

ดูรหัส

แสดงหรือซ่อนโค้ด Java สำหรับกิจกรรมการนําทางปลายทางเดียว

package com.example.navsdksingledestination;

import android.content.pm.PackageManager;
import android.os.Bundle;
import android.util.Log;
import android.widget.Toast;
import androidx.annotation.NonNull;
import androidx.appcompat.app.AppCompatActivity;
import androidx.core.app.ActivityCompat;
import androidx.core.content.ContextCompat;
import com.google.android.gms.maps.GoogleMap.CameraPerspective;
import com.google.android.libraries.navigation.ListenableResultFuture;
import com.google.android.libraries.navigation.NavigationApi;
import com.google.android.libraries.navigation.Navigator;
import com.google.android.libraries.navigation.RoutingOptions;
import com.google.android.libraries.navigation.SimulationOptions;
import com.google.android.libraries.navigation.SupportNavigationFragment;
import com.google.android.libraries.navigation.Waypoint;

/**
 * An activity that displays a map and a navigation UI, guiding the user from their current location
 * to a single, given destination.
 */
public class NavigationActivitySingleDestination extends AppCompatActivity {

  private static final String TAG = NavigationActivitySingleDestination.class.getSimpleName();
  private Navigator mNavigator;
  private SupportNavigationFragment mNavFragment;
  private RoutingOptions mRoutingOptions;

  // Define the Sydney Opera House by specifying its place ID.
  private static final String SYDNEY_OPERA_HOUSE = "ChIJ3S-JXmauEmsRUcIaWtf4MzE";

  // Set fields for requesting location permission.
  private static final int PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION = 1;
  private boolean mLocationPermissionGranted;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Initialize the Navigation SDK.
    initializeNavigationSdk();
  }

  /**
   * Starts the Navigation SDK and sets the camera to follow the device's location. Calls the
   * navigateToPlace() method when the navigator is ready.
   */
  private void initializeNavigationSdk() {
    /*
     * Request location permission, so that we can get the location of the
     * device. The result of the permission request is handled by a callback,
     * onRequestPermissionsResult.
     */
    if (ContextCompat.checkSelfPermission(
            this.getApplicationContext(), android.Manifest.permission.ACCESS_FINE_LOCATION)
        == PackageManager.PERMISSION_GRANTED) {
      mLocationPermissionGranted = true;
    } else {
      ActivityCompat.requestPermissions(
          this,
          new String[] {android.Manifest.permission.ACCESS_FINE_LOCATION},
          PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION);
    }

    if (!mLocationPermissionGranted) {
      displayMessage(
          "Error loading Navigation SDK: " + "The user has not granted location permission.");
      return;
    }

    // Get a navigator.
    NavigationApi.getNavigator(
        this,
        new NavigationApi.NavigatorListener() {
          /** Sets up the navigation UI when the navigator is ready for use. */
          @Override
          public void onNavigatorReady(Navigator navigator) {
            displayMessage("Navigator ready.");
            mNavigator = navigator;
            mNavFragment =
                (SupportNavigationFragment)
                    getSupportFragmentManager().findFragmentById(R.id.navigation_fragment);

            // Set the last digit of the car's license plate to get route restrictions
            // in supported countries. (optional)
            // mNavigator.setLicensePlateRestrictionInfo(getLastDigit(), "BZ");

            // Set the camera to follow the device location with 'TILTED' driving view.
            mNavFragment.getMapAsync(
                googleMap -> googleMap.followMyLocation(CameraPerspective.TILTED));

            // Set the travel mode (DRIVING, WALKING, CYCLING, or TWO_WHEELER).
            mRoutingOptions = new RoutingOptions();
            mRoutingOptions.travelMode(RoutingOptions.TravelMode.DRIVING);

            // Navigate to a place, specified by Place ID.
            navigateToPlace(SYDNEY_OPERA_HOUSE, mRoutingOptions);
          }

          /**
           * Handles errors from the Navigation SDK.
           *
           * @param errorCode The error code returned by the navigator.
           */
          @Override
          public void onError(@NavigationApi.ErrorCode int errorCode) {
            switch (errorCode) {
              case NavigationApi.ErrorCode.NOT_AUTHORIZED:
                displayMessage(
                    "Error loading Navigation SDK: Your API key is "
                        + "invalid or not authorized to use the Navigation SDK.");
                break;
              case NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED:
                displayMessage(
                    "Error loading Navigation SDK: User did not accept "
                        + "the Navigation Terms of Use.");
                break;
              case NavigationApi.ErrorCode.NETWORK_ERROR:
                displayMessage("Error loading Navigation SDK: Network error.");
                break;
              case NavigationApi.ErrorCode.LOCATION_PERMISSION_MISSING:
                displayMessage(
                    "Error loading Navigation SDK: Location permission " + "is missing.");
                break;
              default:
                displayMessage("Error loading Navigation SDK: " + errorCode);
            }
          }
        });
  }

  /**
   * Requests directions from the user's current location to a specific place (provided by the
   * Google Places API).
   */
  private void navigateToPlace(String placeId, RoutingOptions travelMode) {
    Waypoint destination;
    try {
      destination = Waypoint.builder().setPlaceIdString(placeId).build();
    } catch (Waypoint.UnsupportedPlaceIdException e) {
      displayMessage("Error starting navigation: Place ID is not supported.");
      return;
    }

    // Create a future to await the result of the asynchronous navigator task.
    ListenableResultFuture<Navigator.RouteStatus> pendingRoute =
        mNavigator.setDestination(destination, travelMode);

    // Define the action to perform when the SDK has determined the route.
    pendingRoute.setOnResultListener(
        new ListenableResultFuture.OnResultListener<Navigator.RouteStatus>() {
          @Override
          public void onResult(Navigator.RouteStatus code) {
            switch (code) {
              case OK:
                // Hide the toolbar to maximize the navigation UI.
                if (getActionBar() != null) {
                  getActionBar().hide();
                }

                // Enable voice audio guidance (through the device speaker).
                mNavigator.setAudioGuidance(Navigator.AudioGuidance.VOICE_ALERTS_AND_GUIDANCE);

                // Simulate vehicle progress along the route for demo/debug builds.
                if (BuildConfig.DEBUG) {
                  mNavigator
                      .getSimulator()
                      .simulateLocationsAlongExistingRoute(
                          new SimulationOptions().speedMultiplier(5));
                }

                // Start turn-by-turn guidance along the current route.
                mNavigator.startGuidance();
                break;
              // Handle error conditions returned by the navigator.
              case NO_ROUTE_FOUND:
                displayMessage("Error starting navigation: No route found.");
                break;
              case NETWORK_ERROR:
                displayMessage("Error starting navigation: Network error.");
                break;
              case ROUTE_CANCELED:
                displayMessage("Error starting navigation: Route canceled.");
                break;
              default:
                displayMessage("Error starting navigation: " + String.valueOf(code));
            }
          }
        });
  }

  /** Handles the result of the request for location permissions. */
  @Override
  public void onRequestPermissionsResult(
      int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
    mLocationPermissionGranted = false;
    switch (requestCode) {
      case PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION:
        {
          // If request is canceled, the result arrays are empty.
          if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
            mLocationPermissionGranted = true;
          }
        }
    }
  }

  /**
   * Shows a message on screen and in the log. Used when something goes wrong.
   *
   * @param errorMessage The message to display.
   */
  private void displayMessage(String errorMessage) {
    Toast.makeText(this, errorMessage, Toast.LENGTH_LONG).show();
    Log.d(TAG, errorMessage);
  }
}

เพิ่มองค์ประกอบ UI ลงในแอป

ส่วนนี้จะอธิบายวิธีเพิ่มแผนที่แบบอินเทอร์แอกทีฟและ UI สำหรับแสดงการนําทางแบบเลี้ยวต่อเลี้ยว 2 วิธี ในกรณีส่วนใหญ่ เราขอแนะนำให้ใช้ SupportNavigationFragment ซึ่งเป็น Wrapper ของ NavigationView แทนการโต้ตอบกับ NavigationView โดยตรง ดูข้อมูลเพิ่มเติมได้ที่แนวทางปฏิบัติแนะนำสำหรับการโต้ตอบกับแผนที่การนำทาง

ใช้ข้อมูลโค้ดส่วนการนําทาง

SupportNavigationFragment คือคอมโพเนนต์ UI ที่แสดงผลลัพธ์ภาพของการนําทาง รวมถึงแผนที่แบบอินเทอร์แอกทีฟและเส้นทางแบบเลี้ยวต่อเลี้ยว คุณสามารถประกาศข้อมูลโค้ดในไฟล์เลย์เอาต์ XML ดังที่แสดงที่นี่

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.libraries.navigation.SupportNavigationFragment"
    android:id="@+id/navigation_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

หรือจะสร้างข้อมูลโค้ดผ่านโปรแกรมก็ได้ตามที่อธิบายไว้ในเอกสารประกอบของ Android โดยใช้ FragmentActivity.getSupportFragmentManager()

ใช้มุมมองการนําทาง

คอมโพเนนต์ UI สำหรับแสดงแผนที่สำหรับการนำทางมีให้บริการเป็น NavigationView อีกด้วย ซึ่งเป็นอีกทางเลือกหนึ่งนอกเหนือจากการใช้ฟragment

ข้อควรระวัง: อย่าลืมอ่านคำแนะนำที่ด้านบนของคำอธิบายคลาส NavigationView โดยเฉพาะอย่างยิ่งคำแนะนำในการส่งต่อและเรียกใช้เมธอดของวงจรชีวิตของคลาสอย่างเหมาะสมจากกิจกรรมหรือแฟรกเมนต์ที่มีมุมมอง

ขอสิทธิ์เข้าถึงตำแหน่ง

ส่วนนี้จะแสดงวิธีขอสิทธิ์เข้าถึงตําแหน่งแบบละเอียด ดูรายละเอียดเพิ่มเติมได้ที่คู่มือสิทธิ์ของ Android

1. เพิ่มสิทธิ์เป็นองค์ประกอบย่อยขององค์ประกอบ <manifest> ในไฟล์ Manifest ของ Android โดยทำดังนี้

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
       package="com.example.navsdksingledestination">
       <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   </manifest>
   

2. ขอสิทธิ์รันไทม์ในแอปเพื่อให้ผู้ใช้มีโอกาสให้หรือปฏิเสธสิทธิ์เข้าถึงตำแหน่ง โค้ดต่อไปนี้จะตรวจสอบว่าผู้ใช้ได้ให้สิทธิ์ตำแหน่งที่แน่นอนหรือไม่ หากไม่ได้ใช้ อุปกรณ์จะขอสิทธิ์ดังนี้

   if (ContextCompat.checkSelfPermission(this.getApplicationContext(),
           android.Manifest.permission.ACCESS_FINE_LOCATION)
               == PackageManager.PERMISSION_GRANTED) {
       mLocationPermissionGranted = true;
   } else {
       ActivityCompat.requestPermissions(this,
               new String[] { android.Manifest.permission.ACCESS_FINE_LOCATION },
               PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION);
   }
   
   if (!mLocationPermissionGranted) {
       displayMessage("Error loading Navigation SDK: "
               + "The user has not granted location permission.");
       return;
   }
   

3. ลบล้างการเรียกกลับ onRequestPermissionsResult() เพื่อจัดการผลลัพธ์ของคำขอสิทธิ์ ดังนี้

   @Override
   public void onRequestPermissionsResult(int requestCode, @NonNull String permissions[],
                                          @NonNull int[] grantResults) {
       mLocationPermissionGranted = false;
       switch (requestCode) {
           case PERMISSIONS_REQUEST_ACCESS_FINE_LOCATION: {
               // If request is canceled, the result arrays are empty.
               if (grantResults.length > 0
                       && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                   mLocationPermissionGranted = true;
               }
           }
       }
   }
   

เริ่มต้น Navigation SDK

คลาส NavigationApi มีตรรกะการเริ่มต้นที่อนุญาตให้แอปของคุณใช้การนําทางของ Google ส่วนนี้จะอธิบายวิธีเริ่มต้นใช้งาน Navigator รวมถึงการกําหนดค่าอื่นๆ ที่คุณเปิดใช้สําหรับแอปได้

1. เริ่มต้น Navigation SDK และลบล้างการเรียกกลับ onNavigatorReady() เพื่อเริ่มการนําทางเมื่อพร้อม

2. ไม่บังคับ กำหนดค่าแอปเพื่อให้การแจ้งเตือนคำแนะนำและบริการที่ทำงานอยู่เบื้องหลังปิดลงเมื่อผู้ใช้ปิดแอปจากอุปกรณ์ ตัวเลือกนี้ขึ้นอยู่กับรูปแบบธุรกิจของคุณ คุณอาจต้องการใช้ลักษณะการทํางานของโปรแกรมนำทางเริ่มต้น ซึ่งจะแสดงการแนะนำทางเลี้ยวและการอัปเดตตำแหน่งต่อไปแม้ว่าจะปิดแอปไปแล้วก็ตาม หากต้องการปิดการนําทางและการอัปเดตตําแหน่งเมื่อผู้ใช้ปลายทางปิดแอป ให้ใช้การกําหนดค่านี้แทน

3. ไม่บังคับ เปิดใช้ข้อจำกัดทางถนนในประเทศที่รองรับ ตั้งค่าตัวเลขสุดท้ายของป้ายทะเบียน การเรียกใช้นี้ต้องทำเพียงครั้งเดียวเท่านั้น คำขอเส้นทางต่อๆ ไปจะใช้การเรียกใช้นี้ต่อไป การเรียกใช้นี้จะใช้ได้เฉพาะในภูมิภาคที่รองรับเท่านั้น ดูประเทศที่ Navigation SDK รองรับ

   NavigationApi.getNavigator(this, new NavigationApi.NavigatorListener() {
               /**
                * Sets up the navigation UI when the navigator is ready for use.
                */
               @Override
               public void onNavigatorReady(Navigator navigator) {
                   displayMessage("Navigator ready.");
                   mNavigator = navigator;
                   mNavFragment = (NavigationFragment) getFragmentManager()
                           .findFragmentById(R.id.navigation_fragment);
   
                   // Optional. Disable the guidance notifications and shut down the app
                   // and background service when the user closes the app.
                   // mNavigator.setTaskRemovedBehavior(Navigator.TaskRemovedBehavior.QUIT_SERVICE)
   
                   // Optional. Set the last digit of the car's license plate to get
                   // route restrictions for supported countries.
                   // mNavigator.setLicensePlateRestrictionInfo(getLastDigit(), "BZ");
   
                   // Set the camera to follow the device location with 'TILTED' driving view.
                   mNavFragment.getCamera().followMyLocation(Camera.Perspective.TILTED);
   
                   // Set the travel mode (DRIVING, WALKING, CYCLING, TWO_WHEELER, or TAXI).
                   mRoutingOptions = new RoutingOptions();
                   mRoutingOptions.travelMode(RoutingOptions.TravelMode.DRIVING);
   
                   // Navigate to a place, specified by Place ID.
                   navigateToPlace(SYDNEY_OPERA_HOUSE, mRoutingOptions);
               }
   
               /**
                * Handles errors from the Navigation SDK.
                * @param errorCode The error code returned by the navigator.
                */
               @Override
               public void onError(@NavigationApi.ErrorCode int errorCode) {
                   switch (errorCode) {
                       case NavigationApi.ErrorCode.NOT_AUTHORIZED:
                           displayMessage("Error loading Navigation SDK: Your API key is "
                                   + "invalid or not authorized to use the Navigation SDK.");
                           break;
                       case NavigationApi.ErrorCode.TERMS_NOT_ACCEPTED:
                           displayMessage("Error loading Navigation SDK: User did not accept "
                                   + "the Navigation Terms of Use.");
                           break;
                       case NavigationApi.ErrorCode.NETWORK_ERROR:
                           displayMessage("Error loading Navigation SDK: Network error.");
                           break;
                       case NavigationApi.ErrorCode.LOCATION_PERMISSION_MISSING:
                           displayMessage("Error loading Navigation SDK: Location permission "
                                   + "is missing.");
                           break;
                       default:
                           displayMessage("Error loading Navigation SDK: " + errorCode);
                   }
               }
           });
   

กำหนดจุดหมาย

คลาส Navigator ให้คุณควบคุมการกำหนดค่า การเริ่มต้น และการหยุดเส้นทางการนำทางได้

ใช้ข้อมูล Navigator ที่ได้จากส่วนก่อนหน้าเพื่อกําหนดปลายทาง Waypoint ของเส้นทางนี้ หลังจากคำนวณเส้นทางแล้ว SupportNavigationFragment จะแสดงเส้นประกอบที่แสดงเส้นทางบนแผนที่และเครื่องหมายที่จุดหมาย

    private void navigateToPlace(String placeId, RoutingOptions travelMode) {
        Waypoint destination;
        try {
            destination = Waypoint.builder().setPlaceIdString(placeId).build();
        } catch (Waypoint.UnsupportedPlaceIdException e) {
            displayMessage("Error starting navigation: Place ID is not supported.");
            return;
        }

        // Create a future to await the result of the asynchronous navigator task.
        ListenableResultFuture<Navigator.RouteStatus> pendingRoute =
                mNavigator.setDestination(destination, travelMode);

        // Define the action to perform when the SDK has determined the route.
        pendingRoute.setOnResultListener(
                new ListenableResultFuture.OnResultListener<Navigator.RouteStatus>() {
                    @Override
                    public void onResult(Navigator.RouteStatus code) {
                        switch (code) {
                            case OK:
                                // Hide the toolbar to maximize the navigation UI.
                                if (getActionBar() != null) {
                                    getActionBar().hide();
                                }

                                // Enable voice audio guidance (through the device speaker).
                                mNavigator.setAudioGuidance(
                                        Navigator.AudioGuidance.VOICE_ALERTS_AND_GUIDANCE);

                                // Simulate vehicle progress along the route for demo/debug builds.
                                if (BuildConfig.DEBUG) {
                                    mNavigator.getSimulator().simulateLocationsAlongExistingRoute(
                                            new SimulationOptions().speedMultiplier(5));
                                }

                                // Start turn-by-turn guidance along the current route.
                                mNavigator.startGuidance();
                                break;
                            // Handle error conditions returned by the navigator.
                            case NO_ROUTE_FOUND:
                                displayMessage("Error starting navigation: No route found.");
                                break;
                            case NETWORK_ERROR:
                                displayMessage("Error starting navigation: Network error.");
                                break;
                            case ROUTE_CANCELED:
                                displayMessage("Error starting navigation: Route canceled.");
                                break;
                            default:
                                displayMessage("Error starting navigation: "
                                        + String.valueOf(code));
                        }
                    }
                });
    }

สร้างและเรียกใช้แอป

1. เชื่อมต่ออุปกรณ์ Android กับคอมพิวเตอร์ ทำตามวิธีการของ Android Studio ในวิธีเรียกใช้แอปในอุปกรณ์ฮาร์ดแวร์ หรือจะกำหนดค่าอุปกรณ์เสมือนโดยใช้เครื่องมือจัดการอุปกรณ์เสมือน Android (AVD) ก็ได้ เมื่อเลือกโปรแกรมจำลอง ให้ตรวจสอบว่าคุณเลือกภาพที่มี Google APIs
2. ใน Android Studio ให้คลิกตัวเลือกเมนูเรียกใช้หรือไอคอนปุ่มเล่น เลือกอุปกรณ์ตามข้อความแจ้ง

คำแนะนำเพื่อประสบการณ์การใช้งานที่ดียิ่งขึ้น

• ผู้ใช้ต้องยอมรับข้อกำหนดในการให้บริการของ Google Navigation ก่อนจึงจะใช้การนําทางได้ โดยคุณจะต้องยอมรับข้อกำหนดนี้เพียงครั้งเดียว โดยค่าเริ่มต้น SDK จะแจ้งให้ยอมรับเมื่อเรียกใช้ Navigator เป็นครั้งแรก หากต้องการ คุณเรียกใช้กล่องโต้ตอบข้อกำหนดในการให้บริการการนำทางได้ตั้งแต่เนิ่นๆ ในขั้นตอนการนำทาง UX ของแอป เช่น ในระหว่างการลงชื่อสมัครใช้หรือเข้าสู่ระบบ โดยใช้ TermsAndConditionsCheckOption
• หากต้องการปรับปรุงคุณภาพการนําทางและความแม่นยําของเวลาถึงโดยประมาณ (ETA) อย่างมีนัยสําคัญ ให้ใช้รหัสสถานที่เพื่อเริ่มต้นจุดแวะพักแทนพิกัดละติจูด/ลองจิจูด
• ตัวอย่างนี้ดึงข้อมูลจุดสังเกตปลายทางจากรหัสสถานที่ที่เฉพาะเจาะจงสำหรับโรงละครโอเปร่าซิดนีย์ คุณสามารถใช้เครื่องมือค้นหารหัสสถานที่เพื่อรับรหัสสถานที่สำหรับสถานที่อื่นๆ ที่เฉพาะเจาะจง