رسم الخرائط

يمكن لتطبيقات التنقّل ونقاط الاهتمام والطقس التي تستخدم النماذج التالية رسم الخرائط من خلال الوصول إلى 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، يمكنك أيضًا عرض "طرق العرض" في Surface باستخدام واجهتَي برمجة التطبيقات VirtualDisplay وPresentation، كما يوضّح المثال التالي:

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.

رسم الخرائط على شاشة العرض

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