Android รองรับรูปแบบของอุปกรณ์ที่หลากหลายนอกเหนือจากสมาร์ทโฟนแนวตั้งแบบเดิม ซึ่งรวมถึงอุปกรณ์แบบพับได้ แท็บเล็ต สภาพแวดล้อมหน้าต่างเดสก์ท็อป และจอแสดงผลภายนอก หากคุณคิดว่ารูปทรงเรขาคณิตของหน้าจอเป็นแบบคงที่ เนื้อหาสื่ออาจถูกยืด ครอบตัด หรือมีแถบสีดำโดยไม่ได้ตั้งใจ แอปของคุณต้องปรับเปลี่ยนตามสัดส่วนภาพของสื่อต้นฉบับที่หลากหลาย (ตั้งแต่ 4:3 แบบคลาสสิกไปจนถึงแบบกว้างพิเศษ) ในโหมดการแสดงผลที่พัฒนาไปเรื่อยๆ
ความล้มเหลวด้านเลย์เอาต์สื่อส่วนใหญ่ใน Jetpack Compose เกิดจากข้อผิดพลาดทางสถาปัตยกรรมที่พบบ่อย 3 ประการ ได้แก่
- การจัดการส่วนแทรกของหน้าต่างและการชนกันแบบไร้ขอบที่ไม่สอดคล้องกัน
- การอัปเดตเลย์เอาต์ไม่สอดคล้องกันเนื่องจากการคำนวณขนาดหน้าต่างไม่ถูกต้อง
- การกำหนดค่าตัวเลือกการปรับขนาดเนื้อหาไม่ถูกต้อง
คู่มือนี้จะกล่าวถึงกลยุทธ์และแนวทางปฏิบัติแนะนำสำหรับการจัดการแต่ละด้านโดยใช้ Media3 และ Jetpack Compose
จัดการส่วนที่เว้นไว้ในหน้าต่างและการชนกันแบบไร้ขอบ
ในอุปกรณ์ที่ใช้ Android 15 (ระดับ API 35) ขึ้นไป แอปที่กำหนดเป้าหมายเป็นระดับ API 35 ขึ้นไปจะแสดงผลแบบไร้ขอบโดยค่าเริ่มต้น แถบระบบ เช่น แถบสถานะ แถบการนำทาง และแถบคำบรรยายบนเดสก์ท็อปจะแสดงทับเนื้อหาของแอป และหน้าจอรอยบากอาจบดบังบางส่วนของเนื้อหา
หากไม่มีการจัดการส่วนแทรกของหน้าต่างที่เหมาะสม จะเกิดความขัดแย้งของเลย์เอาต์ที่สำคัญ 2 ประการดังนี้
- แถบระบบซ้อนทับ: เฟรมวิดีโอ คำบรรยาย และตัวควบคุมการเล่นถูกบดบังบางส่วนโดยแถบสถานะ (นาฬิกา ไอคอนแบตเตอรี่) แถบการนำทางหรือท่าทางสัมผัส หรือหน้าจอรอยบาก (รอยบากกล้อง) ดูคำแนะนำการตั้งค่าทั่วไปได้ที่ตั้งค่าแบบไร้ขอบ
- การรบกวนแถบคำอธิบายภาพในโหมดเดสก์ท็อป: ในโหมดหน้าต่างเดสก์ท็อป ระบบจะเพิ่มแถบคำอธิบายภาพด้านบนสำหรับการจัดการหน้าต่าง เลย์เอาต์มาตรฐานที่แสดงผลส่วนหัวที่กำหนดเองหรือ 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 ) ), ) }, ) }
การกำหนดค่าแบบสมจริง (แนวตั้งและแนวนอน)
ในโหมดใหญ่พิเศษแบบเต็มหน้าจอ เป้าหมายคือการเพิ่มขนาด Canvas ให้ใหญ่ที่สุดเพื่อประสบการณ์การรับชมแบบภาพยนตร์ ขณะเดียวกันก็ยังเข้าถึงตัวควบคุมการเล่นได้ ดังนี้
- ใช้
windowInsetsPaddingกับการวางซ้อนตัวควบคุมสื่อ (เช่น ตัวควบคุมด้านบนและด้านล่าง) เพื่อป้องกันไม่ให้ทับซ้อนกับหน้าจอรอยบากหรือพื้นที่ท่าทางสัมผัสของระบบ (เช่น การรวมWindowInsets.displayCutoutกับWindowInsets.systemGesturesในตัวควบคุมด้านล่างเพื่อให้แถบเลื่อนไม่ขัดแย้งกับท่าทางสัมผัสการปัดขอบ) - ซ่อนแถบระบบโดยใช้
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) ), ) }, ) }
คำนวณการปรับขนาดหน้าต่างแบบไดนามิกและการอัปเดตเลย์เอาต์
การคำนวณความกว้างหรือความสูงของหน้าจอเพียงครั้งเดียวเมื่อเริ่มต้นแอปจะทำให้เลย์เอาต์ใช้ค่าที่ล้าสมัยเมื่อการกำหนดค่าอุปกรณ์เปลี่ยนแปลง เช่น เมื่อกางอุปกรณ์แบบพับได้ออก มีการปรับขนาดเซสชันแบบหลายหน้าต่าง หรือมีการหมุนจอแสดงผล
ในกรณีเหล่านี้ แม้ว่าคอมโพเนนต์ย่อยจะใช้ Modifier.fillMaxWidth() อย่างถูกต้อง แต่ก็จะไม่สามารถปรับเปลี่ยนได้หากคอนเทนเนอร์หลักถูกจำกัดด้วยมิติข้อมูลที่ล้าสมัย ซึ่งทำให้เกิดการยืด การตัด หรือเลย์เอาต์ที่ไม่ตอบสนอง
ในตัวอย่างต่อไปนี้ เฟรมด้านซ้ายแสดงการแสดงผลที่ถูกต้องในวิวพอร์ตมาตรฐาน ส่วนเฟรมด้านขวาแสดงความล้มเหลวของขนาดหน้าต่างที่ล้าสมัยในการปรับเมื่อกางอุปกรณ์ออก ส่งผลให้เลย์เอาต์เนื้อหาไม่ตอบสนอง
หากต้องการหลีกเลี่ยงข้อจำกัดของเลย์เอาต์ที่ล้าสมัย ให้ใช้ 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() } } } }
กำหนดค่าการปรับขนาดเนื้อหาและสัดส่วนภาพ
แยกความแตกต่างระหว่างการจัดการพื้นที่คอนเทนเนอร์ที่ใช้ได้กับการปรับขนาดเนื้อหาสื่อเอง ใช้การจัดการส่วนแทรก เช่น ระยะห่างจากขอบของพื้นที่ปลอดภัย เพื่อกำหนดขอบเขตคอนเทนเนอร์ที่สัมพันธ์กับแถบระบบและหน้าจอรอยบาก จากนั้นใช้กลยุทธ์การปรับขนาดภายในขอบเขตเหล่านั้น ดูคำแนะนำด้านการออกแบบเกี่ยวกับการจัดโครงสร้างคอนเทนเนอร์และการปรับขนาดเนื้อหาภาพในสัดส่วนภาพต่างๆ ได้ที่องค์ประกอบและโครงสร้างเนื้อหา
ในตัวอย่างต่อไปนี้ รูปภาพด้านซ้ายแสดงให้เห็นว่ากลยุทธ์การครอบตัดสามารถตัดเนื้อหาออกเมื่อจำเป็นต้องแสดงผลแบบเต็มได้อย่างไร ขณะที่รูปภาพด้านขวาแสดงให้เห็นว่ากลยุทธ์การปรับพอดีจะรักษาสัดส่วนภาพดั้งเดิมสำหรับการแสดงผลแบบเต็มเฟรมได้อย่างไร
คอมโพเนนต์ 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 แบบไดนามิกโดยใช้การบีบเพื่อซูมหรือท่าทางสัมผัสแบบมัลติทัชอื่นๆ ได้ด้วย ซึ่งคล้ายกับแอปพลิเคชันสตรีมมิงวิดีโอสมัยใหม่
@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 เป็นค่าเริ่มต้นสำหรับสื่อที่มีข้อมูลขอบที่สำคัญ เช่น คะแนนกีฬาหรือคำบรรยาย เพื่อปกป้องบริบทภาพที่สำคัญ