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

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

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

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

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

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

با استفاده از Force Dark، تاریک شدن الگوریتمی محتوای وب را امکان‌پذیر کنید

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

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

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

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

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

برای برنامه‌هایی که از Force Dark در سطح برنامه استفاده نمی‌کنند و اندروید ۱۳ (سطح API ۳۳) یا بالاتر را هدف قرار می‌دهند، از متد setAlgorithmicDarkeningAllowed() در Jetpack Webkit استفاده کنید و مقدار true را برای مشخص کردن اینکه یک WebView باید امکان تاریک‌سازی الگوریتمی را فراهم کند، به آن بدهید. این متد با نسخه‌های قبلی اندروید سازگاری معکوس دارد.

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

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

اجازه تاریک شدن الگوریتمی (برنامه‌هایی که اندروید ۱۲ یا پایین‌تر را هدف قرار می‌دهند)

برای برنامه‌هایی که از حالت تاریک اجباری در سطح برنامه استفاده نمی‌کنند و اندروید ۱۲ (سطح API ۳۲) یا پایین‌تر را هدف قرار می‌دهند، 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(...);
}

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

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

کاتلین 

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

سفارشی‌سازی مدیریت تم تیره

همچنین می‌توانید از API مربوط به ForceDarkStrategy در کتابخانه Jetpack برای کنترل نحوه اعمال تیرگی به یک WebView مشخص استفاده کنید. این API فقط در صورتی قابل اجرا است که Force Dark روی FORCE_DARK_ON یا FORCE_DARK_AUTO تنظیم شده باشد.

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

  • تیره کردن تم وب : توسعه‌دهندگان وب ممکن است از @media (prefers-color-scheme: dark) برای کنترل ظاهر صفحه وب در حالت تاریک استفاده کنند. 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 صفحه وب پشتیبانی کند. می‌توانید از WebViewها با حالت 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 مراجعه کنید.