تعتيم محتوى الويب في WebView

في نظام التشغيل Android 10 والإصدارات الأحدث، يمكن للتطبيق أن يتوافق مع المظهر الداكن والتغيير تلقائيًا بين المظهرَين الفاتح والداكن حسب مظهر النظام. ولمطابقة المظهر الحالي للتطبيق، يمكن أيضًا لمحتوى الويب في WebView استخدام التصميم الفاتح أو الداكن أو التلقائي.

يتكامل سلوك WebView مع معيارَي الويب prefers-color-scheme وcolor-scheme. إذا كنت مؤلف محتوى الويب الذي تريد أن يعرضه تطبيقك في WebView، عليك تحديد مظهر داكن لموقعك الإلكتروني و تنفيذ prefers-color-scheme حتى تتمكّن WebView من مطابقة مظهر محتوى الويب مع مظهر تطبيقك.

يوضّح الجدول التالي كيفية عرض WebView لمحتوى الويب في تطبيقك، استنادًا إلى أسلوب محتوى الويب وشروط تطبيقك:

شروط التطبيق محتوى الويب الذي يستخدم prefers-color-scheme محتوى ويب لا يستخدم prefers-color-scheme
يستخدم التطبيق مظهرًا فاتحًا تم ضبط isLightTheme عليه على true أو لم يتم ضبطه. يعرض WebView المحتوى باستخدام المظهر الفاتح الذي حدَّده مؤلف المحتوى. يعرض WebView المحتوى باستخدام التصميم التلقائي الذي حدّده مؤلّف المحتوى.
يستخدم التطبيق فرض المظهر الداكن لتطبيق مظهر داكن بشكل آلي على التطبيق. يعرض WebView المحتوى باستخدام المظهر الداكن الذي حدَّده مؤلف المحتوى. إذا سمح مؤلف المحتوى بذلك، يعرض WebView المحتوى باستخدام مظهر داكن يتم إنشاؤه باستخدام خوارزمية.
يستخدم التطبيق مظهرًا داكنًا مع isLightTheme تم ضبطه على false ولا يسمح التطبيق باستخدام أسلوب algorithmic لتفعيل المظهر الداكن في WebView. يعرض WebView المحتوى باستخدام المظهر الداكن الذي حدَّده مؤلف المحتوى. يعرض WebView المحتوى بالنمط التلقائي الذي حدّده مؤلف المحتوى.
يستخدم التطبيق مظهرًا داكنًا مع isLightTheme تم ضبطه على false والتطبيق يسمح باستخدام الخوارزميات لتفعيل المظهر الداكن في WebView. يعرض WebView المحتوى باستخدام المظهر الداكن الذي حدَّده مؤلف المحتوى. إذا سمح مؤلف المحتوى بذلك، يعرض WebView المحتوى باستخدام مظهر داكن يتم إنشاؤه باستخدام خوارزمية.

تنسيق مؤلف المحتوى

تشير سمة isLightTheme للتطبيق إلى ما إذا كان مظهر التطبيق فاتحًا أو داكنًا. يضبط WebView دائمًا prefers-color-scheme وفقًا لـ isLightTheme. إذا كانت قيمة isLightTheme هي true أو لم يتم تحديدها، تكون قيمة prefers-color-scheme هي light، وإلا ستكون dark.

وهذا يعني أنّه إذا كان محتوى الويب يستخدم prefers-color-scheme وسمح مؤلف المحتوى بذلك، يتم دائمًا تطبيق المظهر الفاتح أو الداكن الذي حدّده مؤلف المحتوى تلقائيًا على محتوى الويب لمطابقة مظهر التطبيق.

تعتيم خوارزميات

لتغطية الحالات التي لا يستخدم فيها محتوى الويب علامة prefers-color-scheme، يمكن لتطبيقك السماح لمكوّن WebView، عند الضرورة، بتطبيق أسلوب برمجيًا لتطبيق theme داكن على محتوى الويب الذي يعرضه.

إذا كان تطبيقك يستخدم ميزة Force Dark على مستوى التطبيق لتطبيق مظهر داكن على تطبيقك باستخدام الخوارزميات، اطّلِع على القسم التالي الذي يصف كيفية السماح بتطبيق مظهر داكن على محتوى الويب باستخدام ميزة Force Dark.

إذا كان تطبيقك لا يستخدم "فرض المظهر الداكن"، تستند طريقة تطبيقك إلى مستوى واجهة برمجة التطبيقات المستهدَف في تطبيقك. اطّلِع على الأقسام التالية لمعرفة تفاصيل عن التطبيقات التي تستهدف الإصدار 13 من نظام التشغيل Android أو الإصدارات الأحدث والتطبيقات التي تستهدف الإصدار 12 من نظام التشغيل Android أو الإصدارات الأقدم.

السماح بالتعتيم الخوارزمي لمحتوى الويب باستخدام فرض المظهر الداكن

إذا كان تطبيقك يستخدم فرض الوضع الداكن على مستوى التطبيق، يطبّق WebView ميزة تعتيم المحتوى استنادًا إلى الخوارزميات على محتوى الويب في حال استيفاء الشروط التالية:

  • يسمح WebView والعناصر الرئيسية له بتطبيق ميزة "فرض المظهر الداكن".
  • تم وضع علامة على مظهر النشاط الحالي على أنّه فاتح مع ضبط isLightTheme على true.
  • عدم إيقاف ميزة "تعتيم الشاشة" صراحةً من قِبل مؤلف محتوى الويب
  • بالنسبة إلى التطبيقات التي تستهدف الإصدار 13 من نظام التشغيل Android (المستوى 33 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، لا يستخدم محتوى الويبprefers-color-scheme.
  • بالنسبة إلى التطبيقات التي تستهدف الإصدار 12 من نظام التشغيل Android (المستوى 32 لواجهة برمجة التطبيقات) أو الإصدارات الأقدم: ضبط التطبيق إعداد forceDarkMode في WebView على FORCE_DARK_AUTO وضبط استراتيجية "فرض المظهر الداكن" على DARK_STRATEGY_USER_AGENT_DARKENING_ONLY.

يمكن أن يسمح WebView وجميع عناصره الرئيسية بفرض المظهر الداكن باستخدام View.setForceDarkAllowed(). يتم الحصول على القيمة التلقائية من سمة setForceDarkAllowed() في مظهر Android، والتي يجب ضبطها أيضًا على true.

يتم توفير ميزة "فرض الوضع الداكن" في المقام الأول لضمان التوافق مع الإصدارات القديمة في التطبيقات التي لا توفّر مظهرًا داكنًا خاصًا بها. إذا كان تطبيقك يستخدم ميزة "فرض المظهر الداكن"، ننصحك بإتاحة المظهر الداكن.

السماح بتفعيل ميزة "التعتيم الآلي" (التطبيقات التي تستهدف الإصدار 13 من نظام التشغيل Android أو الإصدارات الأحدث)

بالنسبة إلى التطبيقات التي لا تستخدم سياسة "فرض المظهر الداكن" على مستوى التطبيق وتستهدف الإصدار 13 من نظام التشغيل Android (المستوى 33 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، استخدِم طريقة AndroidX setAlgorithmicDarkeningAllowed() ومرر في true لتحديد أنّ WebView يجب أن يسمح بتعتيم الخوارزميات. تتوافق هذه الطريقة مع الإصدارات السابقة من Android.

بعد ذلك، يطبّق WebView ميزة التعتيم الآلي في حال استيفاء الشروط التالية:

  • لا يستخدم محتوى الويب prefers-color-scheme.
  • عدم إيقاف ميزة "تعتيم الشاشة" صراحةً من قِبل مؤلف محتوى الويب

السماح بالتعتيم الخوارزمي (التطبيقات التي تستهدف الإصدار 12 من نظام التشغيل Android أو الإصدارات الأقدم)

بالنسبة إلى التطبيقات التي لا تستخدم ميزة "فرض الوضع الداكن" على مستوى التطبيق والتي تستهدف الإصدار 12 من Android (المستوى 32 لواجهة برمجة التطبيقات) أو الإصدارات الأقدم، استخدِم FORCE_DARK_ON للسماح بتطبيق الخوارزميات على الوضع الداكن.

استخدِم FORCE_DARK_ON مع FORCE_DARK_OFF إذا كان تطبيقك يقدّم طريقة خاصة به للتبديل بين المظهرَين الفاتح والداكن، مثل عنصر قابل للتبديل في واجهة المستخدم أو اختيار تلقائي يستند إلى الوقت.

للتحقّق مما إذا كانت الميزة متاحة، أضِف سطور الرمز التالية أينما أعددت عنصر WebView، مثلاً في Activity.onCreate:

Kotlin

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

Java

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

إذا كان تطبيقك يعتمد على اكتشاف التغييرات التي تطرأ على الإعدادات المفضّلة للنظام، يجب أن يصغي تطبيقك بوضوح إلى تغييرات المظهر ويطبّقها على WebView الذي يتضمّن الحالتين FORCE_DARK_ON وFORCE_DARK_OFF.

يوضّح المقتطف التالي من الرمز كيفية تغيير تنسيق المظهر:

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

تخصيص طريقة التعامل مع المظهر الداكن

يمكنك أيضًا استخدام ForceDarkStrategy API في AndroidX للتحكّم في كيفية تطبيق الوضع الداكن على WebView معيّن. لا تنطبق واجهة برمجة التطبيقات هذه إلا في حال ضبط ميزة "فرض وضع الظلام" على FORCE_DARK_ON أو FORCE_DARK_AUTO.

باستخدام واجهة برمجة التطبيقات، يمكن لتطبيقك استخدام خيار "تعتيم مظهر الويب" أو تعتيم وكيل المستخدم:

  • تعتيم مظهر الويب: قد يطبّق مطوّرو الويب @media (prefers-color-scheme: dark) للتحكّم في مظهر صفحة الويب في الوضع الداكن. يعرض WebView المحتوى وفقًا لهذه الإعدادات. لمزيد من المعلومات عن تعتيم مظهر الويب، يُرجى الاطّلاع على المواصفات.
  • تعتيم وكيل المستخدم: يعكس WebView تلقائيًا ألوان صفحة الويب. في حال استخدام ميزة إخفاء وكيل المستخدم، يتم تقييم طلب البحث @media (prefers-color-scheme: dark) على أنّه false.

للاختيار من بين الاستراتيجيتَين، استخدِم واجهة برمجة التطبيقات التالية:

Kotlin

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

Java

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

في ما يلي خيارات الاستراتيجيات المتوافقة:

  • DARK_STRATEGY_PREFER_WEB_THEME_OVER_USER_AGENT_DARKENING: هذا هو الخيار التلقائي. على الرغم من أنّ معظم المتصفّحات تتعامل مع علامة <meta name="color-scheme" content="dark light"> على أنّها اختيارية، يتطلّب الوضع التلقائي لواجهة Android WebView أن تلتزم العلامة الوصفية بطلبات البحث عن الوسائط في prefers-color-scheme صفحة الويب. يمكنك استخدام مكوّنات WebView مع وضع DARK_STRATEGY_WEB_THEME_DARKENING_ONLY ، وفي هذه الحالة يطبّق WebView دائمًا طلبات البحث عن الوسائط حتى إذا تم حذف العلامة.

    ومع ذلك، ننصح مطوّري برامج الويب بإضافة علامة <meta name="color-scheme" content="dark light"> إلى مواقعهم الإلكترونية لضمان عرض المحتوى بشكل صحيح في مكوّنات WebView من خلال الإعدادات التلقائية.

  • DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: يُعرف هذا الإجراء باسم "تعتيم وكيل المستخدم"، ويتجاهل WebView أيّ عملية تعتيم لصفحة الويب ويطبق التعتيم التلقائي.

إذا كان تطبيقك يعرض محتوى ويب تابعًا لجهة خارجية خصّصته باستخدام طلب الوسائط prefers-color-scheme، ننصحك DARK_STRATEGY_WEB_THEME_DARKENING_ONLY بضمان استخدام WebView للموضوع المخصّص.

للاطّلاع على مثال على تطبيق المظهر الداكن، يمكنك الاطّلاع على العرض التجريبي لـ WebView على GitHub.