پیاده‌سازی زمینه تیره

امتحان کردن روش Compose

Jetpack Compose جعبه‌ابزار واسط کاربر توصیه‌شده برای Android است. با نحوه کار با زمینه‌سازی در Compose آشنا شوید.

آرایش رنگ‌ها - Material Design 3 →

زمینه تیره در Android 10 (سطح API‏ ۲۹) و بالاتر دردسترس است. این ویژگی مزایای زیر را دارد:

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

«زمینه تیره» روی رابط کاربری سیستم Android و برنامه‌هایی که در دستگاه اجرا می‌شوند اعمال می‌شود.

سه روش برای فعال کردن زمینه تیره در Android نسخه ۱۰ و بالاتر وجود دارد:

• با رفتن به تنظیمات > نمایشگر > زمینه، از تنظیمات سیستم برای فعال کردن زمینه تیره استفاده کنید.
• وقتی فعال باشد، از کاشی «تنظیمات فوری» برای تغییر دادن زمینه‌ها از سینی اعلان استفاده کنید.
• در دستگاه‌های Pixel، حالت «بهینه‌سازی باتری» را فعال کنید تا زمینه تیره هم‌زمان فعال شود. ممکن است دستگاه‌های دیگر از این رفتار پشتیبانی نکنند.

برای دستورالعمل‌های مربوط به اعمال زمینه تیره در محتوای مبتنی بر وب بااستفاده از مؤلفه WebView، به تیره کردن محتوای وب در WebView مراجعه کنید.

پشتیبانی از زمینه تیره در برنامه

برای پشتیبانی از زمینه تیره، زمینه برنامه‌تان را (که معمولاً در res/values/styles.xml یافت می‌شود) طوری تنظیم کنید که از زمینه DayNight ارث‌بری کند:

<style name="AppTheme" parent="Theme.AppCompat.DayNight">

همچنین می‌توانید از زمینه تیره Material Components استفاده کنید:

<style name="AppTheme" parent="Theme.MaterialComponents.DayNight">

این کار زمینه اصلی برنامه را به پرچم‌های حالت شب تحت کنترل سیستم گره می‌زند و زمینه تیره پیش‌فرضی را به برنامه می‌دهد که فعال است.

زمینه و سبک

از رنگ‌ها یا نمادهای کدگذاری‌شده که برای استفاده در زمینه روشن درنظر گرفته شده‌اند استفاده نکنید. درعوض از مشخصه‌های زمینه یا منابع واجدشرایط شب استفاده کنید.

دو مشخصه زمینه برای زمینه تیره از همه مهم‌تر است:

• ‫?android:attr/textColorPrimary: رنگ نوشتار چندمنظوره. این رنگ در زمینه روشن تقریباً سیاه و در زمینه‌های تیره تقریباً سفید است. حاوی وضعیت غیرفعال است.
• ‫?attr/colorControlNormal: رنگ نماد چندمنظوره. حاوی وضعیت غیرفعال است.

توصیه می‌کنیم از مؤلفه‌های طراحی مواد استفاده کنید، زیرا سیستم زمینه‌سازی رنگ آن، مانند مشخصه‌های زمینه ?attr/colorSurface و ?attr/colorOnSurface، دسترسی آسان به رنگ‌های مناسب را فراهم می‌کند. می‌توانید این مشخصه‌ها را در زمینه‌تان سفارشی‌سازی کنید.

تغییر دادن زمینه‌ها در برنامه

می‌توانید به کاربران اجازه دهید زمینه برنامه را درحین اجرای برنامه تغییر دهند. گزینه‌های زیر توصیه می‌شود:

• روشن
• تیره
• پیش‌فرض سیستم (گزینه پیش‌فرض توصیه‌شده)

این گزینه‌ها مستقیماً به حالت‌های AppCompat.DayNight نگاشت می‌شوند:

• روشن: MODE_NIGHT_NO.

• تیره: MODE_NIGHT_YES.

• پیش‌فرض سیستم: MODE_NIGHT_FOLLOW_SYSTEM.

برای تغییر دادن زمینه، کارهای زیر را انجام دهید:

• در سطح میانای برنامه‌سازی کاربردی ۳۱ و بالاتر، از UiModeManager#setApplicationNightMode استفاده کنید تا سیستم بداند برنامه‌تان با چه زمینه‌ای اجرا می‌شود. این کار به سیستم اجازه می‌دهد زمینه را در صفحه اسپلش مطابقت دهد.

• در سطح میانای برنامه‌سازی کاربردی ۳۰ و پایین‌تر، از AppCompatDelegate.setDefaultNightMode() برای تغییر دادن زمینه استفاده کنید.

حالت تاریک اجباری

Android 10 حالت تیره اجباری را ارائه می‌دهد، ویژگی‌ای برای توسعه‌دهندگان تا به‌سرعت زمینه تیره را بدون تنظیم صریح زمینه DayNight پیاده‌سازی کنند.

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

برنامه‌ها باید با تنظیم android:forceDarkAllowed="true" در زمینه فعالیت، با «حالت تاریک اجباری» موافقت کنند. این مشخصه در همه زمینه‌های روشن ارائه‌شده توسط سیستم و AndroidX، مانند Theme.Material.Light، تنظیم شده است. وقتی از «حالت تاریک اجباری» استفاده می‌کنید، برنامه‌تان را به‌طور کامل آزمایش کنید و درصورت نیاز، نماها را مستثنی کنید.

اگر برنامه‌تان از زمینه تیره استفاده می‌کند، مثلاً Theme.Material)، «حالت تاریک اجباری» اعمال نمی‌شود. به‌طور مشابه، اگر زمینه برنامه‌تان از زمینه DayNight ارث‌بری کند، «حالت تاریک اجباری» به‌دلیل تعویض خودکار زمینه اعمال نمی‌شود.

غیرفعال کردن «حالت تاریک اجباری» در نما

«حالت تاریک اجباری» را می‌توان در نماهای خاص با ویژگی چیدمان android:forceDarkAllowed یا با setForceDarkAllowed() کنترل کرد.

محتوای وب

برای اطلاعات درباره استفاده از زمینه‌های تیره در محتوای مبتنی بر وب، به تیره کردن محتوای وب در WebView مراجعه کنید. برای نمونه‌ای از زمینه تیره اعمال‌شده در WebView، به نمونه نمایشی WebView در GitHub مراجعه کنید.

روال‌های مطلوب

بخش‌های زیر روال‌های مطلوب را برای پیاده‌سازی زمینه‌های تیره ارائه می‌دهند.

اعلان‌ها و ابزاره‌ها

برای سطوح میانای کاربری که در دستگاه نمایش می‌دهید اما مستقیماً کنترل نمی‌کنید، مطمئن شوید که هر نمایی که استفاده می‌کنید منعکس‌کننده زمینه برنامه میزبان باشد. دو نمونه از این موارد اعلان‌ها و ابزاره‌های راه‌انداز است.

اعلان‌ها

از الگوهای اعلان ارائه‌شده توسط سیستم، مانند MessagingStyle، استفاده کنید. این یعنی سیستم مسئول اعمال سبک‌بندی نمای صحیح است.

ابزاره‌ها و نماهای اعلان سفارشی

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

مشکلات رایجی که باید مراقب آن‌ها باشید شامل موارد زیر است:

• با فرض اینکه رنگ پس‌زمینه همیشه روشن است.
• رنگ‌های نوشتار کدگذاری‌شده.
• تنظیم رنگ پس‌زمینه کدگذاری‌شده ثابت هنگام استفاده از رنگ نوشتار پیش‌فرض.
• استفاده از نماد قابل‌رسم که رنگ ثابتی دارد.

در همه این موارد، به‌جای رنگ‌های کدگذاری‌شده از مشخصه‌های زمینه مناسب استفاده کنید.

صفحه‌های راه‌اندازی

اگر برنامه‌تان صفحه راه‌اندازی سفارشی دارد، ممکن است لازم باشد آن را اصلاح کنید تا زمینه انتخاب‌شده را منعکس کند.

هرگونه رنگ کدگذاری‌شده ثابت مانند رنگ‌های پس‌زمینه را که به‌صورت برنامه‌نویسی روی سفید تنظیم شده‌اند بردارید. درعوض از مشخصه زمینه ?android:attr/colorBackground استفاده کنید.

تغییرات پیکربندی

وقتی زمینه برنامه ازطریق تنظیمات سیستم یا AppCompat تغییر می‌کند، تغییر پیکربندی uiMode را راه‌اندازی می‌کند. این یعنی فعالیت‌ها به‌طور خودکار دوباره ایجاد می‌شوند.

در برخی موارد، ممکن است بخواهید برنامه‌ای تغییر پیکربندی را مدیریت کند. برای مثال، ممکن است بخواهید تغییر پیکربندی را به‌تأخیر بیندازید چون ویدیویی درحال پخش است.

برنامه می‌تواند با اعلام اینکه هر Activity می‌تواند تغییر پیکربندی uiMode را مدیریت کند، پیاده‌سازی زمینه تیره را مدیریت کند:

<activity
    android:name=".MyActivity"
    android:configChanges="uiMode" />

وقتی Activity اعلام می‌کند که تغییرات پیکربندی را مدیریت می‌کند، روش onConfigurationChanged() آن هنگام تغییر زمینه فراخوانی می‌شود.

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

val currentNightMode = configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
when (currentNightMode) {
    Configuration.UI_MODE_NIGHT_NO -> {} // Night mode is not active, we're using the light theme.
    Configuration.UI_MODE_NIGHT_YES -> {} // Night mode is active, we're using dark theme.
}

int currentNightMode = configuration.uiMode & Configuration.UI_MODE_NIGHT_MASK;
switch (currentNightMode) {
    case Configuration.UI_MODE_NIGHT_NO:
        // Night mode is not active, we're using the light theme
        break;
    case Configuration.UI_MODE_NIGHT_YES:
        // Night mode is active, we're using dark theme
        break;
}