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. 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 Paksa Gelap untuk menerapkan tema gelap secara algoritma ke aplikasi. WebView merender konten dengan tema gelap yang telah ditentukan oleh penulis konten. Jika diizinkan oleh penulis konten, WebView merender konten dengan tema gelap yang dibuat menggunakan algoritme.
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 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 perlu, untuk menerapkan tema gelap secara algoritme ke konten web yang direndernya.

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

Jika aplikasi tidak menggunakan Paksa Gelap, cara aplikasi menentukan kapan harus mengizinkan penggelapan algoritma di WebView bergantung pada level API target aplikasi. 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 memungkinkan Paksa Gelap.
  • Tema aktivitas saat ini ditandai sebagai terang dengan isLightTheme disetel ke true.
  • Penulis konten web tidak secara eksplisit menonaktifkan 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 (level API 32) atau yang lebih rendah: Aplikasi telah menetapkan setelan forceDarkMode WebView ke FORCE_DARK_AUTO dan telah menetapkan strategi Paksa Gelap ke DARK_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.

Izinkan penggelapan algoritma (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 tersebut, 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 informasi selengkapnya tentang penggelapan tema web, 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 menjadi false.

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: 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 media prefers-color-scheme halaman web. Anda dapat menggunakan WebView dengan mode DARK_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