Jetpack WindowManager memungkinkan pengembang aplikasi mendukung faktor bentuk perangkat baru dan lingkungan multi-aplikasi.
Ekstensi WindowManager (Ekstensi) adalah modul platform Android yang dapat digunakan
mengaktifkan berbagai fitur Jetpack WindowManager. Modul ini diimplementasikan
dalam AOSP di frameworks/base/libs/WindowManager/Jetpack
dan dikirim di perangkat yang mendukung fitur WindowManager.
Distribusi modul ekstensi
Ekstensi dikompilasi ke dalam library .jar
dan ditempatkan di system_ext
partisi pada perangkat jika Ekstensi
diaktifkan di makefile perangkat.
Untuk mengaktifkan Ekstensi di perangkat, tambahkan hal berikut ke perangkat produk makefile:
$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)
Tindakan ini akan mengaktifkan androidx.window.extensions
dan androidx.window.sidecar
paket di perangkat dan menetapkan properti persist.wm.extensions.enabled
.
Menyertakan paket-paket ini dalam makefile
juga menempatkan deklarasi di
etc/permissions/
, sehingga tersedia untuk proses aplikasi. Biasanya,
modul dimuat ke dan dieksekusi sebagai bagian dari proses aplikasi di
runtime saat digunakan oleh library Jetpack WindowManager, yang membuat
yang mirip dengan kode framework sisi klien, seperti yang ditunjukkan pada
gambar:
Modul androidx.window.extensions
adalah modul Ekstensi saat ini yang berada di
pengembangan aktif. Modul androidx.window.sidecar
adalah modul lama
disertakan untuk kompatibilitas dengan Jetpack WindowManager versi paling awal,
tetapi file bantuan tidak lagi
dipelihara secara aktif.
Gambar berikut menampilkan logika untuk menentukan penggunaan
androidx.window.extensions
atau androidx.window.sidecar
.
Modul ekstensi
Ekstensi menyediakan fitur jendela untuk perangkat layar besar foldable dan yang mendukung windowing pada layar eksternal. Area fitur meliputi:
Implementasi OEM dari Ekstensi dapat menyediakan komponen atau komponen null dengan
implementasi default atau stub dari metode
WindowExtensions
antarmuka jika perangkat keras perangkat
tidak mendukung fitur yang sesuai,
kecuali jika fitur tersebut
secara khusus diminta dalam
Compatibility Definition Document (CDD) 7.1.1.1.
Ekstensi dan Jetpack API
Modul Ekstensi WindowManager menyediakan platform API-nya sendiri selain
API platform publik. Modul Extensions dikembangkan secara publik dalam sebuah
androidx.window.extensions
yang digunakan oleh non-developer
Library Jetpack, agar Jetpack WindowManager
(androidx.window
)
dapat menautkannya pada waktu kompilasi. Platform Extensions API biasanya
menyediakan API dengan tingkat yang lebih rendah.
API yang disediakan Ekstensi dimaksudkan untuk digunakan oleh Jetpack Khusus library WindowManager. API Ekstensi tidak dimaksudkan untuk dipanggil oleh developer aplikasi secara langsung. Library Extensions tidak boleh ditambahkan sebagai untuk aplikasi dalam file build Gradle untuk memastikan fungsionalitasnya. Menghindari kompilasi library Ekstensi terlebih dahulu ke dalam aplikasi directly; mengandalkan pemuatan runtime untuk mencegah pemuatan campuran dari class Extensions yang telah dikompilasi sebelumnya dan yang disediakan runtime.
Jetpack WindowManager (androidx.window
) dimaksudkan untuk ditambahkan sebagai aplikasi
dan menyediakan API yang ditampilkan kepada developer publik, termasuk
untuk fitur Ekstensi WindowManager. Library WindowManager secara otomatis
memuat Ekstensi ke dalam proses aplikasi dan menggabungkan Ekstensi tingkat rendah
API Perluasan ke abstraksi yang lebih tinggi dan fokus
antarmuka. Jetpack API WindowManager mengikuti standar
Pengembangan aplikasi Android dan dimaksudkan untuk memberikan
interoperabilitas dengan mengintegrasikan codebase yang menggunakan AndroidX lainnya
library.
Versi dan update ekstensi
Modul Extensions dapat diupdate bersama dengan platform Android setiap tahun atau per kuartal. Dengan update kuartalan, API level Extensions dapat meningkat di antara update API platform Android, memungkinkan iterasi dan memberikan kesempatan kepada OEM untuk menambahkan akses API resmi ke fitur baru menjelang peluncuran perangkat keras.
Tabel berikut mencantumkan versi androidx.window.extensions
API untuk
berbagai rilis Android.
Versi platform Android | Level API Extensions WindowManager | Versi androidx.window.extensions API |
---|---|---|
Android 15 | 6 | 1.5.0 (segera hadir) |
Android 14 QPR3 | 5 | 1.4.0 (segera hadir) |
Android 14 QPR1 | 4 | 1.3.0 |
Android 14 | 3 | 1.2.0 |
Android 13 QPR3 | 2 | 1.1.0 |
Android 13 | 1 | 1.0.0 |
Android 12L | 1 | 1.0.0 |
Level API Ekstensi (kolom tengah) ditingkatkan setiap kali ada selain platform API stabil yang sudah ada (kolom kanan).
Kompatibilitas mundur dan maju
Jetpack WindowManager menangani kompleksitas dalam menangani level API yang sering update terbaru, evolusi API yang cepat, dan kompatibilitas mundur. Ketika kode library dieksekusi dalam proses aplikasi, library akan memeriksa API level Extensions dan memberikan akses ke fitur sesuai dengan level organisasi.
Untuk melindungi aplikasi dari error saat runtime, WindowManager juga melakukan pemeriksaan refleksi Java runtime dari Extensions API yang tersedia sesuai dengan level API Ekstensi yang dideklarasikan. Jika terdapat ketidakcocokan, WindowManager dapat menonaktifkan penggunaan Ekstensi (sebagian atau seluruhnya) dan melaporkan konten sebagai tidak tersedia untuk aplikasi.
Ekstensi WindowManager diimplementasikan sebagai modul system_ext
yang menggunakan
API platform pribadi untuk memanggil WindowManager core,
DeviceStateManager
,
dan layanan sistem lainnya dalam
implementasi fitur Ekstensi.
Kompatibilitas tidak dapat dipertahankan dengan Ekstensi versi pra-rilis
sebelum rilis platform Android tiga bulanan atau tahunan yang sesuai dengan
versi mana yang telah difinalisasi. Histori lengkap API Ekstensi dapat
ditemukan di cabang rilis
window:extensions:extensions
file teks API.
Ekstensi versi lebih baru harus terus berfungsi dengan versi lama WindowManager dikompilasi ke dalam aplikasi untuk mempertahankan kompatibilitas dengan versi baru. Kepada memastikan hal ini, setiap versi baru Extensions API hanya akan menambahkan API dan tidak menghapus yang lebih lama. Akibatnya, aplikasi dengan WindowManager versi lama versi saat ini dapat terus menggunakan Extensions API lama saat aplikasi dikompilasi lawan.
Verifikasi CTS memastikan bahwa untuk setiap versi Extensions API yang dideklarasikan pada perangkat, semua API untuk versi tersebut dan versi sebelumnya ada dan berfungsi.
Performa
Modul Ekstensi di-cache di loader class sistem non‐bootclasspath secara default mulai dari Android 14 (level API 34), sehingga tidak ada dampak performa karena memuat modul ke dalam memori saat aplikasi dimulai. Menggunakan fitur modul individual mungkin memiliki sedikit pengaruh terhadap karakteristik kinerja aplikasi saat panggilan IPC tambahan dilakukan antara klien dan server.
Modul
Penyematan aktivitas
Penyematan aktivitas menyediakan seperangkat fitur yang memungkinkan aplikasi mengatur presentasi jendela aktivitas di dalam batas aplikasi induk. Ini menampilkan dua aktivitas secara bersamaan dalam tata letak multi-panel, yang memfasilitasi pengoptimalan perangkat layar besar untuk menggunakan berbagai aplikasi obrolan.
Komponen penyematan aktivitas harus tersedia di semua perangkat yang memiliki
layar bawaan yang berukuran sama dengan atau lebih besar dari sw600 dp
.
Penyematan aktivitas juga harus diaktifkan di perangkat yang mendukung layar eksternal
koneksi jarak jauh, karena aplikasi mungkin ditampilkan
dalam ukuran yang lebih besar saat
terhubung saat runtime.
Konfigurasi perangkat
Tidak ada konfigurasi perangkat khusus yang diperlukan selain mengaktifkan Ekstensi seperti yang dijelaskan dalam Distribusi modul ekstensi bagian. Masuk akal untuk mengaktifkan Ekstensi di semua perangkat yang mendukung mode multi-aplikasi. Versi Android mendatang kemungkinan akan membuat Ekstensi diperlukan pada konfigurasi perangkat genggam dan layar besar yang umum.
Informasi tata letak jendela
Komponen informasi tata letak jendela mengidentifikasi posisi dan status engsel pada perangkat foldable saat engsel melintasi jendela aplikasi. Informasi tata letak jendela memungkinkan aplikasi merespons dan menampilkan tata letak dalam mode di atas meja di perangkat foldable. Lihat Membuat aplikasi Anda fold aware untuk detail penggunaan.
Perangkat Android foldable yang memiliki engsel yang menghubungkan
area panel layar berkelanjutan harus membuat informasi tentang engsel
tersedia untuk aplikasi melalui WindowLayoutComponent
.
Posisi dan batas engsel harus dilaporkan relatif terhadap aplikasi
jendela yang diidentifikasi oleh Context
yang diteruskan ke API. Jika periode pendaftaran
batas tidak berpotongan dengan batas engsel, engsel
DisplayFeature
tidak boleh dilaporkan. Anda juga dapat tidak melaporkan fitur tampilan
ketika posisinya mungkin tidak dapat dilaporkan dengan andal, seperti ketika sebuah aplikasi
dan jendela dapat dipindahkan dengan bebas oleh pengguna dalam mode multi-aplikasi atau
mode tampilan lebar kompatibilitas.
Untuk fitur lipat,
update status harus dilaporkan ketika posisi engsel berubah antara
stabil. Secara default dalam status tampilan datar, API harus melaporkan
FoldingFeature.State.FLAT
Jika hardware perangkat dapat dibiarkan dalam mode setengah terlipat dalam keadaan stabil,
API harus melaporkan FoldingFeature.State.HALF_OPENED
.
Tidak ada status tertutup di API, karena dalam kasus seperti itu jendela aplikasi
tidak akan terlihat atau
tidak akan melewati batas engsel.
Konfigurasi perangkat
Untuk mendukung penerapan fitur lipat, OEM harus melakukan hal berikut:
Konfigurasi status perangkat di
device_state_configuration.xml
yang akan digunakan olehDeviceStateManagerService
. LihatDeviceStateProviderImpl.java
untuk referensi.Jika implementasi default
DeviceStateProvider
atauDeviceStatePolicy
tidak cocok untuk perangkat, implementasi kustom dapat digunakan.Aktifkan modul Ekstensi seperti yang dijelaskan dalam Bagian Distribusi modul ekstensi.
Menentukan lokasi fitur tampilan di
com.android.internal.R.string.config_display_features
resource string (biasanya dalamframeworks/base/core/res/res/values/config.xml
di overlay perangkat).Format yang diharapkan untuk string ini adalah:
<type>-[<left>,<top>,<right>,<bottom>]
type
dapat berupafold
atauhinge
. Nilai untukleft
,top
,right
danbottom
adalah koordinat piksel bilangan bulat di ruang koordinat tampilan di orientasi tampilan alami. String konfigurasi bisa berisi beberapa menampilkan fitur yang dipisahkan dengan titik koma.Contoh:
<!-- Jetpack WindowManager display features --> <string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>
Menentukan pemetaan antara ID status perangkat internal yang digunakan dalam
DeviceStateManager
dan konstanta status publik yang dikirim ke developer dicom.android.internal.R.array.config_device_state_postures
.Format yang diharapkan untuk setiap entri adalah:
<device_specific_state_identifier>:<Jetpack WindowManager state identifier>
ID status yang didukung adalah:
COMMON_STATE_NO_FOLDING_FEATURES = 1
: Status tidak memiliki fitur lipat untuk laporan. Misalnya, dapat berupa status tertutup dari mode lipat biasa perangkat dengan layar utama di sisi dalam.COMMON_STATE_HALF_OPENED = 2
: Fitur lipat terbuka setengah.COMMON_STATE_FLAT = 3
: Fitur lipat menjadi datar. Misalnya, ini dapat berupa status terbuka dari perangkat lipat biasa dengan layar utama di sisi dalam.COMMON_STATE_USE_BASE_STATE = 1000
: Masuk Android 14, nilai yang dapat digunakan untuk diemulasi status di mana status engsel diperoleh menggunakan status dasar, seperti yangCommonFoldingFeature.java
Lihat
DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int)
untuk mengetahui informasi selengkapnya.Contoh:
<!-- Map of System DeviceState supplied by DeviceStateManager to WindowManager posture.--> <string-array name="config_device_state_postures" translatable="false"> <item>0:1</item> <!-- CLOSED : COMMON_STATE_NO_FOLDING_FEATURES --> <item>1:2</item> <!-- HALF_OPENED : COMMON_STATE_HALF_OPENED --> <item>2:3</item> <!-- OPENED : COMMON_STATE_FLAT --> <item>3:1</item> <!-- REAR_DISPLAY : COMMON_STATE_NO_FOLDING_FEATURES --> <item>4:1000</item> <!-- CONCURRENT : COMMON_STATE_USE_BASE_STATE --> </string-array>
Area jendela
Komponen area jendela menyediakan serangkaian fitur yang memberikan akses ke layar dan area tampilan tambahan pada beberapa perangkat foldable dan perangkat multi-tampilan.
Mode tampilan belakang memungkinkan aplikasi menampilkan UI pratinjau kamera pada layar penutup perangkat foldable untuk memungkinkan penggunaan kamera perangkat utama untuk selfie dan video. Perangkat yang kompatibel dengan Android (seperti yang didefinisikan oleh Android CDD dalam hal atribut seperti ukuran, kepadatan, dan kemampuan navigasi yang tersedia) penutup layar yang sejajar dengan perangkat belakang kamera harus menyediakan akses ke mode tampilan belakang.
Di Android 14, mode layar ganda memungkinkan aplikasi yang berjalan di layar dalam perangkat foldable menampilkan konten tambahan di layar penutup yang menghadap ke pengguna lain; misalnya, tampilan sampul dapat menampilkan pratinjau kamera kepada orang yang difoto atau direkam.
Konfigurasi perangkat
Untuk mendukung penerapan fitur lipat, OEM harus melakukan hal berikut:
Konfigurasi status perangkat di
device_state_configuration.xml
yang akan digunakan olehDeviceStateManagerService
. LihatDeviceStateProviderImpl.java
untuk informasi selengkapnya.Jika implementasi {i>default<i} dari
DeviceStateProvider
atauDeviceStatePolicy
tidak cocok untuk perangkat, implementasi kustom dapat digunakan.Untuk perangkat foldable yang mendukung mode terbuka atau datar, tentukan ID status di
com.android.internal.R.array.config_openDeviceStates
.Untuk perangkat lipat yang mendukung status terlipat, cantumkan item yang sesuai ID status di
com.android.internal.R.array.config_foldedDeviceStates
.Untuk perangkat lipat yang mendukung kondisi setengah terlipat (engsel setengah terbuka seperti laptop), cantumkan status yang sesuai di
com.android.internal.R.array.config_halfFoldedDeviceStates
.Untuk perangkat yang mendukung mode tampilan belakang:
- Cantumkan status yang sesuai di
com.android.internal.R.array.config_rearDisplayDeviceStates
untukDeviceStateManager
. - Tentukan alamat tampilan fisik tampilan belakang di
com.android.internal.R.string.config_rearDisplayPhysicalAddress
. - Menentukan ID status di
com.android.internal.R.integer.config_deviceStateRearDisplay
yang akan digunakan oleh Ekstensi. - Tambahkan ID status di
com.android.internal.R.array.config_deviceStatesAvailableForAppRequests
agar tersedia untuk aplikasi.
- Cantumkan status yang sesuai di
Di Android 14, untuk perangkat yang mendukung mode tampilan ganda (serentak):
- Setel
com.android.internal.R.bool.config_supportsConcurrentInternalDisplays
ketrue
. - Tentukan alamat tampilan fisik tampilan belakang di
com.android.internal.R.config_deviceStateConcurrentRearDisplay
. - Tentukan ID status di
com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay
yang akan digunakan oleh Ekstensi jika ID tersebut dimaksudkan untuk disediakan untuk aplikasi. - Tambahkan ID status di
com.android.internal.R.array.config_deviceStatesAvailableForAppRequests
agar tersedia untuk aplikasi.
- Setel
Verifikasi
OEM harus memverifikasi penerapannya untuk memastikan kesamaan perilaku yang diharapkan yang signifikan. Pengujian CTS menggunakan Jetpack WindowManager tersedia untuk OEM untuk implementasi pengujian.
Uji CTS
Untuk menjalankan uji CTS, lihat Menjalankan uji CTS. CTS
pengujian yang terkait dengan Jetpack WindowManager berada di cts/tests/framework/base/windowmanager/jetpack/
.
Nama modul pengujian adalah CtsWindowManagerJetpackTestCases
.
Pengujian WindowManager
Untuk mendownload pengujian Jetpack WindowManager, ikuti
Petunjuk Android Jetpack.
Pengujian ini berada di library jendela pada modul window:window
: window/window/src/androidTest/
.
Untuk menjalankan pengujian perangkat bagi modul window:window
dari command line, lakukan
hal berikut:
- Colokkan perangkat yang mengaktifkan opsi developer dan Proses debug USB.
- Izinkan komputer untuk men-debug perangkat.
- Buka shell di direktori utama repositori androidx.
- Ubah direktori ke
framework/support
. - Jalankan perintah berikut:
./gradlew window:window:connectedAndroidTest
. - Menganalisis hasilnya.
Untuk menjalankan pengujian dari Android Studio, lakukan hal berikut:
- Buka Android Studio.
- Colokkan perangkat yang mengaktifkan opsi developer dan Proses debug USB.
- Izinkan komputer untuk men-debug perangkat.
- Buka pengujian dalam library jendela di modul jendela.
- Buka class pengujian dan jalankan menggunakan panah hijau di sisi kanan .
Atau, Anda bisa membuat konfigurasi di Android Studio untuk menjalankan pengujian pengujian, class pengujian, atau semua pengujian dalam modul.
Hasil dapat dianalisis secara manual dengan melihat output shell. Agak besar pengujian dilewati jika perangkat tidak memenuhi asumsi tertentu. Hasilnya adalah disimpan di lokasi standar, dan analis dapat menulis skrip untuk mengotomatisasi analisis terhadap hasil yang diperoleh.