تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

نظرة عامة

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

استخدام ميزة TurnByTurn

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

إنشاء خدمة لتلقّي آخر المعلومات حول التنقّل
تسجيل الخدمة
فهم حالات التنقّل

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

تربط حزمة تطوير البرامج للتنقّل بخدمة 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() يدويًا للتحكّم في دورة حياة خدمة التنقّل، ولكن عند تسجيل خدمتك باستخدام Navigation SDK، تبدأ خدمتك تلقائيًا، ولا تتوقف إلا عند إلغاء تسجيلها. استنادًا إلى طريقة إعداد تطبيقك، قد تحتاج إلى بدء خدمة تعمل في المقدّمة، كما هو موضّح في مستندات Android نظرة عامة على الخدمات.

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

لإيقاف تلقّي تحديثات التنقّل، عليك إلغاء تسجيل الخدمة من حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation.

navigator.unregisterServiceForNavUpdates();

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

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

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

ملء شاشة الخلاصة

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

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

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

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

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

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

توجيه خط السير

تمثّل حزمة تطوير البرامج (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) هذا التصنيف استنادًا إلى جهة القيادة في البلد. على سبيل المثال، في البلدان التي يتم فيها القيادة على الجانب الأيسر من الطريق، يتّخذ السائقون دوارًا أو منعطفًا على شكل حرف U في اتجاه عقارب الساعة، بينما تتّخذ البلدان التي يتم فيها القيادة على الجانب الأيمن من الطريق اتجاهًا معاكسًا لعقارب الساعة. ترصد حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation ما إذا كانت المناورة تحدث في حركة المرور على الجانب الأيسر أو الأيمن، وتعرض المناورة المناسبة. لذلك، قد يختلف رمز المناورة بين المناورة في اتجاه عقارب الساعة والمناورة في عكس اتجاه عقارب الساعة.

توسيع القائمة للاطّلاع على رموز أمثلة للمناورات المختلفة

رمز العيّنة	TurnByTurn Maneuvers
	`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) الخاصة بخدمة Navigation

لتسهيل حالات استخدام Android Auto، تتيح حزمة تطوير البرامج (SDK) الخاصة بخدمة Navigation إنشاء رموز إرشادية للمناورة والمسار. تتوافق هذه الرموز مع إرشادات تحديد حجم الصور في مكتبة تطبيقات السيارات في 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:
- ارسم الخريطة وفعِّل التنقّل.