مقیاس‌بندی محتوای رسانه‌ای در همه ضرایب شکل

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

در حالت غیرفراگیر، برنامه لایه داخلی پنجره را ادغام می‌کند تا محتوا را به‌طور پویا به داخل منتقل کند.
شکل ۲. در حالت غیرفراگیر، برنامه حاشیه داخلی پنجره را اعمال می‌کند تا کنترل‌ها را به داخل منتقل کند.

پیکربندی‌های فراگیر (عمودی و افقی)

در حالت فراگیر تمام‌صفحه، هدف این است که بوم را برای تجربه سینمایی بیشینه کنیم و درعین‌حال کنترل‌های بازپخش را دردسترس نگه داریم:

  1. windowInsetsPadding را روی هم‌پوشانی‌های کنترل رسانه اعمال کنید (مانند کنترل‌های بالا و پایین) تا از هم‌پوشانی آن‌ها با برش‌های نمایشگر یا نواحی اشاره سیستم جلوگیری شود (برای مثال، ترکیب کردن WindowInsets.displayCutout با WindowInsets.systemGestures در کنترل‌های پایین تا نوار کاوش با اشاره‌های تند کشیدن از لبه تداخل نداشته باشد).
  2. نوارهای سیستم را بااستفاده از 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 بااستفاده از نزدیک یا دور کردن انگشتان برای زوم‌پیش یا زوم‌پس یا دیگر اشاره‌های چندلمسی، مشابه برنامه‌های جاری‌سازی ویدیویی مدرن، گسترش دهید.

شکل ۶. جابه‌جایی بین 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 برای رسانه‌هایی با اطلاعات حاشیه‌ای حیاتی، مانند نتایج ورزشی یا زیرنویس‌ها، استفاده کنید تا بافت بصری ضروری حفظ شود.