Vẽ bản đồ

Các ứng dụng chỉ đường, địa điểm yêu thích (POI) và thời tiết sử dụng các mẫu sau có thể vẽ bản đồ bằng cách truy cập vào Surface.

Để sử dụng các mẫu sau, ứng dụng của bạn phải khai báo một trong những quyền tương ứng này trong phần tử <uses-permission> trong tệp AndroidManifest.xml.

Xem cách triển khai tham chiếu

Để xem một cách triển khai tham chiếu đầy đủ, hãy xem Mẫu điều hướng.

Khai báo quyền truy cập vào bề mặt

Ngoài quyền bắt buộc đối với mẫu mà ứng dụng của bạn đang dùng, ứng dụng của bạn phải khai báo quyền androidx.car.app.ACCESS_SURFACE trong tệp AndroidManifest.xml để có quyền truy cập vào nền tảng:

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

Truy cập vào bề mặt

Để truy cập vào Surface mà máy chủ cung cấp, bạn phải triển khai SurfaceCallback và cung cấp phương thức triển khai đó cho dịch vụ ô tô AppManager. Surface hiện tại được truyền đến SurfaceCallback của bạn trong tham số SurfaceContainer của các lệnh gọi lại onSurfaceAvailable() và onSurfaceDestroyed().

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

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

Sử dụng màn hình ảo để hiển thị nội dung

Ngoài việc kết xuất trực tiếp vào Surface bằng API Canvas, bạn cũng có thể kết xuất các Khung hiển thị vào Surface bằng API VirtualDisplay và Presentation, như ví dụ này cho thấy:

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()
  }
}

Sử dụng Compose để kết xuất vào màn hình ảo

Bạn có thể dùng ComposeView làm khung hiển thị nội dung của Presentation. Vì ComposeView được dùng bên ngoài một hoạt động, hãy xác nhận rằng hoạt động đó hoặc một khung hiển thị mẹ sẽ truyền một LifecycleOwner và SavedStateRegistryOwner. Để làm điều này, hãy sử dụng setViewTreeLifecycleOwner và setViewTreeSavedStateRegistryOwner.

Session đã triển khai LifecycleOwner. Để đảm nhận cả hai vai trò, quá trình triển khai của bạn có thể triển khai thêm 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()
  }

  ...
}

Tìm hiểu về diện tích bề mặt có thể nhìn thấy

Máy chủ có thể vẽ các phần tử trên giao diện người dùng cho các mẫu trên bản đồ. Máy chủ lưu trữ gọi phương thức SurfaceCallback.onVisibleAreaChanged để thông báo về khu vực của bề mặt có khả năng không bị che khuất và người dùng có thể nhìn thấy nhất.

Để giảm thiểu số lần thay đổi, máy chủ sẽ gọi phương thức SurfaceCallback.onStableAreaChanged có hình chữ nhật nhỏ nhất luôn hiển thị theo mẫu hiện tại.

Ví dụ: khi một ứng dụng chỉ đường dùng NavigationTemplate với một chuỗi hành động ở trên cùng, để có thêm không gian trên màn hình, chuỗi hành động có thể bị che khuất khi người dùng không tương tác với màn hình. Trường hợp này dẫn đến lệnh gọi lại onStableAreaChanged và onVisibleAreaChanged có cùng hình chữ nhật.

Khi chuỗi hành động bị che khuất, chỉ onVisibleAreaChanged được gọi với khu vực lớn hơn. Nếu người dùng tương tác với màn hình, thì chỉ onVisibleAreaChanged được gọi với hình chữ nhật đầu tiên.

Hỗ trợ giao diện tối

Các ứng dụng phải vẽ lại bản đồ của ứng dụng vào thực thể Surface bằng màu tối thích hợp khi chủ thể xác định rằng các điều kiện đó đảm bảo cho thực thể, như mô tả trong phần Chất lượng ứng dụng Android dành cho ô tô.

Để vẽ bản đồ màu tối, hãy sử dụng phương thức CarContext.isDarkMode. Khi trạng thái giao diện tối thay đổi, bạn sẽ nhận được một lệnh gọi tới Session.onCarConfigurationChanged.

Vẽ bản đồ trên màn hình cụm đồng hồ

Ngoài việc vẽ bản đồ trên màn hình chính, các ứng dụng chỉ đường cũng có thể hỗ trợ vẽ bản đồ trên màn hình cụm phía sau vô lăng. Để tìm hiểu thêm, hãy xem phần Vẽ vào màn hình cụm.