縮放各種板型規格的媒體內容

Android 支援多種板型規格,不限於傳統直向智慧型手機,包括摺疊式裝置、平板電腦、電腦分割視窗環境和外接螢幕。如果假設螢幕幾何圖形是靜態的,媒體內容可能會被拉伸、裁剪或意外加上黑邊。應用程式必須動態調整,以因應不斷演進的顯示模式,支援各種來源媒體顯示比例 (從傳統 4:3 到超寬螢幕)。

Jetpack Compose 中大多數媒體版面配置失敗的原因,都源自三個常見的架構問題:

  • 視窗插邊處理不一致,且與無邊框設計衝突。
  • 視窗大小計算錯誤,導致版面配置更新不一致。
  • 內容縮放選項設定錯誤。

本指南將說明使用 Media3 和 Jetpack Compose 處理各個領域的策略和最佳做法。

處理視窗插邊和無邊框衝突

在搭載 Android 15 (API 級別 35) 以上版本的裝置上,指定 API 級別 35 以上版本的應用程式預設會無邊框顯示。狀態列、導覽列和桌面標題列等系統資訊列會繪製在應用程式內容上方,而螢幕凹口可能會遮住部分內容。

如果沒有妥善管理視窗插邊,會發生兩種主要的版面配置衝突:

  • 系統資訊列重疊:影片影格、字幕和播放控制項部分遭到狀態列 (時鐘、電池圖示)、手勢或導覽列,或螢幕凹口 (相機凹口) 遮擋。如需一般設定指南,請參閱「設定無邊框」。
  • 電腦模式說明文字列干擾:在電腦分割視窗模式中,系統會導入頂端說明文字列,用於管理視窗。如果標準版面配置在算繪自訂標頭或無邊框媒體畫布時,未考量到這個字幕列,就會導致影片影格和頂端播放控制項遭到遮蓋,無法點選。如要進一步瞭解視窗狀態,請參閱「支援電腦分割視窗」。
系統狀態列與無邊框媒體畫布和播放控制項重疊。 手勢操作導覽列與無邊框媒體畫布重疊。 電腦版字幕列與頂端影片播放控制項重疊。
圖 1. 系統狀態列、手勢操作導覽列和桌面標題列與無邊框媒體畫布重疊,遮住影片內容和播放控制項。

插頁管理策略

應用程式應根據玩家是否處於非沉浸模式或沉浸模式,動態調整系統插邊。

非沉浸式設定

在非沉浸式播放模式中,系統資訊列會保持顯示,以保留裝置背景資訊。

當播放器延伸至視窗邊緣時,請在與系統資訊列或螢幕凹口相接的邊緣,對每個 PlayerDefaults 控制列套用 windowInsetsPadding,並搭配 WindowInsets.safeDrawing 和 only (例如 TopControls 上的 Top + Horizontal 和 BottomControls 上的 Bottom + Horizontal)。這樣一來,當影片介面延伸至整個容器時,控制項就不會與系統資訊列重疊。

@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
              )
            ),
      )
    },
  )
}

在非沉浸模式下,應用程式會整合視窗內嵌邊框間距,動態向內移動內容。
圖 2. 在非沉浸模式下,應用程式會套用視窗內嵌邊框間距,將控制項向內移動。

沉浸式設定 (直向和橫向)

在全螢幕沉浸模式下,目標是盡可能擴大畫布,提供電影般的體驗,同時讓使用者能存取播放控制項:

  1. 將 windowInsetsPadding 套用至媒體遙控器疊加層 (例如頂端和底部控制項),避免與螢幕凹口或系統手勢區域重疊 (例如在底部控制項上結合 WindowInsets.displayCutout 和 WindowInsets.systemGestures,避免跳轉滑桿與邊緣滑動手勢衝突)。
  2. 在 DisposableEffect 中使用 WindowInsetsControllerCompat 隱藏系統資訊列,確保離開可組合函式時,系統 UI 會恢復顯示。

@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)
            ),
      )
    },
  )
}

影片播放器進入沉浸模式時,系統資訊列會自動隱藏,提供全螢幕電影級體驗。
圖 3. 影片播放器進入沉浸模式時,系統資訊列會隱藏。

計算動態視窗大小和版面配置更新

如果只在應用程式啟動時計算螢幕寬度或高度,當裝置設定變更時 (例如摺疊式裝置展開、多視窗模式工作階段大小調整,或螢幕旋轉),版面配置就會依賴過時的值。

在這種情況下,即使子項元件正確使用 Modifier.fillMaxWidth(),如果父項容器受限於過時的尺寸,子項元件也無法調整,導致版面配置拉伸、裁剪或沒有回應。

在以下範例中,左側畫面顯示標準可視區域的正確算繪,右側畫面則顯示裝置展開時,過時的視窗尺寸無法調整,導致內容版面配置不具回應性。

在標準可視區域中正確顯示,並動態調整顯示比例。 裝置展開時,舊視窗尺寸無法調整。
圖 4. 動態顯示比例調整功能比較。

為避免版面配置限制過時,請使用 Jetpack 媒體查詢 API。由於這個 API 屬於實驗性質,且預設為停用,因此請先設定 ComposeUiFlags.isMediaQueryIntegrationEnabled = true (例如在呼叫 setContent 之前),啟用 mediaQuery 函式,並使用 @OptIn(ExperimentalMediaQueryApi::class) 選擇加入。

使用 derivedMediaQuery 評估目前視窗大小的條件 (例如 windowWidth),這樣一來,版面配置就會在視窗變更時更新,而不會進行不必要的重組。您可以將 derivedMediaQuery 與 WindowSizeClass 中斷點結合,在視窗展開時切換單窗格和多窗格播放器版面配置:

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

設定內容縮放和顯示比例

請區分管理可用容器區域和縮放媒體內容本身。使用插邊管理 (例如安全區域邊框間距),設定容器相對於系統資訊列和螢幕凹口的邊界。然後在這些界限內套用資源調度策略。如需有關建構容器和跨顯示比例縮放視覺內容的設計指南,請參閱「內容組成和結構」。

在以下範例中,左圖顯示裁剪策略如何在需要完整顯示時切除內容,右圖則顯示調整策略如何保留原生顯示比例,以全螢幕顯示。

裁剪策略導致重要內容遺失,但需要完整顯示。 維持原生顯示比例,以全幅顯示。
圖 5. 縮放行為比較。

Media3 元件會自動處理標準影片顯示比例,但使用自訂 Compose 版面配置或受限容器 (例如可捲動的社群動態) 時,明確的 ContentScale 設定就變得至關重要。如果選取不當的內容縮放比例,可能會導致版面配置問題,例如影片失真 (拉伸) 或非預期的上下黑邊,導致可視區域留空。如果沒有這些選項,手動管理影片介面也可能導致螢幕旋轉或摺疊式裝置狀態變更時,版面配置損毀。

無論是在 4:3 螢幕上顯示 16:9 影片,還是在 16:9 螢幕上顯示 4:3 影片,Player 可組合項預設都會採用 ContentScale.Fit。這樣一來,系統就會套用上下黑邊或左右黑邊,完整顯示影片,不會裁剪。

後續的顯示模式變更 (例如縮放或裁剪) 應由使用者驅動。例如,切換至 ContentScale.Crop 即可完全填滿容器。互動式縮放切換鈕可平衡版面配置需求和使用者選擇。

導入範例

您可以使用標準 Compose ContentScale 屬性,強制顯示完整影格並處理顯示比例。

使用 Player 可組合函式

最簡單直接的方法是使用 Player 可組合函式。這個高階包裝函式會自動處理縮放邊界,並將用於影片算繪的 ContentFrame 與可自訂的控制項疊加層 (topControls、centerControls、bottomControls) 和快門層配對:

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

建構自訂影片播放器版面配置,或直接在影片串流上放置自訂 UI 圖層時,可以直接使用 ContentFrame,進行精確的低階版面配置控制。

動態使用者控制資源配置切換鈕

如要提升應用程式的觀看體驗,可以新增選用切換鈕,在不同的內容縮放選項之間切換。偵測到輕觸兩下的手勢時,即可立即在 ContentScale.Fit 和 ContentScale.Crop 之間切換播放器狀態。您也可以擴充這項功能,支援使用雙指撥動縮放或其他多點觸控手勢動態調整 ContentScale,類似於現代影片串流應用程式。

圖 6. 在 ContentScale.Fit 和 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,
  )
}

雖然有多種內容縮放選項,但請根據用途選擇縮放選項:如果是短篇影片或可捲動的動態消息,且主要目標是填滿螢幕,請使用 ContentScale.Crop;如果是含有重要邊界資訊的媒體 (例如運動賽事比分或字幕),請預設使用 ContentScale.Fit,以保護重要的視覺背景資訊。