تفعيل اتّجاهات مفصّلة للبيانات

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

  • الرموز (اليسار واليمين والانعطاف بدرجة 180)
  • أرقام المنعطفات في الدوارات
  • أسماء الطرق
  • المسافات المقدَّرة والوقت المستغرَق للوصول إلى خطوة التنقّل التالية أو الوجهة النهائية

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

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

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

نظرة عامة

يلخّص هذا القسم الخطوات الأساسية لتفعيل ميزة التنقّل من نقطة إلى أخرى.

استخدام ميزة "الاتّجاهات المفصّلة"

في ما يلي الخطوات الأساسية لتفعيل ميزة التنقّل بالاتّجاهات. تقدّم ال أقسام التالية تفاصيل عن كل خطوة.

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

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

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

إنشاء خدمة لتلقّي آخر المعلومات المتعلّقة بالتنقّل

ترتبط حزمة تطوير البرامج (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);

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

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

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

لإيقاف تلقّي آخر المعلومات عن التنقّل، يجب إلغاء تسجيل الخدمة من Navigation SDK.

navigator.unregisterServiceForNavUpdates();

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

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

  • في الطريق: تعني الحالة ENROUTE أنّ ميزة التنقّل الإرشادي مفعّلة حاليًا ويسير المستخدم على المسار المقدَّم. تتوفّر معلومات عن الخطوة الراهنة المقبلة من المناورة.

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

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

تعبئة شاشة الخلاصة

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

شاشة جهاز جوّال تعرض إشارة إلى أنّه عليك الانعطاف يسارًا بعد 30 مترًا على W Ahwanee Ave. في أسفل الشاشة، يظهر الوقت المتبقّي للوصول إلى الوجهة وهو 46 دقيقة، والمسافة المتبقّية هي 39 ميل.

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

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

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

إرشادات بشأن الممر

تمثّل حزمة Navigation SDK المسارات في بطاقة التنقّل للانعطاف على هيئة كائنَي بيانات Lane و LaneDirection. يمثّل عنصر Lane حارة معيّنة أثناء التنقّل ويحتوي على قائمة بعناصر LaneDirection التي تصف جميع المنعطفات التي يمكن إجراؤها من هذه الحارة.

مثال على إعدادات توجيهات المسارات

يتم وضع علامة على الاتجاه المقترَح الذي يجب أن يسلكه المستخدم في حارة باستخدام الحقل isRecommended.

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

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

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

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

إنشاء رموز للعمليات

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

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

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

توسيع الرمز لعرض أمثلة على الرموز الخاصة بالمناورات المختلفة

رمز عيّنة المناورات في ميزة "الاتّجاهات المفصّلة"
DEPART
UNKNOWN
STRAIGHT
ON_RAMP_UNSPECIFIED
OFF_RAMP_UNSPECIFIED
NAME_CHANGE
TURN_RIGHT
ON_RAMP_RIGHT
TURN_LEFT
ON_RAMP_LEFT
TURN_SLIGHT_RIGHT
ON_RAMP_SLIGHT_RIGHT
OFF_RAMP_SLIGHT_RIGHT
TURN_SLIGHT_LEFT
ON_RAMP_SLIGHT_LEFT
OFF_RAMP_SLIGHT_LEFT
TURN_SHARP_RIGHT
ON_RAMP_SHARP_RIGHT
OFF_RAMP_SHARP_RIGHT
TURN_SHARP_LEFT
ON_RAMP_SHARP_LEFT
OFF_RAMP_SHARP_LEFT
TURN_U_TURN_COUNTERCLOCKWISE
ON_RAMP_U_TURN_COUNTERCLOCKWISE
OFF_RAMP_U_TURN_COUNTERCLOCKWISE
TURN_U_TURN_CLOCKWISE
ON_RAMP_U_TURN_CLOCKWISE
OFF_RAMP_U_TURN_CLOCKWISE
ROUNDABOUT_SHARP_RIGHT_COUNTERCLOCKWISE
ROUNDABOUT_SHARP_RIGHT_CLOCKWISE
ROUNDABOUT_RIGHT_COUNTERCLOCKWISE
ROUNDABOUT_RIGHT_CLOCKWISE
ROUNDABOUT_SLIGHT_RIGHT_COUNTERCLOCKWISE
ROUNDABOUT_SLIGHT_RIGHT_CLOCKWISE
ROUNDABOUT_STRAIGHT_COUNTERCLOCKWISE
ROUNDABOUT_STRAIGHT_CLOCKWISE
ROUNDABOUT_SLIGHT_LEFT_COUNTERCLOCKWISE
ROUNDABOUT_SLIGHT_LEFT_CLOCKWISE
ROUNDABOUT_LEFT_COUNTERCLOCKWISE
ROUNDABOUT_LEFT_CLOCKWISE
ROUNDABOUT_SHARP_LEFT_COUNTERCLOCKWISE
ROUNDABOUT_SHARP_LEFT_CLOCKWISE
ROUNDABOUT_U_TURN_COUNTERCLOCKWISE
ROUNDABOUT_U_TURN_CLOCKWISE
ROUNDABOUT_COUNTERCLOCKWISE
ROUNDABOUT_CLOCKWISE
ROUNDABOUT_EXIT_COUNTERCLOCKWISE
ROUNDABOUT_EXIT_CLOCKWISE
MERGE_RIGHT
OFF_RAMP_RIGHT
MERGE_LEFT
OFF_RAMP_LEFT
FORK_RIGHT
TURN_KEEP_RIGHT
ON_RAMP_KEEP_RIGHT
OFF_RAMP_KEEP_RIGHT
FORK_LEFT
TURN_KEEP_LEFT
ON_RAMP_KEEP_LEFT
OFF_RAMP_KEEP_LEFT
MERGE_UNSPECIFIED
DESTINATION
DESTINATION_RIGHT
DESTINATION_LEFT
FERRY_BOAT
FERRY_TRAIN

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

قائمة صغيرة بالرموز التي تم إنشاؤها من خلال حزمة SDK لميزة التنقل

لتسهيل حالات استخدام Android Auto، يتيح IDE لنظام تحديد المواقع إنشاء رموز إرشادات المناورات والممرات. تتوافق هذه الرموز مع إرشادات تحديد حجم الصور في مكتبة تطبيقات Android Auto Car App التي تنصح باستهداف مربّع حدود بحجم 500 x ‏74 dp. راجِع 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 بالرموز.

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