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 penataan gaya terang, gelap, atau default.

Perilaku WebView memiliki interoperabilitas dengan prefers-color-scheme dan color-scheme standar web. Bila memungkinkan, jika Anda menulis isi web yang Anda inginkan, aplikasi Anda agar ditampilkan di WebView, Anda harus menentukan tema gelap untuk situs Anda dan terapkan prefers-color-scheme agar WebView dapat mencocokkan konten web ke 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 yang telah ditentukan oleh penulis konten. WebView merender konten dengan gaya default yang ditentukan oleh penulis konten.
Aplikasi sedang menggunakan Gelap Otomatis dapat menerapkan tema gelap secara algoritma pada aplikasi. WebView merender konten dengan tema gelap yang yang telah ditentukan oleh penulis konten. Jika diizinkan oleh penulis konten, WebView merender konten dengan tema gelap yang dibuat menggunakan algoritma.
Aplikasi menggunakan tema gelap dengan isLightTheme disetel ke false dan aplikasi tidak mengizinkan berbasis algoritma menjadi gelap untuk WebView. WebView merender konten dengan tema gelap yang 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 mengizinkan penggelapan algoritma untuk WebView. WebView merender konten dengan tema gelap yang yang telah ditentukan oleh penulis konten. Jika diizinkan oleh penulis konten, WebView merender konten dengan tema gelap yang dibuat menggunakan algoritma.

Gaya penulis konten

Atribut isLightTheme menunjukkan apakah tema aplikasi terang atau gelap. WebView selalu disetel prefers-color-scheme menurut isLightTheme. Jika isLightTheme adalah true atau tidak ditentukan, maka prefers-color-scheme adalah light; jika tidak, akan dark.

Artinya, jika konten web menggunakan prefers-color-scheme dan konten bebas, tema terang atau gelap yang ditentukan oleh penulis konten selalu diterapkan secara otomatis 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 diperlukan, untuk menerapkan tema gelap secara algoritmis tema dengan konten web yang direndernya.

Jika aplikasi Anda menggunakan level aplikasi Paksa Gelap untuk menggunakan algoritma menerapkan tema gelap ke aplikasi Anda, lihat bagian berikut yang menjelaskan cara izinkan penggelapan algoritma untuk konten web dengan Paksa Gelap.

Jika aplikasi Anda tidak menggunakan Paksa Gelap, cara aplikasi menentukan kapan harus mengizinkan penggelapan algoritma di WebView bergantung pada konfigurasi level API target 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.

Izinkan penggelapan berbasis algoritma untuk konten web dengan Paksa Gelap

Jika aplikasi Anda menggunakan level aplikasi Gelap Otomatis, WebView berlaku penggelapan algoritma terhadap konten web jika kondisi berikut terpenuhi:

  • WebView dan elemen induknya memungkinkan Paksa Gelap.
  • Tema aktivitas saat ini ditandai sebagai terang dengan isLightTheme ditetapkan 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 (API level 32) atau yang lebih rendah: Aplikasi telah menetapkan Setelan forceDarkMode WebView dapat FORCE_DARK_AUTO dan telah mengatur strategi Force Dark mereka untuk DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

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

Mode Gelap Force disediakan terutama untuk kompatibilitas mundur di aplikasi yang tidak menyediakan tema gelapnya sendiri. Jika aplikasi Anda menggunakan Paksa Gelap, sebaiknya menambahkan dukungan untuk tema gelap.

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

Untuk aplikasi yang tidak menggunakan Force Dark level aplikasi dan menargetkan Android 13 (API level 33) atau yang lebih tinggi, gunakan AndroidX setAlgorithmicDarkeningAllowed() dan meneruskan true untuk menentukan bahwa WebView harus mengizinkan algoritma menjadi lebih gelap. Metode ini memiliki kompatibilitas mundur dengan Android sebelumnya versi.

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 (level API 32) atau yang lebih rendah, gunakan FORCE_DARK_ON untuk memungkinkan 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 diganti statusnya di UI atau pilihan 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 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 API ForceDarkStrategy di AndroidX untuk mengontrol bagaimana penggelapan diterapkan pada WebView tertentu. API ini merupakan 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 agen pengguna menggelapkan:

  • Penggelapan tema web: Developer web mungkin berlaku @media (prefers-color-scheme: dark) untuk mengontrol tampilan halaman web di mode gelap. WebView merender konten sesuai dengan setelan ini. Untuk informasi selengkapnya tentang tema web menjadi gelap, lihat spesifikasi lebih lanjut.
  • Penggelapan agen pengguna: WebView otomatis membalikkan warna web kami. Jika Anda menggunakan penggelapan agen pengguna, Kueri @media (prefers-color-scheme: dark) 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: Opsi ini adalah opsi default. Meskipun sebagian besar {i>browser<i} memperlakukan Tag <meta name="color-scheme" content="dark light"> sebagai opsional, Android Mode default WebView memerlukan tag meta untuk mematuhi prefers-color-scheme kueri media. Anda dapat menggunakan WebView dengan DARK_STRATEGY_WEB_THEME_DARKENING_ONLY , di mana WebView selalu menerapkan kueri media meskipun tag dihilangkan.

    Namun, kami menyarankan pengembang web menambahkan <meta name="color-scheme" content="dark light"> tag ke situsnya untuk memastikan bahwa konten dirender dengan benar di WebView dengan konfigurasi default-nya.

  • DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: Disebut sebagai "{i>user-agent penggelapan<i}, WebView mengabaikan penggelapan laman web dan menerapkan penggelapan otomatis.

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

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