استفاده از «تصویردرتصویر» (PiP)

امتحان کردن روش Compose

Jetpack Compose جعبه‌ابزار واسط کاربر توصیه‌شده برای Android است. با نحوه پشتیبانی از تصویردرتصویر در Compose آشنا شوید.

تصویردرتصویر →

از Android 8.0 (سطح میانای برنامه‌سازی کاربردی ۲۶) به بعد، Android به فعالیت‌ها اجازه می‌دهد در حالت تصویردرتصویر (PiP) راه‌اندازی شوند. «تصویر در تصویر» نوع خاصی از حالت چندپنجره‌ای است که برای بازپخش ویدیو، تماس‌های ویدیویی، و پیمایش استفاده می‌شود. این ویژگی به کاربر اجازه می‌دهد پنجره فعالیت موجود را به گوشه‌ای از صفحه‌نمایش سنجاق کند و هم‌زمان بین برنامه‌ها پیمایش کند یا محتوای روی صفحه اصلی را مرور کند.

«تصویردرتصویر» از میاناهای برنامه‌سازی کاربردی چندپنجره‌ای که در Android 7.0 دردسترس قرار گرفته است برای ارائه پنجره هم‌پوشانی ویدیویی سنجاق‌شده استفاده می‌کند. برای افزودن PiP به برنامه‌تان، باید فعالیت‌هایی را که از PiP پشتیبانی می‌کنند ثبت کنید، فعالیتتان را درصورت نیاز به حالت PiP تغییر دهید، و مطمئن شوید که عناصر میانای کاربر پنهان هستند و وقتی فعالیت در حالت PiP است، بازپخش ویدیو ادامه می‌یابد.

پنجره PiP در بالاترین لایه صفحه، در گوشه‌ای که سیستم انتخاب کرده است، ظاهر می‌شود.

«تصویر در تصویر» در دستگاه‌های سازگار با سیستم‌عامل Android TV که Android 14 (سطح API 34) یا بالاتر را اجرا می‌کنند نیز پشتیبانی می‌شود. درحالی‌که شباهت‌های زیادی وجود دارد، ملاحظات دیگری هنگام استفاده از PiP در تلویزیون وجود دارد.

نحوه تعامل کاربران با پنجره PiP

کاربران می‌توانند پنجره PiP را به مکان دیگری بکشند. از Android 12، کاربران می‌توانند کارهای زیر را نیز انجام دهند:

• یک‌بار روی پنجره تک‌ضرب بزنید تا کلید تمام‌صفحه، دکمه بستن، دکمه تنظیمات، و کنش‌های سفارشی ارائه‌شده توسط برنامه‌تان (برای مثال، کنترل‌های پخش) نمایش داده شود.

• روی پنجره دو تک‌ضرب بزنید تا بین اندازه فعلی PiP و حداکثر یا حداقل اندازه PiP جابه‌جا شوید—برای مثال، دو تک‌ضرب زدن روی پنجره بیشینه‌شده آن را کمینه می‌کند و برعکس.

• با کشیدن پنجره به لبه چپ یا راست، آن را پنهان کنید. برای بازگرداندن پنجره، روی بخش قابل‌مشاهده پنجره پنهان‌شده تک‌ضرب بزنید یا آن را به بیرون بکشید.

• با نزدیک کردن یا دور کردن انگشتان، اندازه پنجره «تصویردرتصویر» را تغییر دهید.

برنامه شما کنترل می‌کند که فعالیت فعلی چه زمانی وارد حالت «تصویر در تصویر» شود. چند نمونه در زیر آمده است:

• وقتی کاربر روی دکمه صفحه اصلی تک‌ضرب می‌زند یا تند به بالا به‌سمت صفحه اصلی می‌کشد، فعالیت می‌تواند وارد حالت «تصویر در تصویر» شود. این همان روشی است که Google Maps ازطریق آن به نمایش مسیرها ادامه می‌دهد درحالی‌که کاربر به‌طور هم‌زمان فعالیت دیگری را اجرا می‌کند.

• وقتی کاربر از ویدیو به عقب پیمایش می‌کند تا محتوای دیگری را مرور کند، برنامه شما می‌تواند ویدیو را به حالت PiP منتقل کند.

• برنامه شما می‌تواند ویدیو را به حالت PiP تغییر دهد درحالی‌که کاربر درحال تماشای پایان یک قسمت از محتوا است. صفحه اصلی اطلاعات تبلیغاتی یا خلاصه‌ای درباره قسمت بعدی مجموعه نمایش می‌دهد.

• برنامه شما می‌تواند راهی برای کاربران فراهم کند تا محتوای اضافی را در صف قرار دهند درحالی‌که آن‌ها ویدیو تماشا می‌کنند. ویدیو در حالت PiP به پخش ادامه می‌دهد درحالی‌که صفحه اصلی فعالیت انتخاب محتوا را نمایش می‌دهد.

اعلام پشتیبانی از PiP

به‌طور پیش‌فرض، سیستم به‌طور خودکار از PiP برای برنامه‌ها پشتیبانی نمی‌کند. اگر می‌خواهید از PiP در برنامه‌تان پشتیبانی کنید، فعالیت ویدیویی‌تان را با تنظیم android:supportsPictureInPicture روی true در مانیفست خود ثبت کنید. همچنین، مشخص کنید که فعالیت شما تغییرات پیکربندی چیدمان را مدیریت می‌کند تا فعالیت شما هنگام تغییرات چیدمان درطول انتقال حالت «تصویر در تصویر» مجدداً راه‌اندازی نشود.

<activity android:name="VideoActivity"
    android:supportsPictureInPicture="true"
    android:configChanges=
        "screenSize|smallestScreenSize|screenLayout|orientation"
    ...

پیاده‌سازی PiP با Jetpack

از کتابخانه Jetpack Picture-in-Picture برای پیاده‌سازی تجربه تصویر در تصویر استفاده کنید، زیرا ادغام را ساده کرده و مشکلات رایج درون برنامه‌ای را کاهش می‌دهد. برای مشاهده نمونه‌ای از کاربرد آن، به برنامه نمونه پلتفرم ما مراجعه کنید. با این حال، اگر ترجیح می‌دهید PiP را با استفاده از APIهای پلتفرم پیاده‌سازی کنید، به مستندات زیر مراجعه کنید.

پیاده‌سازی PiP با Jetpack

از کتابخانه Jetpack Picture-in-Picture برای پیاده‌سازی تجربه تصویر در تصویر استفاده کنید، زیرا ادغام را ساده کرده و مشکلات رایج درون برنامه‌ای را کاهش می‌دهد. برای مشاهده نمونه‌ای از کاربرد آن، به برنامه نمونه پلتفرم ما مراجعه کنید. با این حال، اگر ترجیح می‌دهید PiP را با استفاده از APIهای پلتفرم پیاده‌سازی کنید، به مستندات زیر مراجعه کنید.

فعالیتتان را به «تصویر در تصویر» تغییر دهید

در Android 12 و نسخه‌های جدیدتر، می‌توانید با تنظیم کردن پرچم setAutoEnterEnabled روی true، فعالیتتان را به حالت «تصویر در تصویر» تغییر دهید. با این تنظیم، فعالیت به‌طور خودکار درصورت نیاز به حالت PiP تغییر می‌کند بدون اینکه لازم باشد صریحاً enterPictureInPictureMode() را در onUserLeaveHint فراخوانی کنید. و این مزیت اضافی را دارد که انتقال‌ها را بسیار روان‌تر می‌کند. برای جزئیات، به روان‌تر کردن انتقال به حالت «تصویر در تصویر» از پیمایش اشاره‌ای مراجعه کنید.

اگر Android 11 یا نسخه‌های پایین‌تر را هدف‌یابی می‌کنید، فعالیتی باید enterPictureInPictureMode() را فراخوانی کند تا به حالت «تصویر در تصویر» برود. برای مثال، کد زیر وقتی کاربر روی دکمه اختصاصی در میانای کاربر برنامه کلیک می‌کند، فعالیت را به حالت «تصویر در تصویر» تغییر می‌دهد:

override fun onActionClicked(action: Action) {
    if (action.id.toInt() == R.id.lb_control_picture_in_picture) {
        activity?.enterPictureInPictureMode()
        return
    }
}

شاید بخواهید منطقی را اضافه کنید که به‌جای رفتن به پس‌زمینه، فعالیت را به حالت «تصویر در تصویر» تغییر دهد. برای مثال، اگر کاربر هنگام پیمایش برنامه دکمه صفحه اصلی یا برنامه‌های اخیر را فشار دهد، Google Maps به حالت «تصویر در تصویر» می‌رود. می‌توانید این مورد را با لغو کردن onUserLeaveHint() بگیرید:

override fun onUserLeaveHint() {
    if (iWantToBeInPipModeNow()) {
        enterPictureInPictureMode()
    }
}

توصیه می‌شود: تجربه انتقال «تصویر در تصویر» بی‌نقصی به کاربران ارائه دهید

Android 12 بهبودهای ظاهری قابل‌توجهی به انتقال‌های پویانمایی‌شده بین پنجره‌های تمام‌صفحه و PiP اضافه کرده است. قویاً توصیه می‌کنیم همه تغییرات قابل‌اجرا را پیاده‌سازی کنید؛ پس‌از انجام این کار، این تغییرات به‌طور خودکار و بدون نیاز به کار بیشتر، برای صفحه‌نمایش‌های بزرگ مانند دستگاه‌های تاشو و رایانه‌های لوحی مقیاس‌بندی می‌شوند.

اگر برنامه‌تان شامل به‌روزرسانی‌های مربوطه نباشد، انتقال‌های «تصویر در تصویر» همچنان کار می‌کنند، اما پویانمایی‌ها کمتر صیقل‌خورده هستند. برای مثال، انتقال از حالت تمام‌صفحه به حالت «تصویر در تصویر» می‌تواند باعث شود پنجره «تصویر در تصویر» درطول انتقال ناپدید شود و پس‌از تکمیل انتقال دوباره ظاهر شود.

این تغییرات شامل موارد زیر است.

• انتقال به حالت «تصویر در تصویر» از پیمایش اشاره‌ای روان‌تر شده است
• تنظیم sourceRectHint مناسب برای ورود و خروج از حالت «تصویر در تصویر»
• غیرفعال کردن تغییر اندازه یکپارچه برای محتوای غیرویدیویی

به نمونه Android Kotlin PictureInPicture به‌عنوان مرجعی برای فعال کردن تجربه انتقال صیقلی مراجعه کنید.

انتقال به حالت «تصویر در تصویر» از پیمایش اشاره‌ای روان‌تر شده است

از Android 12 به‌بعد، پرچم setAutoEnterEnabled پویانمایی بسیار روان‌تری برای انتقال به محتوای ویدیویی در حالت «تصویردرتصویر» بااستفاده از پیمایش اشاره‌ای ارائه می‌دهد—برای مثال، هنگام تند کشیدن به بالا برای رفتن به صفحه اصلی از حالت تمام‌صفحه.

برای اعمال این تغییر، مراحل زیر را تکمیل کنید:

1. از setAutoEnterEnabled برای ساختن PictureInPictureParams.Builder استفاده کنید:

setPictureInPictureParams(PictureInPictureParams.Builder()
  .setAspectRatio(aspectRatio)
  .setSourceRectHint(sourceRectHint)
  .setAutoEnterEnabled(true)
  .build())

Note: When `setAutoEnterEnabled` is enabled, you don't need to explicitly
call [`enterPictureInPictureMode`][5] in [`onUserLeaveHint`][6].

1. با setPictureInPictureParams تماس بگیرید و PictureInPictureParams را زودتر به‌روز کنید. برنامه منتظر فراخوانی برگشتی onUserLeaveHint نمی‌ماند (همان‌طور که در Android 11 این کار را می‌کرد).

   برای مثال، ممکن است بخواهید setPictureInPictureParams را در اولین بازپخش و هر بازپخش بعدی درصورت تغییر نسبت ابعادی فراخوانی کنید.

2. با setAutoEnterEnabled(false) تماس بگیرید، اما فقط درصورت لزوم. برای مثال، اگر بازپخش فعلی در حالت مکث باشد، احتمالاً نمی‌خواهید وارد PiP شوید.

sourceRectHint مناسبی برای ورود و خروج از حالت «تصویر در تصویر» تنظیم کنید

با معرفی PiP در Android 8.0، setSourceRectHint نشان‌دهنده ناحیه‌ای از فعالیت است که پس‌از انتقال به تصویردرتصویر قابل‌مشاهده است—برای مثال، مرزهای نمای ویدیو در پخش‌کننده ویدیو.

با Android 12، سیستم از sourceRectHint برای پیاده‌سازی پویانمایی بسیار روان‌تر هنگام ورود و خروج از حالت PiP استفاده می‌کند.

برای تنظیم صحیح sourceRectHint برای ورود و خروج از حالت «تصویر در تصویر»:

1. PictureInPictureParams را بااستفاده از حدود مناسب به‌صورت sourceRectHint بسازید. توصیه می‌کنیم شنونده تغییر چیدمان را نیز به پخش‌کننده ویدیو پیوست کنید:

val mOnLayoutChangeListener =
    OnLayoutChangeListener { v: View?, left: Int,
            top: Int, right: Int, bottom: Int, oldLeft: Int, oldTop:
            Int, oldRight: Int, oldBottom: Int ->
        val sourceRectHint = Rect()
        mYourVideoView.getGlobalVisibleRect(sourceRectHint)
        val builder = PictureInPictureParams.Builder()
            .setSourceRectHint(sourceRectHint)
        setPictureInPictureParams(builder.build())
    }

mYourVideoView.addOnLayoutChangeListener(mOnLayoutChangeListener)

1. درصورت لزوم، sourceRectHint را قبل‌از شروع انتقال خروج توسط سیستم به‌روز کنید. وقتی سیستم در آستانه خروج از حالت «تصویر در تصویر» است، سلسله‌مراتب نمای فعالیت در پیکربندی مقصد آن (برای مثال، تمام‌صفحه) چیده می‌شود. برنامه می‌تواند یک شنونده تغییر چیدمان را به نمای ریشه یا نمای هدف (مانند نمای پخش‌کننده ویدیو) متصل کند تا رویداد را شناسایی کرده و sourceRectHint را قبل‌از شروع پویانمایی به‌روز کند.

// Listener is called immediately after the user exits PiP but before animating.
playerView.addOnLayoutChangeListener { _, left, top, right, bottom,
                    oldLeft, oldTop, oldRight, oldBottom ->
    if (left != oldLeft
        || right != oldRight
        || top != oldTop
        || bottom != oldBottom) {
        // The playerView's bounds changed, update the source hint rect to
        // reflect its new bounds.
        val sourceRectHint = Rect()
        playerView.getGlobalVisibleRect(sourceRectHint)
        setPictureInPictureParams(
            PictureInPictureParams.Builder()
                .setSourceRectHint(sourceRectHint)
                .build()
        )
    }
}

غیرفعال کردن تغییر اندازه یکپارچه برای محتوای غیرویدیویی

Android 12 پرچم setSeamlessResizeEnabled را اضافه می‌کند که هنگام تغییر اندازه محتوای غیرویدیویی در پنجره «تصویردرتصویر»، پویانمایی محو تدریجی متقاطع بسیار روان‌تری ارائه می‌دهد. قبلاً، تغییر اندازه محتوای غیرویدیویی در پنجره «تصویردرتصویر» می‌توانست آرتیفکت‌های بصری ناهنجار ایجاد کند.

برای فعال کردن تغییر اندازه یکپارچه برای محتوای ویدیویی:

setPictureInPictureParams(PictureInPictureParams.Builder()
    .setSeamlessResizeEnabled(true)
    .build())

مدیریت واسط کاربر درحین PiP

وقتی فعالیت وارد حالت «تصویردرتصویر» (PiP) می‌شود یا از آن خارج می‌شود، سیستم Activity.onPictureInPictureModeChanged() یا Fragment.onPictureInPictureModeChanged() را فراخوانی می‌کند.

Android 15 تغییراتی را معرفی می‌کند که باعث می‌شود انتقال به حالت «تصویر در تصویر» حتی روان‌تر انجام شود. این برای برنامه‌هایی که عناصر میانای کاربر روی میانای کاربر اصلی‌شان هم‌پوشانی شده است و به حالت «تصویر در تصویر» می‌روند مفید است.

توسعه‌دهندگان از فراخوانی برگشتی onPictureInPictureModeChanged() برای تعریف منطقی استفاده می‌کنند که رؤیت‌پذیری عناصر میانای کاربر هم‌پوشان را تغییر می‌دهد. این فراخوانی برگشتی زمانی راه‌اندازی می‌شود که پویانمایی ورود یا خروج «تصویر در تصویر» تکمیل شود. از Android 15، کلاس PictureInPictureUiState شامل یک حالت جدید است.

با این وضعیت جدید واسط کاربر، برنامه‌هایی که Android 15 را هدف قرار می‌دهند، فراخوانی برگشتی Activity#onPictureInPictureUiStateChanged() را که با isTransitioningToPip() فراخوانی می‌شود به‌محض شروع پویانمایی PiP مشاهده می‌کنند. عناصر میانای کاربر زیادی وجود دارد که وقتی برنامه در حالت «تصویر در تصویر» است، به آن مربوط نمی‌شود، برای مثال، نماها یا چیدمانی که شامل اطلاعاتی مانند پیشنهادها، ویدیوهای بعدی، رده‌بندی‌ها، و عنوان‌ها است. وقتی برنامه وارد حالت PiP می‌شود، از onPictureInPictureUiStateChanged() callback برای پنهان کردن این عناصر میانای کاربر استفاده کنید. وقتی برنامه از پنجره PiP به حالت تمام‌صفحه می‌رود، از فراخوان برگشتی onPictureInPictureModeChanged() برای آشکار کردن این عناصر استفاده کنید، همان‌طور که در مثال‌های زیر نشان داده شده است:

override fun onPictureInPictureUiStateChanged(pipState: PictureInPictureUiState) {
    if (pipState.isTransitioningToPip()) {
        // Hide UI elements.
    }
}

override fun onPictureInPictureModeChanged(
    isInPictureInPictureMode: Boolean,
    newConfig: Configuration
) {
    super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)
    if (!isInPictureInPictureMode) {
        // Unhide UI elements.
    }
}

این کلید تغییر وضعیت سریع برای نمایان کردن عناصر نامربوط میانای کاربر (برای پنجره PiP) کمک می‌کند پویانمایی ورود به PiP روان‌تر و بدون لرزش باشد.

این فراخوانی‌های برگشتی را لغو کنید تا عناصر میانای کاربر فعالیت را دوباره ترسیم کنید. به‌خاطر داشته باشید که در حالت PiP، فعالیت شما در پنجره کوچکی نشان داده می‌شود. وقتی برنامه در حالت «تصویر در تصویر» است، کاربران نمی‌توانند با عناصر میانای کاربر برنامه‌تان تعامل داشته باشند و ممکن است دیدن جزئیات عناصر کوچک میانای کاربر دشوار باشد. فعالیت‌های بازپخش ویدیو با حداقل واسط کاربر بهترین تجربه کاربری را ارائه می‌دهد.

اگر برنامه‌تان باید کنش‌های سفارشی برای PiP ارائه دهد، به افزودن کنترل‌ها در این صفحه مراجعه کنید. قبل‌از اینکه فعالیتتان وارد PiP شود، دیگر عناصر میانای کاربر را بردارید و وقتی فعالیتتان دوباره تمام‌صفحه شد، آن‌ها را بازیابی کنید.

افزودن کنترل‌ها

وقتی کاربر منو پنجره را باز می‌کند (با تک‌ضرب زدن روی پنجره در دستگاه همراه، یا انتخاب منو از کنترل از راه دور تلویزیون)، پنجره PiP می‌تواند کنترل‌ها را نمایش دهد.

اگر برنامه‌ای جلسه رسانه فعال داشته باشد، کنترل‌های پخش، مکث، بعدی، و قبلی نشان داده خواهد شد.

همچنین می‌توانید کنش‌های سفارشی را با ساختن PictureInPictureParams با PictureInPictureParams.Builder.setActions() قبل‌از ورود به حالت «تصویر در تصویر» به‌طور صریح مشخص کنید، و هنگام ورود به حالت «تصویر در تصویر» بااستفاده از enterPictureInPictureMode(android.app.PictureInPictureParams) یا setPictureInPictureParams(android.app.PictureInPictureParams) پارامترها را ارسال کنید. مراقب باشید. اگر بخواهید بیش‌از getMaxNumPictureInPictureActions() اضافه کنید، فقط حداکثر تعداد را دریافت خواهید کرد.

ادامه بازپخش ویدیو درحین استفاده از PiP

وقتی فعالیت شما به PiP تغییر می‌کند، سیستم فعالیت را در حالت مکث قرار می‌دهد و روش onPause() فعالیت را فراخوانی می‌کند. اگر فعالیت درحین انتقال به حالت «تصویردرتصویر» موقتاً متوقف شود، بازپخش ویدیو نباید موقتاً متوقف شود و درعوض باید ادامه یابد.

در Android نسخه ۷.۰ (سطح میانای برنامه‌سازی کاربردی ۲۴) و بالاتر، وقتی سیستم onStop() و onStart() فعالیت شما را فراخوانی می‌کند، باید بازپخش ویدیو را موقتاً متوقف و ازسر بگیرید. با انجام این کار، می‌توانید از بررسی اینکه آیا برنامه‌تان در حالت «تصویردرتصویر» در onPause() است یا نه و ادامه صریح بازپخش اجتناب کنید.

اگر پرچم setAutoEnterEnabled را روی true تنظیم نکرده‌اید و لازم است بازپخش را در پیاده‌سازی onPause() موقتاً متوقف کنید، با فراخوانی isInPictureInPictureMode()، حالت «تصویر در تصویر» را بررسی کنید و بازپخش را به‌درستی مدیریت کنید. برای مثال:

override fun onPause() {
    super.onPause()
    // If called while in PiP mode, don't pause playback.
    if (isInPictureInPictureMode) {
        // Continue playback.
    } else {
        // Use existing playback logic for paused activity behavior.
    }
}

وقتی فعالیت شما از حالت PiP به حالت تمام‌صفحه برمی‌گردد، سیستم فعالیت شما را ازسر می‌گیرد و متد onResume() شما را فراخوانی می‌کند.

استفاده از یک فعالیت بازپخش برای PiP

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

برای اطمینان از اینکه از یک فعالیت برای درخواست‌های بازپخش ویدیو استفاده می‌شود و درصورت نیاز به حالت PiP وارد یا از آن خارج می‌شود، android:launchMode فعالیت را در مانیفست خود روی singleTask تنظیم کنید:

<activity android:name="VideoActivity"
    ...
    android:supportsPictureInPicture="true"
    android:launchMode="singleTask"
    ...

در فعالیتتان، onNewIntent() را لغو کنید و ویدیو جدید را مدیریت کنید، و درصورت نیاز، پخش ویدیو موجود را متوقف کنید.

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

برای فعال کردن PiP برای برنامه‌های دوربین، باید مطمئن شوید که دوربین در حالت PiP فعال باقی می‌ماند و هنگام فراخوانی onPause()، دوربین بسته نمی‌شود:

override fun onPause() {
    super.onPause()
    // Don't close the camera if the app is entering PiP mode
    if (!isInPictureInPictureMode) {
        closeCamera()
    }
}

مانند سایر موارد استفاده، عناصر غیرضروری میانای کاربر (مانند کنترل‌ها و هم‌پوشانی‌ها) را پنهان کنید و کنش‌های سفارشی برای کنترل دوربین اضافه کنید (برای مثال، توقف ضبط یا برگرداندن دوربین).

محاسبه sourceRectHint برای انتقال‌های روان

ارائه sourceRectHint دقیق با مختصات دقیق صفحه‌نمایش نمایاب دوربین برای پویانمایی ورود روان ضروری است. می‌توانید محدوده‌ها را از نمای پیش‌نمایش بااستفاده از getGlobalVisibleRect() به‌صورت زیر دریافت کنید:

val previewView = findViewById<View>(R.id.preview_view)
val globalRect = Rect()
// Ensure the view is laid out before calling getGlobalVisibleRect() to get valid screen coordinates.
previewView.getGlobalVisibleRect(globalRect)
val params = PictureInPictureParams.Builder()
    .setSourceRectHint(globalRect)
    .build()
setPictureInPictureParams(params)

سایر ملاحظات

ممکن است PiP در دستگاه‌هایی که RAM پایینی دارند غیرفعال باشد. قبل‌از اینکه برنامه‌تان از PiP استفاده کند، با فراخوانی hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE) مطمئن شوید که دردسترس است.

«تصویر در تصویر» برای فعالیت‌هایی درنظر گرفته شده است که ویدیو را به‌صورت تمام‌صفحه پخش می‌کنند. هنگام تغییر دادن فعالیت به حالت «تصویردرتصویر»، از نشان دادن هر چیزی به‌جز محتوای ویدیویی خودداری کنید. همان‌طور که در مدیریت میانای کاربر درطول PiP شرح داده شده است، زمان ورود فعالیتتان به حالت PiP را ردیابی کنید و عناصر میانای کاربر را پنهان کنید.

وقتی فعالیتی در حالت «تصویر در تصویر» باشد، به‌طور پیش‌فرض تمرکز ورودی را دریافت نمی‌کند. برای دریافت رویدادهای ورودی درحین استفاده از حالت «تصویر در تصویر»، از MediaSession.setCallback() استفاده کنید. برای اطلاعات بیشتر درباره استفاده از setCallback()، به نمایش کارت «درحال پخش» مراجعه کنید.

وقتی برنامه‌تان در حالت PiP است، بازپخش ویدیو در پنجره PiP می‌تواند باعث تداخل صوتی با برنامه دیگری شود، مثلاً برنامه پخش‌کننده موسیقی یا برنامه جستجوی گفتاری. برای جلوگیری از این مشکل، هنگام شروع پخش ویدیو، درخواست تمرکز صوتی کنید و اعلان‌های تغییر تمرکز صوتی را مدیریت کنید، همان‌طور که در مدیریت تمرکز صوتی شرح داده شده است. اگر در حالت PiP اعلانی مبنی بر ازدست رفتن تمرکز صوتی دریافت کردید، بازپخش ویدیو را موقتاً متوقف یا متوقف کنید.

وقتی برنامه‌تان در آستانه ورود به PiP است، توجه داشته باشید که فقط فعالیت بالایی وارد تصویردرتصویر می‌شود. در برخی شرایط، مثلاً در دستگاه‌های چندپنجره‌ای، ممکن است فعالیت زیرین اکنون نشان داده شود و دوباره درکنار فعالیت «تصویر در تصویر» نمایان شود. باید این مورد را به‌طور مناسب مدیریت کنید، ازجمله فعالیت زمینه‌ای که یک فراخوانی برگشتی onResume() یا onPause() دریافت می‌کند. همچنین ممکن است کاربر با فعالیت تعامل داشته باشد. برای مثال، اگر فعالیت فهرست ویدیو را نمایش می‌دهید و فعالیت ویدیو درحال پخش در حالت PiP است، کاربر ممکن است ویدیو جدیدی را از فهرست انتخاب کند و فعالیت PiP باید مطابق با آن به‌روز شود.

کدگذاری نمونه بیشتر

برای بارگیری برنامه نمونه‌ای که به زبان Kotlin نوشته شده است، به نمونه Android PictureInPicture (Kotlin) مراجعه کنید.