تعتيم محتوى الويب في 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، ولا يسمح التطبيق باستخدام المظهر الداكن الخوارزميات في 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 عند الضرورة بتطبيق مظهر داكن على محتوى الويب الذي يعرضه باستخدام الخوارزميات.

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

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

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

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

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

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

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

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

بالنسبة إلى التطبيقات التي لا تستخدم ميزة فرض المظهر الداكن على مستوى التطبيق وتستهدف Android 13 (المستوى 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"> على أنّها اختيارية، يتطلّب الوضع التلقائي في WebView في نظام التشغيل Android أن تتعامل العلامة الوصفية مع طلبات البحث عن الوسائط في 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.