Điều chỉnh tỷ lệ nội dung nghe nhìn trên nhiều kiểu dáng thiết bị

Android hỗ trợ nhiều kiểu dáng thiết bị đa dạng ngoài điện thoại thông minh dọc thông thường, bao gồm cả thiết bị gập, máy tính bảng, môi trường cửa sổ kiểu máy tính và màn hình ngoài. Nếu bạn giả định hình dạng màn hình là tĩnh, thì nội dung nghe nhìn có thể bị kéo giãn, cắt bớt hoặc vô tình bị thêm dải đen. Ứng dụng của bạn phải tự động thích ứng với nhiều tỷ lệ khung hình của nội dung nghe nhìn nguồn (từ tỷ lệ 4:3 cổ điển đến tỷ lệ siêu rộng) trên các chế độ hiển thị ngày càng phát triển.

Hầu hết các lỗi bố cục nội dung nghe nhìn trong Jetpack Compose đều bắt nguồn từ 3 lỗi kiến trúc phổ biến:

  • Xử lý phần lồng ghép cửa sổ không nhất quán và xung đột tràn viền.
  • Nội dung cập nhật bố cục không nhất quán do tính toán kích thước cửa sổ không chính xác.
  • Định cấu hình sai các tuỳ chọn điều chỉnh tỷ lệ nội dung.

Hướng dẫn này trình bày các chiến lược và phương pháp hay nhất để giải quyết từng khía cạnh này bằng Media3 và Jetpack Compose.

Xử lý các phần lồng ghép cửa sổ và xung đột tràn viền

Trên các thiết bị chạy Android 15 (cấp độ API 35) trở lên, các ứng dụng nhắm đến cấp độ API 35 trở lên sẽ hiển thị tràn viền theo mặc định. Các thanh hệ thống như thanh trạng thái, thanh điều hướng và thanh chú thích trên màn hình sẽ vẽ đè lên nội dung của ứng dụng, còn vết cắt trên màn hình có thể che khuất một phần nội dung.

Nếu không quản lý đúng cách phần lồng ghép cửa sổ, hai xung đột bố cục chính sẽ xảy ra:

  • Chồng chéo thanh hệ thống: Khung video, phụ đề và bộ điều khiển chế độ phát bị che khuất một phần bởi thanh trạng thái (đồng hồ, biểu tượng pin), thanh điều hướng hoặc cử chỉ, hoặc vết cắt trên màn hình (tai thỏ camera). Để biết hướng dẫn thiết lập chung, hãy xem bài viết Thiết lập chế độ tràn viền.
  • Sự can thiệp của thanh chú thích ở chế độ máy tính: Ở chế độ cửa sổ kiểu máy tính, hệ thống sẽ thêm một thanh chú thích trên cùng để quản lý cửa sổ. Bố cục chuẩn hiển thị tiêu đề tuỳ chỉnh hoặc canvas nội dung nghe nhìn tràn viền mà không tính đến thanh chú thích này sẽ khiến khung video và các nút điều khiển chế độ phát ở trên cùng bị che khuất và không thể nhấp vào. Để biết thêm thông tin chi tiết về trạng thái cửa sổ, hãy xem phần Hỗ trợ cửa sổ kiểu máy tính.
Thanh trạng thái hệ thống chồng lên canvas nội dung nghe nhìn tràn viền và bộ điều khiển chế độ phát. Thanh điều hướng bằng cử chỉ chồng lên canvas nội dung nghe nhìn tràn viền. Thanh phụ đề trên máy tính che khuất bộ điều khiển chế độ phát video ở trên cùng.
Hình 1. Thanh trạng thái hệ thống, thanh điều hướng bằng cử chỉ và thanh chú thích trên máy tính chồng lên canvas nội dung nghe nhìn tràn viền, đồng thời che khuất nội dung video và các bộ điều khiển chế độ phát.

Chiến lược quản lý lồng ghép

Ứng dụng của bạn phải tự động điều chỉnh theo các phần lồng ghép hệ thống dựa trên việc trình phát đang ở chế độ không hiển thị tối đa hay chế độ hiển thị tối đa.

Cấu hình không nhập vai

Trong chế độ phát không tràn màn hình, các thanh hệ thống vẫn hiển thị để giữ nguyên bối cảnh của thiết bị.

Khi trình phát mở rộng đến các cạnh cửa sổ, hãy áp dụng windowInsetsPadding bằng WindowInsets.safeDrawing và only cho mỗi thanh điều khiển PlayerDefaults trên các cạnh nơi thanh điều khiển gặp các thanh hệ thống hoặc vết cắt trên màn hình (ví dụ: Top + Horizontal trên TopControls và Bottom + Horizontal trên BottomControls). Thao tác này giúp các nút điều khiển không bị che khuất bởi các thanh hệ thống trong khi giao diện video mở rộng trên vùng chứa.

@Composable
fun NonImmersiveVideoPlayer(
  player: Player,
  showControls: Boolean,
  modifier: Modifier = Modifier,
) {
  Player(
    player = player,
    modifier = modifier,
    showControls = showControls,
    // Keep top controls clear of the status bar, caption bar, and display cutout
    topControls = {
      PlayerDefaults.TopControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.safeDrawing.only(WindowInsetsSides.Top + WindowInsetsSides.Horizontal)
            ),
      ) {
        MuteButton(player = player, modifier = Modifier.align(Alignment.TopEnd).padding(16.dp))
      }
    },
    // Keep bottom controls clear of the navigation bar and display cutout
    bottomControls = {
      PlayerDefaults.BottomControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.safeDrawing.only(
                WindowInsetsSides.Bottom + WindowInsetsSides.Horizontal
              )
            ),
      )
    },
  )
}

Ở chế độ hiển thị tối đa, ứng dụng tích hợp khoảng đệm lồng ghép cửa sổ để tự động dịch chuyển nội dung vào trong.
Hình 2. Ở chế độ không hiển thị tối đa, ứng dụng sẽ áp dụng khoảng đệm lồng ghép cửa sổ để dịch chuyển các thành phần điều khiển vào trong.

Cấu hình hiển thị toàn màn hình (dọc và ngang)

Ở chế độ nhập vai toàn màn hình, mục tiêu là tối đa hoá canvas để mang lại trải nghiệm đậm chất điện ảnh, đồng thời vẫn cho phép người dùng truy cập vào bộ điều khiển chế độ phát:

  1. Áp dụng windowInsetsPadding cho lớp phủ điều khiển nội dung nghe nhìn (chẳng hạn như các nút điều khiển trên cùng và dưới cùng) để ngăn các lớp phủ này chồng chéo lên vết cắt trên màn hình hoặc vùng cử chỉ hệ thống (ví dụ: kết hợp WindowInsets.displayCutout với WindowInsets.systemGestures trên các nút điều khiển dưới cùng để thanh tua không xung đột với cử chỉ vuốt từ cạnh).
  2. Ẩn thanh hệ thống bằng cách sử dụng WindowInsetsControllerCompat bên trong DisposableEffect, đảm bảo chế độ hiển thị Giao diện người dùng hệ thống được khôi phục khi rời khỏi composable.

@Composable
fun ImmersiveVideoPlayer(player: Player, showControls: Boolean, modifier: Modifier = Modifier) {
  val view = LocalView.current

  // Manages the system UI lifecycle to create an edge-to-edge cinematic experience
  DisposableEffect(view) {
    // Finds the hosting Activity, unwrapping any ContextWrapper around the view's context
    val activity =
      generateSequence(view.context) { (it as? ContextWrapper)?.baseContext }
        .filterIsInstance<Activity>()
        .firstOrNull()
    val window = activity?.window ?: return@DisposableEffect onDispose {}
    val controller = WindowCompat.getInsetsController(window, view)

    // Records the current system bar state so it can be restored on dispose
    val insets = ViewCompat.getRootWindowInsets(view)
    val wereSystemBarsVisible =
      insets == null ||
        insets.isVisible(WindowInsetsCompat.Type.statusBars()) ||
        insets.isVisible(WindowInsetsCompat.Type.navigationBars())
    val previousBehavior = controller.systemBarsBehavior

    // Hides status bars, navigation bars, and caption bars to maximize the video canvas
    controller.hide(WindowInsetsCompat.Type.systemBars())

    // Allows hidden system bars to temporarily reappear with a swipe gesture from the edge
    controller.systemBarsBehavior =
      WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

    onDispose {
      // Restores the previous system bar state when leaving the composable
      controller.systemBarsBehavior = previousBehavior
      if (wereSystemBarsVisible) {
        controller.show(WindowInsetsCompat.Type.systemBars())
      }
    }
  }

  Player(
    player = player,
    modifier = modifier,
    showControls = showControls,
    // Keep top controls clear of the display cutout while the system bars are hidden
    topControls = {
      PlayerDefaults.TopControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.displayCutout.only(
                WindowInsetsSides.Top + WindowInsetsSides.Horizontal
              )
            ),
      ) {
        MuteButton(player = player, modifier = Modifier.align(Alignment.TopEnd).padding(16.dp))
      }
    },
    // Keep bottom controls clear of the display cutout and system gesture areas
    bottomControls = {
      PlayerDefaults.BottomControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.displayCutout
                .union(WindowInsets.systemGestures)
                .only(WindowInsetsSides.Bottom + WindowInsetsSides.Horizontal)
            ),
      )
    },
  )
}

Thanh hệ thống sẽ tự động ẩn khi trình phát video chuyển sang chế độ hiển thị tối đa, mang đến trải nghiệm xem phim toàn màn hình.
Hình 3. Thanh hệ thống sẽ ẩn khi trình phát video chuyển sang chế độ hiển thị tối đa.

Tính toán kích thước cửa sổ động và cập nhật bố cục

Việc chỉ tính toán chiều rộng hoặc chiều cao màn hình một lần khi khởi động ứng dụng sẽ khiến bố cục dựa vào các giá trị cũ khi cấu hình thiết bị thay đổi, chẳng hạn như khi thiết bị có thể gập lại được mở ra, phiên nhiều cửa sổ được đổi kích thước hoặc màn hình được xoay.

Trong những trường hợp này, ngay cả khi thành phần con sử dụng đúng cách Modifier.fillMaxWidth(), thành phần đó vẫn không thể thích ứng nếu vùng chứa mẹ bị ràng buộc bởi các phương diện cũ, gây ra tình trạng kéo giãn, cắt bớt hoặc bố cục không thích ứng.

Trong ví dụ sau, khung bên trái minh hoạ việc kết xuất chính xác trên một khung nhìn chuẩn, trong khi khung bên phải minh hoạ việc kích thước cửa sổ cũ không thích ứng khi thiết bị được mở ra, dẫn đến bố cục nội dung không thích ứng.

Hiển thị chính xác trên khung nhìn chuẩn với khả năng điều chỉnh tỷ lệ khung hình linh động. Kích thước cửa sổ cũ không điều chỉnh được khi thiết bị mở ra.
Hình 4. So sánh khả năng thích ứng tỷ lệ khung hình động.

Để tránh các quy tắc ràng buộc bố cục cũ, hãy sử dụng Jetpack Media Query API. Vì API này đang trong giai đoạn thử nghiệm và bị tắt theo mặc định, nên trước tiên, hãy bật hàm mediaQuery bằng cách đặt ComposeUiFlags.isMediaQueryIntegrationEnabled = true (ví dụ: trước khi gọi setContent) và chọn sử dụng bằng @OptIn(ExperimentalMediaQueryApi::class).

Sử dụng derivedMediaQuery để đánh giá các điều kiện về kích thước cửa sổ hiện tại, chẳng hạn như windowWidth, nhờ đó bố cục của bạn sẽ cập nhật khi cửa sổ thay đổi mà không cần kết hợp lại không cần thiết. Bạn có thể kết hợp derivedMediaQuery với các điểm ngắt WindowSizeClass để chuyển đổi giữa bố cục trình phát một ngăn và nhiều ngăn khi cửa sổ mở rộng:

@OptIn(ExperimentalMediaQueryApi::class)
@Composable
fun AdaptiveVideoPlayerScreen(
  player: Player,
  modifier: Modifier = Modifier,
  relatedContent: @Composable () -> Unit,
) {
  val isWideWindow by derivedMediaQuery {
    windowWidth >= WindowSizeClass.WIDTH_DP_MEDIUM_LOWER_BOUND.dp
  }

  if (isWideWindow) {
    // Medium or expanded width: place the player alongside a details or playlist pane
    Row(modifier = modifier.fillMaxSize()) {
      Player(player = player, modifier = Modifier.weight(0.65f).fillMaxHeight())
      Box(modifier = Modifier.weight(0.35f).fillMaxHeight()) { relatedContent() }
    }
  } else {
    // Compact width: stack a 16:9 player above the details pane
    Column(modifier = modifier.fillMaxSize()) {
      Player(player = player, modifier = Modifier.fillMaxWidth().aspectRatio(16f / 9f))
      Box(modifier = Modifier.weight(1f).fillMaxWidth()) { relatedContent() }
    }
  }
}

Định cấu hình tỷ lệ khung hình và tỷ lệ nội dung

Phân biệt giữa việc quản lý vùng chứa có sẵn và việc điều chỉnh tỷ lệ nội dung nghe nhìn. Sử dụng tính năng quản lý phần lồng ghép, chẳng hạn như khoảng đệm vùng an toàn, để đặt ranh giới vùng chứa tương ứng với thanh hệ thống và vết cắt trên màn hình. Sau đó, hãy áp dụng các chiến lược điều chỉnh tỷ lệ trong những ranh giới đó. Để biết hướng dẫn thiết kế về cách tạo cấu trúc cho vùng chứa và điều chỉnh tỷ lệ nội dung hình ảnh theo tỷ lệ khung hình, hãy xem bài viết Cấu trúc và bố cục nội dung.

Trong ví dụ sau, hình ảnh bên trái cho thấy cách chiến lược cắt có thể cắt bỏ nội dung khi cần hiển thị đầy đủ, trong khi hình ảnh bên phải cho thấy cách chiến lược điều chỉnh giữ nguyên tỷ lệ khung hình gốc để hiển thị toàn khung hình.

Chiến lược cắt ảnh gây mất nội dung đáng kể khi cần hiển thị đầy đủ. Chiến lược điều chỉnh duy trì tỷ lệ khung hình gốc để kết xuất toàn khung hình.
Hình 5. So sánh các hành vi điều chỉnh tỷ lệ.

Các thành phần Media3 tự động xử lý tỷ lệ khung hình video chuẩn, nhưng cấu hình ContentScale rõ ràng sẽ trở nên quan trọng khi làm việc với bố cục Compose tuỳ chỉnh hoặc vùng chứa bị ràng buộc (chẳng hạn như nguồn cấp dữ liệu trên mạng xã hội có thể cuộn). Việc chọn tỷ lệ nội dung không phù hợp có thể dẫn đến các vấn đề về bố cục, chẳng hạn như video bị méo (giãn) hoặc hiệu ứng hòm thư không mong muốn khiến khung nhìn có khoảng trống. Việc quản lý các nền tảng video theo cách thủ công mà không có các tuỳ chọn này cũng có thể dẫn đến bố cục bị hỏng trong quá trình xoay màn hình hoặc thay đổi trạng thái thiết bị có thể gập lại.

Cho dù hiển thị video 16:9 trên màn hình 4:3 hay video 4:3 trên màn hình 16:9, thành phần kết hợp Player đều mặc định là ContentScale.Fit. Điều này giúp toàn bộ video hiển thị mà không bị cắt bằng cách áp dụng hiệu ứng hòm thư hoặc hiệu ứng cột.

Các thay đổi tiếp theo về chế độ hiển thị (chẳng hạn như thu phóng hoặc cắt) phải do người dùng thực hiện. Ví dụ: chuyển sang ContentScale.Crop để lấp đầy vùng chứa. Nút bật/tắt tỷ lệ tương tác giúp cân bằng giữa yêu cầu về bố cục và sự lựa chọn của người dùng.

Ví dụ về cách triển khai

Bạn có thể thực thi chế độ hiển thị toàn khung hình và xử lý tỷ lệ khung hình bằng các thuộc tính ContentScale tiêu chuẩn của Compose.

Sử dụng thành phần kết hợp Player

Cách đơn giản và trực tiếp nhất là sử dụng thành phần kết hợp Player. Đóng vai trò là một trình bao bọc cấp cao tự động xử lý ranh giới điều chỉnh tỷ lệ, trình bao bọc này ghép nối ContentFrame để kết xuất video với các lớp phủ điều khiển có thể tuỳ chỉnh (topControls, centerControls, bottomControls) và một lớp màn trập:

@Composable
fun FitVideoPlayer(player: Player, modifier: Modifier = Modifier) {
  Player(
    player = player,
    modifier = modifier.fillMaxSize(), // Fill the available space
    contentScale = ContentScale.Fit, // Default; shown for clarity
  )
}

Khi tạo bố cục trình phát video tuỳ chỉnh hoặc đặt các lớp giao diện người dùng tuỳ chỉnh ngay trên luồng video, bạn có thể sử dụng trực tiếp ContentFrame để kiểm soát bố cục chính xác và ở cấp thấp hơn.

Nút bật/tắt tính năng tự động điều chỉnh tỷ lệ do người dùng kiểm soát

Để nâng cao trải nghiệm xem của ứng dụng, bạn có thể thêm một nút bật/tắt không bắt buộc để chuyển đổi giữa các lựa chọn điều chỉnh tỷ lệ nội dung. Bằng cách phát hiện cử chỉ nhấn đúp, bạn có thể chuyển đổi ngay trạng thái của trình phát giữa ContentScale.Fit và ContentScale.Crop. Bạn cũng có thể mở rộng chức năng này để hỗ trợ điều chỉnh ContentScale linh động bằng cử chỉ chụm để thu phóng hoặc các cử chỉ nhiều điểm chạm khác, tương tự như các ứng dụng truyền phát video hiện đại.

Hình 6. Chuyển đổi giữa ContentScale.Fit và ContentScale.Crop.

@Composable
fun ZoomableVideoPlayer(player: Player, modifier: Modifier = Modifier) {
  var isCropped by rememberSaveable { mutableStateOf(false) }

  Player(
    player = player,
    modifier =
      modifier
        .fillMaxSize()
        // Handle double-tap to toggle between Fit and Crop scaling
        .pointerInput(Unit) { detectTapGestures(onDoubleTap = { isCropped = !isCropped }) },
    contentScale = if (isCropped) ContentScale.Crop else ContentScale.Fit,
  )
}

Mặc dù có một số lựa chọn điều chỉnh tỷ lệ nội dung, nhưng hãy chọn lựa chọn điều chỉnh tỷ lệ dựa trên trường hợp sử dụng của bạn: sử dụng ContentScale.Crop cho video ngắn hoặc nguồn cấp dữ liệu có thể cuộn, trong đó mục tiêu chính là lấp đầy màn hình và đặt mặc định thành ContentScale.Fit cho nội dung nghe nhìn có thông tin lề quan trọng, chẳng hạn như điểm số thể thao hoặc phụ đề, để bảo vệ bối cảnh hình ảnh thiết yếu.