تیره کردن محتوای وب در «وب‌نما»

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

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

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

شرایط برنامه	محتوای وبی که از prefers-color-scheme استفاده می‌کند	محتوای وبی که از prefers-color-scheme استفاده نمی‌کند
برنامه از زمینه روشن استفاده می‌کند و isLightTheme روی true تنظیم شده است یا تنظیم نشده است.	WebView محتوا را با زمینه روشنی که نویسنده محتوا تعریف کرده است ارائه می‌دهد.	«وب‌نما» محتوا را با سبک پیش‌فرضی که نویسنده محتوا تعریف کرده است ارائه می‌دهد.
برنامه از حالت تاریک اجباری برای اعمال الگوریتمی زمینه تیره به برنامه استفاده می‌کند.	WebView محتوا را با زمینه تیره که نویسنده محتوا تعریف کرده است ارائه می‌کند.	اگر نویسنده محتوا اجازه دهد، WebView محتوا را با زمینه تیره که بااستفاده از الگوریتم تولید شده است ارائه می‌کند.
برنامه از زمینه تیره با isLightTheme تنظیم‌شده روی false استفاده می‌کند و برنامه اجازه تیره کردن الگوریتمی برای 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 (سطح میانای برنامه‌سازی کاربردی ۳۳) یا بالاتر را هدف قرار می‌دهند، محتوای وب از prefers-color-scheme استفاده نمی‌کند.
• برای برنامه‌هایی که Android 12 (سطح میانای برنامه‌سازی کاربردی ۳۲) یا پایین‌تر را هدف قرار می‌دهند: برنامه تنظیم WebViewforceDarkMode را روی FORCE_DARK_AUTO تنظیم کرده است و استراتژی «حالت تاریک اجباری» خود را روی DARK_STRATEGY_USER_AGENT_DARKENING_ONLY تنظیم کرده است.

«وب‌نما» و همه والدین آن می‌توانند بااستفاده از View.setForceDarkAllowed() حالت تاریک اجباری را مجاز کنند. مقدار پیش‌فرض از مشخصه setForceDarkAllowed() در زمینه Android گرفته می‌شود که باید روی true نیز تنظیم شود.

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

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

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

سپس اگر شرایط زیر برقرار باشد، «وب‌نما» تاریک‌سازی الگوریتمی را اعمال می‌کند:

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

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

برای برنامه‌هایی که از «حالت تاریک اجباری» در سطح برنامه استفاده نمی‌کنند و Android 12 (سطح میانای برنامه‌سازی کاربردی 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(...);
}

اگر برنامه شما به تشخیص تغییرات در اولویت‌های سیستم متکی است، برنامه‌تان باید به‌طور صریح به تغییرات زمینه گوش دهد و آن‌ها را با حالت‌های 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;
    }
}

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

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

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

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

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

کاتلین

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 صفحه وب به متا تگ نیاز دارد. می‌توانید از «وب‌نماها» با حالت DARK_STRATEGY_WEB_THEME_DARKENING_ONLY استفاده کنید، که در این صورت «وب‌نما» همیشه پُرسمان‌های رسانه را اعمال می‌کند حتی اگر برچسب حذف شده باشد.

  بااین‌حال، به توسعه‌دهندگان وب توصیه می‌کنیم برچسب <meta name="color-scheme" content="dark light"> را به وب‌سایت‌هایشان اضافه کنند تا مطمئن شوند محتوا به‌درستی در «وب‌نماها» با پیکربندی پیش‌فرض ارائه می‌شود.

• DARK_STRATEGY_USER_AGENT_DARKENING_ONLY: به‌نام «تیره کردن نماینده کاربر»، WebView هرگونه تیره کردن صفحه وب را نادیده می‌گیرد و تیره کردن خودکار را اعمال می‌کند.

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

برای مشاهده نمونه‌ای از اعمال زمینه تیره، نمونه نمای وب در GitHub را ببینید