Menggelapkan konten web di WebView

Di Android 10 dan yang lebih tinggi, aplikasi dapat mendukung Tema gelap dan otomatis berubah 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 memiliki interoperabilitas dengan standar web prefers-color-scheme dan color-scheme. Jika memungkinkan, jika Anda menulis konten web yang Anda inginkan untuk ditampilkan oleh aplikasi di WebView, Anda harus menentukan tema gelap untuk situs Anda 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 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 secara algoritmis menerapkan tema gelap 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 berbasis algoritma 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 ditetapkan ke false dan aplikasi mengizinkan penggelapan algoritma untuk WebView. 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.

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 algoritma

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

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

Jika aplikasi Anda tidak menggunakan Force Dark, cara aplikasi menentukan waktu untuk mengizinkan penggelapan algoritma di WebView bergantung pada level API target aplikasi Anda. Lihat bagian berikut untuk aplikasi yang menargetkan Android 13 atau yang lebih baru dan aplikasi yang menargetkan Android 12 atau yang lebih rendah untuk mengetahui detailnya.

Izinkan penggelapan berbasis algoritme untuk konten web dengan Force Dark

Jika aplikasi Anda menggunakan Force Dark tingkat aplikasi, WebView akan menerapkan penggelapan algoritma ke konten web jika kondisi berikut terpenuhi:

  • WebView dan elemen induknya mengizinkan Force Dark.
  • 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 baru, 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 ke FORCE_DARK_AUTO dan telah menetapkan strategi Force Dark ke DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

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

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

Izinkan penggelapan berbasis algoritma (aplikasi yang menargetkan Android 13 atau yang lebih tinggi)

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

WebView kemudian menerapkan penggelapan berbasis algoritma jika kondisi berikut terpenuhi:

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

Izinkan penggelapan berbasis algoritma (aplikasi yang menargetkan Android 12 atau yang lebih rendah)

Untuk aplikasi yang tidak menggunakan Force Dark tingkat aplikasi dan menargetkan Android 12 (API level 32) atau yang lebih rendah, gunakan FORCE_DARK_ON untuk mengizinkan penggelapan berbasis 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 diganti statusnya di UI atau pemilihan berbasis waktu otomatis.

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 mengandalkan deteksi perubahan pada preferensi sistem, aplikasi 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 AndroidX untuk mengontrol cara penggelapan diterapkan pada WebView tertentu. API ini hanya berlaku jika gelap paksa 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 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 membalik warna halaman web. Jika Anda menggunakan penggelapan agen pengguna, kueri @media (prefers-color-scheme: dark) akan bernilai false.

Untuk memilih di 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 memerlukan tag meta untuk mematuhi kueri media prefers-color-scheme halaman web. Anda dapat menggunakan WebView dengan mode DARK_STRATEGY_WEB_THEME_DARKENING_ONLY, yang dalam hal ini WebView selalu menerapkan kueri media meskipun tag dihapus.

    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 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