توفّر خلاصة بيانات الاتّجاهات المفصّلة معلومات عن التنقّل فقط للأجهزة التي لم يتم تصميمها لإرشادات التنقّل المستندة إلى الخرائط. وهي تزود المناورات القادمة بالعناصر التي تقدمها:
- الرموز (اليسار، اليمين، دوران على شكل حرف U)
- أرقام المنعطفات في الدوارات
- أسماء الطرق
- المسافات والوقت المقدرة إلى خطوة التنقل التالية أو الوجهة النهائية
يمكنك استخدام خلاصة التوجيهات التفصيلية لإنشاء تجارب لا يكون فيها واجهة مستخدم حزمة SDK الكاملة للتنقّل مناسبة، مثل واجهة مستخدم Android Auto أو شاشات الشاشة الصغيرة التي لا تتوفّر فيها حزمة Android الكاملة. على سبيل المثال، يمكنك استخدام هذه الميزة لسائقي المركبات ذات العجلتين، حيث يمكنك بث توجيهات للتنقّل فقط لمساعدتهم في الوصول إلى وجهاتهم بشكل أسرع وبدرجة أكبر من الثقة مع الحد الأدنى من التشتيت.
لاستخدام حزمة SDK، عليك إنشاء خدمة وتسجيلها باستخدام حزمة تطوير البرامج (SDK) للتنقّل على Android حتى تتمكّن من تلقّي معلومات جديدة عن التنقّل في الوقت الفعلي (مرة واحدة تقريبًا في الثانية أثناء التنقّل).
يوضّح لك هذا المستند كيفية إنشاء خدمة تنقّل وتسجيلها بحيث تتلقّى معلومات التنقّل من حزمة تطوير البرامج (SDK) وتوفّر حالة التنقّل للجهاز المستلِم.
نظرة عامة
يصف هذا القسم كيفية إضافة مكتبة TurnByTurn إلى مشاريعك وي summarizingsummarizes سير العمل على مستوى عالٍ لإنشاء وظيفة التنقّل بالاتّجاهات.
إضافة مكتبة TurnByTurn إلى مشروعك باستخدام Maven (إجراء يُنصح به)
لاستخدام إصدار مستقل من مكتبةTurnByTurn، يُرجى اتّباع الخطوات التالية:
- إعداد بيئتك للوصول إلى مستودع 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:
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 هذا. إذا لم يكن لديك إذن الوصول، يُرجى التواصل مع ممثلك.
- نزِّل
google_turnbyturn_*.jar
وفكِّ ضغطه. - انسخ ملف JAR الذي تم تنزيله إلى الدليل
app/libs
في مشروعك. أضِف ما يلي إلى
build.gradle
لتضمين JAR في تصميمك.dependencies { ... api fileTree(include: ['*.jar'], dir: 'libs') }
استخدام مكتبة TurnByTurn
إليك الخطوات رفيعة المستوى لتفعيل الوظائف المفصّلة. تقدّم ال أقسام التالية تفاصيل عن كل خطوة.
إنشاء خدمة لتلقّي آخر المعلومات المتعلّقة بالتنقّل
ترتبط حزمة تطوير البرامج (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 |
اسم الطريق بالكامل | الوقت المتبقي |
رمز المناورة | المسافة إلى الوجهة |
المسافة إلى الخطوة التالية | |
حقول توجيهات خطوط السير |
توجيه خط السير
تمثّل حزمة 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
|
استخدام الرموز التي تم إنشاؤها
لتسهيل حالات استخدام Android Auto، يتيح IDE لنظام تحديد المواقع إنشاء رموز إرشادات المناورات والممرات. تتناسب هذه الرموز مع إرشادات تغيير حجم الصور لمكتبة تطبيق Android Auto السيارة التي تقترح استهداف مربع الإحاطة بحجم 500 × 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 باستخدام الرموز.
الخطوات التالية
- بالنسبة إلى تطبيقات Android Auto: