Halaman ini diterjemahkan oleh Cloud Translation API.

Mode kompatibilitas perangkat

Android mengaktifkan mode kompatibilitas untuk aplikasi yang mendeklarasikan batasan orientasi atau kemampuan mengubah ukuran. Mode kompatibilitas memastikan perilaku aplikasi yang dapat diterima di perangkat layar besar dan ponsel flip foldable, tetapi dengan kegunaan yang kurang optimal.

Penggantian per aplikasi memungkinkan produsen perangkat mengubah perilaku aplikasi untuk meningkatkan pengalaman pengguna atau mencegah aplikasi agar tidak rusak di perangkat tertentu.

Perangkat referensi

Perangkat berikut mungkin memerlukan penggantian per aplikasi karena konfigurasi yang tidak biasa atau konfigurasi yang tidak didukung dengan baik oleh aplikasi:

Tablet: Orientasi alami beberapa tablet, seperti Pixel Tablet, adalah lanskap. Perangkat dalam orientasi alami saat Display#getRotation() menampilkan Surface.ROTATION_0. Jika aplikasi mengasumsikan ROTATION_0 adalah potret, tata letak aplikasi dan pratinjau kamera dapat tidak cocok dengan tampilan perangkat.
Perangkat foldable lanskap: Beberapa perangkat foldable, seperti Pixel Fold, berada dalam orientasi potret saat dilipat, tetapi orientasi lanskap saat dibentangkan. Jika aplikasi mengasumsikan orientasi yang dibentangkan adalah potret, kemungkinan akan terjadi loop berkedip atau masalah tata letak.
Ponsel lipat foldable: Ponsel lipat yang tidak dilipat biasanya dalam orientasi potret. Namun, saat dilipat, ponsel biasanya memiliki layar kecil dalam orientasi lanskap. Aplikasi harus mengidentifikasi dan mengakomodasi berbagai orientasi layar.

Masalah kompatibilitas umum

Aplikasi sering mengalami masalah kompatibilitas karena batasan orientasi aplikasi, batasan perubahan ukuran dan rasio aspek, penanganan orientasi pratinjau kamera yang salah, dan API yang disalahgunakan.

Tampilan Lebar

Tampilan lebar memosisikan aplikasi di bagian tengah layar atau pada satu sisi atau sisi lainnya di layar besar untuk memudahkan akses. Matte (kolom berwarna solid atau wallpaper buram) mengisi area tampilan yang tidak digunakan di sepanjang sisi atau bagian atas dan bawah aplikasi.

Tampilan lebar sering terjadi di perangkat layar besar karena dimensi dan rasio aspek layar perangkat biasanya berbeda dengan ponsel standar, yang menjadi acuan rancangan sebagian besar aplikasi.

Gambar 1. Aplikasi yang dibatasi untuk orientasi potret memiliki tampilan lebar pada tablet lanskap dan perangkat foldable.

Masalah

Aplikasi tidak mendukung semua konfigurasi tampilan karena aplikasi tersebut memiliki orientasi tetap, rasio aspek tetap, atau tidak dapat diubah ukurannya.

Setelan konfigurasi yang mengontrol orientasi dan respons aplikasi meliputi hal berikut:

screenOrientation: Menentukan orientasi tetap untuk aplikasi. Aplikasi juga dapat menetapkan orientasi pada runtime dengan menggunakan Activity#setRequestedOrientation().
resizeableActivity: Menunjukkan apakah sistem dapat mengubah ukuran aplikasi agar sesuai dengan jendela dalam berbagai dimensi. Di Android 11 (level API 30) dan yang lebih rendah, menentukan apakah aplikasi mendukung mode multi-aplikasi. Di Android 12 (level API 31) dan yang lebih tinggi, menentukan apakah aplikasi mendukung mode multi-aplikasi di layar kecil (class ukuran jendela yang ringkas). Di Android 12 dan yang lebih tinggi, aplikasi mendukung mode multi-aplikasi di perangkat layar besar (class ukuran jendela sedang atau diperluas), terlepas dari setelan ini.
maxAspectRatio: Menentukan rasio aspek maksimum yang didukung oleh aplikasi. Hanya aplikasi dengan resizeableActivity yang ditetapkan ke false yang dapat menetapkan maxAspectRatio.
minAspectRatio: Menentukan rasio aspek minimum yang didukung oleh aplikasi. Hanya aplikasi dengan resizeableActivity yang ditetapkan ke false yang dapat menetapkan minAspectRatio.

Aplikasi yang dibatasi untuk orientasi potret saja tidak dapat digunakan di perangkat lanskap.

Pengoptimalan

Aplikasi harus mendukung semua ukuran dan orientasi tampilan mode multi-aplikasi serta perangkat. Hapus semua batasan rasio aspek tetap dan orientasi dari tata letak aplikasi dan file manifes aplikasi Anda.

Aplikasi mendukung semua orientasi perangkat.

Solusi kompatibilitas

Jika aplikasi dengan orientasi tetap atau rasio aspek tetap berjalan di jendela tempat aplikasi tidak secara langsung mendukung ukuran atau orientasi jendela, Android akan menampilkan aplikasi dengan tampilan lebar untuk mempertahankan kontinuitas.

Mulai Android 12 (API level 31) dan berlanjut dengan 12L (API level 32), platform ini menerapkan berbagai peningkatan untuk aplikasi dengan tampilan lebar. Produsen perangkat menerapkan peningkatan UI. Anda tidak perlu melakukan pengembangan tambahan agar aplikasi dapat memanfaatkan peningkatan ini.

Android 12 (level API 31) memperkenalkan peningkatan estetika berikut, yang dapat dikonfigurasi oleh produsen perangkat:

Sudut bulat: Sudut jendela aplikasi memiliki tampilan yang lebih sempurna.
Transparansi kolom sistem: Status dan menu navigasi, yang menempatkan aplikasi, bersifat semi-transparan sehingga ikon pada menu selalu terlihat di latar belakang tampilan lebar.
Rasio aspek yang dapat dikonfigurasi: Rasio aspek aplikasi dapat disesuaikan untuk meningkatkan tampilan aplikasi.

Gambar 2. Aplikasi tampilan lebar dengan peningkatan UI.

12L (level API 32) menambahkan peningkatan fungsional berikut:

Posisi yang dapat dikonfigurasi: Di layar besar, produsen perangkat dapat memosisikan aplikasi ke sisi kiri atau kanan layar, sehingga interaksi menjadi lebih mudah.
Tombol mulai ulang yang didesain ulang: Produsen perangkat dapat memberikan tombol mulai ulang untuk tampilan baru mode kompatibilitas ukuran agar pengguna mendapatkan pengenalan yang lebih baik.

Android 13 (level API 33) menambahkan dialog edukasi pengguna tentang pemosisian aplikasi dengan tampilan lebar di layar atau menyertakan tampilan lebar dalam mode layar terpisah:

Gambar 3. Aplikasi tampilan lebar dengan dialog edukasi pengguna.

Mode kompatibilitas ukuran

Mode kompatibilitas ukuran adalah tampilan lebar yang menyertakan kontrol mulai ulang. Kontrol ini memungkinkan pengguna memulai ulang aplikasi dan menggambar ulang tampilan. Android memanggil mode kompatibilitas ukuran untuk aplikasi yang ditentukan untuk tidak dapat diubah ukurannya. Saat aktivitas berpindah ke penampung tampilan yang tidak kompatibel dengan dimensi aktivitas, sistem dapat menskalakan ulang aplikasi untuk mengisi layar perangkat dalam setidaknya satu dimensi.

Perubahan konfigurasi perangkat yang dapat memicu mode kompatibilitas ukuran mencakup hal berikut:

Rotasi perangkat
Melipat atau membuka lipatan perangkat foldable
Beralih antara mode tampilan layar penuh dan layar terpisah

Masalah

Mode kompatibilitas ukuran biasanya berlaku untuk aktivitas yang dibatasi dalam orientasi atau rasio aspek, dan dikonfigurasi (atau ditentukan oleh sistem) agar tidak dapat diubah ukurannya.

Aplikasi Anda dianggap dapat diubah ukurannya—dan tidak akan ditempatkan dalam mode kompatibilitas ukuran—jika memenuhi salah satu kriteria berikut:

Dapat diubah ukurannya dengan resizeableActivity="true"
Mendukung mode picture-in-picture (PIP)
Disematkan
Memiliki penggantian per aplikasi FORCE_RESIZE_APP yang diterapkan oleh produsen perangkat (properti yang ditetapkan oleh aplikasi diabaikan)

Jika aplikasi Anda tidak memenuhi salah satu kondisi tersebut, aplikasi dianggap tidak dapat diubah ukurannya dan dapat ditempatkan dalam mode kompatibilitas ukuran.

Aplikasi yang tidak dapat diubah ukurannya mengalami error dalam mode multi-aplikasi.

Pengoptimalan

Aplikasi harus mendukung semua ukuran tampilan. Buat aplikasi Anda dapat diubah ukurannya dengan menetapkan atribut android:resizeableActivity dari elemen <activity> atau <application> ke true di manifes aplikasi. Desain tata letak responsif/adaptif untuk aplikasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mendukung berbagai ukuran tampilan dan Mendukung mode multi-aplikasi.

Aplikasi berfungsi di semua ukuran jendela.

Solusi kompatibilitas

Android menempatkan aplikasi dalam mode kompatibilitas ukuran saat sistem menentukan tampilan aplikasi tampilan lebar dapat ditingkatkan dengan mengubah skala aplikasi untuk mengisi jendela tampilan dalam setidaknya satu dimensi. Sistem menampilkan kontrol mulai ulang yang membuat ulang proses aplikasi, membuat ulang aktivitas, dan menggambar ulang tampilan. Lihat juga Ringkasan proses dan thread.

Aplikasi khusus potret dengan tampilan lebar dalam orientasi lanskap diubah skalanya dengan kontrol mulai ulang.

Loop berkedip

Jika tidak mendukung semua orientasi layar, aplikasi mungkin berulang kali meminta orientasi baru saat terjadi perubahan konfigurasi, sehingga menghasilkan loop terus-menerus yang membuat layar berkedip atau aplikasi berputar tanpa henti.

Masalah

Di Android 12 (level API 31) dan yang lebih tinggi, produsen perangkat dapat mengonfigurasi perangkat mereka untuk mengabaikan batasan orientasi yang ditentukan aplikasi, dan sebagai gantinya menerapkan mode kompatibilitas. Misalnya, perangkat foldable dapat mengabaikan setelan android:screenOrientation="portrait" aktivitas saat aktivitas ditampilkan di layar dalam seukuran tablet lanskap pada perangkat.

Jika batasan orientasi aplikasi diabaikan, aplikasi dapat menetapkan orientasinya secara terprogram dengan memanggil Activity#setRequestedOrientation(). Panggilan memicu mulai ulang aplikasi jika aplikasi tidak menangani perubahan konfigurasi (lihat Menangani perubahan konfigurasi). Setelah mulai ulang, batasan orientasi aplikasi akan diabaikan lagi, aplikasi akan mengulangi panggilan ke setRequestedOrientation(), panggilan akan memicu mulai ulang aplikasi, dan seterusnya dalam loop yang terus-menerus berlangsung.

Cara lain yang mungkin Anda lihat adalah saat orientasi alami (orientasi biasa seperti yang ditentukan oleh Android) layar perangkat adalah lanskap (yaitu, memanggil Display#getRotation() menampilkan Surface.ROTATION_0 saat perangkat memiliki rasio aspek lanskap). Secara historis, aplikasi mengasumsikan bahwa Display.getRotation() = Surface.ROTATION_0 berarti perangkat dalam orientasi potret, tetapi tidak selalu demikian, misalnya, di layar dalam beberapa perangkat foldable dan di beberapa tablet.

Aplikasi dalam orientasi lanskap di layar dalam perangkat foldable dapat memeriksa rotasi layar, menerima nilai ROTATION_0, mengasumsikan bahwa orientasi alami perangkat adalah potret, dan memanggil setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT ) untuk mengonfigurasi ulang tata letak aplikasi. Setelah dimulai ulang (dalam orientasi lanskap), aplikasi dapat memeriksa kembali rotasi layar, menerima nilai ROTATION_0, memanggil setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT), dan melanjutkan loop tanpa batas.

Aplikasi khusus lanskap pada tampilan potret melakukan panggilan berulang ke `Activity#setRequestedOrientation()`.

Pengoptimalan

Aplikasi tidak boleh melakukan hal berikut:

Setel orientasi default dengan Activity#setRequestedOrientation() dalam metode onCreate() aktivitas karena permintaan orientasi dapat dipicu secara tidak terduga oleh perubahan konfigurasi yang tidak tertangani
Asumsikan bahwa orientasi alami perangkat (ROTATION_0) adalah potret
Setel orientasi berdasarkan sinyal yang tidak terkait dengan ukuran jendela saat ini seperti Display#getRotation(), keberadaan FoldingFeature, atau API yang tidak digunakan lagi.

Aplikasi menangani perubahan konfigurasi, tidak memiliki batasan orientasi, sehingga tidak memasuki loop yang berkedip.

Solusi kompatibilitas

Android mengabaikan panggilan ke Activity#setRequestedOrientation() dalam situasi berikut:

Aktivitas telah diluncurkan kembali dari panggilan sebelumnya ke metode, atau perlakuan putar paksa kompatibilitas kamera telah diaktifkan (lihat Pratinjau kamera di bawah).

Produsen perangkat dapat menerapkan perilaku ini ke aplikasi dengan OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION.
Aktivitas ini membuat lebih dari dua permintaan orientasi dalam satu detik, yang menunjukkan adanya loop. Dari dua permintaan dalam loop, Android menggunakan permintaan yang memaksimalkan area tampilan aplikasi.

Produsen perangkat dapat menerapkan perilaku ini ke aplikasi dengan OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED.

Pratinjau kamera

Pratinjau kamera (atau jendela bidik) aplikasi kamera mungkin tidak selaras atau terdistorsi di tablet, laptop, dan layar perangkat foldable.

Masalah

Android Compatibility Definition Document menyatakan bahwa sensor gambar kamera "HARUS diorientasikan sehingga dimensi panjang kamera sejajar dengan dimensi panjang layar".

Aplikasi sering kali mengasumsikan bahwa orientasi perangkat dan orientasi sensor kamera adalah potret—asumsi yang wajar pada ponsel standar. Namun, orientasi alami tablet dan laptop beserta sensor kameranya dapat berupa lanskap. Selain itu, faktor bentuk baru seperti perangkat foldable dapat memiliki beberapa orientasi alam dan beberapa sensor kamera dalam berbagai orientasi.

Memulai aktivitas dengan orientasi kamera yang tidak diharapkan aplikasi atau beralih antara kamera atau layar perangkat yang berbeda (untuk perangkat foldable) dapat menyebabkan pratinjau kamera yang tidak selaras atau terdistorsi.

Pratinjau kamera yang tidak selaras dan terdistorsi pada perangkat foldable layar besar.

Pengoptimalan

Aplikasi kamera harus mengidentifikasi dan mengelola orientasi perangkat serta orientasi sensor kamera dengan benar untuk menampilkan pratinjau kamera yang diselaraskan dan diskalakan dengan benar. Aplikasi harus menghitung rotasi perangkat, rotasi sensor, dan rasio aspek layar atau jendela, lalu menerapkan hasilnya ke pratinjau kamera. Untuk panduan mendetail, lihat Pratinjau kamera dan Memperkenalkan Jendela Bidik Kamera.

Pratinjau kamera diselaraskan dan diskalakan dengan benar di semua orientasi perangkat.

Solusi kompatibilitas

Perangkat dalam orientasi alami saat Display#getRotation() menampilkan Surface.ROTATION_0. Sistem menghitung CameraCharacteristics.SENSOR_ORIENTATION dari orientasi alami perangkat. Android menyejajarkan jendela potret aplikasi yang dibatasi untuk potret dengan orientasi alami perangkat, yang diharapkan oleh sebagian besar aplikasi. Android juga memangkas gambar sensor kamera saat orientasi sensornya adalah lanskap dan pratinjau kamera adalah potret. Solusi khusus meliputi hal berikut:

Paksa putar pratinjau kamera bagi aplikasi yang dibatasi untuk potret: Aplikasi yang dibatasi untuk orientasi potret mengharapkan orientasi alami perangkat dan orientasi sensor kamera adalah potret. Namun, di Android 12 (level API 31) dan yang lebih tinggi, aplikasi dapat berjalan di beberapa orientasi perangkat jika produsen perangkat mengabaikan spesifikasi orientasi.

Saat aplikasi yang dibatasi untuk potret terhubung ke kamera, Android akan memutar paksa aplikasi untuk menyejajarkan jendela potret aplikasi dengan orientasi alami perangkat.

Di beberapa tablet (lihat perangkat referensi), jendela potret aplikasi diputar ke potret layar penuh agar selaras dengan orientasi alami perangkat. Aplikasi menempati layar penuh setelah diputar paksa.

Tablet — Memutar paksa aplikasi yang dibatasi untuk potret.

Di layar dalam lanskap perangkat foldable (lihat perangkat referensi), aktivitas khusus potret diputar ke lanskap agar selaras dengan orientasi alami yang dibentangkan. Aplikasi memiliki tampilan lebar setelah diputar paksa.

Perangkat foldable — Memutar paksa aplikasi yang dibatasi untuk potret. Aplikasi ini juga memiliki tampilan lebar.

Catatan: Pemutaran paksa tidak terjadi jika aplikasi Anda responsif dan menangani orientasi potret dan lanskap.
Pemangkasan kamera depan bagian dalam: Sensor kamera depan bagian dalam di beberapa perangkat foldable berada dalam orientasi lanskap. Selain memutar paksa pratinjau kamera di layar dalam perangkat foldable, Android memangkas ruang pandang kamera depan (lanskap) internal sehingga sensor menangkap tampilan yang berlawanan dengan orientasi perangkat.
Muat ulang paksa pratinjau kamera: Sistem melakukan siklus melalui metode aktivitas onStop() dan onStart() (secara default) atau onPause() dan onResume() (diterapkan oleh penggantian OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE per aplikasi) setelah pemutaran paksa untuk memastikan pratinjau kamera ditampilkan dengan benar.
Penskalaan rasio aspek: Sistem secara dinamis mengubah rasio aspek pratinjau kamera yang diputar paksa menjadi rasio aspek minimum yang lebih tinggi, yang memastikan pratinjau kamera diskalakan dengan benar.

Developer aplikasi dapat mengganti solusi ini jika aplikasi menangani pratinjau kamera dengan benar. Lihat Penggantian per aplikasi.

API yang sering disalahgunakan

Karena Android telah menambahkan dukungan untuk fitur seperti mode multi-aplikasi dan perangkat seperti perangkat foldable, API lama tidak digunakan lagi dan diganti dengan API terbaru yang berfungsi untuk semua ukuran layar dan faktor bentuk perangkat. Namun, API yang tidak digunakan lagi masih tersedia untuk kompatibilitas mundur.

Beberapa View API dirancang untuk tujuan khusus yang tidak selalu dipahami dengan baik oleh developer.

Masalah

Developer terus menggunakan Display API yang tidak digunakan lagi dan salah menganggap API menampilkan batas aplikasi, bukan batas area tampilan perangkat. Atau, developer salah menggunakan API tampilan tujuan khusus untuk mendapatkan metrik tampilan umum. Hasilnya adalah kesalahan penghitungan saat memosisikan ulang elemen UI setelah peristiwa pengubahan ukuran jendela aplikasi, sehingga menyebabkan masalah tata letak.

Display API yang tidak digunakan lagi dan umumnya disalahgunakan:

Untuk mengetahui informasi selengkapnya, lihat Mendukung mode multi-aplikasi.

View API yang disalahgunakan:

API yang tidak digunakan lagi salah menghitung batas aplikasi. Konten aplikasi dinonaktifkan di layar.

Pengoptimalan

Jangan pernah mengandalkan ukuran tampilan fisik untuk memosisikan elemen UI. Migrasikan aplikasi Anda ke API berdasarkan WindowMetrics, termasuk WindowManager API berikut:

API menghitung metrik jendela aplikasi dengan benar.

Solusi kompatibilitas

Dua penggantian menyesuaikan Display API yang tidak digunakan lagi dan View API yang disalahgunakan untuk menampilkan batas aplikasi: ALWAYS_SANDBOX_DISPLAY_APIS untuk Display API; OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS untuk View API. ALWAYS_SANDBOX_DISPLAY_APIS juga diterapkan secara default untuk aplikasi yang memenuhi syarat untuk mode kompatibilitas ukuran.

Aktivitas yang transparan

Aktivitas yang transparan adalah hasil dari gaya latar belakang transparan, misalnya:

<style name="Transparent" parent="AppTheme">
    <item name="android:windowIsTranslucent">true</item>
    <item name="android:windowBackground">@android:color/transparent</item>
</style>

Tema terkait dialog, seperti Theme.MaterialComponents.Dialog, dapat menyertakan gaya yang membuat aktivitas transparan.

Aktivitas transparan tidak mencakup semua ruang tampilan yang tersedia, sehingga sulit dikelola karena area tampilan yang tersedia dapat berubah berdasarkan perubahan konfigurasi seperti rotasi perangkat, perangkat dilipat dan dibentangkan, serta mode multi-aplikasi.

Masalah

Aktivitas transparan harus sesuai dengan batas aktivitas buram pertama di bawah aktivitas transparan dalam tumpukan aktivitas tugas. Namun, aktivitas buram yang meluncurkan dialog izin dapat berupa trampolin (aktivitas yang meluncurkan aktivitas lain, lalu menghilang); sehingga sistem tidak dapat menentukan batas aktivitas trampolin yang meluncurkan aktivitas dialog izin transparan.

Dialog salah ditempatkan karena aktivitas diluncurkan dari trampolin.

Pengoptimalan

Aktivitas transparan mewarisi batasannya dari aktivitas buram paling atas di bawahnya dalam tumpukan aktivitas tugas. Aktivitas buram harus tersedia untuk seluruh siklus proses aktivitas transparan, dari pembuatan aktivitas hingga penghancuran. Oleh karena itu, jangan luncurkan permintaan izin dari aktivitas trampolin.

Jika aktivitas trampolin meluncurkan permintaan izin, pengguna mungkin tidak dapat melihat dialog izin karena aktivitas trampolin akan dihancurkan sebelum pengguna memiliki kesempatan untuk merespons dialog, dan dimensi serta posisi aktivitas dialog mungkin telah dihitung secara tidak benar.

Aplikasi harus selalu meluncurkan permintaan izin dari aktivitas yang tetap terlihat sampai pengguna membuat keputusan izin.

Sudut membulat

Aktivitas dapat menjadi transparan karena gaya yang menentukan transparansi latar belakang atau karena konten aktivitas tidak mengisi ruang tampilan yang tersedia. Jika aktivitas transparan mengisi ruang tampilan yang tersedia, sistem akan secara otomatis menerapkan sudut membulat ke aktivitas tersebut jika dikonfigurasi demikian oleh produsen perangkat. Namun, jika aktivitas transparan (seperti dialog izin) tidak mengisi ruang yang tersedia, Anda dapat memutuskan apakah akan menerapkan sudut membulat atau tidak.

Dialog izin tidak mengisi ruang tampilan yang tersedia karena tata letak dialog biasanya menggunakan LayoutParams.WRAP_CONTENT, bukan LayoutParams.MATCH_PARENT.

Dialog dengan sudut membulat diposisikan dengan benar di atas aktivitas peluncuran yang terlihat.

Solusi kompatibilitas

Tetap tampilkan aktivitas yang meluncurkan aktivitas dialog hingga pengguna merespons dialog tersebut.

Sistem memastikan aktivitas transparan mewarisi semua batasan dari aktivitas buram pertama di bawah aktivitas transparan dalam tumpukan aktivitas, termasuk batasan yang terkait dengan:

Mode kompatibilitas ukuran
Orientasi
Rasio Aspek

Game Unity

Game Unity berjalan di layar penuh Android atau dalam mode multi-aplikasi. Namun, banyak game Unity kehilangan fokus dan berhenti menggambar konten saat aplikasi ditempatkan dalam mode multi-aplikasi.

Masalah

Unity menambahkan opsi Resizable Window di Unity 2019.4 untuk mendukung mode multi-aplikasi di Android. Namun, implementasi awal tidak bereaksi terhadap siklus proses aktivitas dalam mode multi-aplikasi dengan benar, sehingga menyebabkan UnityPlayer menangguhkan pemutaran saat aplikasi kehilangan fokus. Pemain merender layar gelap atau periode frozen terakhir di game. Gameplay dilanjutkan hanya saat pengguna mengetuk layar. Banyak aplikasi yang menggunakan mesin Unity menghadapi masalah ini dan merender sebagai jendela gelap dalam mode multi-aplikasi.

Game kehilangan fokus dalam mode multi-aplikasi dan merender sebagai jendela gelap.

Pengoptimalan

Upgrade Unity ke versi 2019.4.40 atau yang lebih baru, lalu ekspor ulang game Anda. Biarkan opsi Resizable Window tetap dicentang di setelan Android Player. Jika tidak, game akan dijeda saat tidak dalam fokus, meskipun game sepenuhnya terlihat dalam mode multi-aplikasi.

Game merender konten dengan benar dalam mode multi-aplikasi bahkan saat tidak dalam fokus.

Solusi kompatibilitas

Produsen perangkat dapat menerapkan penggantian per aplikasi OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS untuk memberikan peristiwa fokus palsu ke aplikasi dalam mode multi-aplikasi. Penggantian memungkinkan aktivitas menggambar ulang konten dan tidak berhenti berfungsi.

Uji aplikasi Anda untuk menemukan masalah kompatibilitas

Untuk menguji aplikasi Anda dan memahami perilakunya pada berbagai faktor bentuk, manfaatkan referensi berikut:

Streaming perangkat: Untuk menguji aplikasi Anda di perangkat produksi (termasuk perangkat referensi) yang dihosting di pusat data Google, lihat Streaming Perangkat Android, yang didukung oleh Firebase
Emulator di Android Studio Hedgehog: Untuk mengetahui informasi tentang cara membuat emulator untuk perangkat referensi, lihat Membuat dan mengelola perangkat virtual
Emulator Android Studio yang dapat diubah ukurannya: Untuk informasi tentang cara mengakses perangkat virtual, lihat Menjalankan aplikasi di Android Emulator

Memiliki tampilan lebar

Pastikan setiap aktivitas bisa menggunakan semua ruang layar yang tersedia untuk aplikasi. Pertama, deklarasikan kode berikut di folder pengujian Anda:

Kotlin

fun Activity.isLetterboxed() : Boolean {
    if (isInMultiWindowMode) return false

    val wmc = WindowMetricsCalculator.getOrCreate()
    val currentBounds = wmc.computeCurrentWindowMetrics(this).bounds
    val maxBounds = wmc.computeMaximumWindowMetrics(this).bounds

    val isScreenPortrait = maxBounds.height() > maxBounds.width()

    return if (isScreenPortrait) {
        currentBounds.height() < maxBounds.height()
    } else {
        currentBounds.width() < maxBounds.width()
    }
}

Java

public boolean isLetterboxed(Activity activity) {
    if (activity.isInMultiWindowMode()) {
        return false;
    }

    WindowMetricsCalculator wmc = WindowMetricsCalculator.getOrCreate();
    Rect currentBounds = wmc.computeCurrentWindowMetrics(activity).getBounds()
    Rect maxBounds = wmc.computeMaximumWindowMetrics(activity).getBounds();

    boolean isScreenPortrait = maxBounds.height() > maxBounds.width();

    return (isScreenPortrait)
        ? currentBounds.height() < maxBounds.height()
        : currentBounds.width() < maxBounds.width();
}

Kemudian, jalankan pengujian untuk menyatakan perilaku dan pastikan aktivitas target tidak menjadi tampilan lebar:

Kotlin

@get:Rule
val activityRule = ActivityScenarioRule(MainActivity::class.java)

@Test
fun activity_launched_notLetterBoxed() {
    activityRule.scenario.onActivity {
        assertThat(it.isLetterboxed()).isFalse()
    }
}

Java

@Rule
public ActivityScenarioRule<MainActivity> rule = new ActivityScenarioRule<>(MainActivity.class);

public void activity_launched_notLetterBoxed() {
    try (ActivityScenario<MainActivity> scenario = ActivityScenario.launch(MainActivity.class)) {
        scenario.onActivity(activity -> {
            assertThat(isLetterboxed(activity)).isFalse();
        });
    }
}

Idealnya, jalankan pengujian semacam ini hanya sampai lulus dan nyatakan bahwa aktivitas aplikasi Anda menggunakan seluruh ruang layar yang tersedia untuk aplikasi. Uji aplikasi Anda di semua jenis perangkat untuk memastikan perilaku yang konsisten.

Penggantian per aplikasi

Android menyediakan penggantian yang mengubah perilaku aplikasi yang dikonfigurasi. Misalnya, penggantian FORCE_RESIZE_APP menginstruksikan sistem untuk mengabaikan mode kompatibilitas ukuran dan mengubah ukuran aplikasi agar sesuai dengan dimensi tampilan meskipun resizeableActivity="false" ditentukan dalam manifes aplikasi.

Produsen perangkat menerapkan penggantian untuk aplikasi tertentu—atau semua aplikasi—di perangkat layar besar tertentu. Di Android 14 (API level 34) dan yang lebih tinggi, pengguna dapat menerapkan penggantian ke aplikasi melalui setelan perangkat.

Penggantian per aplikasi pengguna

Di Android 14 dan yang lebih baru, menu setelan memungkinkan pengguna mengubah rasio aspek aplikasi. Perangkat layar besar seperti perangkat referensi menerapkan menu.

Menu ini berisi daftar semua aplikasi yang diinstal di perangkat. Pengguna memilih aplikasi, lalu menetapkan rasio aspek aplikasi ke 3:4, 1:1, layar penuh, atau nilai lain yang dikonfigurasi oleh produsen perangkat. Pengguna juga dapat mereset rasio aspek ke default aplikasi, yang ditentukan dalam manifes aplikasi.

Aplikasi dapat memilih untuk tidak menggunakan penggantian kompatibilitas dengan menetapkan tag PackageManager.Property berikut:

PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE

Untuk memilih tidak menggunakan penggantian kompatibilitas rasio aspek pengguna, tambahkan properti ke manifes aplikasi Anda dan tetapkan nilai ke false:
```
<application>
    <property
        android:name="android.window.
        PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE"
        android:value="false" />
</application>
```
Aplikasi Anda akan dikecualikan dari daftar aplikasi di setelan perangkat. Pengguna tidak akan dapat mengganti rasio aspek aplikasi.

Menetapkan properti ke true tidak akan berpengaruh.
PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE

Untuk memilih tidak ikut opsi layar penuh penggantian kompatibilitas rasio aspek pengguna, tambahkan properti ke manifes aplikasi Anda dan tetapkan nilai ke false:
```
<application>
    <property
        android:name="android.window.PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_FULLSCREEN_OVERRIDE"
        android:value="false" />
</application>
```
Opsi layar penuh dihapus dari daftar opsi rasio aspek di setelan perangkat. Pengguna tidak akan dapat menerapkan penggantian layar penuh ke aplikasi Anda.

Perhatian: Jika PROPERTY_COMPAT_ALLOW_USER_ASPECT_RATIO_OVERRIDE adalah false, properti ini tidak akan berpengaruh.

Menetapkan properti ini ke true tidak akan berpengaruh.

Optimalkan aplikasi Anda untuk semua layar: Jangan menetapkan batasan rasio aspek di aplikasi Anda. Gunakan class ukuran jendela untuk mendukung berbagai tata letak berdasarkan jumlah ruang tampilan yang tersedia.

Penggantian per aplikasi produsen perangkat

Produsen perangkat menerapkan penggantian per aplikasi di perangkat tertentu. Perangkat referensi dapat menerapkan beberapa penggantian ke berbagai aplikasi secara default.

Aplikasi dapat memilih untuk tidak mengaktifkan sebagian besar penggantian (lihat tabel Penggantian per aplikasi di bawah).

Anda dapat menguji aplikasi dengan penggantian yang diaktifkan atau dinonaktifkan menggunakan framework kompatibilitas (lihat Alat framework kompatibilitas). Jika diaktifkan, penggantian akan diterapkan ke seluruh aplikasi.

Anda juga dapat menggunakan Android Debug Bridge (adb) untuk mengaktifkan atau menonaktifkan penggantian dan menentukan penggantian mana yang berlaku untuk aplikasi Anda.

Aktifkan atau nonaktifkan penggantian sebagai berikut:

adb shell am compat enable/disable <override name/id> <package>

Untuk perangkat referensi, periksa penggantian mana yang berlaku untuk aplikasi Anda:

adb shell dumpsys platform_compat | grep <package name>

Tabel berikut mencantumkan penggantian yang tersedia beserta panduan tentang cara mengoptimalkan aplikasi agar aplikasi tidak perlu mengandalkan penggantian. Anda dapat menambahkan tanda properti ke manifes aplikasi untuk memilih tidak mengaktifkan beberapa penggantian.

Penggantian per aplikasi
Jenis	Nama	ID	Deskripsi
Kemampuan untuk berubah ukuran	FORCE_RESIZE_APP	174042936	Menghindari mode kompatibilitas ukuran untuk aplikasi saat konfigurasi berubah.
	FORCE_NON_RESIZE_APP	181136395	Memaksa aplikasi memasuki mode kompatibilitas ukuran saat konfigurasi berubah.
Rasio aspek	OVERRIDE_MIN_ASPECT_RATIO	174042980	Penggantian Gatekeeper yang harus diaktifkan untuk menerapkan penggantian rasio aspek lainnya.
	OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY	203647190	Jika diaktifkan (default), akan membatasi cakupan penggantian ke aktivitas khusus potret.
	OVERRIDE_MIN_ASPECT_RATIO_MEDIUM	180326845	Mengubah rasio aspek minimum menjadi 3:2.
	OVERRIDE_MIN_ASPECT_RATIO_LARGE	180326787	Mengubah rasio aspek minimum menjadi 16:9.
	OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN	208648326	Mengubah rasio aspek minimum agar sesuai dengan 50% ukuran tampilan (atau rasio aspek layar terpisah).
	OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN	218959984	Menonaktifkan penggantian rasio aspek minimum sehingga aplikasi dalam mode layar penuh saat perangkat dalam mode potret.
Orientasi	OVERRIDE_ANY_ORIENTATION	265464455	Mengaktifkan penggantian orientasi apa pun.
	OVERRIDE_ANY_ORIENTATION_TO_USER	310816437	Mengganti batasan orientasi, kemampuan mengubah ukuran, dan rasio aspek.
	OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT	265452344	Mengganti orientasi menjadi potret saat aktivitas memiliki orientasi yang tidak ditentukan.
	OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR	265451093	Mengganti orientasi menjadi `nosensor` (menggunakan orientasi alami perangkat) saat aktivitas memiliki orientasi yang tidak ditentukan.
	OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE	266124927	Memutar aplikasi khusus lanskap 180 derajat.
	OVERRIDE_ORIENTATION_ONLY_FOR_CAMERA	265456536	Membatasi cakupan penggantian orientasi saat aplikasi terhubung ke kamera.
	OVERRIDE_USE_DISPLAY_LANDSCAPE_NATURAL_ORIENTATION	255940284	Menetapkan tampilan ke orientasi alami lanskap tetap saat tugas dalam mode layar penuh (termasuk dalam tampilan lebar).
	OVERRIDE_ENABLE_COMPAT_IGNORE_REQUESTED_ORIENTATION	254631730	Mengabaikan permintaan orientasi dari aplikasi untuk menghindari loop rotasi tanpa henti.
	OVERRIDE_ENABLE_COMPAT_IGNORE_ORIENTATION_REQUEST_WHEN_LOOP_DETECTED	273509367	Mengabaikan permintaan orientasi berulang saat aktivitas diluncurkan kembali. Jika Android mendeteksi bahwa aplikasi meminta setidaknya dua orientasi baru dalam satu detik, sistem akan menganggapnya sebagai loop rotasi tanpa batas dan menerapkan penggantian.
	OVERRIDE_RESPECT_REQUESTED_ORIENTATION	236283604	Mencegah tampilan lebar dengan menonaktifkan setelan permintaan orientasi mengabaikan produsen perangkat.
Sandbox API	NEVER_SANDBOX_DISPLAY_APIS	184838306	Mencegah perubahan perilaku display API.
	ALWAYS_SANDBOX_DISPLAY_APIS	185004937	Memaksa `Display` API di aplikasi untuk menampilkan batas aplikasi. `Display` API menampilkan batas area tampilan logis, tetapi terkadang aplikasi mengasumsikan `Display` API menampilkan batas aplikasi, yang menyebabkan masalah UI.
	OVERRIDE_SANDBOX_VIEW_BOUNDS_APIS	237531167	Memaksa `View` API yang digunakan dalam aplikasi untuk menampilkan batas aplikasi. `View` API menampilkan batas area tampilan logis, tetapi terkadang aplikasi mengasumsikan `View` API menampilkan batas aplikasi, yang menyebabkan masalah UI.
Kompatibilitas kamera	OVERRIDE_CAMERA_COMPAT_DISABLE_FORCE_ROTATION	263959004	Menonaktifkan pemutaran paksa. Secara default, semua aplikasi kamera berorientasi tetap akan diputar paksa saat pratinjau kamera terbuka.
	OVERRIDE_CAMERA_COMPAT_DISABLE_REFRESH	264304459	Menghapus hard refresh default yang diterapkan saat pratinjau kamera diputar paksa.
	OVERRIDE_CAMERA_COMPAT_ENABLE_REFRESH_VIA_PAUSE	264301586	Mengalihkan hard refresh ke soft refresh saat pratinjau kamera diputar paksa, yang membantu mempertahankan status selama pemutaran paksa. Secara default, Android menerapkan hard refresh saat pratinjau kamera diputar paksa. Hard refresh dapat menyebabkan masalah pada aplikasi yang kehilangan status atau berhenti berfungsi, bergantung pada cara aplikasi menyimpan status sebelumnya di cache.
	OVERRIDE_CAMERA_LANDSCAPE_TO_PORTRAIT	250678880	Memangkas buffer gambar di kamera depan bagian dalam. Jika penggantian dinonaktifkan, pemangkasan kamera depan bagian dalam akan dihapus dan ruang pandang pratinjau kamera akan ditingkatkan. Secara default di beberapa perangkat foldable (lihat perangkat referensi), sistem akan memangkas pratinjau kamera dari semua aplikasi kamera saat menggunakan kamera depan bagian dalam.
Lain-lain	OVERRIDE_ENABLE_COMPAT_FAKE_FOCUS	263259275	Mencegah aplikasi berhenti berfungsi saat aplikasi kehilangan fokus dalam mode layar terpisah. Aplikasi menunggu fokus sebelum menggambar konten aplikasi, yang dapat menyebabkan aplikasi macet atau berhenti berfungsi. Penggantian memungkinkan Android mengirimkan focus event palsu ke aplikasi, yang memberi sinyal ke aplikasi untuk mulai menggambar konten lagi.

FORCE_RESIZE_APP

Memaksa paket yang menerapkan penggantian agar ukurannya dapat diubah. Tidak mengubah apakah aplikasi dapat dialihkan ke mode multi-aplikasi, tetapi memungkinkan aplikasi mengubah ukuran tanpa memasuki mode kompatibilitas ukuran saat layar diubah ukurannya.

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Dalam manifes aplikasi, tetapkan atribut android:resizeableActivity ke true atau, untuk mendukung perubahan ukuran saat menonaktifkan mode multi-aplikasi dengan android:resizeableActivity=false, tetapkan flag metadata android.supports_size_changes ke true.

Cara mengoptimalkan aplikasi

Gunakan tata letak responsif/adaptif agar aplikasi dapat beradaptasi dengan semua ukuran layar dan rasio aspek. Lihat Mendukung berbagai ukuran tampilan.

Cara menonaktifkan atau memilih tidak mengaktifkan penggantian

Tetapkan tanda properti PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES ke false.

Tanda properti untuk menyesuaikan penggantian

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES"
  android:value="true|false"/>

Perintah adb untuk menguji penggantian

Untuk menerapkan penggantian dan membuat ukuran aplikasi dapat diubah:

adb shell am compat enable FORCE_RESIZE_APP <package>

Untuk menghapus penggantian:

adb shell am compat disable FORCE_RESIZE_APP <package>

Catatan: Perintah hanya menerapkan atau menghapus penggantian untuk sementara.

FORCE_NON_RESIZE_APP

Memaksa paket yang menerapkan penggantian agar tidak dapat diubah ukurannya dan memasuki mode kompatibilitas ukuran saat konfigurasi berubah.

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Tetapkan atribut android:resizeableActivity dan tanda metadata android.supports_size_changes ke false dalam manifes aplikasi, dan deklarasikan batasan orientasi atau rasio aspek.

Cara mengoptimalkan aplikasi

Semua aplikasi yang berperilaku baik jika diubah ukurannya harus memiliki android:resizeableActivity atau android.supports_size_changes yang disetel ke true. Aplikasi lain harus ditingkatkan agar berperilaku baik saat diubah ukurannya. Lihat android:resizeableActivity.

Cara menonaktifkan atau memilih tidak mengaktifkan penggantian

Tetapkan tanda properti PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES ke false.

Tanda properti untuk menyesuaikan penggantian

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESIZEABLE_ACTIVITY_OVERRIDES"
  android:value="true|false"/>

Perintah adb untuk menguji penggantian

Untuk menerapkan penggantian dan membuat aplikasi tidak dapat diubah ukurannya:

adb shell am compat enable FORCE_NON_RESIZE_APP <package>

Untuk menghapus penggantian:

adb shell am compat disable FORCE_NON_RESIZE_APP <package>

Catatan: Perintah hanya menerapkan atau menghapus penggantian untuk sementara.

OVERRIDE_MIN_ASPECT_RATIO

Gatekeeper untuk semua penggantian yang memaksa rasio aspek minimum tertentu.

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Tetapkan android:minAspectRatio di tingkat aktivitas atau aplikasi.

Cara mengoptimalkan aplikasi

Jangan menetapkan batasan rasio aspek di aplikasi Anda. Pastikan aplikasi Anda mendukung berbagai ukuran tampilan. Gunakan class ukuran jendela untuk mendukung berbagai tata letak berdasarkan jumlah ruang yang dimiliki aplikasi Anda di layar. Lihat Compose WindowSizeClass API dan View WindowSizeClass API.

Cara menonaktifkan atau memilih tidak mengaktifkan penggantian

Tentukan batasan rasio aspek atau tetapkan tanda properti PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE ke false.

Tanda properti untuk menyesuaikan penggantian

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_MIN_ASPECT_RATIO_OVERRIDE"
  android:value="false"/>

Perintah adb untuk menguji penggantian

Untuk menerapkan penggantian:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO <package>

Untuk menghapus penggantian:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO <package>

Catatan: Perintah hanya menerapkan atau menghapus penggantian untuk sementara.

OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY

Membatasi setelan aplikasi yang memaksa rasio aspek minimum tertentu untuk aktivitas dengan orientasi khusus potret. Diaktifkan secara default dan hanya berlaku jika OVERRIDE_MIN_ASPECT_RATIO juga diaktifkan.

Perintah adb untuk menguji penggantian

Untuk menerapkan penggantian:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

Untuk menghapus penggantian:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY <package>

Catatan: Perintah hanya menerapkan atau menghapus penggantian untuk sementara.

OVERRIDE_MIN_ASPECT_RATIO_MEDIUM

Menetapkan rasio aspek minimum aktivitas ke nilai sedang (3:2)

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Cara mengoptimalkan aplikasi

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Cara menonaktifkan atau memilih tidak mengaktifkan penggantian

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Tanda properti untuk menyesuaikan penggantian

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Perintah adb untuk menguji penggantian

Untuk menerapkan penggantian:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

Untuk menghapus penggantian:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_MEDIUM <package>

Catatan: Perintah hanya menerapkan atau menghapus penggantian untuk sementara.

OVERRIDE_MIN_ASPECT_RATIO_LARGE

Menetapkan rasio aspek minimum aktivitas ke nilai besar (16:9)

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Cara mengoptimalkan aplikasi

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Cara menonaktifkan atau memilih tidak mengaktifkan penggantian

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Tanda properti untuk menyesuaikan penggantian

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Perintah adb untuk menguji penggantian

Untuk menerapkan penggantian:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>

Untuk menghapus penggantian:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_LARGE <package>`

Catatan: Perintah hanya menerapkan atau menghapus penggantian untuk sementara.

OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN

Mengaktifkan penggunaan rasio aspek layar terpisah. Mengizinkan aplikasi menggunakan semua ruang yang tersedia dalam mode layar terpisah, sehingga menghindari tampilan lebar.

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Cara mengoptimalkan aplikasi

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Cara menonaktifkan atau memilih tidak mengaktifkan penggantian

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Tanda properti untuk menyesuaikan penggantian

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Perintah adb untuk menguji penggantian

Untuk menerapkan penggantian:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

Untuk menghapus penggantian:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_TO_ALIGN_WITH_SPLIT_SCREEN <package>

Catatan: Perintah hanya menerapkan atau menghapus penggantian untuk sementara.

OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN

Menonaktifkan penggantian rasio aspek minimum di layar penuh potret untuk menggunakan semua ruang layar yang tersedia.

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Cara mengoptimalkan aplikasi

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Cara menonaktifkan atau memilih tidak mengaktifkan penggantian

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Tanda properti untuk menyesuaikan penggantian

Lihat OVERRIDE_MIN_ASPECT_RATIO.

Perintah adb untuk menguji penggantian

Untuk menerapkan penggantian:

adb shell am compat enable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

Untuk menghapus penggantian:

adb shell am compat disable OVERRIDE_MIN_ASPECT_RATIO_EXCLUDE_PORTRAIT_FULLSCREEN <package>

Catatan: Perintah hanya menerapkan atau menghapus penggantian untuk sementara.

OVERRIDE_ANY_ORIENTATION

Mengaktifkan penggantian berikut untuk mengganti orientasi apa pun:

OVERRIDE_UNDEFINED_ORIENTATION_TO_PORTRAIT
OVERRIDE_UNDEFINED_ORIENTATION_TO_NOSENSOR
OVERRIDE_LANDSCAPE_ORIENTATION_TO_REVERSE_LANDSCAPE

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Tetapkan atribut manifes activity:screenOrientation, atau gunakan Activity#setRequestedOrientation() API.

Cara mengoptimalkan aplikasi

Aplikasi Anda harus mendukung semua orientasi. Perubahan orientasi adalah perubahan konfigurasi, yang dapat ditangani dengan dua cara: membiarkan sistem menghancurkan dan membuat ulang aplikasi, atau mengelola perubahan konfigurasi sendiri. Jika Anda mengelola perubahan konfigurasi sendiri, status aplikasi dapat dipertahankan menggunakan ViewModel. Dalam kasus yang sangat terbatas, Anda dapat memutuskan untuk mengunci orientasi hanya pada layar kecil, meskipun aplikasi mungkin tidak diskalakan sebaik saat membiarkan pengguna memutar aplikasi sesuai kebutuhan. Di Android 12L dan versi yang lebih baru, orientasi tetap dapat diganti oleh konfigurasi perangkat. Untuk informasi selengkapnya tentang menangani perubahan konfigurasi dan mendukung semua orientasi, lihat Menangani perubahan konfigurasi, Ringkasan ViewModel, dan Orientasi aplikasi dibatasi di ponsel, tetapi tidak di perangkat layar besar.

Cara menonaktifkan atau memilih tidak mengaktifkan penggantian

Tetapkan tanda properti PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE ke false.

Tanda properti untuk menyesuaikan penggantian

<property android:name="android.window.PROPERTY_COMPAT_ALLOW_ORIENTATION_OVERRIDE"
  android:value="true|false"/>

Perintah adb untuk menguji penggantian

Untuk menerapkan penggantian:

adb shell am compat enable OVERRIDE_ANY_ORIENTATION <package>

Untuk menghapus penggantian:

adb shell am compat disable OVERRIDE_ANY_ORIENTATION <package>

Catatan: Perintah hanya menerapkan atau menghapus penggantian untuk sementara.

OVERRIDE_ANY_ORIENTATION_TO_USER

Memungkinkan aplikasi mengisi ruang tampilan yang tersedia. Mengganti batasan orientasi, pemberian ukuran, dan rasio aspek yang ditentukan dalam manifes aplikasi. Juga mengabaikan panggilan ke Activity#setRequestedOrientation().

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Jangan menetapkan atribut manifes android:screenOrientation, atau tetapkan atribut ke "user".
Tetapkan atribut manifes android:resizeableActivity ke true.

Catatan: Setelan untuk android:minAspectRatio dan android:maxAspectRatio akan diabaikan jika resizeableActivity disetel ke true.
Pada layar kecil, untuk mendukung perubahan ukuran aplikasi saat menonaktifkan mode multi-aplikasi dengan android:resizeableActivity=false, tetapkan tanda metadata android.supports_size_changes ke true. Jangan tetapkan minAspectRatio dan maxAspectRatio.

Catatan: Di Android 12 (API level 31), semua aplikasi berjalan dalam mode multi-aplikasi di layar besar (class ukuran jendela sedang atau diperluas) terlepas dari konfigurasi aplikasi. Lihat Mendukung mode multi-aplikasi.

Cara mengoptimalkan aplikasi

Buat aplikasi Anda mendukung semua orientasi; jangan tetapkan spesifikasi screenOrientation dalam manifes aplikasi Anda. Dukung kemampuan aplikasi untuk diubah ukurannya, mode multi-aplikasi, dan semua rasio aspek tampilan dengan menetapkan atribut android:resizeableActivity di manifes aplikasi Anda ke true. Lihat Mendukung berbagai ukuran tampilan.

Mode kompatibilitas perangkat

Perangkat referensi

Masalah kompatibilitas umum

Tampilan Lebar

Masalah

Aplikasi yang dibatasi untuk orientasi potret saja tidak dapat digunakan di perangkat lanskap.

Pengoptimalan

Aplikasi mendukung semua orientasi perangkat.

Solusi kompatibilitas

Mode kompatibilitas ukuran

Masalah

Aplikasi yang tidak dapat diubah ukurannya mengalami error dalam mode multi-aplikasi.

Pengoptimalan

Aplikasi berfungsi di semua ukuran jendela.

Solusi kompatibilitas

Aplikasi khusus potret dengan tampilan lebar dalam orientasi lanskap diubah skalanya dengan kontrol mulai ulang.

Loop berkedip

Masalah

Aplikasi khusus lanskap pada tampilan potret melakukan panggilan berulang ke Activity#setRequestedOrientation().

Pengoptimalan

Aplikasi menangani perubahan konfigurasi, tidak memiliki batasan orientasi, sehingga tidak memasuki loop yang berkedip.

Solusi kompatibilitas

Pratinjau kamera

Masalah

Pratinjau kamera yang tidak selaras dan terdistorsi pada perangkat foldable layar besar.

Pengoptimalan

Pratinjau kamera diselaraskan dan diskalakan dengan benar di semua orientasi perangkat.

Solusi kompatibilitas

Tablet — Memutar paksa aplikasi yang dibatasi untuk potret.

Perangkat foldable — Memutar paksa aplikasi yang dibatasi untuk potret. Aplikasi ini juga memiliki tampilan lebar.

API yang sering disalahgunakan

Masalah

API yang tidak digunakan lagi salah menghitung batas aplikasi. Konten aplikasi dinonaktifkan di layar.

Pengoptimalan

API menghitung metrik jendela aplikasi dengan benar.

Solusi kompatibilitas

Aktivitas yang transparan

Masalah

Dialog salah ditempatkan karena aktivitas diluncurkan dari trampolin.

Pengoptimalan

Sudut membulat

Dialog dengan sudut membulat diposisikan dengan benar di atas aktivitas peluncuran yang terlihat.

Solusi kompatibilitas

Game Unity

Masalah

Game kehilangan fokus dalam mode multi-aplikasi dan merender sebagai jendela gelap.

Pengoptimalan

Game merender konten dengan benar dalam mode multi-aplikasi bahkan saat tidak dalam fokus.

Solusi kompatibilitas

Uji aplikasi Anda untuk menemukan masalah kompatibilitas

Memiliki tampilan lebar

Kotlin

Java

Kotlin

Java

Penggantian per aplikasi

Penggantian per aplikasi pengguna

Penggantian per aplikasi produsen perangkat

FORCE_RESIZE_APP

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Cara mengoptimalkan aplikasi

Cara menonaktifkan atau memilih tidak mengaktifkan penggantian

Tanda properti untuk menyesuaikan penggantian

Perintah adb untuk menguji penggantian

FORCE_NON_RESIZE_APP

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Cara mengoptimalkan aplikasi

Cara menonaktifkan atau memilih tidak mengaktifkan penggantian

Tanda properti untuk menyesuaikan penggantian

Perintah adb untuk menguji penggantian

OVERRIDE_MIN_ASPECT_RATIO

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Cara mengoptimalkan aplikasi

Cara menonaktifkan atau memilih tidak mengaktifkan penggantian

Tanda properti untuk menyesuaikan penggantian

Perintah adb untuk menguji penggantian

OVERRIDE_MIN_ASPECT_RATIO_PORTRAIT_ONLY

Cara aplikasi dapat mencapai hasil yang sama dengan penggantian

Cara mengoptimalkan aplikasi

Cara menonaktifkan atau memilih tidak mengaktifkan penggantian

Aplikasi khusus lanskap pada tampilan potret melakukan panggilan berulang ke `Activity#setRequestedOrientation()`.