إنشاء تطبيق للتنقّل

تعرض هذه الصفحة بالتفصيل الميزات المختلفة لمكتبة تطبيقات السيارة التي يمكنك استخدامها لتنفيذ وظائف تطبيق التنقّل باتّجاهات مفصّلة.

توضيح إتاحة التنقّل في البيان

يجب أن يذكر تطبيق التنقّل androidx.car.app.category.NAVIGATION فئة تطبيق السيارة في فلتر الأهداف في CarAppService:

<application>
    ...
   <service
       ...
        android:name=".MyNavigationCarAppService"
        android:exported="true">
      <intent-filter>
        <action android:name="androidx.car.app.CarAppService" />
        <category android:name="androidx.car.app.category.NAVIGATION"/>
      </intent-filter>
    </service>
    ...
</application>

أهداف التنقّل للدعم

لإتاحة أغراض التنقّل إلى تطبيقك، بما في ذلك تلك الواردة من "مساعد Google" باستخدام طلب صوتي، يجب أن يعالج تطبيقك هدف CarContext.ACTION_NAVIGATE في Session.onCreateScreen وSession.onNewIntent.

راجِع المستندات بشأن CarContext.startCarApp للحصول على تفاصيل عن تنسيق الغرض.

الوصول إلى نماذج التنقّل

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

  • NavigationTemplate: يعرض أيضًا رسالة إعلامية اختيارية وتقديرات بشأن السفر أثناء التنقّل النشط.
  • MapTemplate: تقدّم نسخة مصغَّرة من القائمة (كما في ListTemplate) أو من جزء (معلومات تفصيلية مع إجراءات بارزة، كما في PaneTemplate) بجانب الخريطة.
  • PlaceListNavigationTemplate: تعرض أيضًا قائمة بالأماكن، التي يمكن أن تحتوي على علامات مقابلة مرسومة في الخريطة.
  • RoutePreviewNavigationTemplate: تعرض أيضًا قائمة بالمسارات، والتي يمكن اختيار أحدها وتمييزها في الخريطة.

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

للوصول إلى نماذج التنقّل، يجب أن يذكر تطبيقك الإذن androidx.car.app.NAVIGATION_TEMPLATES في ملف AndroidManifest.xml الخاص به:

<uses-permission android:name="androidx.car.app.NAVIGATION_TEMPLATES"/>

رسم الخريطة

يمكن لتطبيقات التنقّل الوصول إلى Surface لرسم الخريطة على النماذج ذات الصلة.

يمكن بعد ذلك الوصول إلى عنصر SurfaceContainer من خلال ضبط مثيل SurfaceCallback في خدمة السيارات AppManager:

Kotlin

carContext.getCarService(AppManager::class.java).setSurfaceCallback(surfaceCallback)

Java

carContext.getCarService(AppManager.class).setSurfaceCallback(surfaceCallback);

توفِّر SurfaceCallback معاودة الاتصال عندما يكون SurfaceContainer متاحًا، إلى جانب عمليات استدعاء أخرى عند تغيير خصائص Surface.

للوصول إلى واجهة برمجة التطبيقات، يجب أن يتضمّن تطبيقك بيانًا عن إذن androidx.car.app.ACCESS_SURFACE في ملف AndroidManifest.xml:

<uses-permission android:name="androidx.car.app.ACCESS_SURFACE"/>

المنطقة المرئية للخريطة

يمكن للمضيف رسم عناصر واجهة المستخدم للنماذج أعلى الخريطة. يبلغ المضيف عن المنطقة التي تضمن عدم وجود عوائق ومرئية بالكامل للمستخدم من خلال استدعاء طريقة SurfaceCallback.onVisibleAreaChanged. لتقليل عدد التغييرات، يستدعي المضيف الطريقة SurfaceCallback.onStableAreaChanged مع أصغر مستطيل، والذي يظهر دائمًا استنادًا إلى النموذج الحالي.

على سبيل المثال، عندما يستخدم تطبيق تنقُّل NavigationTemplate مع شريط إجراءات في الأعلى، يمكن أن يُخفي شريط الإجراءات نفسه عندما لا يتفاعل المستخدم مع الشاشة لفترة من الوقت لتوفير مساحة أكبر للخريطة. في هذه الحالة، هناك استدعاء إلى onStableAreaChanged وonVisibleAreaChanged بنفس المستطيل. عند إخفاء شريط الإجراءات، يتم استدعاء onVisibleAreaChanged فقط مع المنطقة الأكبر. إذا تفاعل المستخدم مع الشاشة، فمرة أخرى يتم استدعاء onVisibleAreaChanged فقط مع المستطيل الأول.

إتاحة "الوضع الداكن"

يجب أن تعيد تطبيقات التنقّل رسم الخريطة على مثيل Surface باستخدام الألوان الداكنة المناسبة عندما يحدّد المضيف أنّ الظروف تقتضي ذلك، كما هو موضّح في جودة تطبيقات Android للسيارات.

لتحديد ما إذا كنت تريد رسم خريطة مظلمة، يمكنك استخدام طريقة CarContext.isDarkMode. كلما تغيرت حالة الوضع الداكن، ستتلقّى مكالمة على الرقم Session.onCarConfigurationChanged.

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

يتم توفير البيانات الوصفية للتنقل من خلال خدمة سيارات NavigationManager التي يمكن الوصول إليها من CarContext:

Kotlin

val navigationManager = carContext.getCarService(NavigationManager::class.java)

Java

NavigationManager navigationManager = carContext.getCarService(NavigationManager.class);

بدء التنقّل وإنهائه وإيقافه

لكي يتمكن المضيف من إدارة تطبيقات تنقّل متعددة وإشعارات التوجيه وبيانات مجموعة المركبات، يجب أن يكون على دراية بحالة التنقّل الحالية. عندما يبدأ المستخدم التنقّل، يمكنك الاتصال بالرقم NavigationManager.navigationStarted. وبالمثل، عند انتهاء التنقّل، مثلاً عندما يصل المستخدم إلى وجهته أو يلغي التنقّل، يمكنك الاتصال NavigationManager.navigationEnded.

لا يجب استدعاء NavigationManager.navigationEnded إلا عند انتهاء المستخدم من التنقل. على سبيل المثال، إذا كنت بحاجة إلى إعادة حساب المسار في منتصف الرحلة، استخدِم Trip.Builder.setLoading(true) بدلاً من ذلك.

يحتاج المضيف أحيانًا إلى تطبيق لإيقاف التنقّل والمكالمات onStopNavigation في عنصر NavigationManagerCallback يوفّره تطبيقك من خلال NavigationManager.setNavigationManagerCallback. ويجب أن يتوقّف التطبيق بعد ذلك عن إصدار معلومات المنعطف التالي في شاشة المجموعة، وإشعارات التنقّل والإرشاد الصوتي.

تعديل معلومات الرحلة

أثناء التنقّل النشط، يمكنك الاتصال بالرقم NavigationManager.updateTrip. يمكن استخدام المعلومات المقدّمة في هذه المكالمة من خلال مجموعة السيارة وشاشات العرض الرأسية. اعتمادًا على المركبة المحددة التي تتم قيادتها، لا يتم عرض كل المعلومات للمستخدم. على سبيل المثال، تُظهر الوحدة الرئيسية للكمبيوتر المكتبي (DHU) Step التي تمت إضافتها إلى Trip، ولكنها لا تعرض معلومات Destination.

الرسم على عرض المجموعة

لتقديم تجربة مستخدم متكاملة، ننصحك بتخطّي عرض البيانات الوصفية الأساسية على الشاشة العنقودية للمركبة. بدءًا من المستوى 6 من واجهة برمجة تطبيقات السيارة، يتوفّر لتطبيقات التنقّل خيار عرض المحتوى الخاص بها مباشرةً على شاشة المجموعة (في المركبات المتوافقة)، مع القيود التالية:

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

تعريف دعم المجموعة

لإعلام التطبيق المضيف بأنّ تطبيقك يتيح العرض على شاشات العرض المجمّعة، يجب إضافة العنصر androidx.car.app.category.FEATURE_CLUSTER <category> إلى <intent-filter> في CarAppService كما هو موضّح في المقتطف التالي:

<application>
    ...
   <service
       ...
        android:name=".MyNavigationCarAppService"
        android:exported="true">
      <intent-filter>
        <action android:name="androidx.car.app.CarAppService" />
        <category android:name="androidx.car.app.category.NAVIGATION"/>
        <category android:name="androidx.car.app.category.FEATURE_CLUSTER"/>
      </intent-filter>
    </service>
    ...
</application>

إدارة الحالة ومراحل النشاط

بدءًا من المستوى 6 لواجهة برمجة التطبيقات، يظل مسار نشاط تطبيق السيارة كما هو، ولكن الآن يأخذ CarAppService::onCreateSession معلَمة من النوع SessionInfo توفر معلومات إضافية حول Session الذي يتم إنشاؤه (أي نوع العرض ومجموعة النماذج المتوافقة).

يمكن للتطبيقات اختيار استخدام فئة Session نفسها للتعامل مع المجموعة والشاشة الرئيسية على حد سواء، أو إنشاء Sessions لعرض تخصيص السلوك على كل شاشة (كما هو موضّح في المقتطف التالي).

Kotlin

override fun onCreateSession(sessionInfo: SessionInfo): Session {
  return if (sessionInfo.displayType == SessionInfo.DISPLAY_TYPE_CLUSTER) {
    ClusterSession()
  } else {
    MainDisplaySession()
  }
}

Java

@Override
@NonNull
public Session onCreateSession(@NonNull SessionInfo sessionInfo) {
  if (sessionInfo.getDisplayType() == SessionInfo.DISPLAY_TYPE_CLUSTER) {
    return new ClusterSession();
  } else {
    return new MainDisplaySession();
  }
}

وما مِن ضمانات بشأن وقت توفير عرض المجموعة أو إمكانية توفيره، ومن الممكن أيضًا أن تكون المجموعة Session هي Session الوحيدة (على سبيل المثال، بدَّل المستخدم الشاشة الرئيسية بتطبيق آخر أثناء تنقّل التطبيق بشكل نشط). تتمثل الاتفاقية "القياسية" في أنه لا يمكن للتطبيق التحكم في عرض المجموعة إلا بعد طلب NavigationManager::navigationStarted. ومع ذلك، من الممكن أن يتم تزويد التطبيق بعرض المجموعة أثناء عدم تنفيذ عملية تنقّل نشطة أو من الممكن عدم توفير طريقة عرض المجموعة مطلقًا. الأمر متروك لتطبيقك للتعامل مع هذه السيناريوهات من خلال عرض حالة عدم نشاط التطبيق لمربعات الخرائط.

ينشئ المضيف برنامج ربط منفصل وCarContext مثيل لكل Session. وهذا يعني أنّه عند استخدام طرق مثل ScreenManager::push أو Screen::invalidate، لن يتأثر سوى Session الذي تم طلبها منه. يجب أن تنشئ التطبيقات قنوات تواصل خاصة بها بين هذه الحالات إذا كان هناك حاجة إلى التواصل بين أكثر من Session (على سبيل المثال، باستخدام رسائل البث أو أغاني فردية مشترَكة أو غير ذلك).

دعم المجموعة التجريبية

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

تخصيص TravelEstimate باستخدام نص أو رمز

لتخصيص مدة الرحلة المقدَّرة من خلال إضافة نص أو رمز أو كليهما، استخدِم طريقة TravelEstimate.Builder للصف setTripIcon أو setTripText. تستخدم NavigationTemplate TravelEstimate لضبط النص والرموز بشكل اختياري، بجانب أو بدلاً من الوقت المقدّر للوصول والوقت المتبقي والمسافة المتبقية.

الشكل 1. تقدير للسفر من خلال رمز ونص مخصّصَين

يستخدم المقتطف التالي setTripIcon وsetTripText لتخصيص تقدير الرحلة:

Kotlin

TravelEstimate.Builder(Distance.create(...), DateTimeWithZone.create(...))
      ...
      .setTripIcon(CarIcon.Builder(...).build())
      .setTripText(CarText.create(...))
      .build()

Java

new TravelEstimate.Builder(Distance.create(...), DateTimeWithZone.create(...))
      ...
      .setTripIcon(CarIcon.Builder(...).build())
      .setTripText(CarText.create(...))
      .build();

توفير إشعارات مفصّلة

قدّم إرشادات التنقل خطوة بخطوة (TBT) باستخدام إشعار تنقل يتم تحديثه بشكل متكرر. ليتم التعامل مع جهات إنشاء الإشعارات على أنّها إشعار تنقُّل في شاشة السيارة، يجب أن تنفّذ أداة إنشاء الإشعارات ما يلي:

  1. ضَع علامة للإشارة إلى أنّ الإشعار مستمر باستخدام الطريقة NotificationCompat.Builder.setOngoing.
  2. اضبط فئة الإشعار على Notification.CATEGORY_NAVIGATION.
  3. يمكنك توسيع نطاق الإشعار باستخدام CarAppExtender.

يظهر إشعار تنقُّل في أداة "السكك الحديدية" أسفل شاشة السيارة. في حال ضبط مستوى أهمية الإشعار على IMPORTANCE_HIGH، سيظهر أيضًا كإشعار تنبيه (HUN). إذا لم يتم ضبط الأهمية باستخدام الإجراء CarAppExtender.Builder.setImportance، يتم استخدام أهمية قناة الإشعار.

يمكن للتطبيق ضبط PendingIntent في CarAppExtender ليتم إرساله إلى التطبيق عندما ينقر المستخدم على HUN أو التطبيق المصغّر للسكك الحديدية.

إذا تم استدعاء NotificationCompat.Builder.setOnlyAlertOnce بقيمة true، يتم إرسال إشعار عالي الأهمية مرة واحدة فقط في HUN.

يوضّح المقتطف التالي كيفية إنشاء إشعار تنقُّل:

Kotlin

NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID)
    ...
    .setOnlyAlertOnce(true)
    .setOngoing(true)
    .setCategory(NotificationCompat.CATEGORY_NAVIGATION)
    .extend(
        CarAppExtender.Builder()
            .setContentTitle(carScreenTitle)
            ...
            .setContentIntent(
                PendingIntent.getBroadcast(
                    context,
                    ACTION_OPEN_APP.hashCode(),
                    Intent(ACTION_OPEN_APP).setComponent(
                        ComponentName(context, MyNotificationReceiver::class.java)),
                        0))
            .setImportance(NotificationManagerCompat.IMPORTANCE_HIGH)
            .build())
    .build()

Java

new NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID)
    ...
    .setOnlyAlertOnce(true)
    .setOngoing(true)
    .setCategory(NotificationCompat.CATEGORY_NAVIGATION)
    .extend(
        new CarAppExtender.Builder()
            .setContentTitle(carScreenTitle)
            ...
            .setContentIntent(
                PendingIntent.getBroadcast(
                    context,
                    ACTION_OPEN_APP.hashCode(),
                    new Intent(ACTION_OPEN_APP).setComponent(
                        new ComponentName(context, MyNotificationReceiver.class)),
                        0))
            .setImportance(NotificationManagerCompat.IMPORTANCE_HIGH)
            .build())
    .build();

حدّث إشعار TBT بانتظام لمعرفة تغييرات المسافة، الذي يؤدي إلى تحديث أداة السكك الحديدية، وعرض الإشعار كـ HUN فقط. يمكنك التحكّم في سلوك HUN من خلال ضبط مدى أهمية الإشعار باستخدام CarAppExtender.Builder.setImportance. يؤدي ضبط الأهمية على IMPORTANCE_HIGH إلى إظهار HUN. يؤدي تعيينه على أي قيمة أخرى إلى تحديث أداة السكك الحديدية فقط.

إعادة تحميل محتوى PlaceList NavigationTemplate

يمكنك السماح للسائقين بإعادة تحميل المحتوى بنقرة زر واحدة أثناء تصفُّح قوائم الأماكن التي تم إنشاؤها باستخدام PlaceListNavigationTemplate. لتفعيل إعادة تحميل القائمة، نفِّذ طريقة OnContentRefreshListener الواجهة onContentRefreshRequested واستخدِم PlaceListNavigationTemplate.Builder.setOnContentRefreshListener لضبط أداة معالجة الحدث على النموذج.

يوضّح المقتطف التالي كيفية ضبط أداة معالجة الحدث في النموذج:

Kotlin

PlaceListNavigationTemplate.Builder()
    ...
    .setOnContentRefreshListener {
        // Execute any desired logic
        ...
        // Then call invalidate() so onGetTemplate() is called again
        invalidate()
    }
    .build()

Java

new PlaceListNavigationTemplate.Builder()
        ...
        .setOnContentRefreshListener(() -> {
            // Execute any desired logic
            ...
            // Then call invalidate() so onGetTemplate() is called again
            invalidate();
        })
        .build();

لا يظهر زر إعادة التحميل في عنوان PlaceListNavigationTemplate إلا إذا كانت المستمع قيمة.

عندما ينقر المستخدم على زر إعادة التحميل، يتم استدعاء طريقة onContentRefreshRequested لتنفيذ OnContentRefreshListener. ضمن onContentRefreshRequested، استدعِ الطريقة Screen.invalidate. بعد ذلك، يتصل المضيف مرة أخرى بطريقة Screen.onGetTemplate في تطبيقك لاسترداد النموذج مع المحتوى الذي تم تحديثه. يمكنك الاطّلاع على إعادة تحميل محتوى نموذج للحصول على مزيد من المعلومات حول إعادة تحميل النماذج. ما دام النموذج التالي الذي يعرضه onGetTemplate من النوع نفسه، يتم احتسابه كإعادة تحميل ولا يتم احتسابه ضمن حصة النموذج.

تقديم التوجيه الصوتي

لتشغيل إرشادات التنقّل عبر مكبرات الصوت بالسيارة، يجب أن يطلب تطبيقك التركيز الصوتي. وكجزء من AudioFocusRequest، يمكنك ضبط الاستخدام على AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE. يمكنك أيضًا ضبط زيادة التركيز على AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK

محاكاة التنقّل

للتحقّق من وظيفة التنقّل في تطبيقك عند إرساله إلى "متجر Google Play"، يجب أن يستخدم تطبيقك معاودة الاتصال NavigationManagerCallback.onAutoDriveEnabled. عند استدعاء معاودة الاتصال هذه، يجب أن يحاكي تطبيقك التنقل إلى الوجهة المختارة عندما يبدأ المستخدم التنقل. يمكن لتطبيقك الخروج من هذا الوضع عندما تصل دورة حياة Session الحالية إلى حالة Lifecycle.Event.ON_DESTROY.

يمكنك اختبار ما إذا كان يتم استدعاء تنفيذ onAutoDriveEnabled عن طريق تنفيذ ما يلي من سطر الأوامر:

adb shell dumpsys activity service CAR_APP_SERVICE_NAME AUTO_DRIVE

يظهر ذلك في المثال التالي:

adb shell dumpsys activity service androidx.car.app.samples.navigation.car.NavigationCarAppService AUTO_DRIVE

تطبيق التنقّل التلقائي للسيارة

في Android Auto، يتوافق تطبيق التنقّل التلقائي في السيارة مع آخر تطبيق تنقُّل أطلقه المستخدم. إنّ التطبيق التلقائي يتلقّى أهداف التنقّل عندما يستدعي المستخدِم أوامر التنقّل من خلال "مساعد Google" أو عندما يرسل تطبيق آخر هدفًا لبدء التنقّل.

السماح للمستخدمين بالتفاعل مع خريطتك

يمكنك توفير إمكانية التفاعل مع الخرائط للمستخدمين، مثل السماح لهم برؤية أجزاء مختلفة من الخريطة عن طريق التكبير أو التصغير والتحريك. لكل نموذج حد أدنى مختلف من متطلبات مستوى واجهة برمجة التطبيقات Car App. راجع الجدول التالي لمعرفة الحد الأدنى للمستوى للقالب الذي تريد تنفيذه.

النموذجميزة التفاعل متاحة منذ استخدام Car App API Level
NavigationTemplate2
PlaceListNavigationTemplate4
RoutePreviewNavigationTemplate4
MapTemplate5

طرق SurfaceCallback

تحتوي واجهة SurfaceCallback على العديد من طرق معاودة الاتصال التي تتيح لك إضافة التفاعل إلى الخرائط التي تم إنشاؤها باستخدام نماذج NavigationTemplate أو PlaceListNavigationTemplate أو RoutePreviewNavigationTemplate أو MapTemplate: onClick وonScroll وonScale وonFling. اطّلِع على الجدول التالي لمعرفة مدى صلة عمليات معاودة الاتصال هذه بتفاعلات المستخدِم.

التفاعل طريقة واحدة (SurfaceCallback) هذا الخيار متوفِّر منذ مستوى واجهة برمجة تطبيقات Car App API
النقر onClick 5
التكبير/التصغير بإصبعَين onScale 2
السحب بلمسة واحدة onScroll 2
رمي الكرة بلمسة واحدة onFling 2
النقر مرتين onScale (مع تحديد عامل القياس من خلال مضيف النموذج) 2
تذكير دوّار في وضع العرض الشامل onScroll (مع تحديد عامل المسافة من خلال مضيف النموذج) 2

شريط إجراءات الخريطة

يمكن أن تحتوي نماذج NavigationTemplate وPlaceListNavigationTemplate وRoutePreviewNavigationTemplate وMapTemplate على شريط إجراءات على الخريطة لتنفيذ الإجراءات المتعلقة بالخرائط مثل التكبير والتصغير وإعادة التوسيط وعرض البوصلة والإجراءات الأخرى التي تختار عرضها. يمكن أن يحتوي شريط إجراءات الخريطة على ما يصل إلى أربعة أزرار للأيقونات فقط يمكن تحديثها بدون التأثير على عمق المهمة. يختبئ أثناء حالة الخمول ويظهر مرة أخرى في حالة النشاط.

لتلقّي استدعاءات التفاعل على الخريطة، يجب إضافة الزر Action.PAN في شريط إجراءات الخريطة. عندما يضغط المستخدم على زر التحريك، يدخل المضيف في وضع العرض الشامل، كما هو موضح في القسم التالي.

إذا حذف تطبيقك الزر Action.PAN في شريط إجراءات الخريطة، لن يتلقّى إدخالات المستخدم من طرق SurfaceCallback، ويخرج المضيف من أي وضع عرض شامل سبق تفعيله.

لا يظهر زر العرض الشامل على شاشة تعمل باللمس.

وضع التحريك

في وضع العرض الشامل، يحوِّل مضيف النموذج البيانات التي يدخلها المستخدم من أجهزة الإدخال التي لا تعمل باللمس، مثل وحدات التحكّم الدوّارة ولوحات اللمس، إلى أساليب SurfaceCallback المناسبة. استجب لإجراء المستخدم للدخول أو الخروج من وضع العرض الشامل باستخدام الطريقة setPanModeListener في NavigationTemplate.Builder. يمكن للمضيف إخفاء مكونات واجهة المستخدم الأخرى في النموذج بينما يكون المستخدم في وضع العرض الشامل.

المنطقة الثابتة

يتم تعديل المنطقة الثابتة بين حالتَي "عدم النشاط" و"وضع عدم النشاط". حدد ما إذا كنت تريد رسم المعلومات المتعلقة بالقيادة، مثل السرعة أو الحد الأقصى للسرعة أو التحذيرات من الطريق، استنادًا إلى حجم المنطقة الثابتة، بحيث لا يتم عرقلة المعلومات المهمة على الخريطة بواسطة شريط الإجراءات على الخريطة.

عرض تنبيهات التنقل في السياق

تعرض أداة Alert معلومات مهمة للسائق من خلال إجراءات اختيارية&dash؛ بدون مغادرة سياق شاشة التنقل. لتوفير أفضل تجربة للسائق، يعمل Alert ضمن NavigationTemplate على تجنُّب حظر مسار التنقُّل وتقليل تشتيت السائق.

لا يتوفّر Alert إلا ضمن NavigationTemplate. لإبلاغ المستخدم من خارج "NavigationTemplate"، يمكنك استخدام إشعار التنبيه (HUN)، على النحو الموضَّح في عرض الإشعارات.

على سبيل المثال، يمكنك استخدام Alert لإجراء ما يلي:

  • أبلِغ السائق بتعديل معلومات التنقّل الحالية، مثل تغيير في أحوال حركة المرور.
  • اطلب من السائق تعديل المعلومات المتعلّقة بالتنقّل الحالي، مثل وجود رادار سرعة متنقّل.
  • اقترح مهمة قادمة واسأل ما إذا كان السائق يقبلها، على سبيل المثال ما إذا كان السائق على استعداد لاصطحاب شخص ما في طريقه.

يتكوّن Alert في شكله الأساسي من عنوان ومدة Alert. يتم تمثيل مدة المدة بشريط تقدم. ويمكنك اختياريًا إضافة عنوان فرعي ورمز وما يصل إلى عنصرَين من Action.

الشكل 2. تنبيه تنقُّل ضمن السياق

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

إنشاء تنبيه

استخدِم Alert.Builder لإنشاء مثيل Alert:

Kotlin

Alert.Builder(
        /*alertId*/ 1,
        /*title*/ CarText.create("Hello"),
        /*durationMillis*/ 5000
    )
    // The fields below are optional
    .addAction(firstAction)
    .addAction(secondAction)
    .setSubtitle(CarText.create(...))
    .setIcon(CarIcon.APP_ICON)
    .setCallback(...)
    .build()

Java

new Alert.Builder(
        /*alertId*/ 1,
        /*title*/ CarText.create("Hello"),
        /*durationMillis*/ 5000
    )
    // The fields below are optional
    .addAction(firstAction)
    .addAction(secondAction)
    .setSubtitle(CarText.create(...))
    .setIcon(CarIcon.APP_ICON)
    .setCallback(...)
    .build();

إذا أردت معرفة قرار Alert الإلغاء أو الرفض، عليك إنشاء عملية تنفيذ لواجهة AlertCallback. مسارا المكالمات "AlertCallback" هما:

  • إذا انتهت مهلة Alert، يستدعي المضيف الطريقة AlertCallback.onCancel بالقيمة AlertCallback.REASON_TIMEOUT. ثم يتم استدعاء الطريقة AlertCallback.onDismiss.

  • إذا نقر السائق على أحد أزرار الإجراءات، سيتصل المضيف بالرمز Action.OnClickListener ثم يتصل بـ AlertCallback.onDismiss.

  • وإذا كانت السمة Alert غير متوافقة، يطلب المضيف AlertCallback.onCancel باستخدام القيمة AlertCallback.REASON_NOT_SUPPORTED. لا يتصل المضيف بـ AlertCallback.onDismiss، لأنه لم يتم عرض Alert.

ضبط مدة التنبيه

اختَر مدة Alert تتناسب مع احتياجات تطبيقك. المدة الموصى بها للتنقل Alert هي 10 ثوانٍ. راجِع تنبيهات التنقّل للحصول على مزيد من المعلومات.

إظهار تنبيه

لعرض Alert، اتصل بطريقة AppManager.showAlert المتاحة من خلال CarContext في تطبيقك.

// Show an alert
carContext.getCarService(AppManager.class).showAlert(alert)
  • إنّ الاتصال بـ showAlert باستخدام Alert يتضمّن معرّف alertId مطابقًا لمعرّف Alert المعروض حاليًا ليس له أي تأثير. ولا يتم تعديل Alert. لتحديث Alert، يجب عليك إعادة إنشائه باستخدام alertId جديد.
  • يؤدي استدعاء showAlert باستخدام Alert الذي يحمل قيمة alertId مختلفة عن Alert المعروض حاليًا إلى تجاهل Alert المعروض حاليًا.

إغلاق تنبيه

على الرغم من أنّ Alert يتم إغلاقها تلقائيًا بسبب انتهاء المهلة أو تفاعل السائق، يمكنك أيضًا إغلاق Alert يدويًا، مثلاً إذا أصبحت معلوماتها قديمة. لإغلاق Alert، عليك استدعاء الطريقة dismissAlert باستخدام alertId السمة Alert.

// Dismiss the same alert
carContext.getCarService(AppManager.class).dismissAlert(alert.getId())

إنّ الاتصال بـ dismissAlert باستخدام alertId والذي لا يتطابق مع Alert المعروض حاليًا لا يؤدي إلى أي شيء. ولا يقدم استثناءً.