محتوای وب را در WebView تیره کنید

در اندروید 10 و بالاتر، یک برنامه می‌تواند از یک تم تیره پشتیبانی کند و به‌طور خودکار بین تم‌های روشن و تاریک برنامه با توجه به موضوع سیستم تغییر کند. برای مطابقت با موضوع برنامه فعلی، محتوای وب در WebView همچنین می‌تواند از سبک روشن، تاریک یا پیش‌فرض استفاده کند.

رفتار WebView با استانداردهای وب prefers-color-scheme و color-scheme تداخل دارد. در صورت امکان، اگر محتوای وب را می‌نویسید که می‌خواهید برنامه شما در WebView نمایش دهد، باید یک تم تیره برای وب‌سایت خود تعریف کنید و prefers-color-scheme پیاده‌سازی کنید تا WebView بتواند موضوع محتوای وب را با موضوع برنامه شما مطابقت دهد.

جدول زیر نحوه نمایش WebView از محتوای وب را در برنامه شما، بسته به سبک محتوای وب و شرایط برنامه، شرح می دهد:

شرایط برنامه	محتوای وب که از prefers-color-scheme	محتوای وب که prefers-color-scheme استفاده نمی کند
برنامه از یک طرح زمینه روشن استفاده می کند که isLightTheme روی true یا تنظیم نشده تنظیم شده است.	WebView محتوا را با موضوع روشن ارائه می کند نویسنده محتوا تعریف کرده است.	WebView محتوا را با سبک پیش فرض تعریف شده توسط نویسنده محتوا ارائه می کند.
برنامه از Force Dark برای اعمال الگوریتمی تم تیره به برنامه استفاده می کند.	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 اجازه دهد تا به صورت الگوریتمی یک تم تیره را برای محتوای وب که ارائه می‌کند اعمال کند.

اگر برنامه شما از Force Dark سطح برنامه برای اعمال الگوریتمی تم تیره روی برنامه شما استفاده می‌کند، بخش زیر را ببینید که نحوه اجازه دادن به تاریکی الگوریتمی برای محتوای وب با استفاده از تاریکی اجباری را توضیح می‌دهد.

اگر برنامه شما از Force Dark استفاده نمی‌کند، نحوه تعیین زمان مجاز تاریک‌سازی الگوریتمی در WebView به سطح API هدف برنامه شما بستگی دارد. برای جزئیات بیشتر، برای برنامه‌هایی که Android 13 یا بالاتر را هدف قرار می‌دهند و برنامه‌هایی که Android 12 یا پایین‌تر را هدف قرار می‌دهند، به بخش‌های زیر مراجعه کنید.

تاریک کردن الگوریتمی برای محتوای وب با تاریکی اجباری مجاز است

اگر برنامه شما از Force Dark در سطح برنامه استفاده می‌کند، WebView در صورت وجود شرایط زیر، تاریک‌سازی الگوریتمی را برای محتوای وب اعمال می‌کند:

• WebView و عناصر والد آن به Force Dark اجازه می دهد.
• طرح زمینه فعالیت فعلی به عنوان روشن با isLightTheme روی true علامت گذاری شده است.
• نویسنده محتوای وب به صراحت تاریک شدن را غیرفعال نمی کند.
• برای برنامه‌هایی که Android 13 (سطح API 33) یا بالاتر را هدف قرار می‌دهند، محتوای وب prefers-color-scheme استفاده نمی‌کند.
• برای برنامه‌هایی که Android 12 (سطح API 32) یا پایین‌تر را هدف قرار می‌دهند: برنامه تنظیمات forceDarkMode WebView را روی FORCE_DARK_AUTO تنظیم کرده است و استراتژی تاریکی اجباری خود را روی DARK_STRATEGY_USER_AGENT_DARKENING_ONLY تنظیم کرده است.

WebView و تمام والدین آن می توانند با استفاده از View.setForceDarkAllowed() اجازه تاریکی را بدهند. مقدار پیش‌فرض از ویژگی setForceDarkAllowed() تم اندروید گرفته شده است که باید روی true نیز تنظیم شود.

حالت تاریک اجباری در درجه اول برای سازگاری با عقب در برنامه‌هایی که تم تاریک خود را ارائه نمی‌دهند ارائه می‌شود. اگر برنامه شما از Force Dark استفاده می‌کند، توصیه می‌کنیم از یک تم تیره پشتیبانی اضافه کنید .

تاریک‌سازی الگوریتمی مجاز است (برنامه‌هایی که اندروید 13 یا بالاتر را هدف قرار می‌دهند)

برای برنامه‌هایی که از Force Dark در سطح برنامه استفاده نمی‌کنند و Android 13 (سطح API 33) یا بالاتر را هدف قرار می‌دهند، از متد AndroidX setAlgorithmicDarkeningAllowed() استفاده کنید و به true ارسال کنید تا مشخص کنید WebView باید تاریک‌سازی الگوریتمی را مجاز کند. این روش با نسخه های قبلی اندروید سازگاری دارد.

سپس WebView در صورت وجود شرایط زیر، تاریک‌سازی الگوریتمی را اعمال می‌کند:

• محتوای وب از prefers-color-scheme استفاده نمی کند.
• نویسنده محتوای وب به صراحت تاریک شدن را غیرفعال نمی کند.

تاریک‌سازی الگوریتمی مجاز است (برنامه‌هایی که Android 12 یا پایین‌تر را هدف قرار می‌دهند)

برای برنامه‌هایی که از Force Dark در سطح برنامه استفاده نمی‌کنند و Android 12 (سطح API 32) یا پایین‌تر را هدف قرار می‌دهند، از FORCE_DARK_ON برای تاریک‌سازی الگوریتمی استفاده کنید.

اگر برنامه شما روش خاص خود را برای جابه‌جایی بین تم‌های روشن و تاریک ارائه می‌دهد، از FORCE_DARK_ON همراه با FORCE_DARK_OFF ، مانند یک عنصر قابل تغییر در رابط کاربری یا انتخاب خودکار مبتنی بر زمان.

برای بررسی اینکه آیا این ویژگی پشتیبانی می‌شود، خطوط کد زیر را در هر کجا که شی WebView خود را پیکربندی می‌کنید، مانند Activity.onCreate اضافه کنید:

کاتلین

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

جاوا

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

اگر برنامه شما متکی به تشخیص تغییرات در تنظیمات برگزیده سیستم است، برنامه شما باید صراحتاً به تغییرات تم گوش دهد و این تغییرات را در WebView با حالت‌های FORCE_DARK_ON و FORCE_DARK_OFF اعمال کند.

قطعه کد زیر نحوه تغییر قالب تم را نشان می دهد:

کاتلین

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 -> {
            //
        }
    }
}

جاوا

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 خاص استفاده کنید. این API فقط در صورتی قابل اجرا است که تاریکی اجباری روی FORCE_DARK_ON یا FORCE_DARK_AUTO تنظیم شده باشد.

با استفاده از API، برنامه شما می‌تواند از تیره کردن تم وب یا تاریک کردن عامل کاربر استفاده کند:

• تاریک شدن تم وب : توسعه دهندگان وب ممکن است از @media (prefers-color-scheme: dark) برای کنترل ظاهر صفحه وب در حالت تاریک استفاده کنند. WebView محتوا را مطابق این تنظیمات ارائه می کند. برای اطلاعات بیشتر در مورد تیره کردن تم وب، مشخصات را ببینید.
• تاریک شدن عامل کاربر : WebView به طور خودکار رنگ های صفحه وب را معکوس می کند. اگر از تاریک کردن عامل کاربر استفاده می‌کنید، پرس و جو @media (prefers-color-scheme: dark) به false ارزیابی می‌شود.

برای انتخاب بین این دو استراتژی، از API زیر استفاده کنید:

کاتلین

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

جاوا

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 صفحه وب را رعایت کند. می‌توانید از 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 سفارشی کرده اید، برای اطمینان از اینکه WebView از طرح زمینه سفارشی استفاده می کند، DARK_STRATEGY_WEB_THEME_DARKENING_ONLY را توصیه می کنیم.

برای نمونه ای از تم تیره اعمال شده، به نسخه نمایشی WebView در GitHub مراجعه کنید