Di Android 10 dan yang lebih tinggi, aplikasi dapat mendukung Tema gelap dan otomatis beralih antara tema aplikasi terang dan gelap sesuai dengan tema sistem. Untuk mencocokkan tema aplikasi saat ini, konten web di WebView juga dapat menggunakan gaya terang, gelap, atau default.
Perilaku WebView berinteraksi dengan standar web
prefers-color-scheme
dan
color-scheme
. Jika memungkinkan, jika Anda menulis konten web yang ingin
ditampilkan aplikasi di WebView, Anda harus menentukan tema gelap untuk
situs dan
menerapkan prefers-color-scheme
sehingga WebView dapat mencocokkan tema
konten web dengan tema aplikasi Anda.
Tabel berikut menjelaskan cara WebView merender konten web di aplikasi Anda, bergantung pada gaya konten web dan kondisi aplikasi Anda:
Kondisi aplikasi | Konten web yang menggunakan prefers-color-scheme |
Konten web yang tidak menggunakan prefers-color-scheme |
---|---|---|
Aplikasi menggunakan tema terang dengan
isLightTheme
disetel ke true atau tidak disetel. |
WebView merender konten dengan tema terang yang telah ditentukan oleh penulis konten. | WebView merender konten dengan gaya default yang ditentukan oleh penulis konten. |
Aplikasi menggunakan Force Dark untuk menerapkan tema gelap secara algoritmis ke aplikasi. | WebView merender konten dengan tema gelap yang telah ditentukan oleh penulis konten. | Jika diizinkan oleh penulis konten, WebView akan merender konten dengan tema gelap yang dihasilkan menggunakan algoritma. |
Aplikasi menggunakan tema gelap dengan
isLightTheme
disetel ke false dan aplikasi tidak mengizinkan penggelapan
algoritme untuk WebView. |
WebView merender konten dengan tema gelap yang telah ditentukan oleh penulis konten. | WebView merender konten dengan gaya default yang ditentukan oleh penulis konten. |
Aplikasi menggunakan tema gelap dengan
isLightTheme
disetel ke false dan aplikasi memungkinkan
penggelapan algoritme untuk WebView. |
WebView merender konten dengan tema gelap yang telah ditentukan oleh penulis konten. | Jika diizinkan oleh penulis konten, WebView akan merender konten dengan tema gelap yang dihasilkan menggunakan algoritma. |
Gaya visual penulis konten
Atribut
isLightTheme
aplikasi
menunjukkan apakah tema aplikasi terang atau gelap. WebView selalu menetapkan
prefers-color-scheme
sesuai dengan isLightTheme
. Jika isLightTheme
adalah true
atau tidak ditentukan, prefers-color-scheme
adalah light
; jika tidak, ini adalah
dark
.
Artinya, jika konten web menggunakan prefers-color-scheme
dan penulis
konten mengizinkannya, tema terang atau gelap yang ditentukan oleh penulis konten
selalu diterapkan secara otomatis ke konten web agar cocok dengan tema aplikasi.
Penggelapan algoritma
Untuk mencakup kasus saat konten web tidak menggunakan
prefers-color-scheme
,
aplikasi Anda dapat mengizinkan WebView, jika diperlukan, untuk menerapkan tema gelap
secara algoritmis ke konten web yang dirender.
Jika aplikasi menggunakan Paksa Gelap tingkat aplikasi untuk menerapkan tema gelap secara algoritmis ke aplikasi, lihat bagian berikut yang menjelaskan cara mengizinkan penggelapan algoritma untuk konten web dengan Force Dark.
Jika aplikasi Anda tidak menggunakan Force Dark, cara aplikasi menentukan kapan harus mengizinkan pemenuran algoritma di WebView bergantung pada level API target aplikasi Anda. Lihat bagian berikut untuk aplikasi yang menargetkan Android 13 atau yang lebih tinggi dan aplikasi yang menargetkan Android 12 atau yang lebih rendah untuk mengetahui detailnya.
Mengizinkan penggelapan algoritme untuk konten web dengan Force Dark
Jika aplikasi Anda menggunakan Force Dark tingkat aplikasi, WebView akan menerapkan penggelapan algoritme ke konten web jika kondisi berikut terpenuhi:
- WebView dan elemen induknya mengizinkan Paksa Gelap.
- Tema aktivitas saat ini ditandai sebagai terang dengan
isLightTheme
disetel ketrue
. - Penulis konten web tidak menonaktifkan secara eksplisit proses penggelapan.
- Untuk aplikasi yang menargetkan Android 13 (API level 33) atau yang lebih tinggi, konten web
tidak menggunakan
prefers-color-scheme
. - Untuk aplikasi yang menargetkan Android 12 (API level 32) atau yang lebih rendah: Aplikasi telah menetapkan
setelan
forceDarkMode
WebView keFORCE_DARK_AUTO
dan telah menetapkan strategi Force Dark keDARK_STRATEGY_USER_AGENT_DARKENING_ONLY
.
WebView dan semua induknya dapat mengizinkan paksa gelap menggunakan
View.setForceDarkAllowed()
.
Nilai default diambil dari atribut setForceDarkAllowed()
tema Android, yang juga harus disetel ke true
.
Mode Gelap Force disediakan terutama untuk kompatibilitas mundur dalam aplikasi yang tidak menyediakan tema gelapnya sendiri. Jika aplikasi Anda menggunakan Paksa Gelap, sebaiknya tambahkan dukungan untuk tema gelap.
Mengizinkan penggelapan algoritmis (aplikasi yang menargetkan Android 13 atau yang lebih baru)
Untuk aplikasi yang tidak menggunakan Force Dark tingkat aplikasi dan menargetkan Android 13 (API level
33) atau yang lebih tinggi, gunakan metode
setAlgorithmicDarkeningAllowed()
AndroidX dan teruskan true
untuk menentukan bahwa WebView harus mengizinkan penggelapan
algoritma. Metode ini memiliki kompatibilitas mundur dengan versi Android
sebelumnya.
WebView kemudian menerapkan penggelapan algoritma jika kondisi berikut terpenuhi:
- Konten web tidak menggunakan
prefers-color-scheme
. - Penulis konten web tidak secara eksplisit menonaktifkan penggelapan.
Mengizinkan penggelapan algoritmis (aplikasi yang menargetkan Android 12 atau yang lebih rendah)
Untuk aplikasi yang tidak menggunakan Force Dark level aplikasi dan menargetkan Android 12 (API level
32) atau yang lebih rendah, gunakan
FORCE_DARK_ON
untuk mengizinkan penggelapan algoritma.
Gunakan FORCE_DARK_ON
bersama dengan
FORCE_DARK_OFF
jika aplikasi Anda menyediakan metodenya sendiri untuk beralih antara tema terang dan gelap,
seperti elemen yang dapat diaktifkan di UI atau pemilihan berbasis waktu otomatis.
Untuk memeriksa apakah fitur didukung, tambahkan baris kode berikut
di mana pun Anda mengonfigurasi objek WebView, seperti di Activity.onCreate
:
Kotlin
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) { WebSettingsCompat.setForceDark(...) }
Java
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) { WebSettingsCompat.setForceDark(...); }
Jika aplikasi Anda mengandalkan deteksi perubahan pada preferensi sistem, aplikasi harus
memproses perubahan tema secara eksplisit dan menerapkannya ke WebView dengan
status FORCE_DARK_ON
dan FORCE_DARK_OFF
.
Cuplikan kode berikut menunjukkan cara mengubah format tema:
Kotlin
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) { when (resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK) { Configuration.UI_MODE_NIGHT_YES -> { WebSettingsCompat.setForceDark(myWebView.settings, FORCE_DARK_ON) } Configuration.UI_MODE_NIGHT_NO, Configuration.UI_MODE_NIGHT_UNDEFINED -> { WebSettingsCompat.setForceDark(myWebView.settings, FORCE_DARK_OFF) } else -> { // } } }
Java
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) { switch (getResources().getConfiguration().uiMode & Configuration.UI_MODE_NIGHT_MASK) { case Configuration.UI_MODE_NIGHT_YES: WebSettingsCompat.setForceDark(myWebView.getSettings(), FORCE_DARK_ON); break; case Configuration.UI_MODE_NIGHT_NO: case Configuration.UI_MODE_NIGHT_UNDEFINED: WebSettingsCompat.setForceDark(myWebView.getSettings(), FORCE_DARK_OFF); break; } }
Menyesuaikan penanganan tema gelap
Anda juga dapat menggunakan
ForceDarkStrategy API
di AndroidX untuk mengontrol cara penggelapan diterapkan ke WebView tertentu. API ini
hanya berlaku jika paksa gelap disetel ke FORCE_DARK_ON
atau FORCE_DARK_AUTO
.
Dengan menggunakan API, aplikasi Anda dapat menggunakan penggelapan tema web atau penggelapan agen pengguna:
- Penggelapan tema web: Developer web mungkin menerapkan
@media (prefers-color-scheme: dark)
untuk mengontrol tampilan halaman web dalam mode gelap. WebView merender konten sesuai dengan setelan ini. Untuk mengetahui informasi selengkapnya tentang tema web yang menjadi gelap, lihat spesifikasi. - Penggelapan agen pengguna: WebView otomatis membalikkan warna halaman
web. Jika Anda menggunakan penggelapan agen pengguna, kueri
@media (prefers-color-scheme: dark)
akan dievaluasi menjadifalse
.
Untuk memilih antara dua strategi tersebut, gunakan API berikut:
Kotlin
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK_STRATEGY)) { WebSettingsCompat.setForceDarkStrategy(...) }
Java
if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK_STRATEGY)) { WebSettingsCompat.setForceDarkStrategy(...); }
Opsi strategi yang didukung adalah:
DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING
: Opsi ini adalah opsi default. Meskipun sebagian besar browser memperlakukan tag<meta name="color-scheme" content="dark light">
sebagai opsional, mode default Android WebView mewajibkan tag meta untuk mematuhi kueri mediaprefers-color-scheme
halaman web. Anda dapat menggunakan WebView dengan modeDARK_STRATEGY_WEB_THEME_DARKENING_ONLY
, dalam hal ini WebView selalu menerapkan kueri media meskipun tag dihilangkan.Namun, sebaiknya developer web menambahkan tag
<meta name="color-scheme" content="dark light">
ke situs mereka untuk memastikan konten dirender dengan benar di WebView dengan konfigurasi default.DARK_STRATEGY_USER_AGENT_DARKENING_ONLY
: Disebut "penggelapan agen pengguna", WebView mengabaikan penggelapan halaman web apa pun dan menerapkan penggelapan otomatis.
Jika aplikasi Anda menampilkan konten web pihak pertama yang Anda sesuaikan dengan
kueri media prefers-color-scheme
, sebaiknya
DARK_STRATEGY_WEB_THEME_DARKENING_ONLY
untuk memastikan WebView menggunakan tema kustom.
Untuk contoh tema gelap yang diterapkan, lihat demo WebView di GitHub