Ekstensi WindowManager

Library Jetpack WindowManager memungkinkan developer aplikasi mendukung faktor bentuk perangkat baru dan lingkungan multi‑aplikasi.

Ekstensi WindowManager (Ekstensi) adalah modul platform Android yang bersifat keikutsertaan dan mengaktifkan berbagai fitur Jetpack WindowManager. Modul ini diimplementasikan di AOSP dalam frameworks/base/libs/WindowManager/Jetpack dan dikirimkan di perangkat yang mendukung fitur WindowManager.

Distribusi modul ekstensi

Ekstensi dikompilasi ke dalam library .jar dan ditempatkan di partisi system_ext pada perangkat jika Ekstensi diaktifkan dalam makefile perangkat.

Untuk mengaktifkan Ekstensi di perangkat, tambahkan kode berikut ke makefile perangkat produk:

$(call inherit-product, $(SRC_TARGET_DIR)/product/window_extensions.mk)

Hal ini mengaktifkan paket androidx.window.extensions dan androidx.window.sidecar di perangkat dan menetapkan properti persist.wm.extensions.enabled. Menyertakan paket ini dalam makefile juga menempatkan deklarasi di etc/permissions/, sehingga membuatnya tersedia untuk proses aplikasi. Biasanya, modul dimuat ke dalam dan dieksekusi sebagai bagian dari proses aplikasi saat runtime ketika digunakan oleh library Jetpack WindowManager, yang membuat operasinya mirip dengan kode framework sisi klien, seperti yang ditunjukkan pada gambar berikut:

Modul androidx.window.extensions adalah modul Ekstensi saat ini yang sedang dalam pengembangan aktif. Modul androidx.window.sidecar adalah modul lama yang disertakan untuk kompatibilitas dengan versi Jetpack WindowManager paling awal, tetapi sidecar tidak lagi dipertahankan secara aktif.

Gambar berikut menunjukkan logika untuk menentukan penggunaan androidx.window.extensions atau androidx.window.sidecar.

Modul ekstensi

Ekstensi menyediakan fitur tampilan jendela untuk perangkat foldable layar besar dan perangkat yang mendukung tampilan jendela di layar eksternal. Area fitur meliputi:

• Penyematan aktivitas
• Informasi tata letak jendela
• Area jendela

Implementasi Ekstensi OEM dapat menyediakan komponen null atau komponen dengan implementasi metode default atau stub dalam antarmuka WindowExtensions jika hardware perangkat tidak mendukung fitur yang sesuai, kecuali jika fitur tersebut secara khusus diminta dalam Dokumen Definisi Kompatibilitas (CDD) 7.1.1.1.

API Ekstensi dan Jetpack

Modul Ekstensi WindowManager menyediakan platform API-nya sendiri selain API platform publik. Modul Ekstensi dikembangkan secara publik di library Jetpack androidx.window.extensions yang tidak ditujukan untuk developer, sehingga Jetpack WindowManager (androidx.window) dapat ditautkan ke modul tersebut pada waktu kompilasi. Platform Extensions API biasanya menyediakan API tingkat yang lebih rendah.

API yang disediakan Ekstensi dimaksudkan untuk digunakan oleh library Jetpack WindowManager saja. API Ekstensi tidak dimaksudkan untuk dipanggil langsung oleh developer aplikasi. Library Extensions tidak boleh ditambahkan sebagai dependensi untuk aplikasi dalam file build Gradle guna memastikan fungsi yang benar. Hindari pra-kompilasi library Ekstensi ke dalam aplikasi secara langsung; sebagai gantinya, andalkan pemuatan runtime untuk mencegah pemuatan campuran class Ekstensi yang telah dikompilasi sebelumnya dan yang disediakan runtime.

Jetpack WindowManager (androidx.window) dimaksudkan untuk ditambahkan sebagai dependensi aplikasi dan menyediakan API publik yang ditujukan untuk developer, termasuk API untuk fitur Ekstensi WindowManager. Library WindowManager otomatis memuat Ekstensi ke dalam proses aplikasi dan membungkus API Ekstensi tingkat bawah ke dalam abstraksi tingkat yang lebih tinggi dan antarmuka yang lebih terfokus. API Jetpack WindowManager mengikuti standar pengembangan aplikasi Android modern dan dimaksudkan untuk memberikan interoperabilitas yang mudah dengan berintegrasi baik dengan codebase yang menggunakan library AndroidX lainnya.

Versi dan update ekstensi

Modul Ekstensi dapat diupdate bersama dengan update platform Android tahunan atau triwulanan. Update per kuartal memungkinkan level API Ekstensi ditingkatkan di antara update API platform Android, sehingga memungkinkan iterasi yang lebih cepat dan memberikan peluang bagi OEM untuk menambahkan akses API resmi ke fitur baru yang mendekati peluncuran hardware.

Tabel berikut mencantumkan versi API androidx.window.extensions untuk berbagai rilis Android.

Level API Ekstensi (kolom tengah) ditingkatkan setiap kali ada penambahan pada permukaan API stabil yang ada (kolom kanan).

Kompatibilitas mundur dan maju

Jetpack WindowManager menangani kompleksitas terkait seringnya update level API, evolusi API yang cepat, dan kompatibilitas mundur. Saat kode library dieksekusi dalam proses aplikasi, library akan memeriksa level API Ekstensi yang dideklarasikan dan memberikan akses ke fitur sesuai dengan level yang dideklarasikan.

Untuk melindungi aplikasi dari error saat runtime, WindowManager juga melakukan pemeriksaan refleksi Java runtime dari API Ekstensi yang tersedia sesuai dengan level API Ekstensi yang dideklarasikan. Jika ada ketidakcocokan, WindowManager dapat menonaktifkan penggunaan Ekstensi (sebagian atau seluruhnya) dan melaporkan fitur yang relevan sebagai tidak tersedia untuk aplikasi.

Ekstensi WindowManager diimplementasikan sebagai modul system_ext yang menggunakan API platform pribadi untuk memanggil inti WindowManager, DeviceStateManager, dan layanan sistem lainnya dalam penerapan fitur Ekstensi.

Kompatibilitas mungkin tidak dipertahankan dengan versi pra-rilis Ekstensi sebelum rilis platform Android kuartalan atau tahunan yang sesuai dengan versi yang diselesaikan. Histori lengkap Extensions API dapat ditemukan di file teks window:extensions:extensions API cabang rilis.

Versi Extensions yang lebih baru harus terus berfungsi dengan versi WindowManager yang lebih lama yang dikompilasi ke dalam aplikasi untuk mempertahankan kompatibilitas ke depan. Untuk memastikan hal ini, setiap versi baru Extensions API hanya menambahkan API baru dan tidak menghapus API lama. Akibatnya, aplikasi dengan WindowManager versi lama dapat terus menggunakan Extensions API lama yang digunakan untuk mengompilasi aplikasi.

Verifikasi CTS memastikan bahwa untuk setiap versi API Ekstensi yang dideklarasikan di perangkat, semua API untuk versi tersebut dan versi sebelumnya ada dan berfungsi.

Performa

Modul Ekstensi di-cache di pemuat 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. Penggunaan fitur modul individual mungkin sedikit memengaruhi karakteristik performa aplikasi saat panggilan IPC tambahan dilakukan antara klien dan server.

Modul

Penyematan aktivitas

Komponen penyematan aktivitas memungkinkan aplikasi mengoptimalkan UI untuk perangkat layar besar dan tampilan eksternal. Penyematan aktivitas memungkinkan penyajian dua aktivitas secara berdampingan dalam tata letak multipanel, sehingga memfasilitasi pengembangan aplikasi adaptif untuk aplikasi lama.

Komponen penyematan aktivitas harus tersedia di semua perangkat yang memiliki layar bawaan yang sama dengan atau lebih besar dari sw600dp. Penyematan aktivitas juga harus diaktifkan di perangkat yang mendukung koneksi layar eksternal, karena aplikasi mungkin ditampilkan dalam ukuran yang lebih besar saat layar eksternal terhubung saat runtime.

Konfigurasi perangkat

Tidak diperlukan konfigurasi perangkat tertentu selain mengaktifkan modul Ekstensi seperti yang dijelaskan di bagian Distribusi modul Ekstensi. Sebaiknya aktifkan Ekstensi di semua perangkat yang mendukung mode multi-aplikasi. Versi Android mendatang kemungkinan akan mewajibkan Ekstensi pada konfigurasi perangkat layar besar dan perangkat genggam 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 yang dioptimalkan dalam mode di atas meja pada perangkat foldable. Lihat Membuat aplikasi Anda fold aware untuk mengetahui detail penggunaan.

Perangkat Android foldable yang menyertakan engsel yang menghubungkan area panel layar terpisah atau berkelanjutan harus menyediakan informasi tentang engsel tersebut untuk aplikasi melalui WindowLayoutComponent.

Posisi dan batas engsel harus dilaporkan relatif terhadap jendela aplikasi yang diidentifikasi oleh Context yang diteruskan ke API. Jika batas jendela aplikasi tidak berpotongan dengan batas engsel, engsel DisplayFeature tidak boleh dilaporkan. Anda juga dapat tidak melaporkan fitur tampilan jika posisinya mungkin tidak dilaporkan secara andal, seperti saat jendela aplikasi dapat dipindahkan secara bebas oleh pengguna dalam mode multi-aplikasi atau mode tampilan lebar kompatibilitas.

Untuk fitur perangkat lipat, pembaruan status harus dilaporkan saat posisi engsel berubah di antara status stabil. Secara default dalam status tampilan datar, API harus melaporkan FoldingFeature.State.FLAT. Jika hardware perangkat dapat dibiarkan dalam mode terlipat setengah dalam kondisi 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 melintasi batas engsel.

Konfigurasi perangkat

Untuk mendukung penerapan fitur perangkat lipat, OEM harus melakukan hal berikut:

• Konfigurasi status perangkat di device_state_configuration.xml yang akan digunakan oleh DeviceStateManagerService. Lihat DeviceStateProviderImpl.java untuk referensi.

  Jika penerapan default DeviceStateProvider atau DeviceStatePolicy tidak sesuai untuk perangkat, penerapan kustom dapat digunakan.

• Aktifkan modul Ekstensi seperti yang dijelaskan di bagian Distribusi modul Ekstensi.

• Tentukan lokasi fitur tampilan di resource string com.android.internal.R.string.config_display_features (biasanya di frameworks/base/core/res/res/values/config.xml dalam overlay perangkat).

  Format yang diharapkan untuk string adalah:

  <type>-[<left>,<top>,<right>,<bottom>]

  type dapat berupa fold atau hinge. Nilai untuk left, top, right, dan bottom adalah koordinat piksel bilangan bulat dalam ruang koordinat tampilan dalam orientasi tampilan alami. String konfigurasi dapat berisi beberapa fitur tampilan yang dipisahkan dengan titik koma.

  Contoh:

  <!-- Jetpack WindowManager display features -->
  <string name="config_display_features" translatable="false">fold-[1000,0,1000,2000]</string>
  

• Tentukan pemetaan antara ID status perangkat internal yang digunakan di DeviceStateManager dan konstanta status publik yang dikirim ke developer di com.android.internal.R.array.config_device_state_postures.

  Format yang diharapkan untuk setiap entri adalah:

  <device_specific_state_identifier>:<Jetpack WindowManager state identifier>

  ID negara bagian yang didukung adalah:

  • COMMON_STATE_NO_FOLDING_FEATURES = 1: Status tidak memiliki fitur pelipatan untuk dilaporkan. Misalnya, ini dapat berupa status tertutup dari perangkat lipat ke dalam biasa dengan layar utama di sisi dalam.
  • COMMON_STATE_HALF_OPENED = 2: Fitur lipat terbuka setengah.
  • COMMON_STATE_FLAT = 3: Fitur pelipatan datar. Misalnya, ini dapat berupa status terbuka perangkat lipat ke dalam yang umum dengan layar utama di sisi dalam.
  • COMMON_STATE_USE_BASE_STATE = 1000: Di Android 14, nilai yang dapat digunakan untuk status yang diemulasi saat status engsel diperoleh menggunakan status dasar, seperti yang ditentukan dalam CommonFoldingFeature.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 memberi aplikasi akses ke tampilan dan area tampilan tambahan di beberapa perangkat foldable dan multi-tampilan.

Mode tampilan belakang memungkinkan aplikasi menampilkan UI pratinjau kamera di layar luar perangkat foldable untuk memungkinkan penggunaan kamera perangkat utama untuk selfie dan video. Perangkat yang memiliki layar luar yang kompatibel dengan Android (sebagaimana ditentukan oleh CDD Android dalam hal atribut seperti ukuran, kepadatan, dan kemampuan navigasi yang tersedia) yang sejajar dengan kamera perangkat belakang harus menyediakan akses ke mode layar belakang.

Di Android 14, mode layar ganda memungkinkan aplikasi yang berjalan di layar dalam perangkat foldable menampilkan konten tambahan di layar luar yang menghadap pengguna lain; misalnya, layar luar dapat menampilkan pratinjau kamera kepada orang yang difoto atau direkam.

Konfigurasi perangkat

Untuk mendukung penerapan fitur perangkat lipat, OEM harus melakukan hal berikut:

• Konfigurasi status perangkat di device_state_configuration.xml yang akan digunakan oleh DeviceStateManagerService. Lihat DeviceStateProviderImpl.java untuk mengetahui informasi selengkapnya.

  Jika penerapan default DeviceStateProvider atau DeviceStatePolicy tidak sesuai untuk perangkat, penerapan kustom dapat digunakan.

• Untuk perangkat foldable yang mendukung mode terbuka atau datar, tentukan ID status yang sesuai di com.android.internal.R.array.config_openDeviceStates.

• Untuk perangkat lipat ke dalam yang mendukung status terlipat, cantumkan ID status yang sesuai di com.android.internal.R.array.config_foldedDeviceStates.

• Untuk perangkat lipat ke dalam yang mendukung kondisi terlipat setengah (engsel terbuka setengah seperti laptop), cantumkan kondisi yang sesuai di com.android.internal.R.array.config_halfFoldedDeviceStates.

• Untuk perangkat yang mendukung mode tampilan belakang:

  • Mencantumkan status yang sesuai di com.android.internal.R.array.config_rearDisplayDeviceStates untuk DeviceStateManager.
  • Tentukan alamat tampilan fisik layar belakang di com.android.internal.R.string.config_rearDisplayPhysicalAddress.
  • Tentukan 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.

• Di Android 14, untuk perangkat yang mendukung mode tampilan ganda (serentak):

  • Tetapkan com.android.internal.R.bool.config_supportsConcurrentInternalDisplays ke true.
  • Tentukan alamat tampilan fisik layar 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 tersedia bagi aplikasi.
  • Tambahkan ID status di com.android.internal.R.array.config_deviceStatesAvailableForAppRequests agar tersedia untuk aplikasi.

Verifikasi

OEM harus memverifikasi implementasinya untuk memastikan perilaku yang diharapkan dalam skenario umum. Pengujian CTS dan pengujian menggunakan Jetpack WindowManager tersedia bagi OEM untuk menguji implementasi.

Pengujian CTS

Untuk menjalankan pengujian CTS, lihat Menjalankan pengujian CTS. Pengujian CTS yang terkait dengan Jetpack WindowManager berada di bagian cts/tests/framework/base/windowmanager/jetpack/. Nama modul pengujian adalah CtsWindowManagerJetpackTestCases.

Pengujian WindowManager

Untuk mendownload pengujian Jetpack WindowManager, ikuti Petunjuk Android Jetpack. Pengujian terletak di library jendela dalam modul window:window: window/window/src/androidTest/.

Untuk menjalankan pengujian perangkat untuk modul window:window dari command line, lakukan hal berikut:

1. Colokkan perangkat yang telah mengaktifkan opsi developer dan proses debug USB.
2. Izinkan komputer men-debug perangkat.
3. Buka shell di direktori root repositori androidx.
4. Ubah direktori ke framework/support.
5. Jalankan perintah berikut: ./gradlew window:window:connectedAndroidTest.
6. Analisis hasilnya.

Untuk menjalankan pengujian dari Android Studio, lakukan hal berikut:

1. Buka Android Studio.
2. Colokkan perangkat yang telah mengaktifkan opsi developer dan proses debug USB.
3. Izinkan komputer men-debug perangkat.
4. Buka pengujian dalam library jendela modul jendela.
5. Buka class pengujian dan jalankan menggunakan panah hijau di sisi kanan editor.

Atau, Anda dapat membuat konfigurasi di Android Studio untuk menjalankan metode pengujian, class pengujian, atau semua pengujian dalam modul.

Hasil dapat dianalisis secara manual dengan melihat output shell. Beberapa pengujian dilewati jika perangkat tidak memenuhi asumsi tertentu. Hasil disimpan di lokasi standar, dan analis dapat menulis skrip untuk mengotomatiskan analisis hasil.