پیمایش مسیر تک‌مقصدی

توجه: fromLatLng() و fromPlaceId() منسوخ شده‌اند، اما بدون به‌روزرسانی‌های بیشتر دردسترس خواهند بود. توصیه می‌کنیم به Waypoint.Builder جدید منتقل شوید.

این راهنما را دنبال کنید تا بااستفاده از «کیت توسعه نرم‌افزار پیمایش» برای Android، مسیری را در برنامه‌تان ترسیم کنید. این راهنما فرض می‌کند که قبلاً Navigation SDK را در برنامه‌تان ادغام کرده‌اید، همان‌طور که در راه‌اندازی پروژه شرح داده شده است.

خلاصه

1. عنصر میانای کاربر را به‌عنوان قطعه پیمایش یا نمای پیمایش به برنامه‌تان اضافه کنید. این عنصر میانای کاربر، نقشه تعاملی و میانای کاربر ناوبری گام‌به‌گام را به فعالیت شما اضافه می‌کند.
2. درخواست اجازه‌های مکان. برنامه شما باید برای تعیین مکان دستگاه، اجازه مکان درخواست کند.
3. کیت توسعه نرم‌افزار را بااستفاده از کلاس NavigationApi مقداردهی اولیه کنید.

4. بااستفاده از کلاس Navigator مقصد را تنظیم کنید و ناوبری گام‌به‌گام را کنترل کنید. این کار شامل سه مرحله است:

   • تنظیم کردن مقصد بااستفاده از 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.AudioGuidanceSettings;
import com.google.android.libraries.navigation.ListenableResultFuture;
import com.google.android.libraries.navigation.NavigationApi;
import com.google.android.libraries.navigation.NavigationFragment;
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.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 NavigationFragment 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 =
                (NavigationFragment)
                    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).
                AudioGuidanceSettings audioSettings =
                    AudioGuidanceSettings.builder()
                        .setGuidanceMode(
                            AudioGuidanceSettings.GuidanceMode.VOICE_ALERTS_AND_GUIDANCE)
                        .build();
                mNavigator.setAudioGuidanceSettings(audioSettings);

                // 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;
              case ROUTING_TIMEOUT:
                displayMessage("Error starting navigation: Routing timed out.");
                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);
  }
}

افزودن عنصر میانای کاربر به برنامه

این بخش دو روش را پوشش می‌دهد که می‌توانید نقشه تعاملی و میانای کاربر را برای نمایش ناوبری گام‌به‌گام اضافه کنید. در اکثر موارد، توصیه می‌کنیم به‌جای تعامل مستقیم با NavigationView، از NavigationFragment که پوششی برای NavigationView است استفاده کنید. برای اطلاعات بیشتر، روال‌های مطلوب تعامل با نقشه ناوبری را ببینید.

توجه: SupportNavigationFragment در کیت توسعه نرم‌افزار ناوبری نسخه ۸.۰.۰ منسوخ شده است. اگر کد موجود را به‌روز می‌کنید، به‌روزرسانی به NavigationFragment را ببینید.

استفاده از قطعه پیمایش

NavigationFragment مؤلفه واسط کاربری است که خروجی دیداری ناوبری را نمایش می‌دهد، ازجمله نقشه تعاملی و مسیر گام‌به‌گام. می‌توانید قطعه را در فایل طرح‌بندی 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.NavigationFragment"
    android:id="@+id/navigation_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

یا می‌توانید قطعه را به‌صورت برنامه‌نویسی‌شده، همان‌طور که در اسناد Android شرح داده شده است، بااستفاده از FragmentActivity.getSupportFragmentManager() بسازید.

استفاده از نمای پیمایش

به‌عنوان جایگزینی برای قطعه، مؤلفه میانای کاربر برای نمایش نقشه برای ناوبری نیز به‌صورت NavigationView دردسترس است.

احتیاط: حتماً راهنمای بالای شرح کلاس NavigationView را بخوانید، به‌ویژه توصیه مربوط به بازارسال و فراخوانی صحیح روش‌های چرخه حیات از فعالیت یا قطعه حاوی نما.

درخواست اجازه مکان

این بخش نحوه درخواست اجازه مکان دقیق را نشان می‌دهد. برای جزئیات بیشتر، راهنمای اجازه‌های Android را ببینید.

1. اجازه را به‌عنوان فرزند عنصر <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;
                   }
               }
           }
       }
   

مقداردهی اولیه کیت توسعه نرم‌افزار پیمایش

کلاس NavigationApi منطق مقداردهی اولیه‌ای را ارائه می‌دهد که به برنامه شما اجازه می‌دهد از ناوبری Google استفاده کند. این بخش نحوه مقداردهی اولیه راهبر را به‌همراه برخی پیکربندی‌های دیگر که می‌توانید برای برنامه‌تان فعال کنید پوشش می‌دهد:

1. «کیت توسعه نرم‌افزار ناوبری» را مقداردهی اولیه کنید و فراخوان برگشتی 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) getSupportFragmentManager()
                               .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 را برای این سفر تنظیم کنید. پس‌از محاسبه مسیرها، NavigationFragment چندخطی‌ای را نمایش می‌دهد که نشان‌دهنده مسیر روی نقشه است، و نشانگری در مقصد.

```none
    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).
                                AudioGuidanceSettings audioSettings =
                                        AudioGuidanceSettings.builder()
                                                .setGuidanceMode(
                                                        AudioGuidanceSettings.GuidanceMode
                                                                .VOICE_ALERTS_AND_GUIDANCE)
                                                .build();
                                mNavigator.setAudioGuidanceSettings(audioSettings);

                                // 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;
                            case ROUTING_TIMEOUT:
                                displayMessage("Error starting navigation: Routing timed out.");
                                break;
                            default:
                                displayMessage("Error starting navigation: "
                                        + String.valueOf(code));
                        }
                    }
                });
    }
```

پیکربندی راهنمای صوتی

برای تنظیم کردن تنظیمات راهنمای صوتی (ازجمله حالت راهنمایی و سطح میزان صدا)، یک شیء AudioGuidanceSettings را به راهبر ارسال کنید.

ناوبر از آخرین تنظیمات پایدار استفاده می‌کند، یا به‌طور پیش‌فرض روی میزان صدای عادی و هشدارهای صوتی با راهنمایی قرار می‌گیرد.

مثال زیر نحوه پیکربندی ناوبر را برای استفاده از صدای کم و فعال کردن هشدارهای صوتی و راهنمایی گام‌به‌گام نشان می‌دهد:

// Configure audio guidance settings.
AudioGuidanceSettings audioSettings = AudioGuidanceSettings.builder()
        .setGuidanceMode(AudioGuidanceSettings.GuidanceMode.VOICE_ALERTS_AND_GUIDANCE)
        .setVolumeLevel(AudioGuidanceSettings.VolumeLevel.LOW)
        .build();

mNavigator.setAudioGuidanceSettings(audioSettings);

ساختن و اجرای برنامه

1. دستگاه Android را به رایانه وصل کنید. دستورالعمل‌های Android Studio را درباره نحوه اجرای برنامه‌ها در دستگاه سخت‌افزاری دنبال کنید. یا اینکه می‌توانید دستگاه مجازی را بااستفاده از مدیر دستگاه مجازی Android (AVD) پیکربندی کنید. هنگام انتخاب شبیه‌ساز، مطمئن شوید تصویری را انتخاب می‌کنید که شامل Google APIs باشد.
2. در Android Studio، روی گزینه منو اجرا یا اجرا کلیک کنید. دستگاهی را طبق درخواست انتخاب کنید.

نکاتی برای بهبود تجربه کاربری

• کاربر باید «شرایط خدمات Google Navigation» را بپذیرد تا ناوبری دردسترس قرار گیرد. این پذیرش فقط یک‌بار لازم است. به‌طور پیش‌فرض، کیت توسعه نرم‌افزار اولین باری که ناوبر فراخوانده می‌شود، درخواست پذیرش می‌کند. اگر ترجیح می‌دهید، می‌توانید کادر گفتگوی «شرایط خدمات ناوبری» را در نقطه‌ای اولیه در جریان تجربه کاربری برنامه‌تان، مثلاً درطول ثبت‌نام یا ورود به سیستم، بااستفاده از TermsAndConditionsCheckOption راه‌اندازی کنید.
• برای بهبود قابل‌توجه کیفیت ناوبری و دقت زمان تخمینی رسیدن، از شناسه جا برای مقداردهی اولیه نقطه‌مسیر استفاده کنید، نه از مختصات طول/عرض جغرافیایی.
• این نمونه نقطه‌مسیر مقصد را از شناسه مکان خاصی برای «تالار اپرای سیدنی» می‌گیرد. می‌توانید از یابنده شناسه مکان برای دریافت شناسه مکان برای مکان‌های خاص دیگر استفاده کنید.