Implementare il tema scuro

Prova Compose

Jetpack Compose è il toolkit per la UI consigliato per Android. Scopri come utilizzare i temi in Compose.

Combinazione di colori - Material Design 3 →

Il tema scuro è disponibile su Android 10 (livello API 29) e versioni successive. Offre i seguenti vantaggi:

• Riduce notevolmente il consumo di energia, a seconda della tecnologia dello schermo del dispositivo.
• Migliora la visibilità per gli utenti ipovedenti e per quelli sensibili alla luce intensa.
• Semplifica l'utilizzo di un dispositivo in un ambiente con scarsa illuminazione.

Il tema scuro viene applicato alla UI del sistema Android e alle app in esecuzione sul dispositivo.

Esistono tre modi per attivare il tema scuro su Android 10 e versioni successive:

• Utilizza l'impostazione di sistema andando su Impostazioni > Display > Tema per attivare il tema scuro.
• Utilizza il riquadro Impostazioni rapide per cambiare tema dalla barra delle notifiche, se abilitato.
• Sui dispositivi Pixel, attiva la modalità di risparmio energetico per attivare contemporaneamente il tema scuro. Altri dispositivi potrebbero non supportare questo comportamento.

Per istruzioni su come applicare un tema scuro ai contenuti basati sul web utilizzando un componente WebView, consulta Scurisci i contenuti web in WebView.

Supporta il tema scuro nella tua app

Per supportare il tema scuro, imposta il tema della tua app, che di solito si trova in res/values/styles.xml, in modo che erediti da un tema DayNight:

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

Puoi anche utilizzare il tema scuro di Material Components:

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

In questo modo, il tema principale dell'app viene collegato ai flag della modalità notturna controllati dal sistema e l'app riceve un tema scuro predefinito quando viene attivato.

Temi e stili

Evita di utilizzare colori o icone impostati come hardcoded destinati all'uso con un tema chiaro. Utilizza invece gli attributi del tema o le risorse idonee per la modalità Buio.

Due attributi del tema sono i più importanti per il tema scuro:

• ?android:attr/textColorPrimary: un colore del testo per uso generico. È quasi nero nel tema chiaro e quasi bianco nei temi scuri. Contiene uno stato disattivato.
• ?attr/colorControlNormal: un colore per icona per uso generico. Contiene uno stato disattivato.

Ti consigliamo di utilizzare i componenti di Material Design, poiché il suo sistema di temi cromatici, come gli attributi del tema ?attr/colorSurface e ?attr/colorOnSurface, fornisce un facile accesso ai colori adatti. Puoi personalizzare questi attributi nel tuo tema.

Cambia i temi nell'app

Puoi consentire agli utenti di modificare il tema dell'app mentre è in esecuzione. Di seguito sono riportate le opzioni consigliate:

• Chiaro
• Scuro
• Predefinita di sistema (l'opzione predefinita consigliata)

Queste opzioni vengono mappate direttamente alle modalità AppCompat.DayNight:

• Luce: MODE_NIGHT_NO.

• Scuro: MODE_NIGHT_YES.

• Impostazione predefinita di sistema: MODE_NIGHT_FOLLOW_SYSTEM.

Per cambiare il tema:

• Sul livello API 31 e versioni successive, utilizza UiModeManager#setApplicationNightMode per comunicare al sistema il tema utilizzato dalla tua app. In questo modo, il sistema può abbinare il tema durante la schermata iniziale.

• Per il livello API 30 e versioni precedenti, utilizza AppCompatDelegate.setDefaultNightMode() per cambiare il tema.

tema scuro forzato

Android 10 offre tema scuro forzato, una funzionalità che consente agli sviluppatori di implementare rapidamente un tema scuro senza impostare esplicitamente un tema DayNight.

Il tema scuro forzato analizza ogni visualizzazione della tua app con tema chiaro e applica automaticamente un tema scuro prima che venga visualizzato sullo schermo. Puoi utilizzare una combinazione di tema scuro forzato e implementazione nativa per ridurre il tempo necessario per implementare il tema scuro.

Le app devono attivare il tema scuro forzato impostando android:forceDarkAllowed="true" nel tema dell'attività. Questo attributo è impostato su tutti i temi chiari forniti dal sistema e da AndroidX, come Theme.Material.Light. Quando utilizzi Tema scuro forzato, testa l'app con attenzione ed escludi le visualizzazioni in base alle necessità.

Se la tua app utilizza un tema scuro, ad esempio Theme.Material), il tema scuro forzato non viene applicato. Analogamente, se il tema della tua app eredita da un tema DayNight, la modalità Buio forzato non viene applicata a causa del passaggio automatico da un tema all'altro.

Disattiva tema scuro forzato su una visualizzazione

Il tema scuro forzato può essere controllato su visualizzazioni specifiche con l'attributo di layout android:forceDarkAllowed o con setForceDarkAllowed().

Contenuti web

Per informazioni sull'utilizzo dei temi scuri nei contenuti basati sul web, consulta Scurisci i contenuti web in WebView. Per un esempio di tema scuro applicato a una WebView, consulta la demo di WebView su GitHub.

Best practice

Le sezioni seguenti forniscono le best practice per l'implementazione dei temi scuri.

Notifiche e widget

Per le piattaforme UI che mostri sul dispositivo, ma che non controlli direttamente, assicurati che tutte le visualizzazioni che utilizzi riflettano il tema dell'app host. Due esempi sono le notifiche e i widget di Avvio app.

Notifiche

Utilizza i modelli di notifica forniti dal sistema, ad esempio MessagingStyle. Ciò significa che il sistema è responsabile dell'applicazione dello stile di visualizzazione corretto.

Widget e visualizzazioni di notifiche personalizzate

Per i widget di Avvio app o se la tua app utilizza visualizzazioni di contenuti di notifica personalizzate, testa i contenuti sia con il tema chiaro sia con quello scuro.

Gli errori comuni da tenere d'occhio includono:

• Supponendo che il colore di sfondo sia sempre chiaro.
• Impostare come hardcoded i colori del testo.
• Impostazione di un colore di sfondo impostato come hardcoded mentre utilizzi il colore del testo predefinito.
• Utilizzo di un'icona drawable con un colore statico.

In tutti questi casi, utilizza gli attributi del tema appropriati anziché i colori impostati come hardcoded.

Schermate di lancio

Se la tua app ha una schermata di avvio personalizzata, potresti doverla modificare in modo che rifletta il tema selezionato.

Rimuovi i colori impostati come hardcoded, ad esempio i colori di sfondo impostati in modo programmatico su bianco. Utilizza invece l'attributo del tema ?android:attr/colorBackground.

Modifiche alla configurazione

Quando il tema dell'app cambia, tramite l'impostazione di sistema o AppCompat, viene attivata una modifica della configurazione uiMode. Ciò significa che le attività vengono ricreate automaticamente.

In alcuni casi, potresti voler che un'app gestisca la modifica della configurazione. Ad esempio, potresti voler ritardare una modifica della configurazione perché è in corso la riproduzione di un video.

Un'app può gestire l'implementazione del tema scuro dichiarando che ogni Activity può gestire la modifica della configurazione uiMode:

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

Quando un'Activity dichiara di gestire le modifiche alla configurazione, il suo metodo onConfigurationChanged() viene chiamato quando viene apportata una modifica al tema.

Per controllare il tema corrente, le app possono eseguire un codice simile al seguente:

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