Web Görünümü'nde web içeriğini koyulaştır

Android 10 ve sonraki sürümlerde uygulamalar koyu temayı destekleyebilir ve sistem temasına göre açık ve koyu uygulama temaları arasında otomatik olarak geçiş yapabilir. WebView'deki web içeriği, mevcut uygulama temasıyla eşleşmesi için açık, koyu veya varsayılan stil kullanabilir.

WebView'ın davranışı, prefers-color-scheme ve color-scheme web standartlarıyla birlikte çalışır. Mümkün olduğunda, uygulamanızın WebView'da göstermesini istediğiniz web içeriğini oluşturuyorsanız web siteniz için koyu bir tema tanımlamalı ve prefers-color-scheme'yi uygulamalısınız. Böylece WebView, web içeriğinin temasını uygulamanızın temasıyla eşleştirebilir.

Aşağıdaki tabloda, WebView'ın web içeriğinin stilini ve uygulamanızın koşullarını dikkate alarak uygulamanızdaki web içeriğini nasıl oluşturduğu açıklanmaktadır:

Uygulama koşulları prefers-color-scheme kullanan web içeriği prefers-color-scheme kullanılmayan web içeriği
Uygulama, isLightTheme olarak ayarlanmış veya ayarlanmamış açık bir tema kullanıyor.true WebView, içeriği, içerik yazarının tanımladığı açık temayla oluşturur. WebView, içeriği içerik yazarı tarafından tanımlanan varsayılan stil ile oluşturur.
Uygulama, zorunlu koyu mod'u kullanarak algoritmik olarak koyu tema uyguluyor. WebView, içeriği, içerik yazarının tanımladığı koyu tema ile oluşturur. İçerik yazarı izin verirse WebView, içeriği algoritma kullanılarak oluşturulan koyu tema ile oluşturur.
Uygulama, isLightTheme false olarak ayarlanmış bir koyu tema kullanıyor ve uygulama, WebView için algoritmik koyulaştırmaya izin vermiyor. WebView, içeriği, içerik yazarının tanımladığı koyu tema ile oluşturur. WebView, içeriği içerik yazarı tarafından tanımlanan varsayılan stil ile oluşturur.
Uygulama, isLightTheme false olarak ayarlanmış bir koyu tema kullanıyor ve uygulama WebView için algoritmik koyulaştırmaya izin veriyor. WebView, içeriği, içerik yazarının tanımladığı koyu tema ile oluşturur. İçerik yazarı izin verirse WebView, içeriği bir algoritma kullanılarak oluşturulan koyu tema ile oluşturur.

İçerik yazarı stili

Bir uygulamanın isLightTheme özelliği, uygulamanın temasının açık mı yoksa koyu mu olduğunu gösterir. WebView, prefers-color-scheme değerini her zaman isLightTheme değerine göre ayarlar. isLightTheme değeri true ise veya belirtilmemişse prefers-color-scheme değeri light olur. Aksi takdirde dark olur.

Bu, web içeriğinde prefers-color-scheme kullanılıyorsa ve içerik yazarı buna izin veriyorsa uygulamanın temasıyla eşleşmesi için içerik yazarı tarafından tanımlanan açık veya koyu temanın web içeriğine her zaman otomatik olarak uygulanacağı anlamına gelir.

Algoritmik karartma

Web içeriğinin prefers-color-scheme kullanmadığı durumlarda uygulamanız, gerektiğinde WebView'un oluşturduğu web içeriğine algoritmik olarak koyu tema uygulamasını sağlayabilir.

Uygulamanız, uygulama düzeyinde zorunlu koyu modu kullanarak uygulamanıza algoritmik olarak koyu tema uyguluyorsa zorunlu koyu mod ile web içeriği için algoritmik koyulaştırmaya izin verme başlıklı bölümü inceleyin.

Uygulamanızda zorunlu koyu mod kullanılmıyorsa uygulamanızın WebView'da algoritmik karartmaya ne zaman izin vereceğini belirtme şekli, uygulamanızın hedef API düzeyine bağlıdır. Ayrıntılı bilgi için Android 13 veya sonraki sürümleri hedefleyen uygulamalar ve Android 12 veya önceki sürümleri hedefleyen uygulamalar ile ilgili aşağıdaki bölümlere bakın.

Zorunlu koyu mod ile web içeriklerinde algoritmik karartmaya izin verme

Uygulamanız uygulama düzeyinde zorunlu koyu mod özelliğini kullanıyorsa WebView, aşağıdaki koşullar karşılandığında web içeriğine algoritmik koyulaştırma uygular:

  • WebView ve üst öğeleri, zorunlu koyu moda izin veriyor.
  • Geçerli etkinlik teması, isLightTheme değeri true olarak ayarlanarak açık olarak işaretlenir.
  • Web içeriği yazarı, karartmayı açıkça devre dışı bırakmamışsa.
  • Android 13'ü (API düzeyi 33) veya sonraki sürümleri hedefleyen uygulamalarda web içeriği prefers-color-scheme kullanmaz.
  • Android 12'yi (API düzeyi 32) veya önceki sürümleri hedefleyen uygulamalar için: Uygulama, WebView'ın forceDarkMode ayarını FORCE_DARK_AUTO olarak ve zorunlu koyu mod stratejisini DARK_STRATEGY_USER_AGENT_DARKENING_ONLY olarak ayarlamış olmalıdır.

WebView ve tüm üst öğeleri, View.setForceDarkAllowed() kullanılarak koyu temayı zorunlu kılmaya izin verebilir. Varsayılan değer, Android temasının setForceDarkAllowed() özelliğinden alınır. Bu özellik de true olarak ayarlanmalıdır.

Zorunlu Koyu Mod, öncelikle kendi koyu temasını sunmayan uygulamalarda geriye dönük uyumluluk için sağlanır. Uygulamanızda zorunlu koyu mod kullanıyorsanız koyu tema desteği eklemenizi öneririz.

Algoritmik karartmaya izin ver (Android 13 veya sonraki sürümleri hedefleyen uygulamalar)

Uygulama düzeyinde zorunlu koyu modu kullanmayan ve Android 13'ü (API düzeyi 33) veya sonraki sürümleri hedefleyen uygulamalar için Jetpack Webkit setAlgorithmicDarkeningAllowed() yöntemini kullanın ve bir WebView'ın algoritmik karartmaya izin vermesi gerektiğini belirtmek için true değerini iletin. Bu yöntem, önceki Android sürümleriyle geriye dönük uyumludur.

WebView, aşağıdaki koşullar karşılandığında algoritmik karartma uygular:

  • Web içeriğinde prefers-color-scheme kullanılmıyor.
  • Web içeriği yazarı, karartmayı açıkça devre dışı bırakmamışsa.

Algoritmik karartmaya izin ver (Android 12 veya daha eski sürümleri hedefleyen uygulamalar)

Uygulama düzeyinde zorunlu koyu modu kullanmayan ve Android 12'yi (API düzeyi 32) veya daha eski bir sürümü hedefleyen uygulamalarda algoritmik karartmaya izin vermek için FORCE_DARK_ON kullanın.

Uygulamanız, açık ve koyu temalar arasında geçiş yapmak için kendi yöntemini (ör. kullanıcı arayüzünde açılıp kapatılabilen bir öğe veya otomatik zaman tabanlı seçim) sunuyorsa FORCE_DARK_ON ile birlikte FORCE_DARK_OFF simgesini kullanın.

Özelliğin desteklenip desteklenmediğini kontrol etmek için WebView nesnenizi yapılandırdığınız her yere (ör. Activity.onCreate) aşağıdaki kod satırlarını ekleyin:

Kotlin

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    WebSettingsCompat.setForceDark(...)
}

Java

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK)) {
    WebSettingsCompat.setForceDark(...);
}

Uygulamanız, sistem tercihlerindeki değişiklikleri algılamaya dayanıyorsa tema değişikliklerini açıkça dinlemeli ve bunları FORCE_DARK_ON ve FORCE_DARK_OFF durumlarıyla WebView'a uygulamalıdır.

Aşağıdaki kod snippet'inde tema biçiminin nasıl değiştirileceği gösterilmektedir:

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

Koyu tema kullanımını özelleştirme

Karartmanın belirli bir WebView'a nasıl uygulanacağını kontrol etmek için Jetpack kitaplığındaki ForceDarkStrategy API'yi de kullanabilirsiniz. Bu API yalnızca koyu tema zorunlu kılma FORCE_DARK_ON veya FORCE_DARK_AUTO olarak ayarlanmışsa geçerlidir.

Uygulamanız, API'yi kullanarak web teması karartma veya kullanıcı aracısı karartma özelliklerinden birini kullanabilir:

  • Web teması karartma: Web geliştiriciler, koyu modda web sayfasının görünümünü kontrol etmek için @media (prefers-color-scheme: dark) uygulayabilir. WebView, içeriği bu ayarlara göre oluşturur. Web teması karartma hakkında daha fazla bilgi için spesifikasyon bölümüne bakın.
  • Kullanıcı aracısı karartma: WebView, web sayfasının renklerini otomatik olarak tersine çevirir. Kullanıcı aracısı karartma kullanıyorsanız @media (prefers-color-scheme: dark) sorgusu false olarak değerlendirilir.

İki strateji arasında seçim yapmak için aşağıdaki API'yi kullanın:

Kotlin

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK_STRATEGY)) {
    WebSettingsCompat.setForceDarkStrategy(...)
}

Java

if (WebViewFeature.isFeatureSupported(WebViewFeature.FORCE_DARK_STRATEGY)) {
    WebSettingsCompat.setForceDarkStrategy(...);
}

Desteklenen strateji seçenekleri şunlardır:

  • DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING: Bu, varsayılan seçenektir. Çoğu tarayıcı <meta name="color-scheme" content="dark light"> etiketini isteğe bağlı olarak değerlendirse de Android WebView'ın varsayılan modu, meta etiketinin web sayfasının prefers-color-scheme medya sorgularına uymasını gerektirir. Web Görünümlerini DARK_STRATEGY_WEB_THEME_DARKENING_ONLY moduyla kullanabilirsiniz. Bu durumda, etiket atlanmış olsa bile WebView her zaman medya sorgularını uygular.

    Ancak, web geliştiricilerin içeriklerin varsayılan yapılandırmaya sahip WebView'larda doğru şekilde oluşturulmasını sağlamak için web sitelerine <0x0x0A><meta name="color-scheme" content="dark light"> etiketini eklemelerini öneririz.

  • DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: WebView,"kullanıcı aracısı karartma" olarak adlandırılan bu özellik sayesinde web sayfalarındaki karartma ayarlarını yok sayar ve otomatik karartma uygular.

Uygulamanızda prefers-color-scheme medya sorgusuyla özelleştirdiğiniz birinci taraf web içeriği gösteriliyorsa WebView'ın özel temayı kullandığından emin olmanızı öneririz.DARK_STRATEGY_WEB_THEME_DARKENING_ONLY

Koyu temanın uygulandığı bir örnek için GitHub'daki WebView demosuna bakın.