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

Tính năng hình trong hình (PIP) dành cho thiết bị di động 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ế độ PiP đặc biệt hữu ích cho các ứng dụng video vì nội dung vẫn 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ị 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 3) 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, nhưng 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ưới 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 khi ở chế độ PiP và các thao tác tuỳ chỉnh. Nhờ đó, người dùng có thể tương tác với hoạt động mà không cần mở rộng hoạt động đó. Ở chế độ PIP, hoạt động ở trạng thái tạm dừng nhưng đang kết xuất và không trực tiếp nhận được 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ể chạy một tác vụ ở chế độ PIP.

Bạn có thể xem thêm thông tin trong tài liệu 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ợ chế độ 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ợ chế độ 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, chế độ PIP cho phép nhiều hoạt động chạy trên màn hình cùng một lúc. Do đó, các 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 đề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 vốn có của hệ thống như được xác định bằng các kiểm thử của Bộ kiểm tra tính tương thích (CTS). Logic hệ thống cho chế độ 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". Sau đây là thông tin tổng quan nhanh về lớp học:

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 nhất định, chẳng hạn như từ màn hình khoá hoặc trong quá trình thực tế ảo, 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 khi cần thiết.
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/ẩn, tỷ lệ khung hình thay đổi hoặc các thao tác thay đổi.
BoundsAnimationController: tạo hiệu ứ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, có chức năng kiểm soát hành vi di chuyển 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 SystemUIcung cấp một cách triển khai hoàn chỉnh chế độ PIP, hỗ trợ việc trình bày 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. Các nhà sản xuất thiết bị có thể dựa trên những thay đổi này, miễn là những thay đổi đó không ảnh hưởng đến các hành vi vốn có theo định nghĩa của CDD. Sau đây là thông tin tổng quan nhanh về lớp học:

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

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 chế độ PIP:

config_defaultPictureInPictureGravity: số nguyên gravity (trọng lực), kiểm soát góc để đặt chế độ PIP, chẳng hạn như BOTTOM|RIGHT.
config_defaultPictureInPictureScreenEdgeInsets: các khoảng cách từ các cạnh của màn hình để đặt chế độ 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 chế độ 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.

Các chế độ 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 từng gói trong AppOpsManager (main/core/java/android/app/AppOpsManager.java) cho phép người dùng kiểm soát chế độ PIP ở cấp độ từng ứng dụng thông qua phần cài đặt hệ thống. Các hoạt động 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 chế độ PIP, hãy chạy tất cả các kiểm thử liên quan đến chế độ hình trong hình có trong các kiểm thử CTS phía máy chủ trong /cts/hostsidetests/services/activitymanager, đặc biệt là trong ActivityManagerPinnedStackTests.java.