Kể từ ngày 27 tháng 3 năm 2025, bạn nên sử dụng android-latest-release thay vì aosp-main để xây dựng và đóng góp cho AOSP. Để biết thêm thông tin, hãy xem phần Thay đổi đối với AOSP.

Trang này được dịch bởi Cloud Translation API.

Hình trong hình
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Tính năng hình trong hình (PIP) dành cho thiết bị cầm tay Android cho phép người dùng đổi kích thước một ứng dụng có hoạt động đang diễn ra thành một cửa sổ nhỏ. Chế độ hình trong hình đặc biệt hữu ích cho các ứng dụng video vì nội dung tiếp tục phát trong khi người dùng có thể thực hiện các thao tác khác. Người dùng có thể thao tác với vị trí của cửa sổ này thông qua SystemUI và tương tác với ứng dụng hiện đang ở chế độ hình trong hình bằng (tối đa ba) thao tác do ứng dụng cung cấp.

Tính năng PIP yêu cầu các ứng dụng hỗ trợ tính năng này phải chọn sử dụng một cách rõ ràng và hoạt động trên cơ sở từng hoạt động. (Một ứng dụng có thể có nhiều hoạt động, trong đó chỉ có một hoạt động ở chế độ PIP.) Các hoạt động yêu cầu chuyển sang chế độ hình trong hình bằng cách gọi enterPictureInPictureMode() và nhận lệnh gọi lại hoạt động ở dạng onPictureInPictureModeChanged().

Phương thức setPictureInPictureParams() cho phép các hoạt động kiểm soát tỷ lệ khung hình trong khi ở chế độ PIP và thao tác tuỳ chỉnh, cho phép người dùng tương tác với hoạt động mà không cần mở rộng hoạt động đó. Trong chế độ PIP, hoạt động ở trạng thái tạm dừng nhưng vẫn hiển thị và không trực tiếp nhận dữ liệu đầu vào cảm ứng hoặc tiêu điểm cửa sổ. Mỗi lần, bạn chỉ có thể mở một tác vụ ở chế độ PIP.

Bạn có thể xem thêm thông tin trong tài liệu về Chế độ hình trong hình dành cho nhà phát triển Android.

Yêu cầu về thiết bị

Để hỗ trợ PIP, hãy bật tính năng hệ thống PackageManager#FEATURE_PICTURE_IN_PICTURE trong /android/frameworks/base/core/java/android/content/pm/PackageManager.java. Các thiết bị hỗ trợ PIP phải có màn hình lớn hơn 220 dp ở chiều rộng nhỏ nhất. Tương tự như chế độ nhiều cửa sổ chia đôi màn hình, PIP cho phép nhiều hoạt động chạy trên màn hình cùng một lúc. Do đó, thiết bị phải có CPU và RAM đủ để hỗ trợ trường hợp sử dụng này.

Triển khai

Hầu hết hoạt động quản lý vòng đời hoạt động đều được thực hiện trong hệ thống giữa ActivityManager và WindowManager. Cách triển khai giao diện người dùng tham chiếu nằm trong gói SystemUI.

Các sửa đổi đối với hệ thống không được ảnh hưởng đến hành vi nội tại của hệ thống như được xác định trong các kiểm thử Bộ kiểm tra tính tương thích (CTS). Logic hệ thống cho PIP chủ yếu xoay quanh việc quản lý các tác vụ và hoạt động trong ngăn xếp "được ghim". Dưới đây là thông tin tổng quan nhanh về lớp:

ActivityRecord: theo dõi trạng thái hình trong hình của từng hoạt động. Để ngăn người dùng chuyển sang chế độ PIP trong một số trường hợp, chẳng hạn như từ màn hình khoá hoặc trong chế độ VR, hãy thêm các trường hợp vào checkEnterPictureInPictureState().
ActivityManagerService: giao diện chính từ hoạt động để yêu cầu chuyển sang chế độ PIP và giao diện cho các lệnh gọi từ WindowManager và SystemUI để thay đổi trạng thái hoạt động PIP.
ActivityStackSupervisor: được gọi từ ActivityManagerService để di chuyển các tác vụ vào hoặc ra khỏi ngăn xếp được ghim, cập nhật WindowManager nếu cần.
PinnedStackWindowController: giao diện WindowManager từ ActivityManager.
PinnedStackController: báo cáo các thay đổi trong hệ thống cho SystemUI, chẳng hạn như IME hiển thị/ẩn, tỷ lệ khung hình thay đổi hoặc hành động thay đổi.
BoundsAnimationController: tạo ảnh động cho các cửa sổ hoạt động PIP theo cách không kích hoạt thay đổi cấu hình trong khi đổi kích thước.
PipSnapAlgorithm: một lớp dùng chung được dùng trong cả hệ thống và SystemUI để kiểm soát hành vi chụp nhanh của cửa sổ PIP gần các cạnh của màn hình.

Tài liệu tham khảo SystemUI cung cấp cách triển khai đầy đủ PIP hỗ trợ việc hiển thị các thao tác tuỳ chỉnh cho người dùng và thao tác chung, chẳng hạn như mở rộng và đóng. Nhà sản xuất thiết bị có thể xây dựng dựa trên những thay đổi này, miễn là những thay đổi đó không ảnh hưởng đến hành vi nội tại như được xác định trong CDD. Dưới đây là thông tin tổng quan nhanh về lớp:

PipManager: thành phần SystemUI bắt đầu bằng SystemUI.
PipTouchHandler: trình xử lý cảm ứng, điều khiển các cử chỉ thao tác với PIP. Phương thức này chỉ được dùng khi trình tiêu thụ đầu vào cho PIP đang hoạt động (xem InputConsumerController). Bạn có thể thêm cử chỉ mới tại đây.
PipMotionHelper: một lớp tiện lợi theo dõi vị trí PIP và vùng cho phép trên màn hình. Gọi đến ActivityManagerService để cập nhật hoặc tạo ảnh động cho vị trí và kích thước của PIP.
PipMenuActivityController: bắt đầu một hoạt động cho thấy các thao tác do hoạt động hiện đang ở chế độ PIP cung cấp. Hoạt động này là một hoạt động lớp phủ tác vụ và xoá trình tiêu thụ đầu vào lớp phủ để cho phép hoạt động tương tác.
PipMenuActivity: cách triển khai cho hoạt động trình đơn.
PipMediaController: trình nghe cập nhật SystemUI khi phiên phát nội dung đa phương tiện thay đổi theo cách có thể ảnh hưởng đến các thao tác mặc định trên PIP.
PipNotificationController: trình điều khiển đảm bảo thông báo đang hoạt động trong khi người dùng đang sử dụng tính năng PIP.
PipDismissViewController: lớp phủ hiển thị cho người dùng khi họ bắt đầu tương tác với PIP để cho biết rằng họ có thể đóng lớp phủ đó.

Vị trí mặc định

Có nhiều tài nguyên hệ thống kiểm soát vị trí mặc định của PIP:

config_defaultPictureInPictureGravity: số nguyên gravity (trọng lực) kiểm soát góc để đặt PIP, chẳng hạn như BOTTOM|RIGHT.
config_defaultPictureInPictureScreenEdgeInsets: độ dời từ các cạnh màn hình để đặt PIP.
config_pictureInPictureDefaultSizePercent và config_pictureInPictureDefaultAspectRatio: sự kết hợp giữa tỷ lệ phần trăm chiều rộng màn hình và tỷ lệ khung hình sẽ kiểm soát kích thước của PIP. Kích thước PIP mặc định được tính toán không được nhỏ hơn @dimen/default_minimal_size_pip_resizable_task, theo định nghĩa của CTS và CDD.
config_pictureInPictureSnapMode: hành vi chụp nhanh như được xác định trong PipSnapAlgorithm.

Việc triển khai thiết bị không được thay đổi tỷ lệ khung hình tối thiểu và tối đa được xác định trong CDD và CTS.

Quyền

"Thao tác ứng dụng" (OP_PICTURE_IN_PICTURE) theo gói trong AppOpsManager (main/core/java/android/app/AppOpsManager.java) cho phép người dùng kiểm soát PIP ở cấp ứng dụng thông qua phần cài đặt hệ thống. Việc triển khai thiết bị cần tuân thủ quy trình kiểm tra này khi một hoạt động yêu cầu chuyển sang chế độ hình trong hình.

Thử nghiệm

Để kiểm thử việc triển khai PIP, hãy chạy tất cả các kiểm thử liên quan đến hình trong hình trong các kiểm thử CTS phía máy chủ trong /cts/hostsidetests/services/activitymanager, đặc biệt là trong ActivityManagerPinnedStackTests.java.