اعتبارًا من 27 آذار (مارس) 2025، ننصحك باستخدام android-latest-release بدلاً من aosp-main لإنشاء AOSP والمساهمة فيه. لمزيد من المعلومات، يُرجى الاطّلاع على التغييرات في AOSP.
نافذة ضمن النافذة
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح ميزة "نافذة ضمن النافذة" (PiP) لأجهزة Android المحمولة تغيير حجم تطبيق يعرض نشاطًا جاريًا إلى نافذة صغيرة. وتُعدّ ميزة "نافذة ضمن النافذة" مفيدة بشكل خاص لتطبيقات الفيديو لأنّ المحتوى
يستمر في التشغيل بينما يكون المستخدم حرًا في تنفيذ إجراءات أخرى. يمكن للمستخدمين التحكّم في موضع هذه
النافذة من خلال SystemUI والتفاعل مع التطبيق الذي يعرض حاليًا
المحتوى في وضع "نافذة ضمن نافذة" من خلال إجراءات (تصل إلى ثلاث) يوفّرها التطبيق.
تتطلّب ميزة "وضع الصورة في الصورة" موافقة صريحة من التطبيقات التي تتيحها، وتعمل على أساس
كل نشاط على حدة. (يمكن أن يتضمّن تطبيق واحد أنشطة متعددة، ويكون أحدها فقط
في وضع "صورة في صورة"). تطلب الأنشطة الدخول إلى وضع "نافذة ضمن النافذة" من خلال الاتصال بـ
enterPictureInPictureMode()، وتتلقّى عمليات استدعاء للنشاط في
شكل onPictureInPictureModeChanged().
تتيح طريقة setPictureInPictureParams() للأنشطة التحكّم في
نسبة العرض إلى الارتفاع أثناء استخدام وضع "صورة في صورة" والإجراءات المخصّصة، ما يسمح للمستخدمين بالتفاعل مع
النشاط بدون الحاجة إلى توسيعه. في وضع "صورة في صورة"، يكون النشاط في حالة إيقاف مؤقت، ولكنه يستمر في العرض، ولا يتلقّى مباشرةً الإدخال باللمس أو تركيز النافذة.
يمكن عرض مهمة واحدة فقط في وضع "صورة في صورة" في كل مرة.
تتوفّر مزيد من المعلومات في مستندات المطوّرين على Android المتعلقة
بوضع "صورة في صورة".
متطلبات الأجهزة
لتفعيل ميزة "وضع الصورة في الصورة"، فعِّل ميزة
PackageManager#FEATURE_PICTURE_IN_PICTURE في النظام في
/android/frameworks/base/core/java/android/content/pm/PackageManager.java.
يجب أن تكون شاشة الأجهزة المتوافقة مع وضع "صورة في صورة" أكبر من 220 وحدة بكسل مستقلة الكثافة عند
أصغر عرض لها. على غرار وضع "نوافذ متعددة" في وضع "تقسيم الشاشة"، يتيح وضع "صورة في صورة" تنفيذ عدّة
أنشطة على الشاشة في الوقت نفسه. لذلك، يجب أن تتضمّن الأجهزة
وحدة معالجة مركزية وذاكرة وصول عشوائي كافيتين لدعم حالة الاستخدام هذه.
التنفيذ
تتم معظم إدارة دورة حياة النشاط في النظام بين
ActivityManager وWindowManager.
يمكن العثور على واجهة المستخدم المرجعية في حزمة SystemUI.
يجب ألا تؤثّر التعديلات التي يتم إجراؤها على النظام في سلوكه الأساسي كما هو محدّد
من خلال اختبارات مجموعة أدوات اختبار التوافق (CTS).
يدور منطق النظام في وضع "صورة في صورة" بشكل أساسي حول إدارة المهام
والنشاطات ضمن الحزمة "المُثبَّتة". في ما يلي نظرة عامة سريعة على الصف:
-
ActivityRecord: تتتبّع حالة "صورة في صورة" لكل نشاط. لمنع المستخدمين من الدخول إلى وضع "صورة في صورة" في حالات معيّنة
، مثل شاشة القفل أو أثناء استخدام الواقع الافتراضي، أضِف حالات إلى
checkEnterPictureInPictureState().
ActivityManagerService: الواجهة الأساسية
من النشاط لطلب الدخول إلى وضع "نافذة ضمن النافذة" والواجهة للمكالمات من
WindowManager وSystemUI لتغيير حالة نشاط "نافذة ضمن النافذة"
-
ActivityStackSupervisor: يتمّ استدعاؤه من
ActivityManagerService لنقل المهام إلى الحزمة المثبّتة أو خارجها،
وتعديل WindowManager حسب الحاجة.
PinnedStackWindowController: واجهة
WindowManager من ActivityManager-
PinnedStackController: يُبلغ عن التغييرات في
النظام إلى SystemUI، مثل عرض/إخفاء IME أو تغيير نسبة العرض إلى الارتفاع
أو تغيير الإجراءات.
-
BoundsAnimationController: لإضافة تأثيرات متحركة على نوافذ نشاط "وضع الصورة في الصورة"
بطريقة لا تؤدي إلى تغيير الإعدادات أثناء
تغيير الحجم
-
PipSnapAlgorithm: فئة مشترَكة تُستخدَم في كلٍّ من
النظام وSystemUI للتحكّم في سلوك التصاق نافذة "وضع الصورة في الصورة"
بالقرب من حواف الشاشة
يقدّم المرجع SystemUI
تنفيذًا كاملاً لميزة "صورة في صورة" يتيح تقديم إجراءات
مخصّصة للمستخدمين والتعامل العام، مثل التوسيع والإغلاق.
يمكن لصنّاع الأجهزة الاستفادة من هذه التغييرات، شرط ألا تؤثّر في
السلوكيات الأساسية كما هو محدّد في CDD. في ما يلي نظرة عامة سريعة على الصف:
PipManager: عنصر SystemUI
الذي يبدأ بالرمز SystemUI.-
PipTouchHandler: معالِج اللمس الذي
يتحكّم في الإيماءات التي تُجري تعديلات على وضع "صورة في صورة" لا يتم استخدام هذا الإجراء إلا عندما يكون مستهلك الإدخال
لميزة "صورة في صورة" نشطًا (راجِع InputConsumerController). يمكن إضافة حركات
جديدة هنا.
-
PipMotionHelper: فئة مساعدة ترصد
موضع الصورة في وضع "صورة داخل صورة" والمنطقة المسموح بها على الشاشة. المكالمات التي يتم توجيهها إلى
ActivityManagerService لتعديل موضع "نافذة ضمن النافذة" (PIP) أو حجمها
أو إضافة تأثيرات متحركة إليها
PipMenuActivityController: يبدأ نشاطًا
يعرض الإجراءات التي يوفّرها النشاط المعروض حاليًا في وضع "صورة في صورة". هذا النشاط
هو نشاط تراكبي للمهام، ويزيل مستخدِم الإدخال المتراكب للسماح
له بأن يكون تفاعليًا.PipMenuActivity: تنفيذ
نشاط القائمة-
PipMediaController: مستمع يُعدِّل
SystemUI عندما تتغيّر جلسة الوسائط بطريقة قد تؤثّر في
الإجراءات التلقائية في وضع "صورة داخل صورة"
-
PipNotificationController: وحدة التحكّم التي
تضمن أنّ الإشعار نشط عندما يستخدم المستخدم ميزة "صورة في صورة"
-
PipDismissViewController: التراكب الذي يظهر
للمستخدمين عند بدء التفاعل مع وضع "صورة داخل صورة" للإشارة إلى إمكانية
إغلاقه
موضع الإعلان التلقائي
هناك موارد نظام مختلفة تتحكّم في موضع
وضع الصورة في الصورة التلقائي:
-
config_defaultPictureInPictureGravity: القيمة الصحيحة gravity
التي تتحكّم في الزاوية التي سيتم وضع الصورة المصغرة المتحركة فيها، مثل
BOTTOM|RIGHT.
config_defaultPictureInPictureScreenEdgeInsets:
Offsets from the sides of the screen to place the PIP-
config_pictureInPictureDefaultSizePercent و
config_pictureInPictureDefaultAspectRatio: تتحكم
النسبة المئوية لعرض الشاشة ونسبة العرض إلى الارتفاع في
حجم الصورة في الصورة. يجب ألا يكون حجم PIP التلقائي المحسوب أصغر من
@dimen/default_minimal_size_pip_resizable_task، كما هو محدّد في CTS
وCDD.
-
config_pictureInPictureSnapMode: سلوك التصاق
كما هو محدّد في PipSnapAlgorithm
يجب ألّا تؤدي عمليات تنفيذ الأجهزة إلى تغيير الحدّ الأدنى والحدّ الأقصى لنسب العرض إلى الارتفاع
التي تم تحديدها في CDD وCTS.
الأذونات
يتيح "إجراء التطبيق" لكل حزمة
(OP_PICTURE_IN_PICTURE) في AppOpsManager
(main/core/java/android/app/AppOpsManager.java)
للمستخدمين التحكّم في وضع "صورة في صورة" على مستوى كل تطبيق من خلال إعدادات النظام.
يجب أن تلتزم عمليات تنفيذ الأجهزة بهذا التحقّق عندما يطلب نشاط ما
دخول وضع "صورة في صورة".
الاختبار
لاختبار عمليات تنفيذ وضع "صورة في صورة"، عليك إجراء جميع الاختبارات المتعلّقة بهذا الوضع في
اختبارات CTS من جهة المضيف ضمن /cts/hostsidetests/services/activitymanager،
وخاصةً في ActivityManagerPinnedStackTests.java.
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-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-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],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`."]]
