تعتيم محتوى الويب في 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 على مستوى واجهة برمجة التطبيقات المستهدف لتطبيقك. يُرجى الاطّلاع على الأقسام التالية لمعرفة التفاصيل حول التطبيقات التي تستهدف Android 13 أو الإصدارات الأحدث و التطبيقات التي تستهدف Android 12 أو الإصدارات الأقدم.

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

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

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

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

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

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

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

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

• لا يستخدم محتوى الويب prefers-color-scheme.
• لا يوقف منشئ محتوى الويب التعتيم بشكلٍ صريح.

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

بالنسبة إلى التطبيقات التي لا تستخدم ميزة "فرض المظهر الداكن" على مستوى التطبيق وتستهدف Android 12 (المستوى 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 في مكتبة Jetpack للتحكّم في كيفية تطبيق التعتيم على 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's أن تلتزم العلامة الوصفية بطلبات البحث عن الوسائط prefers-color-scheme في صفحة الويب. يمكنك استخدام WebViews مع DARK_STRATEGY_WEB_THEME_DARKENING_ONLY وضع، وفي هذه الحالة يطبّق WebView دائمًا طلبات البحث عن الوسائط حتى إذا تم حذف العلامة.

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

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

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

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