Android طیف متنوعی از ابعاد فیزیکی را فراتر از تلفنهای هوشمند عمودی معمولی، ازجمله دستگاههای تاشو، رایانههای لوحی، محیطهای پنجرهبندی رایانهای، و نمایشگرهای خارجی، پشتیبانی میکند. اگر فرض کنید هندسه صفحهنمایش ثابت است، محتوای رسانه ممکن است درنهایت کشیده، برشخورده، یا بهطور ناخواسته در قالب جعبه نامه قرار گیرد. برنامه شما باید بهطور پویا با نسبتهای ابعادی مختلف رسانه منبع (از کلاسیک ۴:۳ تا فوقعریض) در حالتهای نمایش درحال تکامل سازگار شود.
بیشتر خرابیهای طرحبندی رسانه در Jetpack Compose از سه تله معماری رایج ناشی میشود:
- مدیریت ناسازگار درج پنجره و تداخلهای لبهبهلبه.
- بهروزرسانیهای چیدمان ناسازگار بهدلیل محاسبه نادرست اندازه پنجره.
- پیکربندی نادرست گزینههای مقیاسبندی محتوا.
این راهنما استراتژیها و روالهای مطلوب را برای رسیدگی به هریک از این حوزهها بااستفاده از Media3 و Jetpack Compose پوشش میدهد.
رسیدگی کردن به تداخلهای لبهبهلبه و تورفتگیهای پنجره
در دستگاههای دارای Android 15 (سطح میانای برنامهسازی کاربردی ۳۵) و بالاتر، برنامههایی که سطح میانای برنامهسازی کاربردی ۳۵ یا بالاتر را هدف قرار میدهند بهطور پیشفرض لبهبهلبه نمایش داده میشوند. نوارهای سیستم مانند نوار وضعیت، نوار پیمایش، و نوار عنوان میزکار روی محتوای برنامهتان رسم میشوند و برشهای نمایشگر میتوانند بخشهایی از آن را پنهان کنند.
بدون مدیریت مناسب درج پنجره، دو تداخل چیدمان اصلی رخ میدهد:
- همپوشانی نوار سیستم: فریمهای ویدیو، زیرنویسها، و کنترلهای بازپخش تاحدی توسط نوار وضعیت (ساعت، نمادهای باتری)، اشاره یا نوار پیمایش، یا برشهای نمایشگر (بریدگیهای دوربین) پوشانده شدهاند. برای راهنمایی کلی درباره راهاندازی، به راهاندازی لبهبهلبه مراجعه کنید.
- تداخل نوار عنوان حالت رایانه: در حالت پنجرهبندی رایانهای، سیستم یک نوار عنوان بالایی برای مدیریت پنجره معرفی میکند. چیدمانهای استاندارد که سرایندهای سفارشی یا بومهای رسانه لبهبهلبه را بدون درنظر گرفتن این نوار زیرنویس ارائه میکنند، درنهایت با فریمهای ویدیو و کنترلهای بازپخش بالایی مبهم و غیرقابلکلیک مواجه میشوند. برای جزئیات بیشتر درباره حالتهای پنجره، به پشتیبانی از پنجرهبندی رایانهای مراجعه کنید.
راهبردهای مدیریت درج
برنامه شما باید بهطور پویا با درجهای سیستم براساس اینکه پخشکننده در حالت فراگیر است یا غیرفراگیر سازگار شود.
پیکربندیهای غیرفراگیر
در بازپخش غیرفراگیر، نوارهای سیستم برای حفظ بافت دستگاه نمایان میمانند.
وقتی پخشکننده تا لبههای پنجره گسترش مییابد،
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 ) ), ) }, ) }
پیکربندیهای فراگیر (عمودی و افقی)
در حالت فراگیر تمامصفحه، هدف این است که بوم را برای تجربه سینمایی بیشینه کنیم و درعینحال کنترلهای بازپخش را دردسترس نگه داریم:
windowInsetsPaddingرا روی همپوشانیهای کنترل رسانه اعمال کنید (مانند کنترلهای بالا و پایین) تا از همپوشانی آنها با برشهای نمایشگر یا نواحی اشاره سیستم جلوگیری شود (برای مثال، ترکیب کردنWindowInsets.displayCutoutباWindowInsets.systemGesturesدر کنترلهای پایین تا نوار کاوش با اشارههای تند کشیدن از لبه تداخل نداشته باشد).- نوارهای سیستم را بااستفاده از
WindowInsetsControllerCompatدرDisposableEffectپنهان کنید و مطمئن شوید که رؤیتپذیری میانای کاربر سیستم هنگام خروج از 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 استفاده کنید. چون این میانای برنامهسازی کاربردی آزمایشی است و بهطور پیشفرض غیرفعال است،
ابتدا با تنظیم
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() } } } }
پیکربندی مقیاسبندی محتوا و نسبتهای ابعادی
بین مدیریت فضای محتوی دردسترس و مقیاسبندی خود محتوای رسانه تمایز قائل شوید. از مدیریت تورفتگی، مانند حاشیه داخلی ناحیه امن، برای تنظیم مرزهای محفظه نسبتبه نوار سیستم و برشهای نمایشگر استفاده کنید. سپس استراتژیهای مقیاسبندی را در آن مرزها اعمال کنید. برای راهنمایی طراحی درباره ساختاردهی ظرفها و مقیاسبندی محتوای دیداری در نسبتهای ابعادی مختلف، به ساختار و ترکیببندی محتوا مراجعه کنید.
در مثال زیر، تصویر سمت راست نشان میدهد که چگونه استراتژی برش میتواند محتوا را زمانی که دید کامل لازم است قطع کند، درحالیکه تصویر سمت چپ نشان میدهد که چگونه استراتژی تناسب نسبت ابعادی اصلی را برای رندر کردن تمامقاب حفظ میکند.
مؤلفههای Media3 نسبتهای ابعادی استاندارد ویدیو را بهطور خودکار مدیریت میکنند، اما
پیکربندیهای صریح ContentScale هنگام
کار با طرحبندیهای سفارشی Compose یا محفظههای محدودشده (مانند
فیدهای اجتماعی پیمایشی) حیاتی میشوند. انتخاب مقیاس محتوای نامناسب میتواند منجر به مشکلات چیدمان شود، مانند اعوجاج ویدیو (کشیدگی) یا جعبهنامهای ناخواسته که فضای خالی در نمای دید باقی میگذارد. مدیریت دستی سطوح ویدیو بدون
این گزینهها همچنین میتواند منجر به خراب شدن چیدمانها درطول چرخش صفحهنمایش یا
تغییرات وضعیت دستگاه تاشو شود.
چه نمایش ویدیو ۱۶:۹ در صفحهنمایش ۴:۳ باشد چه نمایش ویدیو ۴:۳ در صفحهنمایش ۱۶:۹،
Player composable بهطور پیشفرض روی
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 ) }
هنگام ساختن چیدمان سفارشی پخشکننده ویدیو یا قرار دادن لایههای میانای کاربر سفارشی مستقیماً
روی جاریسازی ویدیو، میتوانید مستقیماً از 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 برای رسانههایی با اطلاعات حاشیهای حیاتی، مانند نتایج ورزشی یا زیرنویسها، استفاده کنید تا بافت بصری ضروری حفظ شود.