رسم الخرائط

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

لاستخدام النماذج التالية، يجب أن يعلن تطبيقك عن أحد هذه الأذونات المقابلة في عنصر <uses-permission> في ملف AndroidManifest.xml.

الاطّلاع على نموذج التنفيذ المرجعي

للاطّلاع على نموذج تنفيذ مرجعي كامل، يُرجى مراجعة نموذج التنقّل.

الإعلان عن إذن مساحة العرض

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

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

الوصول إلى مساحة العرض

للوصول إلى Surface الذي يوفّره المضيف، عليك تنفيذ SurfaceCallback وتقديم هذا التنفيذ إلى AppManager خدمة السيارة. يتم تمرير Surface الحالي إلى SurfaceCallback في المَعلمة SurfaceContainer لطلبَي الاستدعاء onSurfaceAvailable() و onSurfaceDestroyed().

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

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

استخدام شاشة عرض افتراضية لعرض المحتوى

بالإضافة إلى العرض مباشرةً في Surface باستخدام Canvas API، يمكنك أيضًا عرض "طرق العرض" في Surface باستخدام VirtualDisplay و Presentation APIs، كما هو موضّح في هذا المثال:

class HelloWorldSurfaceCallback(context: Context) : SurfaceCallback {
  lateinit var virtualDisplay: VirtualDisplay
  lateinit var presentation: Presentation

  override fun onSurfaceAvailable(surfaceContainer: SurfaceContainer) {
      virtualDisplay = context
          .getSystemService(DisplayManager::class.java)
          .createVirtualDisplay(
              VIRTUAL_DISPLAY_NAME ,
              surfaceContainer.width,
              surfaceContainer.height,
              surfaceContainer.dpi,
              surfaceContainer.surface,
              0
          )

      presentation = Presentation(context, virtualDisplay.display)

      // Instantiate the view to be used as the content view
      val view = ...

      presentation.setContentView(view)
      presentation.show()
  }

  override fun onSurfaceDestroyed(surfaceContainer: SurfaceContainer) {
    presentation.dismiss()
    // This handles releasing the Surface provided when creating the VirtualDisplay
    virtualDisplay.release()
  }
}

استخدام Compose للعرض على الشاشة الافتراضية

يمكنك استخدام ComposeView كطريقة عرض المحتوى في Presentation. بما أنّ ComposeView يتم استخدامه خارج نشاط، تأكَّد من أنّ طريقة العرض هذه أو طريقة العرض الرئيسية تنشر LifecycleOwner وSavedStateRegistryOwner. لإجراء ذلك، استخدِم setViewTreeLifecycleOwner وsetViewTreeSavedStateRegistryOwner.

تنفّذ Session حاليًا LifecycleOwner. لأداء كلا الدورَين، يمكن أن ينفّذ نموذج التنفيذ SavedStateRegistryOwner بالإضافة إلى ذلك.

class HelloWorldSession() : Session(), SavedStateRegistryOwner { ... }

class HelloWorldSurfaceCallback(session: HelloWorldSession) : SurfaceCallback {
  ...

  override fun onSurfaceAvailable(surfaceContainer: SurfaceContainer) {
    ...
    val view = ComposeView(session.carContext)
    view.setViewTreeLifecycleOwner(session)
    view.setViewTreeSavedStateRegistryOwner(session)
    view.setContent {
      // Composable content
    }

    presentation.setContentView(view)
    presentation.show()
  }

  ...
}

فهم مساحة العرض المرئية

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

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

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

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

استخدام المظهر الداكن

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

لرسم خريطة داكنة، استخدِم طريقة CarContext.isDarkMode. عندما تتغيّر حالة المظهر الداكن، ستتلقّى طلب استدعاء إلى Session.onCarConfigurationChanged.

رسم الخرائط على شاشة مجموعة العدادات

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