ตั้งแต่วันที่ 27 มีนาคม 2025 เป็นต้นไป เราขอแนะนำให้ใช้ android-latest-release แทน aosp-main เพื่อสร้างและมีส่วนร่วมใน AOSP โปรดดูข้อมูลเพิ่มเติมที่หัวข้อการเปลี่ยนแปลงใน AOSP
การแสดงภาพซ้อนภาพ
จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน
บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ
ฟีเจอร์ภาพซ้อนภาพ (PIP) สำหรับอุปกรณ์แบบใช้มือถือของ Android ช่วยให้ผู้ใช้ปรับขนาดแอปที่มีกิจกรรมต่อเนื่องเป็นหน้าต่างเล็กๆ ได้ ฟีเจอร์นี้มีประโยชน์อย่างยิ่งสำหรับแอปวิดีโอ เนื่องจากเนื้อหาจะเล่นต่อไปในขณะที่ผู้ใช้ทำสิ่งอื่นๆ ได้ ผู้ใช้สามารถควบคุมตําแหน่งของหน้าต่างนี้ผ่าน SystemUI และโต้ตอบกับแอปพลิเคชันที่กำลังแสดงภาพซ้อนภาพด้วยการดำเนินการ (สูงสุด 3 รายการ) ที่แอประบุ
PIP ต้องมีการเลือกใช้อย่างชัดเจนจากแอปพลิเคชันที่รองรับ และจะทำงานแบบทีละกิจกรรม (แอปพลิเคชันเดียวอาจมีกิจกรรมหลายรายการ แต่จะมีเพียงกิจกรรมเดียวที่อยู่ในโหมด PIP) กิจกรรมขอเข้าสู่โหมดภาพซ้อนภาพโดยเรียกใช้ enterPictureInPictureMode() และรับการเรียกกลับของกิจกรรมในรูปแบบ onPictureInPictureModeChanged()
วิธีการ setPictureInPictureParams() ช่วยให้กิจกรรมควบคุมสัดส่วนภาพได้ขณะอยู่ใน PIP และการดำเนินการที่กำหนดเอง ซึ่งช่วยให้ผู้ใช้โต้ตอบกับกิจกรรมได้โดยไม่ต้องขยาย ในโหมด PIP กิจกรรมจะอยู่ในสถานะหยุดชั่วคราวแต่กำลังแสดงผล และจะไม่รับอินพุตการสัมผัสหรือโฟกัสหน้าต่างโดยตรง
แสดงงานในโหมด PIP ได้ครั้งละ 1 งานเท่านั้น
ดูข้อมูลเพิ่มเติมได้ในเอกสารประกอบภาพในภาพสำหรับนักพัฒนาแอป Android
ข้อกำหนดของอุปกรณ์
หากต้องการรองรับ PIP ให้เปิดใช้ฟีเจอร์ PackageManager#FEATURE_PICTURE_IN_PICTURE ของระบบใน /android/frameworks/base/core/java/android/content/pm/PackageManager.java
อุปกรณ์ที่รองรับ PIP ต้องมีหน้าจอที่กว้างกว่า 220 DP ในส่วนความกว้างที่แคบที่สุด PIP ช่วยให้ทำหลายอย่างบนหน้าจอพร้อมกันได้ ซึ่งคล้ายกับโหมดแยกหน้าจอแบบหลายหน้าต่าง ดังนั้นอุปกรณ์ควรมี CPU และ RAM เพียงพอที่จะรองรับกรณีการใช้งานนี้
การใช้งาน
การจัดการวงจรกิจกรรมส่วนใหญ่จะดำเนินการในระบบระหว่าง ActivityManager ถึง WindowManager
การติดตั้งใช้งาน UI อ้างอิงอยู่ในSystemUI
แพ็กเกจ
การแก้ไขระบบไม่ควรส่งผลต่อลักษณะการทํางานตามปกติตามที่ระบุไว้ในการทดสอบชุดเครื่องมือทดสอบความเข้ากันได้ (CTS)
ตรรกะของระบบสำหรับ PIP ส่วนใหญ่เกี่ยวข้องกับการจัดการงานและกิจกรรมในกองที่ "ปักหมุดไว้" ภาพรวมคร่าวๆ ของชั้นเรียนมีดังนี้
ActivityRecord: ติดตามสถานะภาพในภาพของแต่ละกิจกรรม หากต้องการป้องกันไม่ให้ผู้ใช้เข้าสู่โหมด PIP ในบางกรณี เช่น จากหน้าจอล็อกหรือระหว่าง VR ให้เพิ่มกรณีใน checkEnterPictureInPictureState()ActivityManagerService: อินเทอร์เฟซหลักจากกิจกรรมเพื่อขอเข้าสู่โหมด PIP และอินเทอร์เฟซสำหรับการโทรจาก WindowManager และ SystemUI เพื่อเปลี่ยนสถานะกิจกรรม PIPActivityStackSupervisor: เรียกใช้จาก ActivityManagerService เพื่อย้ายงานเข้าหรือออกจากกองงานที่ปักหมุดไว้ โดยอัปเดต WindowManager ตามที่จำเป็นPinnedStackWindowController: อินเทอร์เฟซ WindowManager จาก ActivityManagerPinnedStackController: รายงานการเปลี่ยนแปลงในระบบไปยัง SystemUI เช่น IME ที่แสดง/ซ่อนอยู่ การเปลี่ยนแปลงสัดส่วนการแสดงผล หรือการเปลี่ยนแปลงการดำเนินการBoundsAnimationController: แสดงภาพเคลื่อนไหวของหน้าต่างกิจกรรม PIP ในลักษณะที่ไม่ทริกเกอร์การเปลี่ยนแปลงการกำหนดค่าขณะปรับขนาดPipSnapAlgorithm: คลาสที่แชร์ซึ่งใช้ในทั้งระบบและ SystemUI ที่ควบคุมลักษณะการยึดของหน้าต่าง PIP ไว้ใกล้กับขอบของหน้าจอ
ข้อมูลอ้างอิง SystemUI
มีการใช้งาน PIP ที่สมบูรณ์ซึ่งรองรับการแสดงการดำเนินการที่กําหนดเองต่อผู้ใช้และการดําเนินการทั่วไป เช่น การขยายและการปิด
ผู้ผลิตอุปกรณ์สามารถพัฒนาการเปลี่ยนแปลงเหล่านี้ได้ ตราบใดที่การเปลี่ยนแปลงดังกล่าวไม่ส่งผลต่อลักษณะการทำงานตามปกติตามที่ CDD กำหนด ภาพรวมคร่าวๆ ของชั้นเรียนมีดังนี้
PipManager: คอมโพเนนต์ SystemUI ที่ขึ้นต้นด้วย SystemUIPipTouchHandler: แฮนเดิลการสัมผัส ซึ่งควบคุมท่าทางสัมผัสที่ใช้จัดการ PIP คำสั่งนี้จะใช้เฉพาะในขณะที่อินพุตสำหรับ PIP ทำงานอยู่ (ดู InputConsumerController) คุณสามารถเพิ่มท่าทางสัมผัสใหม่ได้ที่นี่PipMotionHelper: คลาสอำนวยความสะดวกที่ติดตามตำแหน่ง PIP และภูมิภาคที่อนุญาตบนหน้าจอ โทรผ่าน ActivityManagerService เพื่ออัปเดตหรือทำให้ตำแหน่งและขนาดของ PIP เคลื่อนไหวPipMenuActivityController: เริ่มกิจกรรมที่แสดงการดำเนินการที่กิจกรรมนั้นให้ในโหมด PIP อยู่ กิจกรรมนี้เป็นการซ้อนทับงานและนำเอาอินพุตที่ซ้อนทับออกเพื่อให้เป็นแบบอินเทอร์แอกทีฟPipMenuActivity: การติดตั้งใช้งานสําหรับกิจกรรมในเมนูPipMediaController: ตัวแฟังที่จะอัปเดต SystemUI เมื่อเซสชันสื่อมีการเปลี่ยนแปลงในลักษณะที่อาจส่งผลต่อการดำเนินการเริ่มต้นใน PIPPipNotificationController: ตัวควบคุมที่ตรวจสอบว่าการแจ้งเตือนทำงานอยู่ขณะที่ผู้ใช้ใช้ฟีเจอร์ PIPPipDismissViewController: การซ้อนทับที่แสดงต่อผู้ใช้เมื่อเริ่มโต้ตอบกับ PIP เพื่อระบุว่าสามารถปิดได้
ตําแหน่งเริ่มต้น
ทรัพยากรระบบต่างๆ ที่ควบคุมตำแหน่งเริ่มต้นของ PIP มีดังนี้
config_defaultPictureInPictureGravity: gravity
จำนวนเต็ม ซึ่งควบคุมมุมที่จะวาง PIP เช่น
BOTTOM|RIGHTconfig_defaultPictureInPictureScreenEdgeInsets:
การเลื่อนจากด้านข้างของหน้าจอเพื่อวาง PIPconfig_pictureInPictureDefaultSizePercent และ config_pictureInPictureDefaultAspectRatio: การรวมเปอร์เซ็นต์ของความกว้างของหน้าจอและสัดส่วนภาพจะควบคุมขนาดของ PIP ขนาด PIP เริ่มต้นที่คำนวณแล้วต้องไม่เล็กกว่า @dimen/default_minimal_size_pip_resizable_task ตามที่กำหนดโดย CTS และ CDDconfig_pictureInPictureSnapMode: ลักษณะการยึดตามเส้นตามที่ระบุไว้ใน PipSnapAlgorithm
การติดตั้งใช้งานอุปกรณ์ไม่ควรเปลี่ยนสัดส่วนภาพขั้นต่ำและสูงสุดที่ระบุไว้ใน CDD และ CTS
สิทธิ์
"การดำเนินการของแอปพลิเคชัน" (OP_PICTURE_IN_PICTURE) ต่อแพ็กเกจใน AppOpsManager (main/core/java/android/app/AppOpsManager.java) ช่วยให้ผู้ใช้ควบคุม PIP ในระดับแอปพลิเคชันผ่านการตั้งค่าระบบได้
การติดตั้งใช้งานอุปกรณ์ต้องเป็นไปตามการตรวจสอบนี้เมื่อกิจกรรมขอเข้าสู่โหมดภาพในภาพ
การทดสอบ
หากต้องการทดสอบการใช้งาน PIP ให้เรียกใช้การทดสอบทั้งหมดที่เกี่ยวข้องกับภาพในภาพซึ่งอยู่ในส่วนการทดสอบ CTS ฝั่งโฮสต์ในส่วน /cts/hostsidetests/services/activitymanager โดยเฉพาะอย่างยิ่งใน ActivityManagerPinnedStackTests.java
ตัวอย่างเนื้อหาและโค้ดในหน้าเว็บนี้ขึ้นอยู่กับใบอนุญาตที่อธิบายไว้ในใบอนุญาตการใช้เนื้อหา Java และ OpenJDK เป็นเครื่องหมายการค้าหรือเครื่องหมายการค้าจดทะเบียนของ Oracle และ/หรือบริษัทในเครือ
อัปเดตล่าสุด 2025-07-27 UTC
[[["เข้าใจง่าย","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 UTC"],[],[],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`."]]
