Mulai 27 Maret 2025, sebaiknya gunakan android-latest-release, bukan aosp-main, untuk mem-build dan berkontribusi pada AOSP. Untuk mengetahui informasi selengkapnya, lihat Perubahan pada AOSP.

Halaman ini diterjemahkan oleh Cloud Translation API.

Picture-in-picture
Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Fitur picture-in-picture (PIP) untuk perangkat genggam Android memungkinkan pengguna mengubah ukuran aplikasi dengan aktivitas yang sedang berlangsung menjadi jendela kecil. PIP sangat berguna untuk aplikasi video karena konten terus diputar saat pengguna bebas melakukan tindakan lain. Pengguna dapat memanipulasi posisi jendela ini melalui SystemUI dan berinteraksi dengan aplikasi yang saat ini dalam mode picture-in-picture dengan (maksimal tiga) tindakan yang disediakan aplikasi.

PIP memerlukan keikutsertaan eksplisit dari aplikasi yang mendukungnya dan berfungsi berdasarkan aktivitas. (Satu aplikasi dapat memiliki beberapa aktivitas, hanya satu yang ada dalam PIP.) Aktivitas meminta untuk masuk ke picture-in-picture dengan memanggil enterPictureInPictureMode(), dan menerima callback aktivitas dalam bentuk onPictureInPictureModeChanged().

Metode setPictureInPictureParams() memungkinkan aktivitas mengontrol rasio aspeknya saat dalam tindakan PIP dan kustom, yang memungkinkan pengguna berinteraksi dengan aktivitas tanpa harus meluaskannya. Dalam PIP, aktivitas berada dalam status dijeda, tetapi merender, dan tidak langsung menerima input sentuh atau fokus jendela. Hanya satu tugas yang dapat berada dalam PIP dalam satu waktu.

Informasi selengkapnya tersedia di dokumentasi Picture-in-picture Developer Android.

Persyaratan perangkat

Untuk mendukung PIP, aktifkan fitur sistem PackageManager#FEATURE_PICTURE_IN_PICTURE di /android/frameworks/base/core/java/android/content/pm/PackageManager.java. Perangkat yang mendukung PIP harus memiliki layar yang lebih besar dari 220 dp pada lebar terkecilnya. Serupa dengan multi-aplikasi layar terpisah, PIP memungkinkan beberapa aktivitas berjalan di layar secara bersamaan. Oleh karena itu, perangkat harus memiliki CPU dan RAM yang memadai untuk mendukung kasus penggunaan ini.

Implementasi

Sebagian besar pengelolaan siklus proses aktivitas dilakukan dalam sistem antara ActivityManager dan WindowManager. Implementasi UI referensi ada dalam paket SystemUI.

Modifikasi pada sistem tidak boleh memengaruhi perilaku intrinsiknya seperti yang ditentukan oleh pengujian Compatibility Test Suite (CTS). Logika sistem untuk PIP terutama berfokus pada pengelolaan tugas dan aktivitas dalam stack "disematkan". Berikut adalah ringkasan singkat class:

ActivityRecord: melacak status picture-in-picture setiap aktivitas. Untuk mencegah pengguna memasuki PIP dalam keadaan tertentu, seperti dari layar kunci atau selama VR, tambahkan kasus ke checkEnterPictureInPictureState().
ActivityManagerService: antarmuka utama dari aktivitas untuk meminta masuk ke PIP dan antarmuka untuk panggilan dari WindowManager dan SystemUI untuk mengubah status aktivitas PIP.
ActivityStackSupervisor: dipanggil dari ActivityManagerService untuk memindahkan tugas ke dalam atau keluar dari kelompok yang disematkan, memperbarui WindowManager sesuai kebutuhan.
PinnedStackWindowController: antarmuka WindowManager dari ActivityManager.
PinnedStackController: melaporkan perubahan dalam sistem ke SystemUI, seperti IME ditampilkan/disembunyikan, rasio aspek diubah, atau tindakan diubah.
BoundsAnimationController: menganimasikan jendela aktivitas PIP dengan cara yang tidak memicu perubahan konfigurasi saat mengubah ukuran.
PipSnapAlgorithm: class bersama yang digunakan di sistem dan SystemUI yang mengontrol perilaku snap jendela PIP di dekat tepi layar.

Referensi SystemUI menyediakan implementasi lengkap PIP yang mendukung presentasi tindakan kustom kepada pengguna dan manipulasi umum, seperti perluasan dan penutupan. Produsen perangkat dapat membuat perubahan ini, selama perubahan tersebut tidak memengaruhi perilaku intrinsik seperti yang ditentukan oleh CDD. Berikut adalah ringkasan kelas singkat:

PipManager: komponen SystemUI yang dimulai dengan SystemUI.
PipTouchHandler: pengendali sentuh, yang mengontrol gestur yang memanipulasi PIP. Ini hanya digunakan saat konsumen input untuk PIP aktif (lihat InputConsumerController). Gestur baru dapat ditambahkan di sini.
PipMotionHelper: class praktis yang melacak posisi PIP, dan wilayah yang diizinkan di layar. Memanggil ActivityManagerService untuk memperbarui atau menganimasikan posisi dan ukuran PIP.
PipMenuActivityController: memulai aktivitas yang menampilkan tindakan yang disediakan oleh aktivitas yang saat ini berada dalam PIP. Aktivitas ini adalah aktivitas overlay tugas, dan menghapus konsumen input overlay agar dapat bersifat interaktif.
PipMenuActivity: implementasi untuk aktivitas menu.
PipMediaController: pemroses yang memperbarui SystemUI saat sesi media berubah dengan cara yang dapat memengaruhi tindakan default pada PIP.
PipNotificationController: pengontrol yang memastikan notifikasi aktif saat pengguna menggunakan fitur PIP.
PipDismissViewController: overlay yang ditampilkan kepada pengguna saat mereka mulai berinteraksi dengan PIP untuk menunjukkan bahwa overlay tersebut dapat ditutup.

Penempatan default

Ada berbagai resource sistem yang mengontrol penempatan default PIP:

config_defaultPictureInPictureGravity: bilangan bulat gravitasi, yang mengontrol sudut untuk menempatkan PIP, seperti BOTTOM|RIGHT.
config_defaultPictureInPictureScreenEdgeInsets: offset dari sisi layar untuk menempatkan PIP.
config_pictureInPictureDefaultSizePercent dan config_pictureInPictureDefaultAspectRatio: kombinasi persentase lebar layar dan rasio aspek mengontrol ukuran PIP. Ukuran PIP default yang dihitung tidak boleh lebih kecil dari @dimen/default_minimal_size_pip_resizable_task, seperti yang ditentukan oleh CTS dan CDD.
config_pictureInPictureSnapMode: perilaku snap seperti yang ditentukan dalam PipSnapAlgorithm.

Implementasi perangkat tidak boleh mengubah rasio aspek minimum dan maksimum yang ditentukan dalam CDD dan CTS.

Izin

"Operasi aplikasi" (OP_PICTURE_IN_PICTURE) per paket di AppOpsManager (main/core/java/android/app/AppOpsManager.java), memungkinkan pengguna mengontrol PIP di tingkat per aplikasi melalui setelan sistem. Implementasi perangkat harus mematuhi pemeriksaan ini saat aktivitas meminta untuk masuk ke mode picture-in-picture.

Pengujian

Untuk menguji implementasi PIP, jalankan semua pengujian terkait picture-in-picture yang ditemukan dalam pengujian CTS sisi host di bagian /cts/hostsidetests/services/activitymanager, terutama di ActivityManagerPinnedStackTests.java.