Menggelapkan konten web di WebView

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. Agar sesuai dengan tema aplikasi saat ini, konten web di WebView juga dapat menggunakan gaya terang, gelap, atau default.

Perilaku WebView beroperasi dengan prefers-color-scheme dan color-scheme standar web. Jika memungkinkan, jika Anda membuat 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 yang ditetapkan ke true atau tidak ditetapkan. 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 algoritmik ke aplikasi. WebView merender konten dengan tema gelap yang telah ditentukan oleh penulis konten. Jika diizinkan oleh penulis konten, WebView merender konten dengan a tema gelap yang dibuat menggunakan algoritma.
Aplikasi menggunakan tema gelap dengan isLightTheme yang ditetapkan ke false dan aplikasi tidak mengizinkan penggelapan algoritmik 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 yang ditetapkan ke false dan aplikasi mengizinkan penggelapan algoritmik untuk WebView. WebView merender konten dengan tema gelap yang telah ditentukan oleh penulis konten. Jika diizinkan oleh penulis konten, WebView merender konten dengan a tema gelap yang dibuat menggunakan algoritma.

Gaya 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, dark.

Artinya, jika konten web menggunakan prefers-color-scheme dan penulis konten mengizinkannya, tema terang atau gelap yang ditentukan oleh penulis konten akan selalu otomatis diterapkan ke konten web agar sesuai dengan tema aplikasi.

Penggelapan algoritmik

Untuk mencakup kasus saat konten web tidak menggunakan prefers-color-scheme, aplikasi Anda dapat mengizinkan WebView, jika perlu, untuk menerapkan tema gelap secara algoritmik ke konten web yang dirender.

Jika aplikasi Anda menggunakan Force Dark tingkat aplikasi untuk menerapkan tema gelap secara algoritmik ke aplikasi, lihat bagian berikut yang menjelaskan cara mengizinkan penggelapan algoritmik untuk konten web dengan Force Dark.

Jika aplikasi Anda tidak menggunakan Gelap Otomatis, cara aplikasi Anda menentukan kapan harus mengizinkan penggelapan algoritmik 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 algoritmik untuk konten web dengan Gelap Otomatis

Jika aplikasi Anda menggunakan Gelap Otomatis tingkat aplikasi, WebView akan menerapkan penggelapan algoritmik ke konten web jika kondisi berikut terpenuhi:

  • WebView dan elemen induknya mengizinkan Gelap Otomatis.
  • Tema aktivitas saat ini ditandai sebagai terang dengan isLightTheme yang ditetapkan ke true.
  • Penulis konten web tidak secara eksplisit menonaktifkan penggelapan.
  • Untuk aplikasi yang menargetkan Android 13 (level API 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 forceDarkModeWebView ke FORCE_DARK_AUTO dan telah menetapkan strategi Force Dark ke DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

WebView dan semua induknya dapat mengizinkan force dark menggunakan View.setForceDarkAllowed(). Nilai default diambil dari atribut setForceDarkAllowed() tema Android, yang juga harus ditetapkan ke true.

Gelap Otomatis disediakan terutama untuk kompatibilitas mundur di aplikasi yang tidak menyediakan tema gelapnya sendiri. Jika aplikasi Anda menggunakan Force Dark, sebaiknya tambahkan dukungan untuk tema gelap.

Mengizinkan penggelapan algoritmik (aplikasi yang menargetkan Android 13 atau yang lebih tinggi)

Untuk aplikasi yang tidak menggunakan Gelap Otomatis tingkat aplikasi dan menargetkan Android 13 (level API 33) atau yang lebih tinggi, gunakan metode Jetpack Webkit setAlgorithmicDarkeningAllowed() dan teruskan true untuk menentukan bahwa WebView harus mengizinkan penggelapan algoritmik. Metode ini memiliki kompatibilitas mundur dengan versi Android sebelumnya.

WebView kemudian menerapkan penggelapan algoritmik jika kondisi berikut terpenuhi:

  • Konten web tidak menggunakan prefers-color-scheme.
  • Penulis konten web tidak secara eksplisit menonaktifkan penggelapan.

Mengizinkan penggelapan algoritmik (aplikasi yang menargetkan Android 12 atau yang lebih rendah)

Untuk aplikasi yang tidak menggunakan Gelap Otomatis tingkat aplikasi dan menargetkan Android 12 (level API 32) atau yang lebih rendah, gunakan FORCE_DARK_ON untuk mengizinkan penggelapan algoritmik.

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 dialihkan di UI atau pemilihan otomatis berbasis waktu.

Untuk memeriksa apakah fitur ini 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 bergantung pada pendeteksian perubahan pada preferensi sistem, aplikasi Anda harus secara eksplisit memproses perubahan tema 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 library Jetpack untuk mengontrol cara penggelapan diterapkan ke WebView tertentu. API ini hanya berlaku jika force dark ditetapkan 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 dapat 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 penggelapan tema web, lihat spesifikasinya.
  • Penggelapan agen pengguna: WebView otomatis membalikkan warna halaman web halaman. Jika Anda menggunakan penggelapan agen pengguna, kueri @media (prefers-color-scheme: dark) akan dievaluasi ke false.

Untuk memilih antara dua strategi, 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: Ini adalah opsi default. Meskipun sebagian besar browser memperlakukan tag <meta name="color-scheme" content="dark light"> sebagai opsional, mode default Android WebView's memerlukan tag meta untuk mematuhi kueri media prefers-color-scheme halaman web. Anda dapat menggunakan WebView dengan DARK_STRATEGY_WEB_THEME_DARKENING_ONLY mode, yang dalam hal ini WebView selalu menerapkan kueri media meskipun tag dihilangkan.

    Namun, sebaiknya developer web menambahkan <meta name="color-scheme" content="dark light"> tag 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 dan menerapkan penggelapan otomatis.

Jika aplikasi Anda menampilkan konten web pihak pertama yang Anda sesuaikan dengan kueri media prefers-color-scheme, sebaiknya gunakan DARK_STRATEGY_WEB_THEME_DARKENING_ONLY untuk memastikan WebView menggunakan tema kustom.

Untuk contoh tema gelap yang diterapkan, lihat Demo WebView di GitHub