ترسیم نقشه ها

برنامه‌های ناوبری، نقاط مورد علاقه (POI) و آب و هوا با استفاده از الگوهای زیر می‌توانند با دسترسی به یک Surface نقشه‌ها را ترسیم کنند.

برای استفاده از قالب‌های زیر، برنامه شما باید یکی از این مجوزهای مربوطه را در عنصر <uses-permission> در فایل AndroidManifest.xml اعلان کند.

به پیاده‌سازی مرجع مراجعه کنید

برای مشاهده‌ی یک پیاده‌سازی مرجع کامل، به نمونه‌ی ناوبری مراجعه کنید.

اعلام مجوز سطح

علاوه بر مجوز مورد نیاز برای قالبی که برنامه شما از آن استفاده می‌کند، برنامه شما باید مجوز androidx.car.app.ACCESS_SURFACE را در فایل AndroidManifest.xml خود اعلام کند تا به surface دسترسی پیدا کند:

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

دسترسی به سطح

برای دسترسی به Surface که میزبان ارائه می‌دهد، باید یک SurfaceCallback پیاده‌سازی کنید و آن پیاده‌سازی را به سرویس AppManager car ارائه دهید. Surface فعلی در پارامتر SurfaceContainer از callbackهای onSurfaceAvailable() و onSurfaceDestroyed() به SurfaceCallback شما ارسال می‌شود.

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

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

استفاده از نمایشگر مجازی برای رندر کردن محتوا

علاوه بر رندر کردن مستقیم در Surface با استفاده از Canvas API، می‌توانید Viewها را با استفاده از VirtualDisplay و Presentation APIها نیز در Surface رندر کنید، همانطور که این مثال نشان می‌دهد:

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 خارج از یک activity استفاده می‌شود، مطمئن شوید که آن یا یک نمای والد 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 ترسیم کنند، همانطور که در بخش کیفیت برنامه اندروید برای خودروها توضیح داده شده است.

برای رسم یک نقشه تیره، از متد CarContext.isDarkMode استفاده کنید. وقتی وضعیت تم تیره تغییر می‌کند، فراخوانی به Session.onCarConfigurationChanged دریافت می‌کنید.

نقشه‌ها را روی صفحه نمایش خوشه‌ای رسم کنید

علاوه بر ترسیم نقشه‌ها روی نمایشگر اصلی، برنامه‌های ناوبری می‌توانند از ترسیم نقشه‌ها روی نمایشگر خوشه‌ای پشت فرمان نیز پشتیبانی کنند. برای کسب اطلاعات بیشتر، به «طراحی در نمایشگر خوشه‌ای» مراجعه کنید.