از 27 مارس 2025، توصیه می کنیم از android-latest-release به جای aosp-main برای ساختن و کمک به AOSP استفاده کنید. برای اطلاعات بیشتر، به تغییرات AOSP مراجعه کنید.
تصویر در تصویر
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
ویژگی تصویر در تصویر (PIP) برای دستگاه‌های اندرویدی دستی به کاربران امکان می‌دهد اندازه برنامه‌ای را با فعالیت‌های مداوم در یک پنجره کوچک تغییر دهند. PIP مخصوصاً برای برنامه‌های ویدیویی مفید است زیرا در حالی که کاربر برای انجام سایر اقدامات آزاد است، محتوا به پخش ادامه می‌دهد. کاربران می توانند موقعیت این پنجره را از طریق SystemUI دستکاری کنند و با برنامه ای که در حال حاضر در تصویر در تصویر است با (حداکثر سه) عملکرد ارائه شده توسط برنامه تعامل داشته باشند.
PIP نیاز به انتخاب صریح از برنامه هایی دارد که از آن پشتیبانی می کنند و بر اساس هر فعالیت کار می کند. (یک برنامه منفرد می‌تواند چندین فعالیت داشته باشد که فقط یکی از آنها در PIP است.) Activities با فراخوانی enterPictureInPictureMode() درخواست وارد کردن تصویر در تصویر را می‌دهند و پاسخ‌های تماس فعالیت را به شکل onPictureInPictureModeChanged() دریافت می‌کنند.
متد setPictureInPictureParams() به فعالیت‌ها اجازه می‌دهد نسبت ابعاد خود را در PIP و اکشن‌های سفارشی کنترل کنند، که به کاربران اجازه می‌دهد بدون نیاز به گسترش آن با فعالیت تعامل داشته باشند. در PIP، فعالیت در حالت مکث است، اما رندر، حالت است و مستقیماً ورودی لمسی یا فوکوس پنجره را دریافت نمی‌کند. فقط یک کار می تواند در یک زمان در PIP باشد.
اطلاعات بیشتر در مستندات تصویر در تصویر برنامه‌نویس Android موجود است.
الزامات دستگاه
برای پشتیبانی از PIP، ویژگی سیستم PackageManager#FEATURE_PICTURE_IN_PICTURE در /android/frameworks/base/core/java/android/content/pm/PackageManager.java فعال کنید. دستگاه هایی که از PIP پشتیبانی می کنند باید صفحه نمایشی داشته باشند که در کمترین عرض آن بزرگتر از 220dp باشد. شبیه به چند پنجره ای با صفحه تقسیم شده، PIP به چندین فعالیت اجازه می دهد تا همزمان روی صفحه اجرا شوند. بنابراین، دستگاه ها باید CPU و RAM کافی برای پشتیبانی از این مورد استفاده داشته باشند.
پیاده سازی
بیشتر مدیریت چرخه حیات فعالیت در سیستم بین ActivityManager و WindowManager انجام می شود. پیاده سازی رابط کاربری مرجع در بسته SystemUI است.
تغییرات در سیستم نباید بر رفتار ذاتی آن که توسط تست های مجموعه تست سازگاری (CTS) تعریف شده است، تأثیر بگذارد. منطق سیستم برای PIP عمدتاً حول مدیریت وظایف و فعالیت‌ها در پشته «پین شده» می‌چرخد. در اینجا یک مرور سریع کلاس آمده است:
-
ActivityRecord : وضعیت تصویر در تصویر هر فعالیت را ردیابی می کند. برای جلوگیری از ورود کاربران به PIP در شرایط خاص، مانند صفحه قفل یا در حین VR، موارد را به checkEnterPictureInPictureState() اضافه کنید. -
ActivityManagerService : رابط اصلی از اکتیویتی برای درخواست وارد کردن PIP و رابط برای تماس‌های WindowManager و SystemUI برای تغییر وضعیت فعالیت PIP. -
ActivityStackSupervisor : از ActivityManagerService فراخوانی می شود تا وظایف را به داخل یا خارج از پشته پین شده منتقل کند و در صورت لزوم WindowManager به روز کند. -
PinnedStackWindowController : رابط WindowManager از ActivityManager . -
PinnedStackController : تغییرات سیستم را به SystemUI گزارش می‌کند، مانند IME نشان داده/مخفی، تغییر نسبت ابعاد یا تغییر عملکردها. -
BoundsAnimationController : پنجره‌های فعالیت PIP را به گونه‌ای متحرک می‌کند که هنگام تغییر اندازه باعث تغییر پیکربندی نشود. -
PipSnapAlgorithm : یک کلاس مشترک که هم در سیستم و هم در SystemUI استفاده می‌شود که رفتار قطع شدن پنجره PIP را در نزدیکی لبه‌های صفحه کنترل می‌کند.
مرجع SystemUI یک پیاده سازی کامل از PIP را ارائه می دهد که از ارائه اقدامات سفارشی به کاربران و دستکاری عمومی مانند گسترش و اخراج پشتیبانی می کند. تا زمانی که بر رفتارهای درونی تعریف شده توسط CDD تأثیری نگذارند، سازندگان دستگاه می توانند بر اساس این تغییرات ایجاد کنند. در اینجا یک مرور سریع کلاس آمده است:
-
PipManager : جزء SystemUI که با SystemUI شروع می شود. -
PipTouchHandler : کنترل کننده لمسی، که حرکاتی را که PIP را دستکاری می کنند، کنترل می کند. این تنها زمانی استفاده می شود که مصرف کننده ورودی PIP فعال است (به InputConsumerController مراجعه کنید). حرکات جدید را می توان در اینجا اضافه کرد. -
PipMotionHelper : کلاس راحتی که موقعیت PIP و منطقه مجاز را روی صفحه ردیابی می کند. برای به‌روزرسانی یا متحرک کردن موقعیت و اندازه PIP، با ActivityManagerService تماس می‌گیرد. -
PipMenuActivityController : فعالیتی را شروع می کند که اقدامات ارائه شده توسط فعالیت در حال حاضر در PIP را نشان می دهد. این فعالیت یک فعالیت همپوشانی وظیفه است و مصرف کننده ورودی همپوشانی را حذف می کند تا امکان تعامل داشته باشد. -
PipMenuActivity : پیاده سازی برای فعالیت منو. -
PipMediaController : شنونده ای که SystemUI هنگامی که جلسه رسانه به گونه ای تغییر می کند که ممکن است بر اقدامات پیش فرض PIP تغییر کند، به روز می کند. -
PipNotificationController : کنترل کننده ای که از فعال بودن اعلان در زمانی که کاربر از ویژگی PIP استفاده می کند اطمینان حاصل می کند. -
PipDismissViewController : پوششی که هنگام شروع تعامل با PIP به کاربران نشان داده می شود تا نشان دهد که می توان آن را رد کرد.
قرارگیری پیش فرض
منابع سیستمی مختلفی وجود دارند که قرار دادن پیش فرض PIP را کنترل می کنند:
-
config_defaultPictureInPictureGravity : عدد صحیح گرانشی که گوشه ای را برای قرار دادن PIP کنترل می کند، مانند BOTTOM|RIGHT . -
config_defaultPictureInPictureScreenEdgeInsets : انحرافات از طرفین صفحه برای قرار دادن PIP. -
config_pictureInPictureDefaultSizePercent و config_pictureInPictureDefaultAspectRatio : ترکیب درصد عرض صفحه و نسبت ابعاد اندازه PIP را کنترل می کند. اندازه PIP پیش‌فرض محاسبه‌شده نباید کمتر از @dimen/default_minimal_size_pip_resizable_task باشد، همانطور که توسط CTS و CDD تعریف شده است. -
config_pictureInPictureSnapMode : رفتار snapping همانطور که در PipSnapAlgorithm تعریف شده است.
پیاده سازی دستگاه نباید حداقل و حداکثر نسبت ابعاد تعریف شده در CDD و CTS را تغییر دهد.
مجوزها
"عملیات برنامه" هر بسته ( OP_PICTURE_IN_PICTURE ) در AppOpsManager ( main/core/java/android/app/AppOpsManager.java )، به کاربران اجازه می دهد تا PIP را در سطح هر برنامه از طریق تنظیمات سیستم کنترل کنند. هنگامی که یک فعالیت درخواست ورود به حالت تصویر در تصویر را می دهد، پیاده سازی های دستگاه باید این بررسی را رعایت کنند.
تست کردن
برای آزمایش پیاده‌سازی PIP، تمام تست‌های مربوط به تصویر در تصویر موجود در تست‌های CTS سمت میزبان را در زیر /cts/hostsidetests/services/activitymanager ، به‌ویژه در ActivityManagerPinnedStackTests.java اجرا کنید.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین به‌روزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","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-07-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Picture-in-picture\n\nThe picture-in-picture (PIP) feature for Android handheld devices lets users resize an app with an\nongoing activity into a small window. PIP is especially useful for video apps because content\ncontinues to play while the user is free to perform other actions. Users can manipulate this\nwindow's position through the SystemUI and interact with the application currently\nin picture-in-picture with (up to three) app-provided actions.\n\n\nPIP requires explicit opt-in from applications that support it and works on a\nper-activity basis. (A single application can have multiple activities, only one\nof which is in PIP.) Activities request to enter picture-in-picture by calling\n`enterPictureInPictureMode()`, and receive activity callbacks in the\nform of `onPictureInPictureModeChanged()`.\n\n\nThe `setPictureInPictureParams()` method lets activities control their\naspect ratio while in PIP and custom actions, which allow users to interact with\nthe activity without having to expand it. In PIP, the activity is in a paused,\nbut rendering, state and doesn't directly receive touch input or window focus.\nOnly a single task can be in PIP at a time.\n\n\nMore information is available in the Android Developer\n[Picture-in-picture](https://developer.android.com/training/tv/playback/picture-in-picture.html)\ndocumentation.\n\nDevice requirements\n-------------------\n\n\nTo support PIP, enable the\n`PackageManager#FEATURE_PICTURE_IN_PICTURE` system feature in\n[/android/frameworks/base/core/java/android/content/pm/PackageManager.java](https://android.googlesource.com/platform/frameworks/base/+/android16-release/core/java/android/content/pm/PackageManager.java).\nDevices that support PIP must have a screen that is larger than 220dp at its\nsmallest width. Similar to split screen multi-window, PIP allows multiple\nactivities to run on-screen at the same time. Therefore, devices should have\nsufficient CPU and RAM to support this use case.\n\nImplementation\n--------------\n\n\nMost of the activity lifecycle management is done in system between\n[ActivityManager](https://android.googlesource.com/platform/frameworks/base/+/android16-release/services/core/java/com/android/server/am/) and [WindowManager](https://android.googlesource.com/platform/frameworks/base/+/android16-release/services/core/java/com/android/server/wm/).\nThe reference UI implementation is in the [SystemUI](https://android.googlesource.com/platform/frameworks/base/+/android16-release/packages/SystemUI/)\npackage.\n\n\nModifications to the system should not affect its intrinsic behavior as defined\nby the [Compatibility Test Suite (CTS) tests](#cts-tests).\nThe system logic for PIP mainly revolves around the management of tasks and\nactivities within the \"pinned\" stack. Here is a quick class overview:\n\n- **`ActivityRecord`:** tracks each activity's picture-in-picture state. To prevent users from entering PIP in certain circumstances, such as from the lock screen or during VR, add cases to `checkEnterPictureInPictureState()`.\n- **`ActivityManagerService`:** the primary interface from the activity to request entering PIP and the interface to calls from `WindowManager` and `SystemUI` to change the PIP activity state.\n- **`ActivityStackSupervisor`:** called from the `ActivityManagerService` to move tasks in or out of the pinned stack, updating the `WindowManager` as necessary.\n- **`PinnedStackWindowController`:** the `WindowManager` interface from `ActivityManager`.\n- **`PinnedStackController`:** reports changes in the system to `SystemUI`, such as IME shown/hidden, aspect ratio changed, or actions changed.\n- **`BoundsAnimationController`:** animates the PIP activity windows in a way that does not trigger a configuration change while resizing.\n- **`PipSnapAlgorithm`:** a shared class used in both the system and SystemUI that controls the snapping behaviour of the PIP window near the edges of the screen.\n\n\nThe reference [SystemUI](https://android.googlesource.com/platform/frameworks/base/+/android16-release/packages/SystemUI/)\nprovides a complete implementation of PIP that supports presenting custom\nactions to users and general manipulation, such as expansion and dismissal.\nDevice manufacturers can build upon these changes, as long as they do not affect\nthe intrinsic behaviours as defined by the CDD. Here is a quick class\noverview:\n\n- **`PipManager`:** the `SystemUI` component that is started with `SystemUI`.\n- **`PipTouchHandler`:** the touch handler, which controls the gestures that manipulate the PIP. This is only used while the input consumer for the PIP is active (see `InputConsumerController`). New gestures can be added here.\n- **`PipMotionHelper`:** a convenience class that tracks the PIP position, and allowable region on-screen. Calls through to `ActivityManagerService` to update or animate the position and size of the PIP.\n- **`PipMenuActivityController`:** starts an activity that shows the actions provided by the activity currently in PIP. This activity is a task-overlay activity, and removes the overlaying input consumer to allow it to be interactive.\n- **`PipMenuActivity`:** the implementation for the menu activity.\n- **`PipMediaController`:** the listener that updates `SystemUI` when the media session changes in a way that might affect the default actions on the PIP.\n- **`PipNotificationController`:** the controller that ensures that a notification is active while a user is using the PIP feature.\n- **`PipDismissViewController`:** the overlay shown to users when they start interacting with the PIP to indicate that it can be dismissed.\n\nDefault placement\n-----------------\n\n\nThere are various system resources that control the default placement of the\nPIP:\n\n- **`config_defaultPictureInPictureGravity`:** the [gravity](https://developer.android.com/reference/android/view/Gravity.html) integer, which controls the corner to place the PIP, such as `BOTTOM|RIGHT`.\n- **`config_defaultPictureInPictureScreenEdgeInsets`:** the offsets from the sides of the screen to place the PIP.\n- **`config_pictureInPictureDefaultSizePercent` and\n `config_pictureInPictureDefaultAspectRatio`:** the combination of percentage of the screen width and the aspect ratio controls the size of the PIP. The computed default PIP size should not be smaller than `@dimen/default_minimal_size_pip_resizable_task`, as defined by CTS and the CDD.\n- **`config_pictureInPictureSnapMode`:** the snapping behaviour as defined in `PipSnapAlgorithm`.\n\n\nDevice implementations should not change the minimum and maximum aspect ratios\nthat are defined in the CDD and CTS.\n\nPermissions\n-----------\n\n\nThe per-package \"application operation\"\n(`OP_PICTURE_IN_PICTURE`) in `AppOpsManager`\n(`main/core/java/android/app/AppOpsManager.java`), lets\nusers to control PIP on a per-application level through the system settings.\nDevice implementations need to respect this check when an activity requests to\nenter picture-in-picture mode.\n\nTesting\n-------\n\n\nTo test PIP implementations, run all picture-in-picture related tests found in\nthe host-side CTS tests under [/cts/hostsidetests/services/activitymanager](https://android.googlesource.com/platform/cts/+/android16-release/hostsidetests/services/activitymanager/src/android/server/cts),\nparticularly in `ActivityManagerPinnedStackTests.java`."]]
