اجرای تم تیره

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

Jetpack Compose ابزار رابط کاربری پیشنهادی برای اندروید است. یاد بگیرید که چگونه با تم‌بندی در Compose کار کنید.

طرح رنگی - طراحی متریال ۳ →

تم تاریک در اندروید ۱۰ (سطح API ۲۹) و بالاتر موجود است. این تم مزایای زیر را دارد:

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

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

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

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

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

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

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

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

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

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

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

تم‌ها و سبک‌ها

از استفاده از رنگ‌ها یا آیکون‌های کدنویسی‌شده‌ی آماده که برای استفاده در قالب روشن در نظر گرفته شده‌اند، خودداری کنید. در عوض از ویژگی‌های قالب یا منابع دارای مجوز شب استفاده کنید.

دو ویژگی قالب برای قالب تیره از همه مهم‌تر هستند:

• ?android:attr/textColorPrimary : یک رنگ متن عمومی. در تم روشن تقریباً مشکی و در تم تیره تقریباً سفید است. این رنگ شامل یک حالت غیرفعال است.
• ?attr/colorControlNormal : یک رنگ آیکون عمومی. این شامل یک حالت غیرفعال است.

ما استفاده از کامپوننت‌های طراحی متریال (Material Design Components) را توصیه می‌کنیم، زیرا سیستم تم‌بندی رنگی آن، مانند ویژگی‌های تم ?attr/colorSurface و ?attr/colorOnSurface ، دسترسی آسان به رنگ‌های مناسب را فراهم می‌کند. می‌توانید این ویژگی‌ها را در تم خود سفارشی کنید.

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

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

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

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

• نور: MODE_NIGHT_NO .

• تاریک: MODE_NIGHT_YES .

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

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

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

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

نیروی تاریک

اندروید ۱۰ قابلیتی به نام Force Dark را ارائه می‌دهد که به توسعه‌دهندگان اجازه می‌دهد بدون تنظیم صریح تم DayNight ، به سرعت یک تم تاریک پیاده‌سازی کنند.

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

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

اگر برنامه شما از یک تم تاریک، مانند Theme.Material ، استفاده می‌کند، Force Dark اعمال نمی‌شود. به طور مشابه، اگر تم برنامه شما از یک تم DayNight ارث‌بری کند، Force Dark به دلیل تغییر خودکار تم اعمال نمی‌شود.

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

می‌توان با استفاده از ویژگی طرح‌بندی 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;
}