توفر خلاصة البيانات باتّجاهات مفصّلة معلومات التنقّل فقط للأجهزة غير المصمم لإرشادات التنقل المستند إلى الخريطة. يوفر مناورات قادمة العناصر التي تقدمها:

• الرموز (اليسار، اليمين، دوران على شكل حرف U)
• تحويل الأرقام في الدوارات
• أسماء الطرق
• المسافات والوقت المقدرة إلى خطوة التنقل التالية أو النهائية الوجهة

ويمكنك استخدام الخلاصة المفصّلة للحصول على تجارب تتيح واجهة مستخدم حزمة تطوير البرامج (SDK) الخاصة بالتنقّل غير مناسبة، مثل Android Auto أو للمؤسسات الصغيرة الشاشة التي لا تتوفّر فيها حزمة Android كاملة. على سبيل المثال، هذا الأمر لسائقي المركبات ذات العجلتين، حيث يمكنك عرض إرشادات التنقل فقط لمساعدتهم في الوصول إلى وجهاتهم بشكل أسرع وأكثر بثقة مع الحد الأدنى من عوامل التشتيت.

ولاستخدام حزمة SDK، يجب إنشاء خدمة وتسجيلها لدى حزمة تطوير البرامج (SDK) للتنقّل لنظام التشغيل Android حتى تتلقّى معلومات التنقّل الجديدة في الوقت الفعلي (حوالي مرة واحدة في الثانية أثناء التنقل).

يوضح لك هذا المستند كيفية إنشاء وتسجيل خدمة تنقل تلقّي معلومات التنقّل من حزمة تطوير البرامج (SDK) وتوفير حالة التنقّل إلى الجهاز المستلِم.

نظرة عامة

يصف هذا القسم كيفية إضافة مكتبة TurnByTurn إلى مشاريعك التدفق عالي المستوى لإنشاء وظائف اتّجاهات مفصّلة.

إضافة مكتبة TurnByTurn إلى مشروعك باستخدام Maven (يُنصح بهذا الخيار)

لاستخدام إصدار مستقل من مكتبةTurnByTurn، يُرجى اتّباع الخطوات التالية:

1. اضبط بيئتك للوصول إلى مستودع Maven المضيف:

   Maven

   أضِف ما يلي إلى ملف pom.xml:

       <project>
         ...
         <repositories>
           <repository>
             <id>google-maven-repository</id>
             <url>https://maven.google.com</url>
           </repository>
         </repositories>
         ...
       </project>
       
       

   Gradle

   أضِف ما يلي إلى ملف build.gradle:

   repositories {
       ...
       google()
   }
       

أضِف التبعية التالية إلى إعدادات Maven أو Gradle:

2. Maven

   <dependencies>
   ...
   <dependency>
         <groupId>com.google.android.maps</groupId>
         <artifactId>google_turnbyturn</artifactId>
         <version>1.0.0</version>
   </dependency>
   </dependencies>
       
       

   Gradle

   dependencies {
     ...
     implementation 'com.google.android.maps:google_turnbyturn:1.0.0'
   }
       

إضافة مكتبة TurnByTurn إلى مشروعك باستخدام ملف JAR تم تنزيله (كبديل)

تتوفّر مكتبة TurnByTurn كملف JAR في مجلد حزمة تطوير البرامج (SDK) هذا. إذا لم تكن تملك إذن الوصول، يُرجى التواصل مع ممثل حسابك.

1. نزِّل ملف "google_turnbyturn_*.jar" وألغِ ضغطه.
2. انسخ ملف JAR الذي تم تنزيله إلى دليل app/libs الخاص بمشروعك.

3. أضِف ما يلي إلى build.gradle لتضمين JAR في تصميمك.

   dependencies {
      ...
      api fileTree(include: ['*.jar'], dir: 'libs')
   }
   

استخدام مكتبة TurnByTurn

إليك الخطوات رفيعة المستوى لتفعيل الوظائف المفصّلة. تشير رسالة الأشكال البيانية تقدم الأقسام التالية تفاصيل حول كل خطوة.

1. أنشئ خدمة لتلقّي تحديثات التنقّل.

2. تسجيل الخدمة

3. فهم حالات التنقّل:

4. الاطّلاع على مثال عرض خاص بالتنقل يعرض العناصر الأساسية

إنشاء خدمة لتلقّي تحديثات التنقّل

ترتبط حزمة SDK للتنقل بخدمة TurnByTurn إرسال تحديثات التنقل إليه من خلال نظام التشغيل Android Messenger . يمكنك إنشاء خدمة تنقّل جديدة لهذه التحديثات أو استخدام خدمة تنقّل حالية. خدمة ما.

تكمن فائدة استخدام خدمة لتلقي تحديثات التنقل في أن الخدمة يمكن أن يعيش في عملية خلفية منفصلة.

تتلقى الخدمة في المثال التالي معلومات التنقل وتستخدمها TurnByTurnManager لتحويل البيانات إلى كائن NavInfo يحتوي على تفاصيل التنقل.

/**
 *   Receives turn-by-turn navigation information forwarded from NavSDK.
 */
public class NavInfoReceivingService extends Service {
  /** The messenger used by the service to receive nav step updates. */
  private Messenger incomingMessenger;
  private TurnByTurnManager turnByTurnManager;

  private final class IncomingNavStepHandler extends Handler {
    public IncomingNavStepHandler(Looper looper) {
      super(looper);
    }

    @Override
    public void handleMessage(Message msg) {
      // Identify the message through the msg.what field.
      if (TurnByTurnManager.MSG_NAV_INFO == msg.what) {
        // Extract the NavInfo object using the TurnByTurnManager.
        NavInfo navInfo = turnByTurnManager
          .readNavInfoFromBundle(msg.getData()));
      // Do something with the NavInfo
    }
  }
}

@Nullable
@Override
public IBinder onBind(Intent intent) {
  return incomingMessenger.getBinder();
}

@Override
public void onCreate() {
  turnByTurnManager = TurnByTurnManager.createInstance();
  HandlerThread thread =
    new HandlerThread("NavInfoReceivingService",
      Process.THREAD_PRIORITY_DEFAULT);
  thread.start();
  incomingMessenger = new Messenger(
    new IncomingNavStepHandler(thread.getLooper()));
}

رموز الرسائل

يمكن تحديد NavInfo رسالة من خلال Message.what من الفئة Message، والتي يتم تعيينها على قيمة TurnByTurnManager.MSG_NAV_INFO

تسجيل الخدمة للحصول على تحديثات التنقل

تسجل مقتطفات الرمز التالية خدمة التنقل.

boolean isNavInfoReceivingServiceRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);

بدء الخدمة وإيقافها

تكون خدمة التنقل نشطة طالما ترتبط حزمة تطوير البرامج (SDK) للتنقّل بها. يمكنك الاتصال يدويًا startService() وstopService() للتحكم في مدة خدمة التنقل ولكن عند تسجيل خدمتك لدى حزمة SDK للتنقل، ستبدأ خدمتك تلقائيًا ولا يتوقف إلا عند إلغاء تسجيله. استنادًا إلى طريقة إعداد تطبيقك، يمكنك تريد التفكير في بدء خدمة تعمل في المقدّمة، كما هو موضّح في صفحة نظام Android توثيق الخدمات نظرة عامة.

إلغاء تسجيل الخدمة

لإيقاف تلقي تحديثات التنقل، يجب إلغاء تسجيل الخدمة من حزمة SDK للتنقّل

navigator.unregisterServiceForNavUpdates();

فهم حالات التنقّل

استخدِم NavInfo.getNavState() للحصول على حالة التنقّل الحالية، وهي الوضع "واحد". ما يلي:

• المسار - تعني الحالة ENROUTE أن التنقل الموجه يتم حاليًا نشط والمستخدم على المسار المحدد. معلومات عن الجدول الزمني الحالي تتوفر خطوة مناورة قادمة.

• إعادة التوجيه - REROUTING تعني أن التنقل قيد التقدم، ولكن يبحث المستكشف عن مسار جديد. خطوة المناورة القادمة ليست لأنه لا يوجد مسار جديد حتى الآن. في نموذج التطبيق، ستظهر عبارة "إعادة التوجيه..." تظهر الرسالة في عرض معلومات التنقل. عند العثور على مسار، تظهر رسالة NavInfo يتم إرساله مع الحالة ENROUTE.

• متوقف - STOPPED يعني أن التنقل قد انتهى. على سبيل المثال، التنقل عندما يخرج المستخدم من التنقل في التطبيق. في نموذج التطبيق، تمحو حالة "STOPPED" طريقة عرض معلومات التنقّل لتجنّب إطالة الخطوة. من عرض التعليمات.

تعبئة عرض الخلاصة

والآن بعد أن أعددتَ خدمة الاتّجاهات المفصّلة، يتناول هذا القسم العناصر المرئية والنصية التي يمكنك استخدامها لملء بطاقات الإرشادات الاتّجاهات المفصّلة.

حقول معلومات بطاقة التنقّل

عندما يدخل المستخدم إلى التنقل الإرشادي، تظهر بطاقة تنقل في الأعلى، تحتوي على بيانات التنقل التي تم ملؤها من حزمة SDK للتنقّل توضح الصورة ذات الصلة مثالاً على عناصر التنقل الأساسية هذه.

يعرض هذا الجدول حقول معلومات التنقّل ومكان العثور عليها.

الحقول لكل خطوة تنقُّل	الحقول الخاصة بالرحلة الكاملة
تم العثور عليه في StepInfo	تم العثور عليه في NavInfo
اسم الطريق بالكامل	الوقت المتبقي
رمز المناورة	المسافة إلى الوجهة
المسافة إلى الخطوة التالية
حقول إرشادات الممرات

إرشادات الممرات

تمثل حزمة SDK للتنقل الممرات في شريط التنقل تفعيل البطاقة الخطّ أو LaneDirection وكائنات البيانات. يمثل الكائن Lane ممرًا محددًا أثناء التنقل على قائمة بكائنات LaneDirection التي تصف جميع الانعطافات التي يمكن من هذا الممر.

يتم تمييز الاتجاه الموصى به الذي يجب أن يتخذه المستخدم في الممر بواسطة isRecommended .

مثال على إرشادات الممرات

يوضح المقتطف التالي تمثيل البيانات للممرات المعروضة أعلاه.

// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
                  {/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]

// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]

إنشاء رموز للمناورة

تشير رسالة الأشكال البيانية Maneuver يحدد enum كل مناورة محتملة قد تحدث أثناء التنقل، الحصول على المناورة لخطوة معيّنة من الطريقة StepInfo.getManeuver().

يجب عليك إنشاء أيقونات مناورة وإقرانها مع المناورات المرتبطة بها. بالنسبة لبعض المناورات، يمكنك إعداد تعيين فردي لأيقونة، مثل "DESTINATION_LEFT" وDESTINATION_RIGHT" ومع ذلك، نظرًا لأن بعض المناورات بشكل مشابه، فقد ترغب في تعيين أكثر من مناورة لأيقونة واحدة. بالنسبة يمكن ربط المثال TURN_LEFT وON_RAMP_LEFT برمز الانعطاف لليسار.

تحتوي بعض المناورات على تصنيف clockwise أو counterclockwise إضافي، التي تحدّدها حزمة تطوير البرامج (SDK) استنادًا إلى عوامل القيادة في البلد. على سبيل المثال، في حيث تكون القيادة على الجانب الأيسر من الطريق، يقطع السائقون دوران دائري أو دوران على شكل حرف U في اتجاه عقارب الساعة، بينما الجانب الأيمن من الطريق البلدان تسير في اتجاه عقارب الساعة. ترصد حزمة تطوير البرامج (SDK) للتنقّل ما إذا كانت المناورة تحدث في حركة المرور على الجانب الأيسر أو الأيمن وتُنتج المناورة المناسبة. لذلك، قد يختلف رمز المناورة في اتجاه عقارب الساعة مقابل المناورة عكس عقارب الساعة.

استخدام الرموز التي تم إنشاؤها

لتسهيل حالات استخدام Android Auto، سيتم تطبيق حزمة SDK للتنقّل تدعم إنشاء المناورة والممرات أيقونات الإرشادات. تناسب هذه الرموز إرشادات تغيير حجم الصور في Android Auto. مكتبة تطبيقات السيارات التي تقترح استهداف مربّع حدود بحجم 500 × 74 بكسل مستقل الكثافة عرض setsLaneImage أو CarIcon في مستندات Android المرجعية للحصول على التفاصيل.

مثال على إنشاء الرموز

NavigationUpdatesOptions options =
  NavigationUpdatesOptions.builder()
             .setNumNextStepsToPreview(numNextStepsToPreview)
             .setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
             .setDisplayMetrics(getResources().getDisplayMetrics())
             .build();
boolean isRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(),
              NavInfoReceivingService.class.getName(),
              options);

بعد تفعيل إنشاء الرموز، يملأ عنصر TurnbyTurn StepInfo الحقلان maneuverBitmap وlanesBitmap مع الرموز.

الخطوات التالية

• بالنسبة إلى تطبيقات Android Auto:
  • رسم الخريطة وتفعيل الخيار التنقل.