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