توسيع نطاق محتوى الوسائط على مختلف أشكال الأجهزة

يتيح نظام التشغيل Android استخدام مجموعة متنوعة من أشكال الأجهزة بخلاف الهواتف الذكية التقليدية ذات الوضع العمودي، بما في ذلك الأجهزة القابلة للطي والأجهزة اللوحية وبيئات العرض في نافذة على أجهزة الكمبيوتر المكتبي والشاشات الخارجية. إذا افترضت أنّ شكل الشاشة ثابت، قد يتم تمديد محتوى الوسائط أو اقتصاصه أو عرضه بشكل غير مقصود. يجب أن يتكيّف تطبيقك ديناميكيًا مع نِسب العرض إلى الارتفاع المتنوعة للوسائط المصدر (من النسبة الكلاسيكية 4:3 إلى النسبة العريضة جدًا) في أوضاع العرض المتطوّرة.

تحدث معظم حالات تعذُّر عرض تنسيقات الوسائط في Jetpack Compose بسبب ثلاثة أخطاء شائعة في البنية:

  • عدم اتساق في معالجة العناصر المضمّنة في النافذة وتداخلات في العرض على كامل الشاشة
  • تعديلات غير متسقة في التنسيق بسبب احتساب حجم النافذة بشكل غير صحيح
  • ضبط خيارات تغيير حجم المحتوى بشكل خاطئ

يتناول هذا الدليل الاستراتيجيات وأفضل الممارسات للتعامل مع كل من هذه المجالات باستخدام Media3 وJetpack Compose.

التعامل مع تداخلات النوافذ وتعارضات العرض حتى حافة الشاشة

على الأجهزة التي تعمل بنظام التشغيل Android 15 (مستوى واجهة برمجة التطبيقات 35) والإصدارات الأحدث، يتم تلقائيًا عرض التطبيقات التي تستهدف مستوى واجهة برمجة التطبيقات 35 أو الإصدارات الأحدث حتى حافة الشاشة. تظهر أشرطة النظام، مثل شريط الحالة وشريط التنقّل وشريط العناوين على سطح المكتب، فوق محتوى تطبيقك، ويمكن أن تحجب الصور المقطوعة للشاشة أجزاءً منه.

بدون إدارة مناسبة لـ "مجموعات النوافذ"، يحدث تعارضان رئيسيان في التنسيق:

  • تداخل شريط النظام: يتم حجب إطارات الفيديو والترجمات وعناصر التحكّم في التشغيل جزئيًا بواسطة شريط الحالة (الساعة ورموز البطارية) أو شريط الإيماءات أو شريط التنقّل أو الصور المقطوعة للشاشة (فتحات الكاميرا). للحصول على إرشادات عامة حول الإعداد، يُرجى الاطّلاع على مقالة إعداد ميزة "من الحافة إلى الحافة".
  • تداخُل شريط العناوين في وضع الكمبيوتر المكتبي: في وضع العرض في نافذة على الكمبيوتر المكتبي، يضيف النظام شريط عناوين في أعلى الشاشة لإدارة النوافذ. إنّ التنسيقات العادية التي تعرض رؤوسًا مخصّصة أو لوحات وسائط تمتد من الحافة إلى الحافة بدون مراعاة شريط الترجمة هذا تؤدي إلى حجب إطارات الفيديو وعناصر التحكّم في التشغيل في أعلى الشاشة وجعلها غير قابلة للنقر. لمزيد من التفاصيل حول حالات النوافذ، يُرجى الاطّلاع على مقالة إتاحة العرض في نافذة.
شريط حالة النظام يتداخل مع لوحة الوسائط الممتدة من الحافة إلى الحافة وعناصر التحكّم في التشغيل. شريط التنقّل بالإيماءات يتداخل مع لوحة الوسائط التي تملأ الشاشة بأكملها شريط الترجمة على الكمبيوتر يتداخل مع عناصر التحكّم في تشغيل الفيديو في أعلى الشاشة.
الشكل 1: يتداخل شريط حالة النظام وشريط التنقّل بالإيماءات وشريط العناوين في وضع الكمبيوتر المكتبي مع لوحة الوسائط التي تمتد من الحافة إلى الحافة، ما يحجب محتوى الفيديو وعناصر التحكّم في التشغيل.

استراتيجيات إدارة الحشرات

يجب أن يتكيّف تطبيقك ديناميكيًا مع هوامش النظام استنادًا إلى ما إذا كان المشغّل في وضع مجسم أو غير مجسم.

الإعدادات غير الشاملة

في وضع التشغيل غير الغامر، تظل أشرطة النظام مرئية للحفاظ على سياق الجهاز.

عندما يمتد المشغّل إلى حواف النافذة، يمكنك تطبيق 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. في الوضع غير المجسّم، يطبّق التطبيق مساحة متروكة داخلية على النافذة لنقل عناصر التحكّم إلى الداخل.

الإعدادات الشاملة (الوضع العمودي والأفقي)

في وضع ملء الشاشة المجسم، الهدف هو زيادة مساحة العرض إلى أقصى حد للحصول على تجربة سينمائية مع الحفاظ على إمكانية الوصول إلى عناصر التحكّم في التشغيل:

  1. يجب تطبيق windowInsetsPadding على تراكبات التحكّم في الوسائط (مثل عناصر التحكّم العلوية والسفلية) لمنعها من التداخل مع الصور المقطوعة للشاشة أو مناطق إيماءات نظام التشغيل (على سبيل المثال، دمج WindowInsets.displayCutout مع WindowInsets.systemGestures في عناصر التحكّم السفلية حتى لا يتعارض شريط التقديم/الترجيع مع إيماءات التمرير السريع على الحافة).
  2. يمكنك إخفاء أشرطة النظام باستخدام WindowInsetsControllerCompat داخل DisposableEffect، مع ضمان استعادة مستوى ظهور واجهة مستخدم النظام عند مغادرة الدالة المركّبة.

@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. بما أنّ واجهة برمجة التطبيقات هذه تجريبية وغير مفعَّلة تلقائيًا، عليك أولاً تفعيل الدالة 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 المخصّصة أو الحاويات المقيّدة (مثل الخلاصات على وسائل التواصل الاجتماعي القابلة للتمرير). يمكن أن يؤدي اختيار مقياس محتوى غير مناسب إلى حدوث مشاكل في التنسيق، مثل تشويه الفيديو (تمديده) أو ظهور شريط أسود غير مقصود يترك مساحة فارغة في إطار العرض. ويمكن أن تؤدي إدارة مساحات عرض الفيديو يدويًا بدون هذه الخيارات إلى حدوث خلل في التنسيقات أثناء تدوير الشاشة أو تغيير حالة الجهاز القابل للطي.

سواء كنت تعرض فيديو بنسبة عرض إلى ارتفاع 16:9 على شاشة بنسبة 4:3 أو فيديو بنسبة 4:3 على شاشة بنسبة 16:9، يتم ضبط الدالة المركّبة Player تلقائيًا على ContentScale.Fit. يؤدي ذلك إلى إبقاء الفيديو الكامل مرئيًا بدون اقتصاص من خلال تطبيق تأثير letterboxing أو pillarboxing.

يجب أن تكون التغييرات اللاحقة في وضع العرض (مثل التكبير أو الاقتصاص) من تنفيذ المستخدم. على سبيل المثال، يمكنك التبديل إلى ContentScale.Crop لملء الحاوية بالكامل. يوازن زر التبديل التفاعلي لتغيير الحجم بين متطلبات التنسيق وخيار المستخدم.

أمثلة على عمليات التنفيذ

يمكنك فرض ظهور الإطار بالكامل والتعامل مع نِسب العرض إلى الارتفاع باستخدام سمات ContentScale العادية في Compose.

استخدام الدالة المركّبة 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 باستخدام ميزة التكبير أو التصغير بإصبعَين أو إيماءات أخرى عبر اللمس بأكثر من إصبع، على غرار تطبيقات بث الفيديو الحديثة.

الشكل 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 تلقائيًا للوسائط التي تحتوي على معلومات هامشية مهمة، مثل النتائج الرياضية أو الترجمة، للحفاظ على السياق المرئي الأساسي.