ปรับขนาดเนื้อหาสื่อในอุปกรณ์รูปแบบต่างๆ

Android รองรับรูปแบบของอุปกรณ์ที่หลากหลายนอกเหนือจากสมาร์ทโฟนแนวตั้งแบบเดิม ซึ่งรวมถึงอุปกรณ์แบบพับได้ แท็บเล็ต สภาพแวดล้อมหน้าต่างเดสก์ท็อป และจอแสดงผลภายนอก หากคุณคิดว่ารูปทรงเรขาคณิตของหน้าจอเป็นแบบคงที่ เนื้อหาสื่ออาจถูกยืด ครอบตัด หรือมีแถบสีดำโดยไม่ได้ตั้งใจ แอปของคุณต้องปรับเปลี่ยนตามสัดส่วนภาพของสื่อต้นฉบับที่หลากหลาย (ตั้งแต่ 4:3 แบบคลาสสิกไปจนถึงแบบกว้างพิเศษ) ในโหมดการแสดงผลที่พัฒนาไปเรื่อยๆ

ความล้มเหลวด้านเลย์เอาต์สื่อส่วนใหญ่ใน Jetpack Compose เกิดจากข้อผิดพลาดทางสถาปัตยกรรมที่พบบ่อย 3 ประการ ได้แก่

  • การจัดการส่วนแทรกของหน้าต่างและการชนกันแบบไร้ขอบที่ไม่สอดคล้องกัน
  • การอัปเดตเลย์เอาต์ไม่สอดคล้องกันเนื่องจากการคำนวณขนาดหน้าต่างไม่ถูกต้อง
  • การกำหนดค่าตัวเลือกการปรับขนาดเนื้อหาไม่ถูกต้อง

คู่มือนี้จะกล่าวถึงกลยุทธ์และแนวทางปฏิบัติแนะนำสำหรับการจัดการแต่ละด้านโดยใช้ Media3 และ Jetpack Compose

จัดการส่วนที่เว้นไว้ในหน้าต่างและการชนกันแบบไร้ขอบ

ในอุปกรณ์ที่ใช้ Android 15 (ระดับ API 35) ขึ้นไป แอปที่กำหนดเป้าหมายเป็นระดับ API 35 ขึ้นไปจะแสดงผลแบบไร้ขอบโดยค่าเริ่มต้น แถบระบบ เช่น แถบสถานะ แถบการนำทาง และแถบคำบรรยายบนเดสก์ท็อปจะแสดงทับเนื้อหาของแอป และหน้าจอรอยบากอาจบดบังบางส่วนของเนื้อหา

หากไม่มีการจัดการส่วนแทรกของหน้าต่างที่เหมาะสม จะเกิดความขัดแย้งของเลย์เอาต์ที่สำคัญ 2 ประการดังนี้

  • แถบระบบซ้อนทับ: เฟรมวิดีโอ คำบรรยาย และตัวควบคุมการเล่นถูกบดบังบางส่วนโดยแถบสถานะ (นาฬิกา ไอคอนแบตเตอรี่) แถบการนำทางหรือท่าทางสัมผัส หรือหน้าจอรอยบาก (รอยบากกล้อง) ดูคำแนะนำการตั้งค่าทั่วไปได้ที่ตั้งค่าแบบไร้ขอบ
  • การรบกวนแถบคำอธิบายภาพในโหมดเดสก์ท็อป: ในโหมดหน้าต่างเดสก์ท็อป ระบบจะเพิ่มแถบคำอธิบายภาพด้านบนสำหรับการจัดการหน้าต่าง เลย์เอาต์มาตรฐานที่แสดงผลส่วนหัวที่กำหนดเองหรือ Canvas สื่อแบบเต็มหน้าจอโดยไม่คำนึงถึงแถบคำบรรยายนี้จะทำให้เฟรมวิดีโอและตัวควบคุมการเล่นด้านบนถูกบดบังและคลิกไม่ได้ ดูรายละเอียดเพิ่มเติมเกี่ยวกับสถานะหน้าต่างได้ที่รองรับหน้าต่างเดสก์ท็อป
แถบสถานะของระบบซ้อนทับกับ Canvas สื่อแบบไร้ขอบและตัวควบคุมการเล่น แถบการไปยังส่วนต่างๆ ด้วยท่าทางสัมผัสซ้อนทับกับ Canvas สื่อแบบไร้ขอบ แถบคำบรรยายแทนเสียงบนเดสก์ท็อปซ้อนทับตัวควบคุมการเล่นวิดีโอด้านบน
รูปที่ 1 แถบสถานะของระบบ แถบนำทางด้วยท่าทางสัมผัส และแถบคำบรรยายบนเดสก์ท็อปซ้อนทับกับ Canvas สื่อแบบไร้ขอบ และบดบังเนื้อหาวิดีโอและตัวควบคุมการเล่น

กลยุทธ์การจัดการการลดการปล่อยก๊าซในห่วงโซ่อุปทาน

แอปของคุณควรปรับให้เข้ากับส่วนแทรกของระบบแบบไดนามิกโดยขึ้นอยู่กับว่าโปรแกรมเล่นอยู่ในโหมดไม่ใหญ่พิเศษหรือโหมดใหญ่พิเศษ

การกำหนดค่าแบบไม่สมจริง

ในการเล่นแบบไม่สมจริง แถบระบบจะยังคงมองเห็นได้เพื่อรักษาบริบทของอุปกรณ์

เมื่อเพลเยอร์ขยายไปถึงขอบหน้าต่าง ให้ใช้ windowInsetsPadding กับ WindowInsets.safeDrawing และ only กับแถบควบคุม PlayerDefaults แต่ละแถบที่ขอบซึ่งบรรจบกับแถบระบบหรือหน้าจอรอยบาก (เช่น Top + Horizontal ใน TopControls และ Bottom + Horizontal ใน BottomControls) วิธีนี้จะช่วยให้ตัวควบคุมไม่ทับซ้อนกับแถบระบบขณะที่พื้นผิววิดีโอขยายไปทั่วคอนเทนเนอร์

@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 ในโหมดไม่ใหญ่พิเศษ แอปจะใช้ระยะห่างจากขอบของส่วนแทรกหน้าต่างเพื่อเลื่อนตัวควบคุมเข้าด้านใน

การกำหนดค่าแบบสมจริง (แนวตั้งและแนวนอน)

ในโหมดใหญ่พิเศษแบบเต็มหน้าจอ เป้าหมายคือการเพิ่มขนาด Canvas ให้ใหญ่ที่สุดเพื่อประสบการณ์การรับชมแบบภาพยนตร์ ขณะเดียวกันก็ยังเข้าถึงตัวควบคุมการเล่นได้ ดังนี้

  1. ใช้ windowInsetsPadding กับการวางซ้อนตัวควบคุมสื่อ (เช่น ตัวควบคุมด้านบนและด้านล่าง) เพื่อป้องกันไม่ให้ทับซ้อนกับหน้าจอรอยบากหรือพื้นที่ท่าทางสัมผัสของระบบ (เช่น การรวม WindowInsets.displayCutout กับ WindowInsets.systemGestures ในตัวควบคุมด้านล่างเพื่อให้แถบเลื่อนไม่ขัดแย้งกับท่าทางสัมผัสการปัดขอบ)
  2. ซ่อนแถบระบบโดยใช้ WindowInsetsControllerCompat ภายใน DisposableEffect เพื่อให้มั่นใจว่าระดับการเข้าถึง UI ของระบบจะกลับมาเมื่อออกจาก 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)
            ),
      )
    },
  )
}

แถบระบบจะซ่อนโดยอัตโนมัติเมื่อวิดีโอเพลเยอร์เข้าสู่โหมดใหญ่พิเศษ เพื่อมอบประสบการณ์การรับชมแบบภาพยนตร์เต็มหน้าจอ
รูปที่ 3 แถบระบบจะซ่อนเมื่อวิดีโอเพลเยอร์เข้าสู่โหมดใหญ่พิเศษ

คำนวณการปรับขนาดหน้าต่างแบบไดนามิกและการอัปเดตเลย์เอาต์

การคำนวณความกว้างหรือความสูงของหน้าจอเพียงครั้งเดียวเมื่อเริ่มต้นแอปจะทำให้เลย์เอาต์ใช้ค่าที่ล้าสมัยเมื่อการกำหนดค่าอุปกรณ์เปลี่ยนแปลง เช่น เมื่อกางอุปกรณ์แบบพับได้ออก มีการปรับขนาดเซสชันแบบหลายหน้าต่าง หรือมีการหมุนจอแสดงผล

ในกรณีเหล่านี้ แม้ว่าคอมโพเนนต์ย่อยจะใช้ Modifier.fillMaxWidth() อย่างถูกต้อง แต่ก็จะไม่สามารถปรับเปลี่ยนได้หากคอนเทนเนอร์หลักถูกจำกัดด้วยมิติข้อมูลที่ล้าสมัย ซึ่งทำให้เกิดการยืด การตัด หรือเลย์เอาต์ที่ไม่ตอบสนอง

ในตัวอย่างต่อไปนี้ เฟรมด้านซ้ายแสดงการแสดงผลที่ถูกต้องในวิวพอร์ตมาตรฐาน ส่วนเฟรมด้านขวาแสดงความล้มเหลวของขนาดหน้าต่างที่ล้าสมัยในการปรับเมื่อกางอุปกรณ์ออก ส่งผลให้เลย์เอาต์เนื้อหาไม่ตอบสนอง

การแสดงผลที่ถูกต้องในวิวพอร์ตมาตรฐานที่มีการปรับสัดส่วนภาพแบบไดนามิก ขนาดหน้าต่างที่ล้าสมัยไม่ปรับเปลี่ยนเมื่อกางอุปกรณ์ออก
รูปที่ 4 การเปรียบเทียบการปรับสัดส่วนภาพแบบไดนามิก

หากต้องการหลีกเลี่ยงข้อจำกัดของเลย์เอาต์ที่ล้าสมัย ให้ใช้ Jetpack Media Query API เนื่องจาก API นี้เป็นเวอร์ชันทดลองและปิดใช้อยู่โดยค่าเริ่มต้น ก่อนอื่นให้เปิดใช้ฟังก์ชัน mediaQuery โดยตั้งค่า ComposeUiFlags.isMediaQueryIntegrationEnabled = true (เช่น ก่อนเรียกใช้ setContent) และเลือกใช้ด้วย @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 จะจัดการสัดส่วนภาพวิดีโอมาตรฐานโดยอัตโนมัติ แต่การกำหนดค่า ContentScale อย่างชัดเจนจะมีความสำคัญอย่างยิ่งเมื่อทำงานกับเลย์เอาต์ Compose ที่กำหนดเองหรือคอนเทนเนอร์ที่ถูกจำกัด (เช่น ฟีดโซเชียลที่เลื่อนได้) การเลือกขนาดเนื้อหาที่ไม่เหมาะสมอาจทำให้เกิดปัญหาเกี่ยวกับเลย์เอาต์ เช่น การบิดเบี้ยวของวิดีโอ (การยืด) หรือการแสดงผลแบบ Letterbox โดยไม่ตั้งใจซึ่งทำให้มีพื้นที่ว่างในวิวพอร์ต การจัดการแพลตฟอร์มวิดีโอด้วยตนเองโดยไม่มีตัวเลือกเหล่านี้อาจส่งผลให้เลย์เอาต์เสียหายระหว่างการหมุนหน้าจอหรือการเปลี่ยนแปลงสถานะของอุปกรณ์แบบพับได้

ไม่ว่าจะแสดงวิดีโอ 16:9 บนหน้าจอ 4:3 หรือวิดีโอ 4:3 บนจอแสดงผล 16:9 คอมโพสิเบิล Player จะมีค่าเริ่มต้นเป็น ContentScale.Fit ซึ่งจะช่วยให้วิดีโอแบบเต็มแสดงได้โดยไม่มีการครอบตัดด้วยการใช้แถบสีดำด้านบนและด้านล่างหรือแถบสีดำด้านซ้ายและด้านขวา

การเปลี่ยนแปลงโหมดการแสดงผลในภายหลัง (เช่น การซูมหรือการครอบตัด) ควรเป็นไปตามที่ผู้ใช้กำหนด เช่น เปลี่ยนเป็น ContentScale.Crop เพื่อเติมคอนเทนเนอร์ให้เต็ม ปุ่มเปิด/ปิดการปรับขนาดแบบอินเทอร์แอกทีฟจะช่วยสร้างสมดุลระหว่างข้อกำหนดของเลย์เอาต์กับตัวเลือกของผู้ใช้

ตัวอย่างการใช้งาน

คุณสามารถบังคับใช้การมองเห็นแบบเต็มเฟรมและจัดการสัดส่วนภาพได้โดยใช้พร็อพเพอร์ตี้ ContentScale ของ Compose มาตรฐาน

ใช้ Composable Player

วิธีที่ง่ายและตรงไปตรงมาที่สุดคือการใช้ Composable Player โดยทำหน้าที่เป็น Wrapper ระดับสูงที่จัดการขอบเขตการปรับขนาดโดยอัตโนมัติ โดยจะจับคู่ 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 เป็นค่าเริ่มต้นสำหรับสื่อที่มีข้อมูลขอบที่สำคัญ เช่น คะแนนกีฬาหรือคำบรรยาย เพื่อปกป้องบริบทภาพที่สำคัญ