Ekstensi WindowManager

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 dalam gambar:

Gambar 1. Ekstensi WindowManager dimuat ke dalam aplikasi proses yang mirip dengan kode platform.

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.

Gambar 2. Pohon keputusan untuk mengakses 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 ditujukan 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 secara langsung; 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 publik untuk developer, termasuk untuk fitur Ekstensi WindowManager. Library WindowManager secara otomatis memuat Ekstensi ke dalam proses aplikasi dan menggabungkan Ekstensi tingkat rendah Memperluas API ke dalam abstraksi yang lebih tinggi dan lebih terfokus 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 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 dalam Bagian Distribusi modul ekstensi.

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

    Format yang diharapkan untuk string ini adalah:

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

    type dapat berupa fold atau hinge. Nilai untuk left, top, right dan bottom 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 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 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 yang 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 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 oleh DeviceStateManagerService. Lihat DeviceStateProviderImpl.java untuk informasi selengkapnya.

    Jika implementasi {i>default<i} dari DeviceStateProvider atau DeviceStatePolicy 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 untuk DeviceStateManager.
    • 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.

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

    • Setel com.android.internal.R.bool.config_supportsConcurrentInternalDisplays ke true.
    • 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.

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:

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

Untuk menjalankan pengujian dari Android Studio, lakukan hal berikut:

  1. Buka Android Studio.
  2. Colokkan perangkat yang mengaktifkan opsi developer dan Proses debug USB.
  3. Izinkan komputer untuk men-debug perangkat.
  4. Buka pengujian dalam library jendela di modul jendela.
  5. 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.