راه‌اندازی برنامه برای «تصویردرتصویر»

در برچسب فعالیت فایل AndroidManifest.xml خود، موارد زیر را انجام دهید:

1. ‫supportsPictureInPicture را اضافه کنید و آن را روی true تنظیم کنید تا اعلام کنید که از تصویردرتصویر (PiP) در برنامه‌تان استفاده خواهید کرد.
2. ‫configChanges را اضافه کنید و آن را روی orientation|screenLayout|screenSize|smallestScreenSize تنظیم کنید تا مشخص کنید فعالیت شما تغییرات پیکربندی چیدمان را مدیریت می‌کند. به این ترتیب، فعالیت شما وقتی تغییرات چیدمان درحین انتقال به حالت «تصویردرتصویر» رخ می‌دهد، مجدداً راه‌اندازی نمی‌شود.

<activity
    android:name=".SnippetsActivity"
    android:exported="true"
    android:supportsPictureInPicture="true"
    android:configChanges="orientation|screenLayout|screenSize|smallestScreenSize"
    android:theme="@style/Theme.Snippets">

در کد «نوشتن» خود، موارد زیر را انجام دهید:

1. این افزونه را در Context اضافه کنید. در سراسر راهنما، چندین بار از این افزونه برای دسترسی به فعالیت استفاده خواهید کرد.

   internal fun Context.findActivity(): ComponentActivity {
       var context = this
       while (context is ContextWrapper) {
           if (context is ComponentActivity) return context
           context = context.baseContext
       }
       throw IllegalStateException("Picture in picture should be called in the context of an Activity")
   }
   PictureInPictureSnippets.kt

افزودن «تصویردرتصویر» در برنامه خروج برای Android قبل‌از نسخه ۱۲

برای افزودن PiP برای نسخه‌های قبل‌از Android 12، از addOnUserLeaveHintProvider استفاده کنید. برای افزودن «تصویردرتصویر» برای نسخه‌های قبل‌از Android 12، این مراحل را دنبال کنید:

1. دروازه نسخه‌ای اضافه کنید تا این کد فقط در نسخه‌های O تا R دردسترس باشد.
2. از DisposableEffect با Context به‌عنوان کلید استفاده کنید.
3. در DisposableEffect، رفتار را برای زمانی که onUserLeaveHintProvider بااستفاده از لامبدا راه‌اندازی می‌شود تعریف کنید. در لامبدا، enterPictureInPictureMode() را در findActivity() فراخوانی کنید و PictureInPictureParams.Builder().build() را ارسال کنید.
4. بااستفاده از findActivity()، addOnUserLeaveHintListener را اضافه کنید و آن را در لامبدا بگذرانید.
5. در onDispose، بااستفاده از findActivity() removeOnUserLeaveHintListener را اضافه کنید و آن را به لامبدا منتقل کنید.

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O &&
    Build.VERSION.SDK_INT < Build.VERSION_CODES.S
) {
    val context = LocalContext.current
    DisposableEffect(context) {
        val onUserLeaveBehavior = Runnable {
            context.findActivity()
                .enterPictureInPictureMode(PictureInPictureParams.Builder().build())
        }
        context.findActivity().addOnUserLeaveHintListener(
            onUserLeaveBehavior
        )
        onDispose {
            context.findActivity().removeOnUserLeaveHintListener(
                onUserLeaveBehavior
            )
        }
    }
} else {
    Log.i("PiP info", "API does not support PiP")
}
PictureInPictureSnippets.kt

افزودن PiP در برنامه ترک برای Android نسخه پس‌از ۱۲

پس‌از Android 12، PictureInPictureParams.Builder ازطریق یک اصلاح‌کننده که به پخش‌کننده ویدیو برنامه ارسال می‌شود اضافه می‌شود.

1. modifier بسازید و در آن با onGloballyPositioned تماس بگیرید. از مختصات چیدمان در مرحله بعدی استفاده خواهد شد.
2. متغیری برای PictureInPictureParams.Builder() ایجاد کنید.
3. بیانیه if را اضافه کنید تا بررسی کنید که کیت توسعه نرم‌افزار S یا جدیدتر است. در این صورت، setAutoEnterEnabled را به سازنده اضافه کنید و آن را روی true تنظیم کنید تا با کشیدن انگشت وارد حالت «تصویردرتصویر» شود. این کار پویانمایی روان‌تری نسبت‌به رفتن به enterPictureInPictureMode ارائه می‌دهد.
4. از findActivity() برای تماس با setPictureInPictureParams() استفاده کنید. با build() در builder تماس بگیرید و آن را رد کنید.

val pipModifier = modifier.onGloballyPositioned { layoutCoordinates ->
    val builder = PictureInPictureParams.Builder()

    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        builder.setAutoEnterEnabled(true)
    }
    context.findActivity().setPictureInPictureParams(builder.build())
}
VideoPlayer(pipModifier)
PictureInPictureSnippets.kt

از setAspectRatio برای تنظیم نسبت ابعادی پنجره «تصویردرتصویر» استفاده کنید

برای تنظیم نسبت ابعادی پنجره PiP، می‌توانید نسبت ابعادی خاصی را انتخاب کنید یا از عرض و ارتفاع اندازه ویدیو پخش‌کننده استفاده کنید. اگر از پخش‌کننده media3 استفاده می‌کنید، بررسی کنید که پخش‌کننده null نباشد و اندازه ویدیو پخش‌کننده قبل‌از تنظیم نسبت ابعادی برابر با VideoSize.UNKNOWN نباشد.

val context = LocalContext.current

val pipModifier = modifier.onGloballyPositioned { layoutCoordinates ->
    val builder = PictureInPictureParams.Builder()
    if (shouldEnterPipMode && player != null && player.videoSize != VideoSize.UNKNOWN) {
        val sourceRect = layoutCoordinates.boundsInWindow().toAndroidRectF().toRect()
        builder.setSourceRectHint(sourceRect)
        builder.setAspectRatio(
            Rational(player.videoSize.width, player.videoSize.height)
        )
    }

    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        builder.setAutoEnterEnabled(shouldEnterPipMode)
    }
    context.findActivity().setPictureInPictureParams(builder.build())
}

VideoPlayer(pipModifier)
PictureInPictureSnippets.kt

اگر از پخش‌کننده سفارشی استفاده می‌کنید، نسبت ابعادی را در ارتفاع و عرض پخش‌کننده بااستفاده از دستورگان ویژه پخش‌کننده خود تنظیم کنید. توجه داشته باشید که اگر پخش‌کننده شما درطول مقداردهی اولیه تغییر اندازه دهد و اگر خارج از محدوده معتبر نسبت ابعادی باشد، برنامه شما ازکار خواهد افتاد. شاید لازم باشد بررسی‌هایی را در اطراف زمان محاسبه نسبت ابعادی اضافه کنید، مشابه با نحوه انجام آن برای پخش‌کننده media3.