Ekstensi Manajer Jendela

Pustaka Jetpack WindowManager memungkinkan pengembang aplikasi mendukung faktor bentuk perangkat baru dan lingkungan multi-jendela.

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

Distribusi modul ekstensi

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

Untuk mengaktifkan Ekstensi pada perangkat, tambahkan yang berikut ini 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 pada perangkat dan menyetel properti persist.wm.extensions.enabled . Memasukkan paket-paket ini ke dalam makefile juga menempatkan deklarasi di etc/permissions/ , sehingga tersedia untuk proses aplikasi. Biasanya modul dimuat ke dalam dan dieksekusi sebagai bagian dari proses aplikasi saat runtime ketika digunakan oleh pustaka Jetpack WindowManager, yang membuat operasinya mirip dengan kode kerangka sisi klien, seperti yang ditunjukkan dalam gambar berikut:

Modul androidx.window.extensions adalah modul Ekstensi saat ini yang sedang dikembangkan secara aktif. Modul androidx.window.sidecar adalah modul lama yang disertakan untuk kompatibilitas dengan versi Jetpack WindowManager yang paling awal, namun 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 windowing untuk perangkat layar besar yang dapat dilipat dan perangkat yang mendukung windowing pada layar eksternal. Area fitur meliputi:

• Penyematan aktivitas
• Informasi tata letak jendela
• Daerah jendela

Implementasi OEM dari Ekstensi dapat memberikan komponen null atau komponen dengan implementasi default atau stub dari metode di antarmuka WindowExtensions jika perangkat keras perangkat tidak mendukung fitur terkait, kecuali fitur tersebut diminta secara khusus dalam Dokumen Definisi Kompatibilitas (CDD) 7.1.1.1 .

Ekstensi dan API Jetpack

Modul Ekstensi WindowManager menyediakan permukaan API-nya sendiri selain API platform publik. Modul Extensions dikembangkan secara publik di pustaka Jetpack androidx.window.extensions yang tidak dapat diakses oleh pengembang, sehingga Jetpack WindowManager ( androidx.window ) dapat terhubung dengannya pada waktu kompilasi. Permukaan Extensions API biasanya menyediakan API tingkat rendah.

API yang disediakan Ekstensi dimaksudkan untuk digunakan oleh pustaka Jetpack WindowManager saja. Extensions API tidak dimaksudkan untuk dipanggil oleh pengembang aplikasi secara langsung. Library Extensions tidak boleh ditambahkan sebagai dependensi untuk aplikasi di file build Gradle untuk memastikan fungsionalitas yang benar. Hindari melakukan pra-kompilasi pustaka Ekstensi ke dalam aplikasi secara langsung; sebagai gantinya, andalkan pemuatan waktu proses untuk mencegah kasus pemuatan campuran kelas Ekstensi yang telah dikompilasi sebelumnya dan yang disediakan waktu proses.

Jetpack WindowManager ( androidx.window ) dimaksudkan untuk ditambahkan sebagai dependensi aplikasi dan menyediakan API publik yang dapat diakses oleh pengembang, termasuk untuk fitur Ekstensi WindowManager. Pustaka WindowManager secara otomatis memuat Ekstensi ke dalam proses aplikasi dan menggabungkan API Ekstensi tingkat rendah ke dalam abstraksi tingkat lebih tinggi dan antarmuka yang lebih fokus. API Jetpack WindowManager mengikuti standar pengembangan aplikasi Android modern dan dimaksudkan untuk menyediakan interoperabilitas yang nyaman dengan berintegrasi dengan baik dengan basis kode yang menggunakan pustaka AndroidX lainnya.

Versi dan pembaruan ekstensi

Modul Ekstensi dapat diperbarui bersama dengan pembaruan tahunan atau triwulanan platform Android. Pembaruan triwulanan memungkinkan tingkat API Ekstensi ditingkatkan di antara pembaruan API platform Android, memungkinkan iterasi yang lebih cepat dan memberikan kesempatan kepada OEM untuk menambahkan akses API resmi ke fitur-fitur baru menjelang peluncuran perangkat keras.

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

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

Kompatibilitas mundur dan maju

Jetpack WindowManager menangani kerumitan dalam menangani pembaruan tingkat API yang sering dilakukan, evolusi API yang cepat, dan kompatibilitas mundur. Ketika kode pustaka dijalankan dalam proses aplikasi, pustaka memeriksa level API Ekstensi yang dideklarasikan dan menyediakan akses ke fitur sesuai dengan level yang dideklarasikan.

Untuk melindungi aplikasi agar tidak mogok saat runtime, WindowManager juga melakukan pemeriksaan refleksi Java runtime terhadap Extensions API yang tersedia sesuai dengan level Extensions API yang dideklarasikan. Jika terdapat 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 implementasi fitur Ekstensi.

Kompatibilitas mungkin tidak dipertahankan dengan versi Ekstensi pra-rilis sebelum rilis platform Android triwulanan atau tahunan yang sesuai dengan versi yang diselesaikan. Riwayat lengkap Extensions API dapat ditemukan di cabang rilis window:extensions:extensions API text files .

Versi Ekstensi yang lebih baru harus terus bekerja dengan versi WindowManager yang lebih lama yang dikompilasi ke dalam aplikasi untuk menjaga kompatibilitas ke depan. Untuk memastikan hal ini, setiap versi baru dari Extensions API hanya menambahkan API baru dan tidak menghapus API lama. Hasilnya, aplikasi dengan versi WindowManager yang lebih lama dapat terus menggunakan Extensions API yang lebih lama yang menjadi dasar kompilasi aplikasi tersebut.

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

Pertunjukan

Modul Extensions di-cache di pemuat kelas sistem non-bootclasspath secara default dimulai dengan Android 14 (API level 34), sehingga tidak ada dampak performa karena memuat modul ke memori saat startup aplikasi. Penggunaan fitur modul individual mungkin memiliki sedikit pengaruh pada karakteristik kinerja aplikasi ketika panggilan IPC tambahan dilakukan antara klien dan server.

Modul

Penyematan aktivitas

Komponen Penyematan aktivitas menyediakan serangkaian fitur yang memungkinkan aplikasi mengatur presentasi jendela aktivitas dalam batas-batas aplikasi induk. Hal ini termasuk menampilkan dua aktivitas secara bersamaan secara berdampingan dalam tata letak multipanel, sehingga memfasilitasi optimalisasi layar besar untuk aplikasi lama.

Komponen penyematan aktivitas harus tersedia di semua perangkat yang memiliki layar bawaan dengan ukuran sama atau lebih besar dari sw600 dp . Penyematan aktivitas juga harus diaktifkan pada perangkat yang mendukung koneksi layar eksternal, karena aplikasi mungkin ditampilkan dalam ukuran yang lebih besar ketika layar eksternal tersambung pada waktu proses.

Konfigurasi perangkat

Tidak diperlukan konfigurasi perangkat khusus selain mengaktifkan modul Ekstensi seperti yang dijelaskan di bagian distribusi modul Ekstensi . Masuk akal untuk mengaktifkan Ekstensi di semua perangkat yang mendukung mode multijendela. Versi Android masa depan kemungkinan besar 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 yang dapat dilipat ketika engsel melintasi jendela aplikasi. Informasi tata letak jendela memungkinkan aplikasi merespons dan menampilkan tata letak yang dioptimalkan dalam mode meja pada perangkat lipat. Lihat Membuat aplikasi Anda terlipat untuk mengetahui detail penggunaan.

Perangkat Android yang dapat dilipat yang dilengkapi engsel yang menghubungkan area panel layar terpisah atau berkelanjutan harus membuat informasi tentang engsel tersedia 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, DisplayFeature engsel tidak boleh dilaporkan. Hal ini juga dapat diterima untuk tidak melaporkan fitur tampilan ketika posisinya mungkin tidak dilaporkan secara andal, misalnya ketika jendela aplikasi dapat dipindahkan dengan bebas oleh pengguna dalam mode multi-jendela atau mode letterboxing kompatibilitas.

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

• Konfigurasikan status perangkat di device_state_configuration.xml untuk digunakan oleh DeviceStateManagerService . Lihat DeviceStateProviderImpl.java untuk referensi.

  Jika implementasi default DeviceStateProvider atau DeviceStatePolicy tidak cocok untuk perangkat, implementasi kustom dapat digunakan.

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

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

  Format yang diharapkan untuk string tersebut adalah:

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

  type bisa 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 oleh titik koma.

  Misalnya:

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

• Tentukan pemetaan antara pengidentifikasi status perangkat internal yang digunakan di DeviceStateManager dan konstanta status publik yang dikirim ke pengembang 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>

  Pengidentifikasi negara bagian yang didukung adalah:

  • COMMON_STATE_NO_FOLDING_FEATURES = 1 : Negara bagian tidak memiliki fitur lipat untuk dilaporkan. Misalnya, keadaan tertutup dari perangkat lipat pada umumnya dengan layar utama di sisi dalam.
  • COMMON_STATE_HALF_OPENED = 2 : Fitur pelipatan terbuka setengah.
  • COMMON_STATE_FLAT = 3 : Fitur lipatnya datar. Misalnya, keadaan terbuka dari perangkat lipat pada umumnya dengan layar utama di sisi dalam.
  • COMMON_STATE_USE_BASE_STATE = 1000 : Di Android 14, nilai yang dapat digunakan untuk status emulasi yang mana status engsel diturunkan menggunakan status dasar, seperti yang ditentukan di CommonFoldingFeature.java

  Lihat DeviceStateManager.DeviceStateCallback#onBaseStateChanged(int) untuk informasi selengkapnya.

  Misalnya:

  <!-- 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>
  

Daerah jendela

Komponen area jendela menyediakan serangkaian fitur yang memberi aplikasi akses ke tampilan tambahan dan area tampilan di beberapa perangkat yang dapat dilipat dan multilayar.

Mode tampilan belakang memungkinkan aplikasi menampilkan UI pratinjau kamera pada tampilan sampul perangkat yang dapat dilipat untuk memungkinkan penggunaan kamera perangkat utama untuk selfie dan video. Perangkat yang memiliki tampilan sampul yang kompatibel dengan Android (sebagaimana didefinisikan 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 tampilan belakang.

Di Android 14, mode tampilan ganda memungkinkan aplikasi yang berjalan di layar bagian dalam perangkat yang dapat dilipat menampilkan konten tambahan di layar sampul menghadap 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:

• Konfigurasikan status perangkat di device_state_configuration.xml untuk digunakan oleh DeviceStateManagerService . Lihat DeviceStateProviderImpl.java untuk informasi lebih lanjut.

  Jika implementasi default DeviceStateProvider atau DeviceStatePolicy tidak cocok untuk perangkat, implementasi kustom dapat digunakan.

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

• Untuk perangkat lipat yang mendukung status terlipat, cantumkan pengidentifikasi status terkait di com.android.internal.R.array.config_foldedDeviceStates .

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

• Untuk perangkat yang mendukung mode tampilan belakang:

  • Cantumkan status terkait di com.android.internal.R.array.config_rearDisplayDeviceStates untuk DeviceStateManager .
  • Tentukan alamat tampilan fisik tampilan belakang di com.android.internal.R.string.config_rearDisplayPhysicalAddress .
  • Tentukan pengidentifikasi status di com.android.internal.R.integer.config_deviceStateRearDisplay untuk digunakan oleh Ekstensi.
  • Tambahkan pengidentifikasi status di com.android.internal.R.array.config_deviceStatesAvailableForAppRequests agar tersedia untuk aplikasi.

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

  • Setel com.android.internal.R.bool.config_supportsConcurrentInternalDisplays ke true .
  • Tentukan alamat tampilan fisik tampilan belakang di com.android.internal.R.config_deviceStateConcurrentRearDisplay .
  • Tentukan pengidentifikasi status di com.android.internal.R.integer.config_deviceStateConcurrentRearDisplay untuk digunakan oleh Extensions jika pengidentifikasi dimaksudkan agar tersedia untuk aplikasi.
  • Tambahkan pengidentifikasi status di com.android.internal.R.array.config_deviceStatesAvailableForAppRequests agar tersedia untuk aplikasi.

Verifikasi

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

tes CTS

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

Tes WindowManager

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

Untuk menjalankan pengujian perangkat untuk modul window:window dari baris perintah, lakukan hal berikut:

1. Hubungkan perangkat yang memiliki opsi pengembang dan debugging USB diaktifkan.
2. Izinkan komputer untuk men-debug perangkat.
3. Buka shell di direktori root repositori androidx.
4. Ubah direktori menjadi 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. Hubungkan perangkat yang memiliki opsi pengembang dan debugging USB diaktifkan.
3. Izinkan komputer untuk men-debug perangkat.
4. Navigasikan ke pengujian dalam pustaka jendela modul jendela.
5. Buka kelas pengujian dan jalankan menggunakan panah hijau di sisi kanan editor.

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

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