با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
در تگ فعالیت فایل AndroidManifest.xml ، موارد زیر را انجام دهید:
supportsPictureInPicture اضافه کنید و آن را روی true تنظیم کنید تا اعلام کنید از PiP در برنامه خود استفاده می کنید.
configChanges را اضافه کنید و آن را روی orientation|screenLayout|screenSize|smallestScreenSize تنظیم کنید تا مشخص کنید که فعالیت شما تغییرات پیکربندی طرح را انجام دهد. به این ترتیب، وقتی تغییرات طرح‌بندی در طول انتقال حالت PiP رخ می‌دهد، فعالیت شما دوباره راه‌اندازی نمی‌شود.
این پسوند را به Context اضافه کنید. از این برنامه افزودنی چندین بار در طول راهنما برای دسترسی به فعالیت استفاده خواهید کرد.
internalfunContext.findActivity():ComponentActivity{varcontext=thiswhile(contextisContextWrapper){if(contextisComponentActivity)returncontextcontext=context.baseContext}throwIllegalStateException("Picture in picture should be called in the context of an Activity")}
برنامه PiP on مرخصی را برای نسخه پیش از اندروید 12 اضافه کنید
برای افزودن PiP برای نسخه پیش از اندروید 12، از addOnUserLeaveHintProvider استفاده کنید. برای افزودن PiP برای نسخه پیش از اندروید 12 این مراحل را دنبال کنید:
یک نسخه گیت اضافه کنید تا این کد فقط در نسخه های O تا R قابل دسترسی باشد.
از یک DisposableEffect با Context به عنوان کلید استفاده کنید.
addOnUserLeaveHintListener با استفاده از findActivity() اضافه کنید و لامبدا را ارسال کنید.
در onDispose ، removeOnUserLeaveHintListener با استفاده از findActivity() اضافه کنید و لامبدا را وارد کنید.
if(Build.VERSION.SDK_INT>=Build.VERSION_CODES.O&&
Build.VERSION.SDK_INT < Build.VERSION_CODES.S){valcontext=LocalContext.currentDisposableEffect(context){valonUserLeaveBehavior:()->Unit={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")}
برنامه PiP on مرخصی را برای پس از اندروید 12 اضافه کنید
پس از اندروید 12، PictureInPictureParams.Builder از طریق یک اصلاح کننده که به پخش کننده ویدیوی برنامه ارسال می شود، اضافه می شود.
یک modifier بسازید و روی آن onGloballyPositioned را فراخوانی کنید. مختصات طرح در مرحله بعد استفاده خواهد شد.
یک متغیر برای PictureInPictureParams.Builder() ایجاد کنید.
برای بررسی اینکه آیا SDK S یا بالاتر است، یک عبارت if اضافه کنید. اگر چنین است، setAutoEnterEnabled به سازنده اضافه کنید و آن را روی true تنظیم کنید تا با کشیدن انگشت وارد حالت PiP شوید. این یک انیمیشن روان‌تر از ورود به حالت enterPictureInPictureMode ارائه می‌کند.
از findActivity() برای فراخوانی setPictureInPictureParams() استفاده کنید. build() روی builder فراخوانی کنید و آن را ارسال کنید.
از setAspectRatio برای تنظیم نسبت ابعاد پنجره PiP استفاده کنید
برای تنظیم نسبت تصویر پنجره PiP، می توانید نسبت تصویر خاصی را انتخاب کنید یا از عرض و ارتفاع اندازه ویدیوی پخش کننده استفاده کنید. اگر از پخش کننده media3 استفاده می کنید، قبل از تنظیم نسبت تصویر، بررسی کنید که پخش کننده خالی نباشد و اندازه ویدیوی پخش کننده برابر با [ VideoSize.UNKNOWN ][6] نباشد.
اگر از پخش کننده سفارشی استفاده می کنید، با استفاده از نحو مخصوص پخش کننده خود، نسبت ابعاد را بر روی ارتفاع و عرض پخش کننده تنظیم کنید. توجه داشته باشید که اگر اندازه پخش کننده شما در حین مقداردهی اولیه تغییر اندازه دهد، اگر خارج از محدوده معتبر نسبت ابعاد باشد، برنامه شما از کار می افتد. ممکن است لازم باشد بررسی هایی را در زمانی که می توان نسبت تصویر را محاسبه کرد، اضافه کنید، مشابه روشی که برای پخش کننده media3 انجام می شود.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-08-27 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-08-27 بهوقت ساعت هماهنگ جهانی."],[],[],null,["In the activity tag of your `AndroidManifest.xml` file, do the following:\n\n1. Add `supportsPictureInPicture` and set it to `true` to declare you'll be using PiP in your app.\n2. Add `configChanges` and set it to\n `orientation|screenLayout|screenSize|smallestScreenSize` to specify that\n your activity handles layout configuration changes. This way, your activity\n doesn't relaunch when layout changes occur during PiP mode transitions.\n\n ```kotlin\n \u003cactivity\n android:name=\".SnippetsActivity\"\n android:exported=\"true\"\n android:supportsPictureInPicture=\"true\"\n android:configChanges=\"orientation|screenLayout|screenSize|smallestScreenSize\"\n android:theme=\"@style/Theme.Snippets\"\u003e\n ```\n | **Note:** To learn more about configuration changes, how to restrict activity recreation, and how to react to those configuration changes, see the [Handle\n | configuration changes](/guide/topics/resources/runtime-changes) page.\n\nIn your Compose code, do the following:\n\n1. Add this extension on `Context`. You'll use this extension multiple times throughout the guide to access the activity. \n\n ```kotlin\n internal fun Context.findActivity(): ComponentActivity {\n var context = this\n while (context is ContextWrapper) {\n if (context is ComponentActivity) return context\n context = context.baseContext\n }\n throw IllegalStateException(\"Picture in picture should be called in the context of an Activity\")\n }https://github.com/android/snippets/blob/7a0ebbee11495f628cf9d574f6b6069c2867232a/compose/snippets/src/main/java/com/example/compose/snippets/pictureinpicture/PictureInPictureSnippets.kt#L90-L97\n ```\n\nAdd PiP on leave app for pre-Android 12\n\nTo add PiP for pre-Android 12, use [`addOnUserLeaveHintProvider`](/reference/androidx/core/app/OnUserLeaveHintProvider). Follow\nthese steps to add PiP for pre-Android 12:\n\n1. Add a version gate so that this code is only accessed in versions O until R.\n2. Use a `DisposableEffect` with `Context` as the key.\n3. Inside the `DisposableEffect`, define the behavior for when the `onUserLeaveHintProvider` is triggered using a lambda. In the lambda, call [`enterPictureInPictureMode()`](/reference/android/app/Activity#enterPictureInPictureMode(android.app.PictureInPictureParams)) on `findActivity()` and pass in [`PictureInPictureParams.Builder().build()`](/reference/android/app/PictureInPictureParams.Builder).\n4. Add `addOnUserLeaveHintListener` using `findActivity()` and pass in the lambda.\n5. In `onDispose`, add `removeOnUserLeaveHintListener` using `findActivity()` and pass in the lambda.\n\n\n```kotlin\nif (Build.VERSION.SDK_INT \u003e= Build.VERSION_CODES.O &&\n Build.VERSION.SDK_INT \u003c Build.VERSION_CODES.S\n) {\n val context = LocalContext.current\n DisposableEffect(context) {\n val onUserLeaveBehavior: () -\u003e Unit = {\n context.findActivity()\n .enterPictureInPictureMode(PictureInPictureParams.Builder().build())\n }\n context.findActivity().addOnUserLeaveHintListener(\n onUserLeaveBehavior\n )\n onDispose {\n context.findActivity().removeOnUserLeaveHintListener(\n onUserLeaveBehavior\n )\n }\n }\n} else {\n Log.i(\"PiP info\", \"API does not support PiP\")\n}https://github.com/android/snippets/blob/7a0ebbee11495f628cf9d574f6b6069c2867232a/compose/snippets/src/main/java/com/example/compose/snippets/pictureinpicture/PictureInPictureSnippets.kt#L354-L374\n```\n\n\u003cbr /\u003e\n\nAdd PiP on leave app for post-Android 12\n\nPost-Android 12, the [`PictureInPictureParams.Builder`](/reference/android/app/PictureInPictureParams.Builder) is added through a\nmodifier that is passed to the app's video player.\n\n1. Create a `modifier` and call [`onGloballyPositioned`](/reference/kotlin/androidx/compose/ui/layout/OnGloballyPositionedModifier) on it. The layout coordinates will be used in a later step.\n2. Create a variable for the `PictureInPictureParams.Builder()`.\n3. Add an `if` statement to check if the SDK is S or above. If so, add [`setAutoEnterEnabled`](/reference/android/app/PictureInPictureParams.Builder#setAutoEnterEnabled(boolean)) to the builder and set it to `true` to enter PiP mode upon swipe. This provides a smoother animation than going through [`enterPictureInPictureMode`](/reference/android/app/Activity#enterPictureInPictureMode(android.app.PictureInPictureParams))().\n4. Use `findActivity()` to call `setPictureInPictureParams()`. Call `build()` on the `builder` and pass it in.\n\n\n```kotlin\nval pipModifier = modifier.onGloballyPositioned { layoutCoordinates -\u003e\n val builder = PictureInPictureParams.Builder()\n\n if (Build.VERSION.SDK_INT \u003e= Build.VERSION_CODES.S) {\n builder.setAutoEnterEnabled(true)\n }\n context.findActivity().setPictureInPictureParams(builder.build())\n}\nVideoPlayer(pipModifier)https://github.com/android/snippets/blob/7a0ebbee11495f628cf9d574f6b6069c2867232a/compose/snippets/src/main/java/com/example/compose/snippets/pictureinpicture/PictureInPictureSnippets.kt#L74-L82\n```\n\n\u003cbr /\u003e\n\nUse `setAspectRatio` to set PiP window's aspect ratio\n\nTo set the aspect ratio of the PiP window, you can either choose a specific\naspect ratio or use the width and height of the player's video size. If you are\nusing a media3 player, check that the player is not null and that the player's\nvideo size is not equal to \\[`VideoSize.UNKNOWN`\\]\\[6\\] before setting the aspect\nratio.\n\n\n```kotlin\nval context = LocalContext.current\n\nval pipModifier = modifier.onGloballyPositioned { layoutCoordinates -\u003e\n val builder = PictureInPictureParams.Builder()\n if (shouldEnterPipMode && player != null && player.videoSize != VideoSize.UNKNOWN) {\n val sourceRect = layoutCoordinates.boundsInWindow().toAndroidRectF().toRect()\n builder.setSourceRectHint(sourceRect)\n builder.setAspectRatio(\n Rational(player.videoSize.width, player.videoSize.height)\n )\n }\n\n if (Build.VERSION.SDK_INT \u003e= Build.VERSION_CODES.S) {\n builder.setAutoEnterEnabled(shouldEnterPipMode)\n }\n context.findActivity().setPictureInPictureParams(builder.build())\n}\n\nVideoPlayer(pipModifier)https://github.com/android/snippets/blob/7a0ebbee11495f628cf9d574f6b6069c2867232a/compose/snippets/src/main/java/com/example/compose/snippets/pictureinpicture/PictureInPictureSnippets.kt#L248-L266\n```\n\n\u003cbr /\u003e\n\n| **Warning:** The bounds of what the aspect ratio can be are between 2.39:1 and 1:2.39 (inclusive). If your aspect ratio does not fall between these values, your app will crash.\n\nIf you are using a custom player, set the aspect ratio on the player's height\nand width using the syntax specific to your player. Be aware that if your player\nresizes during initialization, if it falls outside of the valid bounds of what\nthe aspect ratio can be, your app will crash. You may need to add checks around\nwhen the aspect ratio can be calculated, similar to how it is done for a media3\nplayer."]]
