تعتيم محتوى الويب في 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، يعرض WebView المحتوى مع المظهر الداكن الذي يتم إنشاؤه باستخدام خوارزمية.
يستخدم التطبيق مظهرًا داكنًا مع isLightTheme يتم ضبطها على false ولا يسمح التطبيق باستخدام الخوارزميات معتمة لـ WebView. يعرض WebView المحتوى بالمظهر الداكن الذي الذي حدّده مؤلف المحتوى. يعرض WebView المحتوى بالنمط التلقائي المحدّد من خلال مؤلف المحتوى.
يستخدم التطبيق مظهرًا داكنًا مع isLightTheme القيمة على false ويتيح التطبيق التعتيم الخوارزمي على WebView يعرض WebView المحتوى بالمظهر الداكن الذي الذي حدّده مؤلف المحتوى. إذا كان مؤلف المحتوى يسمح بـ WebView، يعرض WebView المحتوى مع المظهر الداكن الذي يتم إنشاؤه باستخدام خوارزمية.

تصميم مؤلف المحتوى

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

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

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

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

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

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

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

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

  • يسمح WebView وعناصره الرئيسية بـ "فرض المظهر الداكن".
  • يظهر موضوع النشاط الحالي على أنّه فاتح اللون تم ضبط isLightTheme على true
  • لا يوقف مؤلف محتوى الويب التعتيم على نحو صريح.
  • بالنسبة إلى التطبيقات التي تستهدف الإصدار 13 من نظام التشغيل Android (المستوى 33 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، يجب أن يكون محتوى الويب لا تستخدم prefers-color-scheme.
  • بالنسبة إلى التطبيقات التي تستهدف الإصدار 12 من نظام التشغيل Android (المستوى 32 لواجهة برمجة التطبيقات) أو الإصدارات الأقدم: ضبط التطبيق إعداد forceDarkMode في WebView إلى FORCE_DARK_AUTO وعيّنت إستراتيجية Force Dark على 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 في 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